mandala-computer-mcp 0.1.0 → 0.3.0

package/dist/tools/computers.js

@@ -1,47 +1,14 @@
 import { z } from 'zod';
-import { CancelledError, isTransientForPoll, MoveRequiredError, NotFoundError, RateLimitError, } from '../errors.js';
-import { describe, guarded, incompleteWarning, json, refused, said, unwrapComputer, withoutCredentials, } from '../format.js';
+import { CancelledError, ConflictError, isTransientForPoll, MoveRequiredError, NotFoundError, } from '../errors.js';
+import { describe, guarded, incompleteWarning, json, nothingAdmitted, refused, said, unwrapComputer, withoutCredentials, } from '../format.js';
 import * as P from '../paths.js';
+import { heartbeat, POLL_MS, pollDelay, sleep } from '../poll.js';
 const idArg = {
     computer_id: z
         .string()
         .optional()
         .describe('Which computer. Defaults to the one selected with use_computer.'),
 };
-/**
- * A pause that ends early when the caller gives up.
- *
- * The wait loops check the signal at the top of each turn, so a sleep that
- * ignored it would still hold a cancelled call for its remaining seconds.
- */
-const sleep = (ms, signal) => new Promise((resolve) => {
-    if (signal?.aborted)
-        return resolve();
-    const t = setTimeout(done, ms);
-    function done() {
-        clearTimeout(t);
-        signal?.removeEventListener('abort', done);
-        resolve();
-    }
-    signal?.addEventListener('abort', done, { once: true });
-});
-/** How long these loops leave between polls. */
-const POLL_MS = 2_000;
-/**
- * The same interval, unless the platform asked for longer.
- *
- * A 429 is the one failure that says how long to wait, and
- * {@link isTransientForPoll} now polls through it — so a loop that ignored
- * `Retry-After` and asked again in two seconds would be spending a rate limit
- * to discover it was still rate limited. The floor stays {@link POLL_MS}: the
- * header can say zero, and a poll loop with no interval is a request storm.
- *
- * Only reached from a failed poll, which is why it takes the error rather than
- * living in {@link sleep}: an ordinary turn has nothing to honour.
- */
-const pollDelay = (err) => err instanceof RateLimitError && err.retryAfterMs !== undefined
-    ? Math.max(POLL_MS, err.retryAfterMs)
-    : POLL_MS;
 /**
  * The answer to a wait the caller ended.
  *
@@ -82,8 +49,15 @@ const movesOf = (body) => {
     const moves = list.filter((row) => row !== null && typeof row === 'object' && !Array.isArray(row));
     return { moves, dropped: list.length - moves.length };
 };
-/** What arrived where a list was expected, for a refusal that names it. */
-const shapeOf = (v) => v === undefined ? 'no body at all' : v === null ? 'null' : typeof v;
+/**
+ * What arrived where a list was expected, for a refusal that names it.
+ *
+ * A list is called a list. `typeof []` is `'object'`, and the usage refusal is
+ * reached BY an array — its guard rejects one explicitly — so without this it
+ * reports a body that arrived as an "object where the totals object goes",
+ * which is a contradiction in the sentence a model has to act on.
+ */
+const shapeOf = (v) => v === undefined ? 'no body at all' : v === null ? 'null' : Array.isArray(v) ? 'a list' : typeof v;
 /**
  * The resize refusal that is an OFFER, turned into a next step (OPL-3775).
  *
@@ -127,12 +101,34 @@ const moveLine = (m) => `${m.computer_id}: ${m.state}${m.live ? ' (running)' : '
  * that could not be reached and comes right when it comes back, `unmetered` is a
  * host running a daemon older than the meter, and telling a caller to wait for
  * that one is advice that never comes true.
+ *
+ * EVERY DIMENSION THE PLATFORM PRICES IS IN THE LINE. This sentence is what a
+ * model reads before it acts on cost, and a dimension the account is billed on
+ * that appears only in the JSON underneath is a figure nobody weighs. Two were
+ * missing: `ram_gb_hours`, although the tool's own description promises hours
+ * "weighted by cores and memory", and `snapshot_gb_months`, which the API
+ * reference calls the unit snapshots are priced in — the figure that explains
+ * the bill
+ * of an account holding many durable snapshots and running almost nothing.
+ *
+ * The `_hours` twins of the two `_months` figures are deliberately NOT here.
+ * `disk_gb_hours` and `snapshot_gb_hours` are the same integral in the unit the
+ * platform does not price, so printing both spellings would double the length
+ * of the line to say each thing twice. Add to this line when the platform
+ * prices something new, not when it reports something new.
+ *
+ * Zeroes are printed rather than omitted, like every other figure here: an
+ * account that ran nothing weighted by memory metered zero, and a clause that
+ * disappears makes that indistinguishable from a platform that did not send the
+ * figure at all — the distinction `get_usage` already refuses a missing totals
+ * object in order to keep.
  */
 const usageLine = (u) => {
     const t = u.usage ?? {};
     const window = u.from && u.to ? `${u.from} to ${u.to}` : 'this billing period';
-    const head = `${t.vcpu_hours ?? 0} vCPU-hours, ${t.run_hours ?? 0} running hours and ` +
-        `${t.disk_gb_months ?? 0} GB-months of disk over ${window}.`;
+    const head = `${t.vcpu_hours ?? 0} vCPU-hours, ${t.ram_gb_hours ?? 0} GB-hours of RAM, ` +
+        `${t.run_hours ?? 0} running hours, ${t.disk_gb_months ?? 0} GB-months of disk ` +
+        `and ${t.snapshot_gb_months ?? 0} GB-months of snapshots over ${window}.`;
     const short = [
         u.degraded && 'a hypervisor could not be reached (retry — this one clears)',
         u.unmetered &&
@@ -180,6 +176,16 @@ const finishedMove = (id, m) => {
     return refused(`The move of ${id} stopped being watched, so we cannot say whether it finished.${detail} Read ` +
         `get_computer to see which size it is at now before doing anything else.`, m);
 };
+/**
+ * What follows an acknowledged power action, where anything does. A start is
+ * the one whose "ok" is furthest from "usable": the VM is booting or resuming
+ * and the desktop inside it answers later, which is the gap the second line of
+ * the server instructions exists for.
+ */
+const POWER_NEXT = {
+    start: ' wait_for_computer with until="guest" is what says when the desktop is answering.',
+    restart: ' wait_for_computer with until="guest" is what says when the desktop is back.',
+};
 const POWER_DESCRIPTIONS = {
     start: 'Boot a computer, or resume a suspended one — a resume restores the saved session, same processes and windows, in about a second.',
     stop: 'Shut a computer down: the guest is asked, and given time to do it. Discards a saved session if there is one. The disk is kept. `force` pulls the power instead, for a guest that will not come down on its own.',
@@ -192,7 +198,15 @@ export const registerComputers = (server, session, opts) => {
         description: 'The base images a computer can be created from — name, OS, and the default CPU, RAM and disk each one implies.',
         inputSchema: {},
         annotations: { readOnlyHint: true },
-    }, (_args, extra) => guarded(async () => json(await session.api.with(extra.signal).json('GET', P.TEMPLATES))));
+    }, (_args, extra) => guarded(async () => {
+        const { items, incomplete } = await session.api.with(extra.signal).listing(P.TEMPLATES);
+        if (items === undefined || items === null) {
+            return refused('The platform did not return a template catalogue. Retry list_templates.');
+        }
+        return incomplete === null
+            ? json(items)
+            : said(incompleteWarning('templates', incomplete).trimEnd(), items);
+    }));
     server.registerTool('list_sizes', {
         title: 'List sizes',
         description: `The named sizes a computer can be launched at — each a template plus a CPU/RAM/disk shape. These are the shapes the platform keeps pre-booted, so ${opts.lifecycle ? 'create_computer with a `size`' : 'a create naming a `size`'} is typically answered in about a second where a custom shape boots cold. ` +
@@ -202,15 +216,28 @@ export const registerComputers = (server, session, opts) => {
     }, (_args, extra) => guarded(async () => json(await session.api.with(extra.signal).json('GET', P.SIZES))));
     server.registerTool('list_computers', {
         title: 'List computers',
-        description: 'Every computer on this account. Desktop credentials are deliberately not included — use get_desktop_url for those.',
+        description: "Every computer on this account that exists or may exist. Desktop credentials are deliberately not included — use get_desktop_url for those. Read `state` before acting on a row: it is the platform's record of whether the machine exists, which is a different question from `status`, what its host says the guest is doing. A row reading `deleting` is on its way out and is not one to bind, start or wait for, and one reading `unreachable` is a row served from the record because the host did not answer — the computer is most likely fine, but nothing only its host knows is on it, `status` included. The two terminal states are not here at all: `deleted` and `lost` come back only when asked for with `state`.",
         inputSchema: {
             allow_partial: z
                 .boolean()
                 .optional()
                 .describe('Accept a short list when a hypervisor cannot be reached, instead of the 503 the platform answers by default. The answer then says it is short — a short list reads exactly like the missing computers were deleted.'),
+            // The control plane's own record, not the guest's (OPL-4554).
+            // Read where the listing is assembled and never forwarded to a host, so
+            // a filtered listing is as complete as an unfiltered one.
+            //
+            // Said in the description rather than assumed: omitting this is NOT
+            // "every computer". `deleted` and `lost` are terminal and withheld from
+            // an unfiltered listing, so this parameter is the only way a caller ever
+            // sees one — which is the question somebody asks when a computer they
+            // remember is not in the list.
+            state: z
+                .enum(['live', 'unreachable', 'deleting', 'deleted', 'lost'])
+                .optional()
+                .describe("Only computers the platform's own record puts in this state — a different question from what the machine is doing, which is `status`. 'live': its host lists it. 'unreachable': its host did not answer THIS request, so the row is the identity on record and not what the machine says; the computer is most likely fine. 'deleting': a delete was sent and not answered yet. 'deleted' and 'lost' are terminal, and asking here is the ONLY way to see one — an unfiltered listing is live, unreachable and deleting, so a computer missing from it may still have a record."),
         },
         annotations: { readOnlyHint: true },
-    }, ({ allow_partial }, extra) => guarded(async () => {
+    }, ({ allow_partial, state }, extra) => guarded(async () => {
         // listing, not json: with allow_partial the platform will hand over an
         // inventory it knows is short, and says so in X-GC-Incomplete. Reading
         // the body and dropping the header turns "here is part of the fleet"
@@ -218,7 +245,7 @@ export const registerComputers = (server, session, opts) => {
         const { items, incomplete } = await session.api
             .with(extra.signal)
             .listing(P.COMPUTERS, {
-            query: { allow_partial: allow_partial ? 1 : undefined },
+            query: { allow_partial: allow_partial ? 1 : undefined, state },
         });
         // Checked rather than asserted. `listing<unknown[]>` is a claim about
         // what the platform sends, not a guarantee — a proxy or a future
@@ -262,6 +289,16 @@ export const registerComputers = (server, session, opts) => {
             if (incomplete !== null) {
                 return said(`${warning}No computers came back from the part of the fleet that answered. This is NOT an empty account — do not create a computer on the strength of it. Retry in a moment.`);
             }
+            // A filtered listing that came back empty is a fact about the FILTER,
+            // and the sentence below is a fact about the account. Saying the
+            // account is empty because nothing is `deleted` is the same
+            // duplicate-create the incomplete branch above guards against,
+            // arrived at from a third direction — and this one is silent, since
+            // the platform answers a filter that matches nothing exactly as it
+            // answers an account with nothing in it.
+            if (state) {
+                return said(`${warning}No computers on this account are ${state}. Other computers may exist — this listing asked only for that state. Call list_computers without \`state\` to see the account.`);
+            }
             // Named only when it is there to call. Under MANDALA_NO_LIFECYCLE
             // create_computer is not registered, and this is the one place the
             // name reached the model at RUN time rather than in a description —
@@ -290,6 +327,15 @@ export const registerComputers = (server, session, opts) => {
         inputSchema: {
             computer_id: z.string().describe('The id from list_computers.'),
         },
+        // No readOnlyHint — this is not a pure read, so the hint would overclaim —
+        // but destructiveHint set, because the spec defaults it to TRUE once
+        // readOnlyHint is absent and this destroys nothing (OPL-4516). Without it,
+        // waiting for a machine to finish booting asks the operator whether
+        // destructive updates may be performed.
+        //
+        // Idempotent: asking again gives the same answer, and a host gating
+        // retry-of-a-timed-out-call on this flag should not refuse.
+        annotations: { destructiveHint: false, idempotentHint: true },
     }, ({ computer_id }, extra) => guarded(async () => {
         const selectionVersion = session.beginSelection(computer_id);
         try {
@@ -306,10 +352,48 @@ export const registerComputers = (server, session, opts) => {
             if (!session.bindIfCurrent(c.id ?? computer_id, c.resolution, selectionVersion)) {
                 return refused(`${c.id ?? computer_id} was deleted while it was being selected. The session selection was not changed.`);
             }
-            return said(`Selected ${describe(c)}. Later calls need no computer_id.` +
-                (c.status === 'running'
-                    ? ''
-                    : `\n\nIt is ${c.status ?? 'not running'} — start_computer before driving it.`), withoutCredentials(c));
+            // The advice has to know what the two waits know, or it sends a model
+            // to start a computer that is already starting — the whole of
+            // OPL-4631, in the one place a model acts on the sentence soonest.
+            //
+            // STATUS FIRST, THEN THE POOL, and that order is the correction: the
+            // first cut asked only about the pool, so it told a caller to start a
+            // build-failed computer, a half-removed one and a build still running
+            // — three machines the platform refuses to start at all. A
+            // reservation is only ever the difference between "start it" and
+            // "wait for it" on a machine that COULD be started.
+            const advice = () => {
+                const status = c.status ?? 'not running';
+                if (status === 'running')
+                    return '';
+                // Terminal, and each with the remedy that actually applies.
+                if (status === 'build-failed') {
+                    return `\n\nIts disk was never finished — delete_computer and build it again. Nothing else clears this.`;
+                }
+                if (status === 'half-removed') {
+                    return `\n\nIts files were partly removed: it cannot be started or used again. delete_computer is what clears it.`;
+                }
+                // A disk copy in progress cannot be started either, and a memory
+                // fork resumes itself at the end of one — so both wait, and only
+                // the reason differs.
+                if (status === 'building') {
+                    return c.running_ram_mb
+                        ? `\n\nIt is still building, and its RAM is already reserved — it will come up on its own when the copy finishes. wait_for_computer.`
+                        : `\n\nIt is still building — wait_for_computer, then start_computer once the copy has finished.`;
+                }
+                // Stopped or suspended: the one place a start is the right advice,
+                // and only when the platform says it is holding nothing.
+                if (nothingAdmitted(c)) {
+                    return `\n\nIt is ${status} — start_computer before driving it.`;
+                }
+                if (c.running_ram_mb !== undefined) {
+                    return `\n\nIt is ${status}, and its start has already been admitted — wait_for_computer, not start_computer.`;
+                }
+                // The pool was not reported, so neither answer is established. Say
+                // that, rather than prescribing one of them as though it were.
+                return `\n\nIt is ${status}, and this host did not say whether a start is under way — wait_for_computer, which starts nothing, says which it is.`;
+            };
+            return said(`Selected ${describe(c)}. Later calls need no computer_id.${advice()}`, withoutCredentials(c));
         }
         finally {
             session.endSelection(computer_id);
@@ -325,9 +409,23 @@ export const registerComputers = (server, session, opts) => {
     // parameter their route does not read.
     const power = (action, computer_id, extra, opts = {}) => guarded(async () => {
         const id = session.resolve(computer_id);
-        const c = unwrapComputer(await session.api
+        const body = await session.api
             .with(extra.signal)
-            .json('POST', P.computerAction(id, action), { query: opts.query }));
+            .json('POST', P.computerAction(id, action), { query: opts.query });
+        const c = unwrapComputer(body);
+        // What the platform documents for all four is an Ack — `{ok: true}` and
+        // nothing else — and that is what it sends. Formatting it as a computer
+        // record answered `suspend: (unnamed) · (no id) · unknown`, which the
+        // first agent to dogfood the skill (OPL-3914) read as a suspend that had
+        // not worked. The id is the one we sent, so say that; a record, should
+        // the platform ever start returning one, is described as before.
+        //
+        // Stripped of credentials on this branch too, and not only on the record
+        // one: the test for "is this an Ack" is the absence of an id, and a body
+        // with no id is not thereby a body with no `vnc`.
+        if (!c.id) {
+            return said(`${action}: ok — ${id}.${POWER_NEXT[action] ?? ''}${opts.note ?? ''}`, withoutCredentials(c));
+        }
         session.noteResolution(id, c.resolution);
         return said(`${action}: ${describe(c)}${opts.note ?? ''}`, withoutCredentials(c));
     });
@@ -412,7 +510,7 @@ export const registerComputers = (server, session, opts) => {
     }));
     server.registerTool('move_computer', {
         title: 'Move a computer to a host that can run a bigger size',
-        description: 'Grow a computer past what its current host can run, by moving it to another host in the same region first. Only call this after update_computer has refused a resize and said a move is possible: it is the second half of that refusal and nothing else. THIS MOVES THE MACHINE TO DIFFERENT HARDWARE and copies its disk to get there — say so before you call it. The computer must be STOPPED (suspended is not stopped here: a saved desktop only loads on the host that wrote it, so resume and stop it, or discard the session). One move runs per account at a time. Everything is decided again when this runs, so it can still refuse. Waits for the outcome and reports it; list_moves reads it if the wait runs out.',
+        description: 'Grow a computer past what its current host can run, by moving it to another host in the same region first. Only call this after update_computer has refused a resize and said a move is possible: it is the second half of that refusal and nothing else. THIS MOVES THE MACHINE TO DIFFERENT HARDWARE and copies its disk to get there — say so before you call it. The computer must be STOPPED (suspended is not stopped here: a saved desktop only loads on the host that wrote it, so resume and stop it, or discard the session). One move runs per account at a time. Everything is decided again when this runs, so it can still refuse. Waits for the outcome and reports it, reporting progress while it waits so a client that sends a progressToken and sets resetTimeoutOnProgress can hold the request open; list_moves reads the outcome if the wait runs out, and is the answer for a client that cannot.',
         inputSchema: {
             ...idArg,
             // Required, unlike every other field here, and unlike the same argument
@@ -466,6 +564,11 @@ export const registerComputers = (server, session, opts) => {
         // and it is kept because it is the only description of this move that
         // does not depend on a later read succeeding.
         const started = (await api.json('POST', P.computerAction(id, 'move'), { body }));
+        // The keepalive. A disk crossing between two hosts is minutes, and a
+        // tool that says nothing for minutes is one a client cancels — see
+        // heartbeat, and OPL-4579 for the wait that proved it.
+        const beat = heartbeat(extra, server.server);
+        await beat(`Moving ${id} — the platform has accepted it.`);
         let last = started;
         let blocked;
         while (!untilDeadline.aborted) {
@@ -487,6 +590,7 @@ export const registerComputers = (server, session, opts) => {
                     if (untilDeadline.aborted)
                         break;
                     blocked = err.message;
+                    await beat(`Moving ${id} — the platform could not be asked: ${blocked}`);
                     await sleep(POLL_MS, signal);
                     continue;
                 }
@@ -500,6 +604,7 @@ export const registerComputers = (server, session, opts) => {
                         `was the poll failing, not the move. list_moves says where it got to.`, last);
                 }
                 blocked = err instanceof Error ? err.message : String(err);
+                await beat(`Moving ${id} — the platform could not be asked: ${blocked}`);
                 await sleep(pollDelay(err), signal);
                 continue;
             }
@@ -509,6 +614,7 @@ export const registerComputers = (server, session, opts) => {
             // not be asked rather than claiming a deletion nothing established.
             if (!table) {
                 blocked = `GET /moves answered with ${shapeOf(raw?.moves)}, not a list of moves`;
+                await beat(`Moving ${id} — the platform could not be asked: ${blocked}`);
                 await sleep(POLL_MS, signal);
                 continue;
             }
@@ -526,6 +632,7 @@ export const registerComputers = (server, session, opts) => {
             // instead of claiming a deletion nothing showed.
             if (!mine && table.dropped) {
                 blocked = `GET /moves answered with ${table.dropped} unreadable row(s), so this move may be among them`;
+                await beat(`Moving ${id} — the platform could not be asked: ${blocked}`);
                 await sleep(POLL_MS, signal);
                 continue;
             }
@@ -536,6 +643,7 @@ export const registerComputers = (server, session, opts) => {
             last = mine;
             if (!mine.live)
                 return finishedMove(id, mine);
+            await beat(`Moving ${id} — ${mine.state}${mine.detail ? `: ${mine.detail}` : ''}`);
             await sleep(POLL_MS, signal);
         }
         return refused(blocked
@@ -601,7 +709,7 @@ export const registerComputers = (server, session, opts) => {
     }));
     server.registerTool('wait_for_computer', {
         title: 'Wait for a computer to be ready',
-        description: 'Poll until the computer is running, or until the software inside it answers. Use "guest" before exec, files or windows, and before expecting a screenshot to show a desktop rather than a boot screen.',
+        description: 'Poll until the computer is running, or until the software inside it answers. Use "guest" before exec, files or windows, and before expecting a screenshot to show a desktop rather than a boot screen. Reports progress while it waits, so a client that sends a progressToken and sets resetTimeoutOnProgress can hold the request open; a client that cannot should lower timeout_s and call again rather than watch its own default timeout cancel the wait.',
         inputSchema: {
             ...idArg,
             until: z
@@ -610,6 +718,15 @@ export const registerComputers = (server, session, opts) => {
                 .describe('"running" is the hypervisor reporting the VM up. "guest" is the software inside it answering, which is what exec and a painted desktop actually need.'),
             timeout_s: z.number().int().min(5).max(900).default(180),
         },
+        // No readOnlyHint — this is not a pure read, so the hint would overclaim —
+        // but destructiveHint set, because the spec defaults it to TRUE once
+        // readOnlyHint is absent and this destroys nothing (OPL-4516). Without it,
+        // waiting for a machine to finish booting asks the operator whether
+        // destructive updates may be performed.
+        //
+        // Idempotent: asking again gives the same answer, and a host gating
+        // retry-of-a-timed-out-call on this flag should not refuse.
+        annotations: { destructiveHint: false, idempotentHint: true },
     }, ({ computer_id, until, timeout_s }, extra) => guarded(async () => {
         const id = session.resolve(computer_id);
         // timeout_s used to gate only the top of the loop, which bounds how
@@ -627,6 +744,7 @@ export const registerComputers = (server, session, opts) => {
             ? AbortSignal.any([extra.signal, untilDeadline])
             : untilDeadline;
         const api = session.api.with(signal);
+        const beat = heartbeat(extra, server.server);
         let last = 'unknown';
         // Kept so the give-up message can name it. A hypervisor that was
         // unreachable for the whole window is the single most useful thing to
@@ -665,18 +783,37 @@ export const registerComputers = (server, session, opts) => {
                         break;
                     }
                     blocked = err.message;
+                    await beat(`Waiting for ${id} — the platform could not be asked: ${blocked}`);
                     await sleep(POLL_MS, signal);
                     continue;
                 }
                 if (!isTransientForPoll(err))
                     throw err;
                 blocked = err instanceof Error ? err.message : String(err);
+                await beat(`Waiting for ${id} — the platform could not be asked: ${blocked}`);
                 await sleep(pollDelay(err), signal);
                 continue;
             }
             blocked = undefined;
             session.noteResolution(id, c.resolution);
             last = c.status ?? 'unknown';
+            // ONE beat per turn, and this is not it when a guest probe is about to
+            // run. Beating here and again in the probe's failure branch sent two
+            // notifications per poll — and because the two lines DIFFER, each read
+            // as news to the throttle and neither was ever held, so the steady
+            // state of the commonest long wait was twice the per-poll rate the
+            // interval exists to avoid (/code-review).
+            //
+            // Fixed by making the two say the SAME thing rather than by silencing
+            // this one, which was the first attempt and dropped the wrong half of
+            // the pair (/code-review again). The probe below is the longest call
+            // in the loop — an undici header timeout or a proxy 524 can hold it
+            // for minutes — so the beat that must survive is the one IN FRONT of
+            // it. The 409 branch repeats this line and the throttle holds it; a
+            // probe that fails some other way says so, which is news and goes out.
+            await beat(until === 'guest' && last === 'running'
+                ? `Waiting for ${id} — running; asking the guest.`
+                : `Waiting for ${id} — ${last}.`);
             if (last === 'build-failed') {
                 // `refused`, for the reason `cancelled` is: the wait never reached
                 // what it was told to wait for, and this one never will. A caller
@@ -695,12 +832,32 @@ export const registerComputers = (server, session, opts) => {
                         : ' — the platform gave no reason';
                 return refused(`Build failed${why}. This does not resolve on its own.`, withoutCredentials(c));
             }
+            // Its files were partly removed and its disk is gone: the platform
+            // refuses to start or use it, and only deleting it again clears it.
+            // Waiting spent the whole budget and then reported "last seen
+            // half-removed", which is the state the caller passed in (Codex
+            // review). Not qualified by the pool: nothing can be admitted for a
+            // machine with no disk.
+            if (last === 'half-removed') {
+                return refused(`${id} is half-removed: its files were partly removed, it cannot be started or used again, and delete_computer is what clears it.`, withoutCredentials(c));
+            }
             // Neither of the next two resolves on its own, so spinning on either
             // burns the whole timeout waiting for something nobody is going to do.
-            if (last === 'suspended') {
+            //
+            // Unless somebody is. `status` is read from the guest process, so a
+            // start that has been ADMITTED reads as `stopped` while it boots and
+            // as `suspended` while it resumes — the session record is spent only
+            // on the way out of a start that worked. Refusing there tells a model
+            // to call start_computer on a computer that is already starting, and
+            // the obvious next thing it does is start it a second time.
+            //
+            // nothingAdmitted is the platform's own word for idle, and it is
+            // absent-aware: a host that did not answer has not said nothing is
+            // coming, so the wait goes on rather than refusing (OPL-4631).
+            if (last === 'suspended' && nothingAdmitted(c)) {
                 return refused(`${id} is suspended, and that state does not clear by itself. start_computer resumes the saved session in about a second.`, withoutCredentials(c));
             }
-            if (last === 'stopped') {
+            if (last === 'stopped' && nothingAdmitted(c)) {
                 return refused(`${id} is stopped. start_computer boots it.`, withoutCredentials(c));
             }
             if (last === 'running') {
@@ -730,11 +887,34 @@ export const registerComputers = (server, session, opts) => {
                             break;
                         }
                         blocked = err.message;
+                        await beat(`Waiting for ${id} — running; the platform could not be asked: ${blocked}`);
                         await sleep(POLL_MS, signal);
                         continue;
                     }
                     if (!isTransientForPoll(err))
                         throw err;
+                    // What actually refused, rather than one sentence for every
+                    // failure. A 409 IS the guest not being up yet — that is the
+                    // probe working, and it repeats the line beat in front of the
+                    // probe so the throttle holds it. A 503 is a hypervisor nobody
+                    // can reach and a transport abort is neither: saying "the guest
+                    // is not answering" over those tells the person watching the log
+                    // the one thing this channel exists to get right.
+                    //
+                    // And it SETS `blocked`, which it never did — not before this
+                    // change and not after the first version of it. A wait that spent
+                    // its whole window failing the probe on 503s gave up saying "was
+                    // last seen running" and named nothing, while the progress
+                    // channel had been reporting the hypervisor the entire time: the
+                    // same contradiction this comment set out to remove, pointed the
+                    // other way (/code-review). Deliberately not for the 409, where
+                    // the platform did answer and `blocked` would be a lie about it.
+                    if (!(err instanceof ConflictError)) {
+                        blocked = err instanceof Error ? err.message : String(err);
+                    }
+                    await beat(err instanceof ConflictError
+                        ? `Waiting for ${id} — running; asking the guest.`
+                        : `Waiting for ${id} — running; the platform could not be asked: ${blocked}`);
                     // The guest probe's own failure decides this turn's interval, for
                     // pollDelay's reason. The ordinary path below keeps POLL_MS.
                     await sleep(pollDelay(err), signal);
@@ -761,7 +941,41 @@ export const registerComputers = (server, session, opts) => {
                 .default(false)
                 .describe('Return the full-control URL instead of the watch-only one. It carries a token that is root-equivalent on that machine — the watch-only socket has input dropped by the platform, not merely hidden by the client.'),
         },
-        annotations: { readOnlyHint: true },
+        // NO readOnlyHint, for a reason distinct from both the ones already in
+        // this codebase: the SPEND rule (OPL-4499 — cursor_position and read_file
+        // resume a suspended computer) and the CONSUMING-READ rule (exec_poll,
+        // poll_events and wait_for_event advance a cursor no later call can
+        // re-read, and wait_for_file_change also configures). This is a fourth,
+        // decided in OPL-4505 and written here so it is not re-litigated.
+        //
+        // `GET /computers/:id` modifies nothing and spends nothing, so under the
+        // rule as first written the hint was accurate. What the rule was missing
+        // is that the annotation does not only describe the route: clients treat
+        // it as licence to call without asking, which is the reading input.ts
+        // already states beside `cursor_position`. This call hands back a
+        // credential — with `control: true`, one that is root-equivalent on the
+        // machine — so under a host that auto-approves read-only tools, a model
+        // could pass out control of a desktop with nobody asked. The description
+        // says "these are credentials in a link", but a description is not a gate.
+        //
+        // So, added to the list: the hint is withheld from a tool that returns a
+        // CREDENTIAL-EQUIVALENT. This is the only one today; the next tool that
+        // hands back a token, a signed URL or a key belongs here with it rather
+        // than in an argument about whether a read is a read.
+        //
+        // Credential-equivalent, and deliberately not "sensitive". A screenshot
+        // of a desktop with a password on it is sensitive, and it is not
+        // something this call revealed the keys to — a rule drawn that wide would
+        // take the hint off every read there is, which is why `screenshot`,
+        // `read_clipboard` and `list_windows` keep theirs.
+        //
+        // The other two flags are set rather than left to default, for the reason
+        // `cursor_position` sets them: the spec defaults destructiveHint to TRUE
+        // and idempotentHint to FALSE once readOnlyHint is gone, so leaving them
+        // out would have a host asking whether it may perform destructive updates
+        // in order to read a URL, and refusing to retry a call that is safe to
+        // retry.
+        annotations: { destructiveHint: false, idempotentHint: true },
     }, ({ computer_id, control }, extra) => guarded(async () => {
         const id = session.resolve(computer_id);
         const c = unwrapComputer(await session.api.with(extra.signal).json('GET', P.computer(id)));
@@ -874,7 +1088,7 @@ export const registerComputers = (server, session, opts) => {
         return;
     server.registerTool('create_computer', {
         title: 'Create a computer',
-        description: 'Build a new cloud desktop and select it for this session. Creating and running a computer costs money on this account.',
+        description: 'Build a new cloud desktop and select it for this session. Creating and running a computer costs money on this account. Continue an image preparation refusal only as its result instructs, retaining all original create arguments, including template, and adding the returned preparation token as an argument. This token is not a create idempotency key. Stop after success; never automatically replay after a lost or ambiguous response.',
         inputSchema: {
             name: z.string().optional().describe('A label. The platform picks one if you do not.'),
             size: z
@@ -885,6 +1099,11 @@ export const registerComputers = (server, session, opts) => {
                 .string()
                 .optional()
                 .describe('From list_templates, e.g. "base" for Linux/Xfce. Defaults to the platform default.'),
+            template_transfer: z
+                .string()
+                .refine((value) => value.trim().length > 0, 'template_transfer must not be blank')
+                .optional()
+                .describe('Nonblank opaque token from an image preparation refusal; preserve it exactly. When the result permits continuation, keep all original create arguments including template, add this token, and wait for the supplied delay. Requires template and cannot be combined with size. Not a create idempotency key: stop after success and never automatically replay after a lost or ambiguous response.'),
             cpu: z.number().int().min(1).optional(),
             ram_mb: z.number().int().min(512).optional(),
             disk_gb: z
@@ -901,9 +1120,48 @@ export const registerComputers = (server, session, opts) => {
         },
         annotations: { destructiveHint: false, openWorldHint: true },
     }, (args, extra) => guarded(async () => {
-        const c = unwrapComputer(await session.api
-            .with(extra.signal)
-            .json('POST', P.COMPUTERS, { body: P.createBody(args) }));
+        let data;
+        try {
+            data = await session.api
+                .with(extra.signal)
+                .json('POST', P.COMPUTERS, { body: P.createBody(args) });
+        }
+        catch (error) {
+            const body = error instanceof ConflictError
+                ? error.body
+                : undefined;
+            if (body?.code === 'template_image_preparing' && error instanceof ConflictError) {
+                const preparation = body.preparation;
+                const state = preparation && typeof preparation === 'object'
+                    ? preparation.state
+                    : undefined;
+                const tokenPresent = typeof body.template_transfer === 'string' &&
+                    body.template_transfer.trim().length > 0;
+                const originalSupportsContinuation = typeof args.template === 'string' &&
+                    args.template.trim().length > 0 &&
+                    args.size === undefined;
+                const canContinue = originalSupportsContinuation &&
+                    tokenPresent &&
+                    typeof state === 'string' &&
+                    ['preparing', 'copying', 'ready'].includes(state) &&
+                    error.retryAfterMs !== undefined;
+                const advice = state === 'failed'
+                    ? 'Image preparation failed. Inspect preparation.error before deciding what to do next; do not automatically wait or retry.'
+                    : canContinue
+                        ? `Wait ${error.retryAfterMs} milliseconds, then repeat create_computer with all original identical arguments, including template, and this template_transfer token. Stop after success.`
+                        : !originalSupportsContinuation
+                            ? 'The original create must include a nonblank template and omit size to continue with this token. Inspect the original request and preparation details; do not automatically wait or retry.'
+                            : 'The response does not supply a known continuation state, usable token, and valid delay. Inspect the preparation details; do not automatically wait or retry.';
+                return refused(`${typeof body.error === 'string' ? body.error : 'The template image is not available for this create.'} No computer has been created. ${advice} The token is not a create idempotency key. Never automatically replay after a lost or ambiguous response.`, {
+                    code: body.code,
+                    template_transfer: body.template_transfer,
+                    preparation,
+                    retry_after_ms: error.retryAfterMs,
+                });
+            }
+            throw error;
+        }
+        const c = unwrapComputer(data);
         // Selection and the sentence claiming it are the same decision. Bound
         // conditionally and reported unconditionally, a create that came back
         // without an id left this session pointing at whatever it held before
@@ -920,7 +1178,9 @@ export const registerComputers = (server, session, opts) => {
         const note = c.start_error
             ? `Created ${describe(c)}, but it did not start: ${c.start_error}\nThe computer exists and is selected. start_computer often works on a second attempt.`
             : `Created and selected ${describe(c)}.`;
-        return said(note, withoutCredentials(c));
+        return said(args.template_transfer === undefined
+            ? note
+            : `${note} Stop retrying this create; the template_transfer token is not a create idempotency key.`, withoutCredentials(c));
     }));
     server.registerTool('clone_computer', {
         title: 'Clone a computer',
@@ -968,7 +1228,7 @@ export const registerComputers = (server, session, opts) => {
         // Not fetched on the caller's behalf, which was the tempting shortcut
         // and is the wrong one. A fingerprint read a millisecond before the
         // delete binds the purge to whatever the set is now, not to what anyone
-        // agreed to — and the race checkExpectation exists for is exactly that:
+        // agreed to — and the race the expectation exists for is exactly that:
         // a capture that finishes between the decision and the click, then gets
         // destroyed by a confirmation that predates it.
         const fingerprint = expect?.trim() || undefined;
@@ -1000,8 +1260,32 @@ export const registerComputers = (server, session, opts) => {
             // Unbound BEFORE the rethrow-or-report decision, because it is true
             // either way: whatever this answers, the caller must not be left
             // selected on a computer the platform says is gone.
-            if (!(err instanceof NotFoundError))
+            if (!(err instanceof NotFoundError)) {
+                // The VM is destroyed before snapshots are purged, so a failed
+                // DELETE does not establish whether it survived. Ask once, with
+                // the same account/workspace scope, and preserve the primary error
+                // even if this read fails. Neither error prose nor a lost or
+                // unreachable record proves deletion. The short deadline includes
+                // reading the body; reconciliation must not hold the error hostage
+                // to the transport's much longer foreground-exec allowance.
+                if (!extra.signal.aborted) {
+                    const signal = AbortSignal.any([extra.signal, AbortSignal.timeout(5_000)]);
+                    let absent = false;
+                    try {
+                        const c = unwrapComputer(await session.api.with(signal).json('GET', P.computer(computer_id)));
+                        absent =
+                            c.id === computer_id.trim() && c.state === 'deleted' && c.unreachable !== true;
+                    }
+                    catch (readError) {
+                        absent = readError instanceof NotFoundError;
+                    }
+                    // unbind also drops events and invalidates pending selections
+                    // of this id, while preserving a different selected computer.
+                    if (absent && !signal.aborted)
+                        session.unbind(computer_id);
+                }
                 throw err;
+            }
             session.unbind(computer_id);
             // Reported as a success rather than an error, and deliberately not as
             // a plain "Deleted": a caller retrying cannot be told its snapshots