mandala-computer-mcp 0.3.0 → 0.5.0

package/dist/tools/signals.js

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+import { said } from '../format.js';
+import * as P from '../paths.js';
+import { count, executionId, exitCode, label, metadata, metadataCall } from './directory.js';
+import { computerSchema, readAnnotations } from './results.js';
+const position = {
+    seq: count,
+    cursor: label,
+    at: label,
+    computer: label,
+    source: z.literal('daemon'),
+};
+const status = z.enum([
+    'running',
+    'stopped',
+    'suspended',
+    'building',
+    'build-failed',
+    'half-removed',
+]);
+const processData = z.union([
+    z.object({
+        pid: count.min(1).max(2147483647),
+        execution_id: executionId.optional(),
+        exit_code: exitCode,
+        lost: z.never().optional(),
+    }),
+    z.object({
+        pid: count.min(1).max(2147483647),
+        execution_id: executionId.optional(),
+        lost: z.literal(true),
+        exit_code: z.never().optional(),
+    }),
+]);
+const event = z.discriminatedUnion('type', [
+    z.object({ ...position, type: z.literal('process.exited'), data: processData }),
+    z.object({
+        ...position,
+        type: z.literal('computer.started'),
+        data: z.object({ status: z.literal('running'), previous: status.optional() }),
+    }),
+    z.object({
+        ...position,
+        type: z.literal('computer.stopped'),
+        data: z.object({ status: z.literal('stopped'), previous: status.optional() }),
+    }),
+    z.object({
+        ...position,
+        type: z.literal('computer.suspended'),
+        data: z.object({ status: z.literal('suspended'), previous: status.optional() }),
+    }),
+    z.object({
+        ...position,
+        type: z.literal('computer.idle'),
+        data: z.object({ idle_seconds: count }),
+    }),
+]);
+const page = z.object({
+    computer: label,
+    from: z.string(),
+    cursor: label,
+    events: z.array(event).max(100),
+    more: z.boolean(),
+    baseline: z.boolean(),
+    gap: z
+        .object({
+        cursor: label,
+        at: label,
+        type: z.literal('gap'),
+        computer: label,
+        source: z.literal('daemon'),
+        data: z.object({ oldest_cursor: label.optional(), detail: label }),
+    })
+        .optional(),
+    supported: z.array(label),
+    retention: z.literal('ephemeral'),
+});
+export const registerSignals = (server, session) => {
+    server.registerTool('read_signals', {
+        title: 'Read one passive platform signal page',
+        description: 'Read finite daemon facts without waking the computer, guest contact, event socket, watcher, capture or polling loop. Omit since or send empty for a head-only baseline with no replay; neither a baseline nor gap proves no earlier activity or task success. Keep the returned cursor even on an empty page: filtered-out rows can advance it. Retention is ephemeral, and resets are explicit gaps.',
+        inputSchema: {
+            computer_id: computerSchema,
+            since: z.string().max(2048).optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: readAnnotations,
+    }, ({ computer_id, since, limit }, extra) => metadataCall(async () => {
+        const id = session.resolve(computer_id);
+        const data = metadata(page, await session.api.json('GET', P.signals(id), {
+            query: { since, limit },
+            signal: extra.signal,
+        }));
+        // Compare opaque checkpoints without parsing or deriving a next cursor.
+        // Baselines and explicit resets describe one head; replay starts at since.
+        // Events must advance; the next cursor may also pass filtered rows.
+        const checkpoints = new Set([data.from, ...data.events.map((e) => e.cursor)]);
+        if (data.computer !== id ||
+            data.events.some((e, i) => e.computer !== id || (i > 0 && e.seq <= data.events[i - 1].seq)) ||
+            checkpoints.size !== data.events.length + 1 ||
+            (data.events.length > 0 &&
+                data.cursor !== data.events.at(-1)?.cursor &&
+                checkpoints.has(data.cursor)) ||
+            data.baseline !== (since === undefined || since === '') ||
+            (data.baseline && data.gap) ||
+            (data.gap && (data.gap.computer !== id || data.gap.cursor !== data.cursor)) ||
+            ((data.baseline || data.gap) &&
+                (data.events.length || data.more || data.from !== data.cursor)) ||
+            (!data.baseline && !data.gap && data.from !== since) ||
+            (data.more && !data.events.length) ||
+            data.events.length > (limit ?? 50))
+            throw new Error('Inconsistent signal page; no checkpoint was established.');
+        return said(`${data.gap ? 'GAP: the checkpoint was reset. ' : ''}${data.baseline ? 'Head-only baseline; no historical replay. ' : ''}One ephemeral page; use the returned cursor, including after an empty page. These facts do not establish task success.`, data);
+    }));
+};
+//# sourceMappingURL=signals.js.map

package/dist/tools/signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.js","sourceRoot":"","sources":["../../src/tools/signals.ts"],"names":[],"mappings":"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"}

package/dist/tools/snapshots.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshots.d.ts","sourceRoot":"","sources":["../../src/tools/snapshots.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAgM5C,eAAO,MAAM,iBAAiB,EAAE,SA6wB/B,CAAC"}
+{"version":3,"file":"snapshots.d.ts","sourceRoot":"","sources":["../../src/tools/snapshots.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA4M5C,eAAO,MAAM,iBAAiB,EAAE,SA40B/B,CAAC"}

package/dist/tools/snapshots.js

@@ -123,21 +123,17 @@ const snapshotTurn = async (api, sid, unfinished) => {
     }
     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
- * do not say what they select.
- *
- * Says what SURVIVES rather than restating the numbers. A tier at zero is left
- * out entirely rather than printed as "0 monthly", which reads like a promise
- * about monthlies; and an all-zero window — what an account with no active
- * subscription reads — is stated as the plan granting no retained history,
- * without claiming anything about what happens to snapshots already taken. The
- * platform's own reference stops in the same place and for the same reason.
- */
-const retentionLine = (r) => {
-    const v = (r ?? {});
-    const n = (x) => (typeof x === 'number' && Number.isFinite(x) && x > 0 ? x : 0);
+const retentionOf = (r) => {
+    if (!isRow(r))
+        return undefined;
+    const fields = [r.daily, r.weekly, r.monthly];
+    if (!fields.every((value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0)) {
+        return undefined;
+    }
+    return { daily: r.daily, weekly: r.weekly, monthly: r.monthly };
+};
+const retentionLine = (v) => {
+    const n = (x) => (x > 0 ? x : 0);
     const parts = [
         n(v.daily) && `${n(v.daily)} daily`,
         n(v.weekly) && `${n(v.weekly)} weekly`,
@@ -295,7 +291,7 @@ export const registerSnapshots = (server, session, opts) => {
             memory: z
                 .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.'),
+                .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 with memory: false instead in that case, which restores the disk and boots fresh.'),
             wait: z
                 .boolean()
                 .default(true)
@@ -419,93 +415,98 @@ export const registerSnapshots = (server, session, opts) => {
         // 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;
+        try {
+            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);
             }
-            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);
+        }
+        finally {
+            await beat.stop();
         }
-        // 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',
@@ -580,7 +581,11 @@ export const registerSnapshots = (server, session, opts) => {
         annotations: { readOnlyHint: true },
     }, (_args, extra) => guarded(async () => {
         const body = await session.api.with(extra.signal).json('GET', P.RETENTION);
-        return said(retentionLine(body), body);
+        const retention = retentionOf(body);
+        if (!retention) {
+            return refused('The retention policy could not be read: GET /retention must answer with nonnegative whole-number `daily`, `weekly`, and `monthly` fields. No retention window is inferred from this response.', body);
+        }
+        return said(retentionLine(retention), body);
     }));
     // clone_snapshot brings a billable machine into existence as surely as
     // create_computer does, and delete_snapshot destroys bytes as surely as
@@ -594,27 +599,63 @@ export const registerSnapshots = (server, session, opts) => {
         return;
     server.registerTool('clone_snapshot', {
         title: 'Fork a snapshot into a new computer',
-        description: 'Build a new computer from a snapshot, leaving the original untouched. This is the fork half of snapshot-and-fork, and the only thing that works on an orphaned snapshot.',
+        description: "Build a new computer from a snapshot, leaving the original untouched. This is the fork half of snapshot-and-fork, and the only thing that works on an orphaned snapshot. A MEMORY snapshot is resumed: the copy comes up running the captured session, sharing its source's network identity, so it cannot run on the same host while its source is running. Pass memory: false to build it from the disk alone instead, as a fresh boot with its own identity. A memory snapshot of a computer that held SECRETS is resumed only with inherit_secrets: true, and then the copy HOLDS THE SAME CREDENTIALS as the computer it came from; without it the clone is built from the disk and this tool says so.",
         inputSchema: {
             snapshot_id: z.string(),
             name: z.string().optional().describe('A name for the new computer.'),
+            memory: z
+                .boolean()
+                .optional()
+                .describe('Memory snapshots only. false builds the new computer from the disk alone and boots it fresh; omitted or true resumes the captured session.'),
+            inherit_secrets: z
+                .boolean()
+                .optional()
+                .describe('Consent to resuming a memory snapshot of a computer that held secrets. The new computer holds the same credentials, bound to the same secrets. Only set this when that is what the user asked for.'),
             select: z
                 .boolean()
                 .default(true)
                 .describe("Make the new computer this session's selected one."),
         },
-    }, ({ snapshot_id, name, select }, extra) => guarded(async () => {
-        const c = unwrapComputer(await session.api
+    }, ({ snapshot_id, name, select, memory, inherit_secrets }, extra) => guarded(async () => {
+        // Each option only when set, so an ordinary clone sends what it always
+        // did; consent is sent only when given, since its absence is the default.
+        const body = {};
+        if (name !== undefined)
+            body.name = name;
+        if (memory !== undefined)
+            body.memory = memory;
+        if (inherit_secrets === true)
+            body.inherit_secrets = true;
+        const answer = await session.api
             .with(extra.signal)
-            .json('POST', P.snapshotAction(snapshot_id, 'clone'), {
-            body: name === undefined ? {} : { name },
-        }));
+            .json('POST', P.snapshotAction(snapshot_id, 'clone'), { body });
+        const c = unwrapComputer(answer);
         if (!c.id) {
             return refused(`The platform accepted the clone of ${snapshot_id} but sent no computer id back, so the copy cannot be identified. It may exist and be billable — list_computers will say. The selected computer is unchanged.`, withoutCredentials(c));
         }
         if (select && c.id)
             session.bind(c.id, c.resolution);
-        return said(`Forked ${snapshot_id} into ${describe(c)}${select && c.id ? ', and selected it' : ''}.`, withoutCredentials(c));
+        // The platform built it from the disk when the session could not come
+        // across (platform OPL-4964). Said first and in words, because a model
+        // that asked for a live fork and got a fresh boot would otherwise go on
+        // as if the session — its open windows, its running programs — were
+        // there.
+        //
+        // Read off the ANSWER as well as the computer: the platform sends the
+        // two fields beside the computer's own, flat, and unwrapComputer keeps
+        // only start_error from an envelope — so a future envelope carrying
+        // them would otherwise report a live fork for a fresh boot.
+        const outer = (answer && typeof answer === 'object' ? answer : {});
+        const raw = { ...c, ...outer };
+        if (raw.memory_dropped === true) {
+            const why = raw.memory_dropped_reason === 'bindings unrecorded'
+                ? "it was taken before copies could be given its computer's secrets"
+                : raw.memory_dropped_reason === 'secrets'
+                    ? 'its computer held secrets and inherit_secrets was not set'
+                    : 'the platform did not resume it';
+            return said(`Built ${describe(c)} from ${snapshot_id}'s DISK, booting fresh — its saved session was NOT resumed, because ${why}. No secrets are bound to it${select && c.id ? '. It is selected' : ''}.`, withoutCredentials(c));
+        }
+        return said(`${memory === false ? 'Built' : 'Forked'} ${snapshot_id} into ${describe(c)}${memory === false ? ' from its disk' : ''}${select && c.id ? ', and selected it' : ''}.`, withoutCredentials(c));
     }));
     server.registerTool('delete_snapshot', {
         title: 'Delete a snapshot',
@@ -725,67 +766,72 @@ export const registerSnapshots = (server, session, opts) => {
                 `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}`);
+        try {
+            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);
-                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);
+        }
+        finally {
+            await beat.stop();
         }
-        // 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