mandala-computer-mcp 0.1.0 → 0.1.2

package/dist/tools/snapshots.js

@@ -1,13 +1,128 @@
 import { z } from 'zod';
-import { NotFoundError } from '../errors.js';
+import { CancelledError, ConflictError, isTransientForPoll, NotFoundError } from '../errors.js';
 import { describe, guarded, incompleteWarning, json, 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.'),
 };
+const isRow = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+/**
+ * The state a capture that has not finished is in, and the ONLY one the poll
+ * below waits out.
+ *
+ * Waiting for `pending` specifically is the bug the platform's own reference
+ * warns about: `pending` is where a finished capture lands, but replication can
+ * carry it on to `durable` between two polls, so a loop matching the literal
+ * string can watch a small snapshot go past and never match. Every state that
+ * is not this one is a state the snapshot can be restored, cloned and deleted
+ * from.
+ */
+const CAPTURING = 'capturing';
+/**
+ * The states a capture is OVER in, and the reason this is a list of names
+ * rather than "anything but {@link CAPTURING}".
+ *
+ * It is read in one place: the check on the acceptance body, which asks "is
+ * there something to wait for". An answer nobody can classify has to mean YES
+ * there — a 202 whose `state` arrives misspelt, renamed, or under another key
+ * would otherwise read as a snapshot that had landed, and what came back would
+ * be the placeholder: `size_bytes: 0` and an id restore, clone and delete all
+ * 404 on, reported as a snapshot that can be acted on. That is the defect
+ * OPL-4568 removed, reached through a typo instead of an omission and
+ * reinstated by drift this server cannot see. An ABSENT state was already
+ * handled; `"capturin"` is every bit as unreadable and was not.
+ *
+ * The POLL LOOP reads the opposite way round and is right to — a row it cannot
+ * classify is not a claim, so it asks again rather than deciding, where the
+ * alternative is a wait that ends on a state nobody could read. Both directions
+ * are the safe one for where they sit, and they are safe in opposite
+ * directions.
+ *
+ * The three names the platform documents beside `capturing`. `deleting` is
+ * among them because a row in it is a row the capture is over for, whatever
+ * else is true of it. A platform that invents a fourth costs one listing: the
+ * poll finds the row already there, carrying whatever state it really has, and
+ * returns it at once. So this list going stale costs a round trip, and the
+ * other spelling costs the bug.
+ *
+ * The TypeScript SDK settled here first, under `acceptedCapture` (OPL-4568,
+ * `33c47b3`).
+ */
+const LANDED = ['pending', 'durable', 'deleting'];
+/**
+ * The state the platform marks a snapshot with once a deletion has detached its
+ * dependents and is removing the stored objects.
+ *
+ * Left out of a bare listing, because a half-deleted snapshot is not one you can
+ * restore or clone — so a poll that wants to SEE one has to ask for
+ * `include=unfinished`. There is no state that means deleted: the row going is
+ * the deletion having finished, and a row that stays in this state is one that
+ * stalled.
+ */
+const DELETING = 'deleting';
+const why = (err) => (err instanceof Error ? err.message : String(err));
+/**
+ * One listing, and what it says about `sid`.
+ *
+ * Asked WITHOUT `allow_partial`, deliberately: the platform then answers a short
+ * inventory with a 503, which arrives here as a failure to ride out rather than
+ * as a 200 whose missing rows could be read as an answer. The `incomplete`
+ * check below is the second line of that defence, for a deployment that sends
+ * the header anyway.
+ */
+const snapshotTurn = async (api, sid, unfinished) => {
+    let items;
+    let incomplete = null;
+    try {
+        ({ items, incomplete } = await api.listing(P.SNAPSHOTS, {
+            query: { include: unfinished ? 'unfinished' : undefined },
+        }));
+    }
+    catch (err) {
+        if (err instanceof CancelledError)
+            return { kind: 'cancelled', why: why(err) };
+        if (!isTransientForPoll(err))
+            return { kind: 'broken', why: why(err) };
+        return { kind: 'blocked', why: why(err), after: pollDelay(err) };
+    }
+    if (!Array.isArray(items)) {
+        const got = items === undefined ? 'no body at all' : items === null ? 'null' : typeof items;
+        return { kind: 'blocked', why: `GET /snapshots answered with ${got}, not a list of snapshots` };
+    }
+    if (incomplete !== null) {
+        return {
+            kind: 'blocked',
+            why: 'GET /snapshots answered short — a hypervisor did not report, so a row missing from it establishes nothing',
+        };
+    }
+    const row = items.find((r) => isRow(r) && r.id === sid);
+    if (!isRow(row)) {
+        // An unreadable identity could be the target. Only a list whose rows can
+        // all be identified establishes absence; a readable target still wins.
+        if (items.some((r) => !isRow(r) || typeof r.id !== 'string' || !r.id.trim())) {
+            return {
+                kind: 'blocked',
+                why: 'GET /snapshots contained rows without readable ids, so a missing snapshot establishes nothing',
+            };
+        }
+        return { kind: 'absent' };
+    }
+    // A row served from the host cache because its host did not answer. It
+    // carries an id and nothing else — its `state` is last-known or absent — so it
+    // can confirm neither what a capture is doing nor that a deletion has not
+    // finished.
+    if (row.unreachable) {
+        return {
+            kind: 'blocked',
+            why: `the hypervisor holding ${sid} did not answer, so its row could not be read`,
+        };
+    }
+    return { kind: 'row', row };
+};
 /**
  * The sentence in front of a retention window, for the reason every tool here
  * leads with one: the model reads the text, and three integers in a JSON blob
@@ -48,7 +163,7 @@ export const registerSnapshots = (server, session, opts) => {
         : 'The fingerprint binds a purge to the snapshots you were shown, so one that arrived after you looked cannot be swept up in it. This server cannot purge them — it was started with the lifecycle tools withheld — so the count and the size are all this answers.';
     server.registerTool('list_snapshots', {
         title: 'List snapshots',
-        description: 'Every snapshot on this account. `orphaned` means its computer is gone: such a snapshot can still be cloned into a new computer, but cannot be restored, because a restore puts the disk back on a source that no longer exists. Read `state` before acting on a row: a capture still being taken is listed FIRST and is not a snapshot yet — it reads `capturing` and its id begins `cap-`, and restore, clone and delete all fail on one. `pending` is the point at which it can be acted on, and `durable` means it has reached backup storage as well.',
+        description: 'Every snapshot on this account. `orphaned` means its computer is gone: such a snapshot can still be cloned into a new computer, but cannot be restored, because a restore puts the disk back on a source that no longer exists. Read `state` ON EVERY ROW before acting, rather than on the newest one — this is one answer per hypervisor concatenated in a fixed host order that has nothing to do with time, so a capture running on one host routinely appears after finished snapshots from another. A row reading `capturing` is not a snapshot yet: the copy is still being taken and restore, clone and delete all fail on it. It carries the id the finished snapshot will keep, so this is also the route to poll after create_snapshot: the row stops reading `capturing` in place rather than being replaced under another id, and a row that vanishes without ever leaving `capturing` is a capture that failed. `pending` is the point at which it can be acted on, and `durable` means it has reached backup storage as well.',
         inputSchema: {
             computer_id: z
                 .string()
@@ -57,7 +172,7 @@ export const registerSnapshots = (server, session, opts) => {
             include_unfinished: z
                 .boolean()
                 .default(false)
-                .describe('Also return deletions that began and did not finish. They are not usable — their state is "deleting" and nothing can be restored or cloned from one — but they still hold objects and are still billed, so this is the flag to set when the question is about storage rather than about what can be restored.'),
+                .describe('Also return deletions that began and did not finish. They are not usable — their state is "deleting" and nothing can be restored or cloned from one — but they still hold objects and are still billed, so this is the flag to set when the question is about storage rather than about what can be restored. It is also the flag to set when following a deletion: without it a snapshot stuck half-deleted is hidden, and a poll watching for the row to go cannot tell that from one that finished.'),
             allow_partial: z
                 .boolean()
                 .optional()
@@ -108,7 +223,7 @@ export const registerSnapshots = (server, session, opts) => {
         // The filter keeps the unreachable placeholders, and that is not a
         // nicety. A partial listing does not merely omit rows — the platform
         // APPENDS one `{id, unreachable: true}` stub per snapshot it could not
-        // reach, and publicSnapshot drops `computer_id` from such a row because
+        // reach, and the platform drops `computer_id` from such a row because
         // there is no daemon to have said what it belongs to. Filtering on
         // equality therefore deletes precisely the markers that say something
         // is missing, and then reports a count: the confident wrong number
@@ -116,7 +231,7 @@ export const registerSnapshots = (server, session, opts) => {
         //
         // They cannot be attributed to a computer, so keeping them over-reports
         // for this one. That is the trade the platform itself makes and writes
-        // down in lib/hostroute: an extra unreachable row is visible and is
+        // down on the platform side: an extra unreachable row is visible and is
         // corrected by the next complete answer, while a withheld one makes a
         // row vanish mid-outage, which is the failure worth preventing.
         // A filter that was GIVEN and trims to nothing is refused, not dropped.
@@ -161,7 +276,7 @@ export const registerSnapshots = (server, session, opts) => {
     }));
     server.registerTool('create_snapshot', {
         title: 'Snapshot a computer',
-        description: 'Capture a computer so it can be restored or forked later. A disk snapshot is the filesystem; a memory snapshot also saves the running session, so a fork of it comes up with the same processes and windows already open. Name it after the step it is about — that name is what picks it out of the list later.',
+        description: 'Capture a computer so it can be restored or forked later. A disk snapshot is the filesystem; a memory snapshot also saves the running session, so a fork of it comes up with the same processes and windows already open. Name it after the step it is about — that name is what picks it out of the list later. THE CAPTURE OUTLIVES THE REQUEST that starts it: the platform accepts it and copies the disk afterwards, which takes minutes and scales with how much has been written. This waits for the copy to land by default and answers with the finished snapshot; pass wait: false to get the id straight back and poll list_snapshots yourself. Everything that can refuse a capture — no such computer, one already running, a memory snapshot of a computer that is not running, an allowance that will not stretch — is refused by this call, so anything else is a capture that started. A wait reports progress while it runs, so a client that sends a progressToken and sets resetTimeoutOnProgress can hold the request open; a client that cannot should pass wait: false and poll list_snapshots, rather than watch its own default timeout cancel a call while the capture goes on running.',
         inputSchema: {
             ...idArg,
             name: z
@@ -181,22 +296,216 @@ export const registerSnapshots = (server, session, opts) => {
                 .boolean()
                 .default(false)
                 .describe('Include the running session. A memory snapshot is a saved machine, so it only loads back into the shape it came off: resize the computer afterwards and the restore is refused, because the vCPU count and the memory size are part of the state rather than decoration around it. Clone it instead in that case, which restores the disk and boots fresh.'),
+            wait: z
+                .boolean()
+                .default(true)
+                .describe('Wait for the copy to finish, and answer with the snapshot rather than with the placeholder. Set it false to get the id back at once — useful when the capture is a side errand and there is other work to do meanwhile — and then poll list_snapshots for that id, which is what this does for you.'),
+            timeout_s: z
+                .number()
+                .int()
+                .min(5)
+                .max(1800)
+                .default(300)
+                .describe('How long to wait for the capture before handing back and letting you poll. Ignored when wait is false. Giving up on the wait does not stop the capture.'),
         },
-    }, ({ computer_id, name, memory }, extra) => guarded(async () => {
+    }, ({ computer_id, name, memory, wait, timeout_s }, extra) => guarded(async () => {
         const id = session.resolve(computer_id);
-        const res = await session.api
-            .with(extra.signal)
-            .json('POST', P.computerAction(id, 'snapshots'), {
-            body: P.snapshotBody({ memory, name }),
-        });
+        // One deadline for the whole call, armed before the POST, exactly as
+        // move_computer arms its own: timeout_s is a promise about when this
+        // comes back, and a POST left on undici's own five-minute header clock
+        // could break that promise before the poll ever ran. Nothing is armed
+        // when nobody is waiting — a caller who asked for the id and no wait
+        // was promised no deadline, so imposing one would cancel a POST that
+        // was still perfectly capable of starting a capture.
+        const untilDeadline = wait ? AbortSignal.timeout(timeout_s * 1000) : undefined;
+        const signal = !untilDeadline
+            ? extra.signal
+            : extra.signal
+                ? AbortSignal.any([extra.signal, untilDeadline])
+                : untilDeadline;
+        const api = session.api.with(signal);
+        // The 202. Its body is a Snapshot row in `state: "capturing"` — a
+        // placeholder rather than a snapshot, on which restore, clone and delete
+        // all answer 404 until the copy lands (OPL-4562). It is kept whatever
+        // happens next, because it is the only description of this capture that
+        // does not depend on a later read succeeding.
+        let started;
+        try {
+            started = await api.json('POST', P.computerAction(id, 'snapshots'), {
+                body: P.snapshotBody({ memory, name }),
+            });
+        }
+        catch (err) {
+            // The deadline, or the caller, arriving while the POST is in flight.
+            // The generic sentence for this says the request may have been
+            // received and to treat what it would have changed as unknown, which
+            // is true and is not enough here: a capture that started is billable,
+            // takes minutes, and — because the answer that carried its id is the
+            // thing that was lost — cannot be polled for at all. Worse, the
+            // obvious next move is wrong. A second capture while one is running is
+            // refused 409, so a model that simply retries reads that as a failure
+            // on top of a capture that is fine (observed live, OPL-4577).
+            if (err instanceof CancelledError) {
+                return refused(`${why(err)}\n\nA CAPTURE OF ${id} MAY BE RUNNING. What was lost is the answer that carried ` +
+                    `its id, so there is nothing here to poll on — look instead: list_snapshots on ${id} shows ` +
+                    `a row reading "${CAPTURING}" if one started, and that row's id is the one to follow. Do ` +
+                    `not simply call this again; a second capture while one is running is refused, and the ` +
+                    `refusal will be about the capture this call may have started.`);
+            }
+            throw err;
+        }
         // The name read back rather than the one sent, because the interesting
         // case is the one that was not sent: the platform generates
         // "<computer> <timestamp>" when `name` is absent, and that generated
         // name is what a later list_snapshots will show. Saying it here is the
         // difference between a caller that can find this capture again and one
         // that has to go looking for it.
-        const called = typeof res?.name === 'string' && res.name.trim() ? ` as "${res.name}"` : '';
-        return said(`Snapshotted ${id}${memory ? ' with its memory' : ''}${called}.`, res);
+        const called = typeof started?.name === 'string' && started.name.trim() ? ` as "${started.name}"` : '';
+        // Two sentences for the two things that can be true, and keeping them
+        // apart is the whole of OPL-4568. "Snapshotted vm-1" over a 202 is the
+        // defect: it is said before a byte has been copied, and a model reads it
+        // as a snapshot it may now restore. So the past tense is reserved for a
+        // capture this call watched land, and everything that hands back with
+        // the copy still running leads with `startedLine` instead.
+        const took = `Snapshotted ${id}${memory ? ' with its memory' : ''}${called}.`;
+        const startedLine = `Capture of ${id}${memory ? ' with its memory' : ''} started${called}.`;
+        // The id allocated before the copy begins, and the whole reason a poll
+        // is possible: it is the SNAPSHOT'S own id and does not change when the
+        // capture lands, so the row stops reading `capturing` in place rather
+        // than being replaced by something under another id.
+        const sid = typeof started?.id === 'string' && started.id.trim() ? started.id.trim() : '';
+        const startedState = typeof started?.state === 'string' ? started.state : undefined;
+        // How to follow it by hand — said wherever this hands back with the
+        // capture still running, because "poll list_snapshots" without the two
+        // rules under it is an instruction a model gets wrong in both
+        // directions: by waiting for the literal `pending`, and by reading a
+        // row that vanished as a row that has not appeared yet.
+        const byHand = `Poll list_snapshots for the id ${sid}: the row stops reading "${CAPTURING}" when the capture ` +
+            `lands — do not wait for "pending" specifically, since replication can carry it straight on to ` +
+            `"durable" — and a row that DISAPPEARS without ever leaving "${CAPTURING}" is a capture that failed.`;
+        // A capture accepted under an id nobody was told cannot be polled for,
+        // and it cannot be found again either — every later call takes the id.
+        // `refused`, for clone_snapshot's reason one route over: the platform
+        // did something billable and the caller has no handle on it, which is
+        // not a result to report as success.
+        //
+        // BEFORE the wait: false branch, not after it, and Codex caught that it
+        // was the other way round. `wait: false` is the answer whose whole
+        // content is an id — handed back without one it reported success and
+        // told the caller to poll list_snapshots for "the id ", which is the
+        // same nothing dressed as an instruction.
+        if (!sid) {
+            return refused(`${startedLine} THE CAPTURE IS RUNNING, but the platform sent no snapshot id back, so there ` +
+                `is nothing to poll on and the snapshot cannot be named — every call that acts on one takes ` +
+                `its id. list_snapshots on ${id} will show it when it lands.`, started);
+        }
+        if (!wait) {
+            return said(`${startedLine} It is NOT a snapshot yet: while its row reads "${CAPTURING}" it is a ` +
+                `placeholder, and restore, clone and delete all fail on it. ${byHand}`, started);
+        }
+        // Already finished when it was answered for — a `201` from a platform
+        // that has not taken the 202 yet, or a capture with nothing to copy.
+        // Not a state to poll out of, and a loop that did would ask for a row it
+        // already holds.
+        //
+        // An ALLOW-LIST, for the reason {@link LANDED} gives: this asks whether
+        // there is anything to wait for, and every unreadable answer — absent,
+        // misspelt, renamed, moved — has to mean yes. Only a state this server
+        // can read AS a landed one skips the wait.
+        if (startedState !== undefined && LANDED.includes(startedState)) {
+            return said(`${took} It is ${startedState} — snapshot ${sid}.`, started);
+        }
+        // The keepalive. Armed after the 202, because everything before it is a
+        // single short request and there is nothing to report until there is a
+        // capture to report on.
+        const beat = heartbeat(extra, server.server);
+        await beat(`Capturing ${sid} of ${id} — the copy has started.`);
+        let blocked;
+        // `untilDeadline &&` rather than `!untilDeadline?.aborted`: the early
+        // return above is what guarantees it is armed here, and the optional
+        // form would turn a later edit that broke that guarantee into a loop
+        // with no deadline at all rather than into a visible mistake.
+        while (untilDeadline && !untilDeadline.aborted) {
+            // The caller giving up ends the wait. The signal aborts the request in
+            // flight, but nothing about an aborted request stops the next
+            // iteration from starting one.
+            if (extra.signal?.aborted) {
+                return refused(`Cancelled while waiting for the capture of ${id}. THE CAPTURE IS STILL RUNNING — nothing ` +
+                    `was stopped, because a disk copy already under way cannot be called back. ${byHand}`, started);
+            }
+            const turn = await snapshotTurn(api, sid, false);
+            if (extra.signal?.aborted)
+                continue;
+            // A body stream can fail without either signal firing, so the
+            // deadline's own arrival is what tells a real timeout from an undici
+            // idle abort. Same shape as the two loops in computers.ts.
+            if (turn.kind === 'cancelled') {
+                if (untilDeadline?.aborted)
+                    break;
+                blocked = turn.why;
+                await beat(`Capturing ${sid} of ${id} — the platform could not be asked: ${turn.why}`);
+                await sleep(POLL_MS, signal);
+                continue;
+            }
+            // A poll that failed for a reason worth riding out is weather; one
+            // that failed for any other reason is a real failure with a capture
+            // still running behind it, and a thrown error's handler has no way to
+            // say so. So it is said here rather than rethrown.
+            if (turn.kind === 'broken') {
+                return refused(`${turn.why}\n\nTHE CAPTURE IS STILL RUNNING — this was the poll failing, not the ` +
+                    `capture. ${byHand}`, started);
+            }
+            if (turn.kind === 'blocked') {
+                blocked = turn.why;
+                await beat(`Capturing ${sid} of ${id} — the platform could not be asked: ${turn.why}`);
+                await sleep(turn.after ?? POLL_MS, signal);
+                continue;
+            }
+            // Absence is the ONLY signal a failed capture leaves, which is what
+            // makes snapshotTurn's guards load-bearing rather than tidy: a body
+            // that is not a list, and a listing the platform had to answer short,
+            // both come back `blocked` there rather than as this, because read as
+            // "the row is not there" they would announce that somebody's backup
+            // failed while it was still being taken.
+            if (turn.kind === 'absent') {
+                return refused(`THE CAPTURE OF ${id} FAILED and nothing was saved. Snapshot ${sid} is no longer listed and ` +
+                    `nothing took its place, which is what a capture that starts and then fails leaves behind — ` +
+                    `this is a failure during the copy, not a wait that ran out. The computer itself is ` +
+                    `untouched and can be snapshotted again.`, started);
+            }
+            const row = turn.row;
+            const state = typeof row.state === 'string' ? row.state : undefined;
+            if (state === CAPTURING) {
+                blocked = undefined;
+                await beat(`Capturing ${sid} of ${id} — still copying.`);
+                await sleep(POLL_MS, signal);
+                continue;
+            }
+            // A row with no readable `state` is the platform failing to describe
+            // it, and it must not be read as "not capturing, therefore landed" —
+            // that sentence says a placeholder may be restored, which is the
+            // defect this whole tool is here to stop. Only a state that SAYS it is
+            // no longer capturing ends the wait; anything else rides out, and the
+            // deadline reports that the platform could not be asked.
+            if (state === undefined) {
+                blocked = `the row for ${sid} carried no state, so nothing said whether the capture had landed`;
+                await beat(`Capturing ${sid} of ${id} — its row carried no state to read.`);
+                await sleep(POLL_MS, signal);
+                continue;
+            }
+            return said(`${took} The capture landed: snapshot ${sid} reads "${state}" and can now be restored, ` +
+                `cloned or deleted.`, row);
+        }
+        // A refusal, for the reason move_computer's is: the wait never reached
+        // what it was told to wait for. What it must not do is read as a capture
+        // that failed — that is a different answer with a different id in it,
+        // and the difference between calling this again and going looking for a
+        // snapshot that is on its way.
+        return refused(blocked
+            ? `${startedLine} Gave up watching after ${timeout_s}s; the platform could not be asked — the ` +
+                `last attempt said: ${blocked}. THE CAPTURE IS STILL RUNNING. ${byHand}`
+            : `${startedLine} Still capturing after ${timeout_s}s, which a large disk takes. THE CAPTURE IS ` +
+                `STILL RUNNING and nothing was changed by giving up on the wait. ${byHand}`, started);
     }));
     server.registerTool('restore_snapshot', {
         title: 'Restore a snapshot',
@@ -246,7 +555,21 @@ export const registerSnapshots = (server, session, opts) => {
         if (clear)
             return said('Schedule cleared.', await session.api.with(extra.signal).send('DELETE', path));
         if (set) {
-            return said(`Snapshot scheduled for ${String(set.hour).padStart(2, '0')}:${String(set.minute).padStart(2, '0')} ${set.tz}.`, await session.api.with(extra.signal).send('PUT', path, { body: P.scheduleBody(set) }));
+            const at = `${String(set.hour).padStart(2, '0')}:${String(set.minute).padStart(2, '0')} ${set.tz}`;
+            const res = await session.api
+                .with(extra.signal)
+                .send('PUT', path, { body: P.scheduleBody(set) });
+            // `enabled` is a required field of `set`, and it is the one that
+            // decides whether backups happen at all — so the sentence has to read
+            // it. "Snapshot scheduled for 03:00 UTC" over `enabled: false` tells a
+            // model the opposite of what the call just did, in the line it acts
+            // on, and the hour it names is real, which is what makes the wrong
+            // reading easy to believe. The hour is kept on a disabled schedule, so
+            // it is worth naming: a model that reads "disabled" and nothing else
+            // calls this again to find out what it would have run at.
+            return said(set.enabled
+                ? `Snapshot scheduled for ${at}.`
+                : `The nightly snapshot on ${id} is now DISABLED — none will be taken automatically. ${at} is the time it holds, which is when it would resume if you set it again with enabled: true. To remove the schedule rather than turn it off, call this with clear.`, res);
         }
         return json(await session.api.with(extra.signal).json('GET', path));
     }));
@@ -295,17 +618,85 @@ export const registerSnapshots = (server, session, opts) => {
     }));
     server.registerTool('delete_snapshot', {
         title: 'Delete a snapshot',
-        description: 'Remove a snapshot permanently. Later snapshots in the same chain are unaffected.',
+        description: 'Remove a snapshot permanently. Later snapshots in the same chain are unaffected. THE DELETION OUTLIVES THE REQUEST that starts it: the platform accepts it and then detaches the dependent snapshots and removes the stored objects, which takes time that scales with the chain and with how much is stored. This waits for it by default and reports what actually happened; pass wait: false to hand back as soon as it is accepted. A 409 saying the snapshot is ALREADY BEING DELETED is progress rather than a fault — the platform is doing what you asked, and the answer is to watch that one finish, never to go and delete something else. A wait reports progress while it runs, so a client that sends a progressToken and sets resetTimeoutOnProgress can hold the request open; a client that cannot should pass wait: false and poll list_snapshots.',
         inputSchema: {
-            snapshot_id: z.string(),
+            snapshot_id: z.string().trim(),
             confirm: z.literal(true).describe('Must be true.'),
+            wait: z
+                .boolean()
+                .default(true)
+                .describe('Wait for the snapshot to stop being listed, which is the only thing that means it is gone. Set it false to hand back as soon as the platform accepts the deletion, and then poll list_snapshots yourself.'),
+            timeout_s: z
+                .number()
+                .int()
+                .min(5)
+                .max(1800)
+                .default(300)
+                .describe('How long to wait for the deletion before handing back. Ignored when wait is false. Giving up on the wait does not stop the deletion.'),
         },
         annotations: { destructiveHint: true, idempotentHint: true },
-    }, ({ snapshot_id }, extra) => guarded(async () => {
+    }, ({ snapshot_id, wait, timeout_s }, extra) => guarded(async () => {
+        // The deadline is armed before the DELETE, as create_snapshot arms its
+        // own and for the same reason: timeout_s is a promise about when this
+        // comes back. Nothing is armed when nobody is waiting.
+        const untilDeadline = wait ? AbortSignal.timeout(timeout_s * 1000) : undefined;
+        const signal = !untilDeadline
+            ? extra.signal
+            : extra.signal
+                ? AbortSignal.any([extra.signal, untilDeadline])
+                : untilDeadline;
+        const api = session.api.with(signal);
+        // How to follow it by hand, said wherever this hands back with the
+        // deletion still running. The polarity is the whole of it and it is the
+        // opposite of a capture's: there is no state that means deleted, so the
+        // row GOING is the finish, and a row that stays is one that stalled.
+        // `include_unfinished` is not a nicety either — the platform marks a
+        // half-finished deletion `deleting` and leaves that state out of a bare
+        // listing, so without the flag a stalled deletion looks exactly like a
+        // finished one.
+        const byHand = `Poll list_snapshots with include_unfinished: true and watch for ${snapshot_id} to stop being ` +
+            `listed — its absence is the deletion having finished, and there is no state that means deleted. ` +
+            `A row that STAYS is one that stalled; the platform retries those itself every fifteen minutes.`;
+        let accepted;
         try {
-            await session.api.with(extra.signal).send('DELETE', P.snapshot(snapshot_id));
+            accepted = await api.send('DELETE', P.snapshot(snapshot_id));
         }
         catch (err) {
+            // Every refusal is still decided before the 202 — no such snapshot, a
+            // capture reading through it, a clone or a migration holding it, a
+            // deletion of this id already running — so a 409 here is a statement
+            // about state that clears itself, and the model needs to be told
+            // which way to read it rather than left to invent a way round it.
+            //
+            // Matched on the CLASS and never on the sentence: the platform sends
+            // no `reason` for these, and keying on prose is the mistake OPL-3724
+            // took out of three clients. So both readings are named and the
+            // platform's own words are printed with them.
+            // The deadline, or the caller, arriving while the DELETE is in
+            // flight. The generic cancellation sentence says the request may have
+            // been received; what it cannot say is that the work it started
+            // OUTLIVES the request, so "cancelled" here reads as a deletion that
+            // did not happen while the objects are being removed. Claiming less
+            // than happened, which on a destructive call is its own kind of wrong
+            // answer (codex review, gpt-5.6-sol).
+            //
+            // The retry rule is worth saying in the same breath, because it is
+            // the one thing that makes this recoverable: repeating the call is
+            // safe. A snapshot already being deleted answers 409, and one that is
+            // gone answers 404, and this tool has a sentence for each.
+            if (err instanceof CancelledError) {
+                return refused(`${why(err)}\n\nTHE DELETION OF ${snapshot_id} MAY BE RUNNING: the request may have reached ` +
+                    `the platform and been accepted, and nothing about the answer being lost calls it back. ` +
+                    `${byHand} Calling this again is safe either way — a snapshot already being deleted ` +
+                    `answers a conflict, and one that is gone answers that there is nothing to delete.`);
+            }
+            if (err instanceof ConflictError) {
+                return refused(`${why(err)}\n\nNOTHING WAS DELETED and nothing is broken. If that says the snapshot is ` +
+                    `already being deleted, the platform is doing what you asked — watch it finish rather ` +
+                    `than deleting anything else: ${byHand} If it says something is reading through the ` +
+                    `snapshot — a restore, a clone, a capture chaining onto it — that finishes on its own and ` +
+                    `the same call works afterwards.`);
+            }
             // A 404 means the snapshot is not there, which is the state this call
             // was asking for. `idempotentHint` above invites a client to retry a
             // lost 2xx, and `#fetch` throws on every non-OK — so that invited
@@ -327,7 +718,74 @@ export const registerSnapshots = (server, session, opts) => {
                 'a real one may still be held under the id you meant. list_snapshots says which of the two ' +
                 'this is.');
         }
-        return said(`Deleted snapshot ${snapshot_id}.`);
+        // The 202 and its body: the snapshot's row as it stood when the deletion
+        // was accepted — the row that GOES when the work finishes.
+        if (!wait) {
+            return said(`Deletion of ${snapshot_id} accepted and RUNNING — it is not gone yet, and this call did not ` +
+                `wait to find out. ${byHand}`, accepted);
+        }
+        const beat = heartbeat(extra, server.server);
+        await beat(`Deleting ${snapshot_id} — the platform has accepted it.`);
+        let blocked;
+        let seen;
+        while (untilDeadline && !untilDeadline.aborted) {
+            if (extra.signal?.aborted) {
+                return refused(`Cancelled while waiting for ${snapshot_id} to be deleted. THE DELETION IS STILL RUNNING — ` +
+                    `nothing was called back, and objects it has already removed are already gone. ${byHand}`, accepted);
+            }
+            // `unfinished`, because the state a stalled deletion sits in is the
+            // one a bare listing hides. Asking without it would read a snapshot
+            // stuck half-deleted as a snapshot successfully deleted, which is the
+            // one wrong answer this tool must not give.
+            const turn = await snapshotTurn(api, snapshot_id, true);
+            if (extra.signal?.aborted)
+                continue;
+            if (turn.kind === 'cancelled') {
+                if (untilDeadline.aborted)
+                    break;
+                blocked = turn.why;
+                await beat(`Deleting ${snapshot_id} — the platform could not be asked: ${turn.why}`);
+                await sleep(POLL_MS, signal);
+                continue;
+            }
+            if (turn.kind === 'broken') {
+                return refused(`${turn.why}\n\nTHE DELETION IS STILL RUNNING — this was the poll failing, not the ` +
+                    `deletion. ${byHand}`, accepted);
+            }
+            if (turn.kind === 'blocked') {
+                blocked = turn.why;
+                await beat(`Deleting ${snapshot_id} — the platform could not be asked: ${turn.why}`);
+                await sleep(turn.after ?? POLL_MS, signal);
+                continue;
+            }
+            // The row is gone from a listing that was read whole and that ASKED
+            // for the unfinished ones. Both halves are what make this sentence
+            // true rather than merely likely.
+            if (turn.kind === 'absent')
+                return said(`Deleted snapshot ${snapshot_id}.`, accepted);
+            blocked = undefined;
+            seen = typeof turn.row.state === 'string' ? turn.row.state : undefined;
+            await beat(`Deleting ${snapshot_id} — still listed${seen ? `, reading "${seen}"` : ''}.`);
+            await sleep(POLL_MS, signal);
+        }
+        // Still listed. Three different things that can mean, and they are not
+        // one sentence: the platform could not be asked, the deletion got part
+        // way and stalled, or it never got started on — which is the shape the
+        // one conflict that arrives AFTER the 202 leaves behind, a dependent
+        // that is itself being deleted and so cannot be detached.
+        return refused(blocked
+            ? `Gave up watching after ${timeout_s}s; the platform could not be asked whether ${snapshot_id} ` +
+                `is gone — the last attempt said: ${blocked}. THE DELETION IS STILL RUNNING. ${byHand}`
+            : seen === DELETING
+                ? `${snapshot_id} is still listed after ${timeout_s}s and reads "${DELETING}": the deletion ` +
+                    `started and has not finished. Nothing was undone by giving up on the wait, and the ` +
+                    `platform retries a stalled deletion itself every fifteen minutes — so this usually needs ` +
+                    `watching rather than repeating. ${byHand}`
+                : `${snapshot_id} is still listed after ${timeout_s}s${seen ? `, reading "${seen}"` : ''} — ` +
+                    `the deletion has not reached the point of marking it "${DELETING}". That is what a big ` +
+                    `chain looks like early on, and it is also what the one conflict that arrives after the ` +
+                    `deletion is accepted looks like: a dependent snapshot that is ITSELF being deleted cannot ` +
+                    `be detached, so this one waits for that one. Nothing was destroyed either way. ${byHand}`, accepted);
     }));
 };
 //# sourceMappingURL=snapshots.js.map