@frockbot/plugin-computer 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-computer",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "private": false,
   "type": "module",
   "exports": {
@@ -29,21 +29,21 @@
   },
   "dependencies": {
     "@cordisjs/client": "0.8.2",
-    "@frockbot/client-core": "0.3.3",
-    "@frockbot/client-ui": "0.3.3",
-    "@frockbot/computer-core": "0.3.3",
-    "@frockbot/computer-host-runtime": "0.3.3",
-    "@frockbot/kernel-agent-loop": "0.3.3",
-    "@frockbot/kernel-contracts": "0.3.3",
-    "@frockbot/plugin-prompt": "0.3.3",
-    "@frockbot/plugin-shell": "0.3.3",
-    "@frockbot/plugin-tools": "0.3.3",
+    "@frockbot/client-core": "0.3.5",
+    "@frockbot/client-ui": "0.3.5",
+    "@frockbot/computer-core": "0.3.5",
+    "@frockbot/computer-host-runtime": "0.3.5",
+    "@frockbot/kernel-agent-loop": "0.3.5",
+    "@frockbot/kernel-contracts": "0.3.5",
+    "@frockbot/plugin-prompt": "0.3.5",
+    "@frockbot/plugin-shell": "0.3.5",
+    "@frockbot/plugin-tools": "0.3.5",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
-    "@frockbot/plugin-models": "0.3.3",
-    "@frockbot/plugin-testkit": "0.3.3",
+    "@frockbot/plugin-models": "0.3.5",
+    "@frockbot/plugin-testkit": "0.3.5",
     "@types/bun": "1.4.0",
     "@types/node": "26.2.0",
     "@vitejs/plugin-vue": "6.0.8",

package/src/agent.test.ts

@@ -256,12 +256,42 @@ describe("computer agent contribution", () => {
     await expect(
       execute(harness, "computer_exec", { command: "pwd" }),
     ).resolves.toEqual({
-      content: "The user is controlling this Computer; do not retry this Turn",
+      content: "held by human:session-1; do not retry this Turn",
       isError: true,
     });
     await harness.dispose();
   });
 
+  test("an unconfigured deployment offers no Computer tool and no Computer prompt", async () => {
+    const harness = await createPluginHarness([
+      ComputerRegistry,
+      ToolRegistry,
+      SystemPromptRegistry,
+      SessionStore,
+    ]);
+    await harness.mount(
+      createComputerAgentPlugin({
+        userId: "user-1",
+        defaultProviderId: "fixture",
+        configured: false,
+      }),
+    );
+
+    const registered = harness.root.tools.registeredNames?.() ?? [];
+    expect(registered.filter((name) => name.startsWith("computer_"))).toEqual(
+      [],
+    );
+    const prompt = await harness.root.systemPrompt.assemble({
+      sessionId: "session-1",
+      provider: "fixture",
+      model: "fixture",
+      turnType: "chat",
+    });
+    expect(prompt.text).not.toContain("Persistent Computer");
+    expect(prompt.text).not.toContain("computer_exec");
+    await harness.dispose();
+  });
+
   test("satisfies plugin package conventions", () => {
     expect(verifyPluginPackage({ packageJson, manifest })).toMatchObject({
       name: "@frockbot/plugin-computer",

package/src/agent.ts

@@ -111,6 +111,16 @@ export interface ComputerWriterIdentityV1 {
 export interface ComputerAgentPluginConfig {
   userId: string;
   defaultProviderId: string;
+  /**
+   * Whether this deployment has a Computer at all.
+   *
+   * False, and the Package mounts no Computer tool and adds no Computer
+   * section to the system prompt: a prompt that promises a persistent Linux
+   * Computer where there is none costs the User a Turn of model spend per
+   * question and ends in the model guessing at a remedy. Absent means
+   * configured, so a host that does not know keeps the tools.
+   */
+  configured?: boolean;
   idempotentEffects?: boolean;
   writer?: ComputerWriterIdentityV1;
   /**
@@ -287,9 +297,13 @@ function decodeBrowser(input: unknown): ComputerBrowserAction | undefined {
 function failure(error: unknown): { content: string; isError: true } {
   if (error instanceof ComputerError) {
     if (error.code === "human-control-active") {
+      // The holder is named, so a second Bot of the same User — and the User
+      // reading the transcript — can tell which session has the desktop.
+      const holder = error.message.trim();
       return {
-        content:
-          "The user is controlling this Computer; do not retry this Turn",
+        content: holder
+          ? `${holder}; do not retry this Turn`
+          : "The user is controlling this Computer; do not retry this Turn",
         isError: true,
       };
     }
@@ -534,6 +548,11 @@ export function createComputerAgentPlugin(
   }
 
   const plugin: Plugin.Function = (ctx) => {
+    // A deployment with no Computer offers no Computer tool and no Computer
+    // prompt. The alternative — tools that always fail — spends a Turn's model
+    // budget discovering what this host already knows, and leaves the model
+    // inventing a way for the User to fix it.
+    if (config.configured === false) return [];
     // One Computer per User (ADR 0012): the assignment is keyed by the User,
     // and the Bot attaches to it as a tenant.
     const identity = { userId };
@@ -783,6 +802,11 @@ export function createComputerAgentPlugin(
         };
       }
       const store = processes;
+      // The intent this call wrote, until the launch that follows it settles.
+      // Left as `starting` by a launch that threw, it is a record nothing can
+      // ever answer for and nothing can forget — a failing Computer would
+      // spend the Bot's whole 100-record budget having run nothing at all.
+      let unsettled: ComputerProcessRecordV1 | undefined;
       try {
         return await useComputer(
           await open(context.botId, context.sessionId, context.signal),
@@ -812,6 +836,7 @@ export function createComputerAgentPlugin(
               logPath: "",
             };
             await store.record({ ...intent, cwd: "/", logPath: "/" });
+            unsettled = { ...intent, cwd: "/", logPath: "/" };
             const launched = await computer.processes.launch(
               { processId, command },
               { signal: context.signal, effectId: context.effectId },
@@ -825,6 +850,7 @@ export function createComputerAgentPlugin(
               pid: launched.pid,
             };
             await store.update(running);
+            unsettled = undefined;
             await noteProcess(context.sessionId, turnOf(context), {
               processId,
               action: "launch",
@@ -845,6 +871,18 @@ export function createComputerAgentPlugin(
           },
         );
       } catch (error) {
+        if (unsettled) {
+          // `unknown`, not deleted: the launch may have started something
+          // before it threw, and "recovery can read its outcome or classify it
+          // as unknown without repeating it". Terminal, so the record is
+          // prunable rather than holding a slot for the life of the Bot.
+          try {
+            await store.update({ ...unsettled, status: "unknown" });
+          } catch {
+            // Reconciling the intent is never why a tool call fails; the
+            // launch failure below is the answer the model needs.
+          }
+        }
         if (error instanceof ComputerProcessLimitError) {
           return { content: error.message, isError: true };
         }

package/src/bot.test.ts

@@ -4,7 +4,11 @@ import type {
   ComputerControlLease,
   ComputerHandle,
 } from "@frockbot/computer-core";
-import { computerBotPathKeyV1, ComputerError } from "@frockbot/computer-core";
+import {
+  computerBotPathKeyV1,
+  COMPUTER_UNCONFIGURED_MESSAGE_V1,
+  ComputerError,
+} from "@frockbot/computer-core";
 import {
   COMPUTER_CONNECT_DEFERRAL_MS,
   COMPUTER_CONNECT_START_DELAY_MS,
@@ -127,6 +131,45 @@ function fakeHandle(options: {
 }
 
 describe("Computer Bot Durable Object Contribution", () => {
+  test("an unconfigured host rejects every command, connect included", async () => {
+    const storage = new MemoryStorage();
+    const contribution = createComputerBotBackendContribution({
+      storage,
+      configured: false,
+      providerLabel: "Fake Computer",
+      openComputer: () => {
+        throw new Error("an unconfigured host must not reach a provider");
+      },
+    });
+
+    for (const type of [
+      "connect",
+      "takeControl",
+      "releaseControl",
+      "runDoctor",
+    ] as const) {
+      const receipt = await contribution.execute("user-1", "scout", {
+        version: 1,
+        commandId: `command-${type}`,
+        botId: "scout",
+        type,
+      });
+      expect(receipt).toMatchObject({
+        version: 1,
+        type,
+        status: "rejected",
+        failure: COMPUTER_UNCONFIGURED_MESSAGE_V1,
+      });
+    }
+    // Nothing was admitted, so the projection never claims work is under way.
+    expect(await contribution.read("user-1", "scout")).toMatchObject({
+      phase: "unconfigured",
+      message: COMPUTER_UNCONFIGURED_MESSAGE_V1,
+    });
+    // The refusal is written for the person reading it.
+    expect(COMPUTER_UNCONFIGURED_MESSAGE_V1).not.toContain("SPRITES_TOKEN");
+  });
+
   test("records provider progress durably and projects its ordered steps", async () => {
     const storage = new MemoryStorage();
     let contribution: ReturnType<typeof createComputerBotBackendContribution>;
@@ -703,6 +746,66 @@ describe("Computer Bot Durable Object Contribution", () => {
     expect(storage.values.has(COMPUTER_CONTROL_RECORD_KEY)).toBe(false);
   });
 
+  test("a release the Computer refuses still drops the durable lease", async () => {
+    const storage = new MemoryStorage();
+    const now = new Date("2026-09-02T00:00:00.000Z");
+    const host = {
+      storage,
+      configured: true,
+      providerLabel: "Fake Computer",
+      now: () => now,
+      newId: () => "owner-1",
+      openComputer: () =>
+        Promise.resolve(
+          fakeHandle({
+            acquire: (ownerId) =>
+              Promise.resolve({
+                id: ownerId,
+                expiresAt: "2026-09-02T00:01:30.000Z",
+              }),
+            renew: (lease) => Promise.resolve({ id: lease.id, expiresAt: "" }),
+            release: () => Promise.reject(new Error("Sprite is unreachable")),
+          }),
+        ),
+    };
+    const contribution = createComputerBotBackendContribution(host);
+    await contribution.execute(
+      "user-1",
+      "scout",
+      command("takeControl", "take-1"),
+    );
+    expect(storage.values.has(COMPUTER_CONTROL_RECORD_KEY)).toBe(true);
+
+    const receipt = await contribution.execute(
+      "user-1",
+      "scout",
+      command("releaseControl", "release-1"),
+    );
+
+    // The failure reaches the User rather than being swallowed...
+    expect(receipt).toMatchObject({
+      status: "rejected",
+      failure: "Sprite is unreachable",
+    });
+    // ...and the User-wide fence is gone, so no heartbeat can renew it and no
+    // other Bot of this User is locked out of the Computer forever.
+    expect(storage.values.has(COMPUTER_CONTROL_RECORD_KEY)).toBe(false);
+    const projection = await contribution.read("user-1", "scout");
+    expect(projection.controlLease).toBeUndefined();
+    expect(projection.phase).toBe("error");
+    // A heartbeat that arrives after the failed release has nothing to renew.
+    await expect(
+      contribution.execute(
+        "user-1",
+        "scout",
+        command("refreshControl", "refresh-1"),
+      ),
+    ).resolves.toMatchObject({
+      status: "rejected",
+      failure: "No control lease is active",
+    });
+  });
+
   test("reclaims a stale lease under a new durable owner", async () => {
     const storage = new MemoryStorage();
     let now = new Date("2026-09-02T00:00:00.000Z");

package/src/bot.ts

@@ -6,6 +6,7 @@
 // the URL is held in this Contribution instance until a read projects it.
 import {
   computerBotPathKeyV1,
+  COMPUTER_UNCONFIGURED_MESSAGE_V1,
   ComputerError,
   decodeComputerDoctorReportV1,
   type ComputerConnectionProgressV1,
@@ -413,6 +414,25 @@ function failureText(error: unknown): string {
   );
 }
 
+/**
+ * One stored record, or nothing when the codec refuses it.
+ *
+ * A projection degrades; it does not fail. Losing one record's contribution to
+ * the card is better than a Bot whose Computer surface throws forever because
+ * a single key holds a shape this version does not know.
+ */
+function decoded<T>(
+  value: unknown,
+  decode: (input: unknown) => T,
+): T | undefined {
+  if (value === undefined) return undefined;
+  try {
+    return decode(value);
+  } catch {
+    return undefined;
+  }
+}
+
 function isFresh(expiresAt: string, now: Date): boolean {
   return Date.parse(expiresAt) > now.getTime();
 }
@@ -685,6 +705,21 @@ export class ComputerBotBackendContribution {
         "Computer command does not match Bot registration",
       );
     }
+    // A host with no Computer rejects every command with the same reason,
+    // before admission. `connect` in particular must not answer `accepted`:
+    // admitting work that provably cannot be done leaves the User watching a
+    // projection that will never move, and there is nothing to reconcile
+    // later because nothing was ever started.
+    if (!this.host.configured) {
+      return {
+        version: 1,
+        commandId: command.commandId,
+        type: command.type,
+        status: "rejected",
+        completedAt: this.now().toISOString(),
+        failure: COMPUTER_UNCONFIGURED_MESSAGE_V1,
+      };
+    }
     const admitted = await this.admit(userId, command);
     if ("replay" in admitted) return admitted.replay;
     if (command.type === "connect") {
@@ -1081,17 +1116,31 @@ export class ComputerBotBackendContribution {
     );
     if (currentValue === undefined) return;
     const current = decodeStoredComputerControlV1(currentValue);
-    await this.withComputer(userId, command, async (computer) => {
-      if (!computer.control) {
-        throw new Error("The selected Computer does not support human control");
-      }
-      await computer.control.release(
-        { id: current.ownerId, expiresAt: current.expiresAt },
-        { scope: "desktop-gui", ownerId: current.ownerId },
-        { effectId: `computer:${command.commandId}:release-control` },
-      );
-    });
-    await this.host.storage.delete(COMPUTER_CONTROL_RECORD_KEY);
+    try {
+      await this.withComputer(userId, command, async (computer) => {
+        if (!computer.control) {
+          throw new Error(
+            "The selected Computer does not support human control",
+          );
+        }
+        await computer.control.release(
+          { id: current.ownerId, expiresAt: current.expiresAt },
+          { scope: "desktop-gui", ownerId: current.ownerId },
+          { effectId: `computer:${command.commandId}:release-control` },
+        );
+      });
+    } finally {
+      // The durable record goes whatever the provider answered. It is the
+      // User-wide `desktop-gui` fence: left behind by a release the Computer
+      // could not confirm, it is renewed by the client heartbeat forever, and
+      // every Bot of this User loses the Computer with no way back. The
+      // provider's own lease expires on its side; this one has no expiry a
+      // failing host can be trusted to reach. The failure still reaches the
+      // User — it rejects the receipt and records the `error` phase — but it
+      // never becomes a lease nobody can drop.
+      // Prior art: `releaseDesktopLease` in `@frockbot/plugin-subagents`.
+      await this.host.storage.delete(COMPUTER_CONTROL_RECORD_KEY);
+    }
   }
 
   /**
@@ -1279,16 +1328,15 @@ export class ComputerBotBackendContribution {
         this.screenshots(userId, botId),
         this.doctor(userId, botId),
       ]);
-    const viewer =
-      viewerValue === undefined ? undefined : decodeStoredViewer(viewerValue);
-    const control =
-      controlValue === undefined
-        ? undefined
-        : decodeStoredComputerControlV1(controlValue);
-    const provider =
-      providerValue === undefined
-        ? undefined
-        : decodeStoredProvider(providerValue);
+    // A record the codec refuses is treated as absent, the way `doctor()`
+    // above and `ComputerProcessStore.list` already do. These three decoders
+    // throw on any unexpected shape — a field a future version adds included —
+    // and this is the read behind the card, the overlay and the poll: one bad
+    // value made `GET /api/bots/:id/computer` throw for that Bot forever, with
+    // nothing in the product able to clear the key.
+    const viewer = decoded(viewerValue, decodeStoredViewer);
+    const control = decoded(controlValue, decodeStoredComputerControlV1);
+    const provider = decoded(providerValue, decodeStoredProvider);
     const liveViewer =
       viewer &&
       this.#liveViewer?.id === viewer.id &&
@@ -1303,7 +1351,7 @@ export class ComputerBotBackendContribution {
     let message: string;
     if (!this.host.configured) {
       phase = "unconfigured";
-      message = "No Computer provider is configured for this host";
+      message = COMPUTER_UNCONFIGURED_MESSAGE_V1;
     } else if (provider?.phase === "disconnected") {
       phase = "disconnected";
       message = provider.message;

package/src/client/ComputerCard.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { readFileSync } from "node:fs";
 import { parse } from "@vue/compiler-sfc";
 import type { ComputerState } from "../shared.js";
+import { COMPUTER_COLD_PROVISION_EXPECTATION } from "../protocol.js";
 import {
   createComputerViewerActions,
   decodeComputerViewerFrameMessageV1,
@@ -121,7 +122,19 @@ describe("Computer viewer", () => {
     const template = parsed.descriptor.template?.content ?? "";
 
     expect(cardSource).toContain("Setting up your computer for the first time");
-    expect(cardSource).toContain("This usually takes 2-3 minutes");
+    // An unconfigured card is not a button — clicking it opened a full-screen
+    // modal that repeated the sentence already on the card — and no card
+    // renders until a Bot exists to have a Computer.
+    expect(cardSource).toContain(':disabled="busy || unconfigured"');
+    expect(cardSource).toContain('<section v-if="hasBot"');
+    // The viewer header names the Bot, not its slug and not the Computer
+    // vendor: both are architecture leaking onto the User's screen.
+    expect(overlaySource).toContain("{{ botName }}");
+    expect(overlaySource).not.toContain("state.providerLabel");
+    expect(COMPUTER_COLD_PROVISION_EXPECTATION).toBe(
+      "This usually takes 2-3 minutes",
+    );
+    expect(cardSource).toContain("COMPUTER_COLD_PROVISION_EXPECTATION");
     expect(cardSource).toContain("Updating your computer");
     expect(template).toContain('role="progressbar"');
     expect(template).toContain(':aria-valuenow="progressValueNow"');

package/src/client/ComputerCard.vue

@@ -2,7 +2,9 @@
 import { useRpc } from "@cordisjs/client";
 import { UiIcon } from "@frockbot/client-ui";
 import { computed, inject, ref } from "vue";
+import { frockBotWebDataKey } from "@frockbot/plugin-shell/shared";
 import { computerKey, type ComputerState } from "../shared.ts";
+import { COMPUTER_COLD_PROVISION_EXPECTATION } from "../protocol.ts";
 import {
   computerProgressElapsedMs,
   computerProgressFrame,
@@ -12,7 +14,16 @@ import {
 const computer = inject(computerKey) ?? useRpc<ComputerState>();
 const state = computed(() => computer.value);
 const busy = ref(false);
+// No Bot, no Computer card. The client machine seeds a placeholder projection
+// before any Bot exists, and rendering it told a brand-new User about the
+// Computer of a Bot they had not created yet.
+const shell = inject(frockBotWebDataKey, undefined);
+const hasBot = computed(() => Boolean(shell?.value.activeBotId));
 const screenshot = computed(() => state.value.screenshots?.[0]);
+// A card that says there is no Computer opens nothing: a full-screen modal
+// repeating the same sentence is a click that costs the User a step and
+// answers nothing.
+const unconfigured = computed(() => state.value.phase === "unconfigured");
 const opening = computed(
   () =>
     state.value.phase === "provisioning" || state.value.phase === "updating",
@@ -32,7 +43,7 @@ const openingHeading = computed(() => {
 });
 const setupExpectation = computed(() =>
   progressRunKind.value === "cold-provision"
-    ? "This usually takes 2-3 minutes"
+    ? COMPUTER_COLD_PROVISION_EXPECTATION
     : undefined,
 );
 const progressPhaseLabel = computed(
@@ -92,11 +103,11 @@ async function open(): Promise<void> {
 </script>
 
 <template>
-  <section class="computer-card">
+  <section v-if="hasBot" class="computer-card">
     <button
       type="button"
       class="computer-screen computer-screen-thumbnail"
-      :disabled="busy"
+      :disabled="busy || unconfigured"
       aria-label="Open computer in full window"
       @click="open"
     >

package/src/client/ComputerViewerOverlay.vue

@@ -10,6 +10,7 @@ import {
   ref,
   watch,
 } from "vue";
+import { frockBotWebDataKey } from "@frockbot/plugin-shell/shared";
 import { computerKey, type ComputerState } from "../shared.ts";
 import { dialogFocusWrapTarget } from "./dialog-focus.ts";
 import { computerProgressFrame, computerProgressRunKind } from "./progress.ts";
@@ -23,6 +24,12 @@ import {
 const computer = inject(computerKey) ?? useRpc<ComputerState>();
 const state = computed(() => computer.value);
 const busy = ref(false);
+// The Bot as its User named it. A raw slug and an infrastructure vendor are
+// architecture, not identity, and the viewer header is the User's screen.
+const shell = inject(frockBotWebDataKey, undefined);
+const botName = computed(
+  () => shell?.value.botSettings?.profile.name ?? "Computer",
+);
 const confirming = ref(false);
 const confirmDialog = ref<HTMLElement>();
 const viewerFrame = ref<HTMLIFrameElement>();
@@ -183,7 +190,9 @@ async function closeViewer(escape = false): Promise<void> {
   try {
     await (escape ? actions.escape() : actions.closeViewer());
   } catch {
-    // A failed release remains visible in the still-open overlay.
+    // The overlay collapses either way: a release the Computer refused is
+    // recorded durably and shown on the card, and is never a reason to trap
+    // the User in a full-screen viewer.
   }
 }
 
@@ -275,7 +284,7 @@ onBeforeUnmount(() => {
     <header class="computer-overlay-toolbar">
       <div class="computer-overlay-identity">
         <strong>Computer</strong>
-        <small>{{ state.botId }} · {{ state.providerLabel }}</small>
+        <small>{{ botName }}</small>
       </div>
       <div class="computer-overlay-actions">
         <span class="computer-status" :class="`status-${state.phase}`">

package/src/client/application.test.ts

@@ -74,6 +74,7 @@ function mountHostedProvider(options: { stateChannel?: boolean } = {}) {
   let hostUpdating = false;
   let controlHeld = false;
   let renewFails = false;
+  let releaseFails = false;
   let heldClose: { release: () => void; pending: Promise<void> } | undefined;
   let state: { value: ComputerState } | undefined;
   const slots: ClientSlotRegistration[] = [];
@@ -118,7 +119,7 @@ function mountHostedProvider(options: { stateChannel?: boolean } = {}) {
             phase = "human-control";
             controlHeld = true;
           }
-          if (command.type === "releaseControl") {
+          if (command.type === "releaseControl" && !releaseFails) {
             controlHeld = false;
             if (phase !== "disconnected") phase = "ready";
           }
@@ -130,13 +131,17 @@ function mountHostedProvider(options: { stateChannel?: boolean } = {}) {
             commandId: command.commandId,
             type: command.type,
             status:
-              command.type === "refreshViewer" && renewFails
+              (command.type === "refreshViewer" && renewFails) ||
+              (command.type === "releaseControl" && releaseFails)
                 ? "rejected"
                 : "applied",
             completedAt: "2026-09-02T00:00:00.000Z",
             ...(command.type === "refreshViewer" && renewFails
               ? { failure: "viewer session expired" }
               : {}),
+            ...(command.type === "releaseControl" && releaseFails
+              ? { failure: "Sprite is unreachable" }
+              : {}),
           };
           if (command.type === "closeViewer" && heldClose) {
             return heldClose.pending.then(() => receipt);
@@ -226,6 +231,9 @@ function mountHostedProvider(options: { stateChannel?: boolean } = {}) {
     failRenewal() {
       renewFails = true;
     },
+    failRelease() {
+      releaseFails = true;
+    },
     setUpdating() {
       phase = "updating";
       hostUpdating = true;
@@ -285,6 +293,35 @@ describe("hosted Computer provider", () => {
     mounted.dispose();
   });
 
+  test("a failed release stops the heartbeat and still closes the viewer", async () => {
+    const mounted = mountHostedProvider();
+    await flush();
+    await mounted.state.openViewer();
+    await mounted.state.takeControl();
+    expect(mounted.state.phase).toBe("human-control");
+
+    mounted.failRelease();
+    await expect(mounted.state.releaseControl()).rejects.toThrow(
+      "Sprite is unreachable",
+    );
+
+    // The projection here keeps reporting the lease — the worst case, a host
+    // that cannot drop it. The client must still stop renewing: a takeover
+    // whose release failed is one the User can never cancel otherwise.
+    const before = postedTypes(mounted.calls).length;
+    mounted.runtime.tick(VIEWER_REFRESH_INTERVAL_MS);
+    await flush();
+    expect(postedTypes(mounted.calls).slice(before)).not.toContain(
+      "refreshControl",
+    );
+
+    // And the full-screen viewer is closable, rather than trapping the User.
+    await mounted.state.closeViewer();
+    await flush();
+    expect(mounted.state.expanded).toBe(false);
+    mounted.dispose();
+  });
+
   test("refreshes the viewer only while the overlay is expanded", async () => {
     const mounted = mountHostedProvider();
     await flush();

package/src/client/application.ts

@@ -93,6 +93,8 @@ export function createComputerClientPlugin(
     let stopStateChannel: (() => void) | undefined;
     let updateRejoin: unknown;
     let controlRequest: Promise<void> | undefined;
+    /** Set by a release the backend refused; no heartbeat renews after it. */
+    let controlAbandoned = false;
 
     const state = ref<ComputerState>({
       ...machine,
@@ -122,7 +124,11 @@ export function createComputerClientPlugin(
     }
 
     function syncControlHeartbeat(): void {
-      if (machine.phase !== "human-control") {
+      // A release the backend could not confirm ends the heartbeat for good.
+      // Renewing a lease the User has already asked to drop is how a takeover
+      // becomes one that cannot be cancelled; the next explicit `takeControl`
+      // is what starts it again.
+      if (machine.phase !== "human-control" || controlAbandoned) {
         stopControlHeartbeat();
         return;
       }
@@ -329,6 +335,8 @@ export function createComputerClientPlugin(
 
     async function closeViewer(): Promise<void> {
       if (!machine.expanded) return;
+      // A host with no Computer never had a viewer session to close.
+      const hadComputer = machine.phase !== "unconfigured";
       if (controlRequest) {
         try {
           await controlRequest;
@@ -337,7 +345,15 @@ export function createComputerClientPlugin(
           // lease to release before this explicit close finishes.
         }
       }
-      if (machine.takingControl) await releaseControl();
+      if (machine.takingControl) {
+        try {
+          await releaseControl();
+        } catch {
+          // A release the Computer refused is already recorded durably and
+          // has stopped the heartbeat. It is not a reason to keep the User
+          // inside a full-screen viewer they asked to leave.
+        }
+      }
       // Collapse first. The capture the backend files on close is
       // opportunistic, and it crosses a service binding to take a screenshot
       // on the Sprite; an overlay that stayed on screen waiting for that would
@@ -345,6 +361,9 @@ export function createComputerClientPlugin(
       // than execute, so a refused capture never projects a failure onto a
       // Computer the User has already stopped watching.
       apply({ type: "viewer-collapsed" });
+      // A viewer that never existed has nothing to close, and the capture the
+      // command files is of a session that was never opened.
+      if (!hadComputer) return;
       void (async () => {
         try {
           await post("closeViewer");
@@ -357,6 +376,7 @@ export function createComputerClientPlugin(
 
     function takeControl(): Promise<void> {
       if (controlRequest) return controlRequest;
+      controlAbandoned = false;
       const pending = (async () => {
         if (!machine.viewerUrl) await connect("connect-requested");
         if (!machine.viewerUrl) return;
@@ -370,7 +390,13 @@ export function createComputerClientPlugin(
     }
 
     async function releaseControl(): Promise<void> {
-      await execute("releaseControl");
+      try {
+        await execute("releaseControl");
+      } catch (error) {
+        controlAbandoned = true;
+        syncControlHeartbeat();
+        throw error;
+      }
     }
 
     async function refreshControl(): Promise<void> {
@@ -404,6 +430,7 @@ export function createComputerClientPlugin(
         stopControlHeartbeat();
         stopViewerHeartbeat();
         stopUpdateRejoin();
+        controlAbandoned = false;
         machine = initialComputerMachineState();
         Object.assign(state.value, machine);
         watchStateChannel(selectedBotId);

package/src/process-records.test.ts

@@ -102,6 +102,53 @@ describe("the process store", () => {
     expect((await store.read(record.processId))?.status).toBe("exited");
   });
 
+  test("prunes finished records rather than disabling background exec forever", async () => {
+    const held = storage();
+    const store = new ComputerProcessStore(held);
+    for (let index = 0; index < COMPUTER_PROCESS_LIMIT_PER_BOT; index += 1) {
+      await store.record({
+        ...record,
+        processId: `p-${index}`,
+        // Ordered oldest first, so the prune has an unambiguous victim.
+        startedAt: new Date(Date.UTC(2026, 7, 31, 0, 0, index)).toISOString(),
+        status: "exited",
+        exitCode: 0,
+      });
+    }
+    expect(held.map.size).toBe(COMPUTER_PROCESS_LIMIT_PER_BOT);
+
+    // The 101st launch is admitted: a finished process's record has already
+    // answered everything anyone can ask of it.
+    await store.record({ ...record, processId: "p-next", status: "starting" });
+
+    expect(await store.read("p-next")).toMatchObject({ status: "starting" });
+    expect(await store.read("p-0")).toBeUndefined();
+    expect(await store.read("p-1")).toMatchObject({ status: "exited" });
+    expect(held.map.size).toBe(COMPUTER_PROCESS_LIMIT_PER_BOT);
+
+    // A record that has not finished is never pruned to make room: it is the
+    // only thing that remembers the process exists.
+    for (let index = 1; index < COMPUTER_PROCESS_LIMIT_PER_BOT; index += 1) {
+      await store.update({
+        ...record,
+        processId: `p-${index}`,
+        status: "running",
+      });
+    }
+    await expect(
+      store.record({ ...record, processId: "p-one-too-many" }),
+    ).rejects.toBeInstanceOf(ComputerProcessLimitError);
+  });
+
+  test("forgets one record on request", async () => {
+    const held = storage();
+    const store = new ComputerProcessStore(held);
+    await store.record(record);
+    await store.delete(record.processId);
+    expect(await store.read(record.processId)).toBeUndefined();
+    expect(held.map.size).toBe(0);
+  });
+
   test("drops a stored value the codec refuses rather than failing the listing", async () => {
     const held = storage();
     const store = new ComputerProcessStore(held);

package/src/process-store.ts

@@ -6,8 +6,8 @@
 // outlives its Turn, and after a Durable Object eviction the record is the only
 // thing that knows the process was ever launched.
 //
-// A deep, small module: `record`, `read`, `update`, `list`. Every write goes
-// through a decoder, so a value that reaches storage is a value the codec
+// A deep, small module: `record`, `read`, `update`, `delete`, `list`. Every
+// write goes through a decoder, so a value that reaches storage is a value the codec
 // accepts, and a stored record the codec later refuses is a visible failure
 // rather than a silently reshaped one.
 import {
@@ -41,21 +41,76 @@ export class ComputerProcessStore {
    */
   async record(intent: ComputerProcessRecordV1): Promise<void> {
     const decoded = decodeComputerProcessRecordV1(intent);
-    const held = await this.storage.list<unknown>({
+    let held = await this.storage.list<unknown>({
       prefix: COMPUTER_PROCESS_PREFIX,
       limit: COMPUTER_PROCESS_LIMIT_PER_BOT + 1,
     });
+    if (
+      held.size >= COMPUTER_PROCESS_LIMIT_PER_BOT &&
+      !held.has(computerProcessKeyV1(decoded.processId))
+    ) {
+      // A finished process's record has already answered every question
+      // anyone can ask of it. Without this prune the hundredth background
+      // command a Bot ever ran disabled `computer_exec{background:true}`
+      // permanently: no tool, no command and no UI could forget a record.
+      held = await this.prune(held, decoded.processId);
+    }
     if (
       held.size >= COMPUTER_PROCESS_LIMIT_PER_BOT &&
       !held.has(computerProcessKeyV1(decoded.processId))
     ) {
       throw new ComputerProcessLimitError(
-        `this Bot already holds ${COMPUTER_PROCESS_LIMIT_PER_BOT} background process records; end or forget one first`,
+        `this Bot already has ${COMPUTER_PROCESS_LIMIT_PER_BOT} background processes that have not finished; stop one with computer_process_stop first`,
       );
     }
     await this.storage.put(computerProcessKeyV1(decoded.processId), decoded);
   }
 
+  /**
+   * Drops finished records, oldest first, until the cap has room again.
+   *
+   * Terminal only: a `starting` or `running` record is the only thing that
+   * remembers the process exists, so it is never pruned to make space. An
+   * undecodable row goes too — it can answer nothing, and leaving it would let
+   * one bad value hold a slot for the life of the Bot.
+   */
+  private async prune(
+    held: Map<string, unknown>,
+    incoming: string,
+  ): Promise<Map<string, unknown>> {
+    const terminal: Array<{ key: string; startedAt: string }> = [];
+    for (const [key, value] of held) {
+      if (key === computerProcessKeyV1(incoming)) continue;
+      try {
+        const record = decodeComputerProcessRecordV1(value);
+        if (record.status === "exited" || record.status === "unknown") {
+          terminal.push({ key, startedAt: record.startedAt });
+        }
+      } catch (error) {
+        if (!(error instanceof ComputerProcessDecodeError)) throw error;
+        terminal.push({ key, startedAt: "" });
+      }
+    }
+    terminal.sort((left, right) =>
+      left.startedAt.localeCompare(right.startedAt),
+    );
+    const remaining = new Map(held);
+    for (const { key } of terminal) {
+      if (remaining.size < COMPUTER_PROCESS_LIMIT_PER_BOT) break;
+      await this.storage.delete(key);
+      remaining.delete(key);
+    }
+    return remaining;
+  }
+
+  /**
+   * Forgets one record. The process it described is over: the caller has read
+   * a terminal status, or is reconciling an intent whose launch never ran.
+   */
+  async delete(processId: string): Promise<void> {
+    await this.storage.delete(computerProcessKeyV1(processId));
+  }
+
   async read(processId: string): Promise<ComputerProcessRecordV1 | undefined> {
     const held = await this.storage.get<unknown>(
       computerProcessKeyV1(processId),

package/src/processes.test.ts

@@ -53,7 +53,7 @@ interface Computer {
   workspace: FakeWorkspace;
 }
 
-function fakeComputer(): Computer {
+function fakeComputer(options: { launchFails?: boolean } = {}): Computer {
   const calls: string[] = [];
   const workspace = new FakeWorkspace();
   const computer: Computer = {
@@ -72,6 +72,9 @@ function fakeComputer(): Computer {
           processes: {
             launch: (request) => {
               calls.push(`launch:${request.processId}:${request.command}`);
+              if (options.launchFails) {
+                return Promise.reject(new Error("Sprite is unreachable"));
+              }
               return Promise.resolve({
                 pid: 4321,
                 logPath: `/processes/${request.processId}/log`,
@@ -174,6 +177,26 @@ describe("computer_exec with background:true", () => {
     await harness.dispose();
   });
 
+  test("settles the intent a failed launch left behind", async () => {
+    const computer = fakeComputer({ launchFails: true });
+    const held = storage();
+    const harness = await mount(computer, held);
+
+    const result = await call(harness, "computer_exec", {
+      command: "npm run build",
+      background: true,
+    });
+
+    expect(result).toMatchObject({ isError: true });
+    // The record survives — the launch may have started something before it
+    // threw — but it is terminal, so the store can prune it. Left `starting`,
+    // a failing Computer would burn the Bot's 100-record budget having run
+    // nothing at all, and permanently disable background exec.
+    const records = [...held.map.values()] as Array<{ status: string }>;
+    expect(records).toMatchObject([{ status: "unknown" }]);
+    await harness.dispose();
+  });
+
   test("is refused where there is nowhere durable to record it", async () => {
     const computer = fakeComputer();
     const harness = await createPluginHarness([

package/src/protocol.ts

@@ -108,6 +108,20 @@ export type ComputerPhase = (typeof COMPUTER_PHASES)[number];
 
 export const COMPUTER_UPDATE_MESSAGE_PREFIX = "Updating the Computer: ";
 
+/**
+ * What the Computer card promises a first-ever cold provision will take, as
+ * copy and as the number that copy means.
+ *
+ * The number is here rather than in the card because a provider's `open`
+ * deadline has to outlast it: a wake that takes exactly as long as the product
+ * promised must not abort on our own clock and reach the User as a broken
+ * Computer. The provider Package's test asserts that relationship, so neither
+ * side can drift alone.
+ */
+export const COMPUTER_COLD_PROVISION_EXPECTATION_MS = 180_000;
+export const COMPUTER_COLD_PROVISION_EXPECTATION =
+  "This usually takes 2-3 minutes";
+
 /** Extracts the provider's update phase label without coupling to a provider. */
 export function computerUpdateLabelV1(
   message: string | undefined,