mandala-computer 0.2.0__tar.gz → 0.4.0__tar.gz

{mandala_computer-0.2.0 → mandala_computer-0.4.0}/.github/workflows/ci.yml

@@ -19,6 +19,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          # The commit-message half of check_internals needs the base branch to
+          # diff against; the default shallow clone has no origin/main.
+          fetch-depth: 0
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
@@ -27,6 +31,19 @@ jobs:
       - run: ruff check .
       - run: ruff format --check .
       - run: mypy
+      # This repo is public and the platform it speaks to is not. Every batch of
+      # client fixes is written by reading that platform, and the reading leaves
+      # fingerprints — file names, internal function names — in comments that
+      # SHIP. OPL-4613 and OPL-4617 scrubbed two of these repos by hand and left
+      # nothing behind to catch the next one; this is that (OPL-4635).
+      #
+      # Both halves. A commit message is public the moment it is pushed, and
+      # three of the five references found in the batch that prompted this were
+      # in messages and PR descriptions rather than in files — which the file
+      # scan cannot see. Needs the full history, hence fetch-depth above.
+      - run: python3 scripts/check_internals.py
+      - run: python3 scripts/check_internals.py --messages origin/${{ github.event.pull_request.base.ref || 'main' }}..HEAD
+        if: github.event_name == 'pull_request'
 
   test:
     runs-on: ubuntu-latest

{mandala_computer-0.2.0 → mandala_computer-0.4.0}/.gitignore

@@ -21,3 +21,6 @@ htmlcov/
 
 # Reports written by the /grok-bug-hunt skill.
 .grok-bug-hunt/
+
+# Adversarial review notes written by the local fix workflow.
+.fix-lanes/

mandala_computer-0.4.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+Notable changes to `mandala-computer`. Dates are release dates; the format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project is pre-1.0, so a minor version may carry a behaviour change.
+
+The reasoning behind a change lives in its commit message rather than here.
+This is the summary you read to decide whether to upgrade.
+
+## [0.4.0] — 2026-09-14
+
+### Added
+
+- **`Computer.read_text_file()` and `AsyncComputer.read_text_file()`** — the
+  same request `read_file()` makes, decoded as UTF-8. `read_file()` stays the
+  primitive and stays `bytes`, because a guest file is not promised to be text
+  and decoding one that is not would put replacement characters at the SDK
+  boundary for every caller. The decode is `errors="replace"`, on the same
+  terms as `ExecResult.stdout_text`: the caller asked for text, and the bytes
+  are one call away.
+
+### Changed
+
+- **An empty clipboard write now clears the selection** instead of being
+  refused locally. `set_clipboard("")` is a thing the platform accepts and a
+  thing callers want; refusing it here was this SDK inventing a rule.
+- **`reason: "revoked"` is classified as permanent.** The platform added a
+  fifth refusal word for the case where the authority a request arrived with no
+  longer holds — suspended, demoted, removed, or a retired session — and it is
+  the first of these words about the *caller* rather than about a computer.
+  Nothing was broken before this: a 401 or 403 is none of the four transient
+  classes, so an unrecognised word already answered `False` from
+  `is_transient()`. What changes is that it is answered on purpose, so a future
+  status for this refusal cannot quietly make a permission failure look
+  replayable. The status still says what to do: 401 means present a credential
+  again, 403 means the role changed and signing in again will not help.
+
+### Fixed
+
+- **A mid-run refusal no longer discards the partial agent run.** Authorization
+  is rechecked before each further piece of work, so a non-streaming
+  `agent()` can be stopped after steps have already run on the desktop and
+  already cost model tokens — and the refusal body is the only place either is
+  ever reported. Those steps and that usage now survive the error.
+- **The documented install works on a Homebrew or distribution Python.** The
+  README opened with `pip install mandala-computer`, which answers
+  `externally-managed-environment` and installs nothing on the ordinary
+  developer Mac (PEP 668). The install guidance now leads with a virtual
+  environment rather than with a command that fails.
+
+### Documentation
+
+- **A run's steps are not its model calls.** Three places said they were and
+  offered `max_steps` as a way to size Anthropic spend on that basis. The
+  platform counts a step per *tool call* and encourages a model to ask for
+  several actions in one reply, so one model call can spend several steps; a
+  paused turn is resubmitted for tokens and no step; and a bash call or a
+  cursor read takes no screenshot. A caller budgeting from the old sentence was
+  wrong whichever way their run went. The README also now states the default,
+  which nothing here did: omit `max_steps` and you get 20, and the ceiling
+  is 100.
+- Webhook idempotency and API usage guidance clarified, and the template
+  section restored the two refusals on the custom-build path that never clear.
+
+### Internal
+
+No effect on the published surface, listed because it is most of the window.
+
+- The drift check reads the platform's published **surface manifest** instead
+  of scanning its TypeScript and Go as text. Eleven hundred lines of
+  hand-written reader are gone, along with the class of defect they kept
+  producing: a false all-clear, reporting the mirror in step because the scan
+  had silently read nothing. The new reader fails closed on a manifest that is
+  missing, unparseable, of an unknown version, or that names a key twice.
+- Surface inventory parsing hardened in the same direction, before the scanner
+  was retired.
+
+[0.4.0]: https://github.com/mandalacomputer/python-sdk/compare/v0.3.0...v0.4.0

{mandala_computer-0.2.0 → mandala_computer-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mandala-computer
-Version: 0.2.0
+Version: 0.4.0
 Summary: Python SDK for Mandala Computer — cloud desktops for AI agents
 Project-URL: Homepage, https://mandala.computer
 Project-URL: Source, https://github.com/mandalacomputer/python-sdk
@@ -61,6 +61,28 @@ pip install mandala-computer
 Python 3.10 or newer. The install also puts a `mandala` command on your PATH —
 see [The `mandala` CLI](#the-mandala-cli).
 
+If that command answers `error: externally-managed-environment`, nothing is
+wrong: the Python you are asking is managed by something else — Homebrew on a
+Mac, the distribution's package manager on Linux — and refuses to install into
+itself ([PEP 668](https://peps.python.org/pep-0668/)). Install into a virtual
+environment instead:
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate   # fish: source .venv/bin/activate.fish
+pip install mandala-computer
+```
+
+For the `mandala` command on your PATH rather than the library in a project,
+let a tool manager own the environment:
+
+```sh
+pipx install mandala-computer   # or: uv tool install mandala-computer
+```
+
+Do not reach for `--break-system-packages`. It does what it says to the Python
+the rest of your system is depending on.
+
 ## Use
 
 Authentication is an API key from the dashboard (Settings → API keys), read from
@@ -165,6 +187,76 @@ t = client.templates.publish(doc)
 c = client.computers.create(template=t.ref)
 ```
 
+When `create()` returns a 409 with `body["code"] == "template_image_preparing"`,
+inspect `body["preparation"]`: it retains the server's `state` and `error`,
+including failed preparation. A failure needs diagnosis before a deliberate
+retry. `APIError.retry_after` preserves the `Retry-After` header as seconds,
+including HTTP dates; absent or malformed metadata is `None`.
+
+For an explicit continuation, wait the returned delay, repeat **all original
+create arguments, including the same template**, and add the returned
+`template_transfer` token. The token and template must be nonempty strings;
+`size` cannot be combined with a token. An opaque token is sent unchanged,
+including surrounding whitespace. A missing or different template can produce
+`NotFoundError`. The token preserves the selected build, **not create
+idempotency**: stop after success and never blindly retry an ambiguous or lost
+response. `is_transient()` returns `False` for this preparation refusal,
+including preparation still in progress.
+
+This helper accepts only a preparation response with usable continuation
+metadata. It surfaces failed preparation for diagnosis:
+
+```python
+def preparation_retry(error):
+    body = error.body
+    if not isinstance(body, dict) or body.get("code") != "template_image_preparing":
+        raise error
+    preparation = body.get("preparation")
+    token = body.get("template_transfer")
+    if (
+        not isinstance(preparation, dict)
+        or preparation.get("state") not in ("preparing", "copying", "ready")
+        or not isinstance(token, str)
+        or not token.strip()
+        or error.retry_after is None
+    ):
+        raise error
+    return error.retry_after, token
+```
+
+A synchronous caller can make one deliberate continuation attempt:
+
+```python
+import time
+from mandala_computer import ConflictError
+
+original = {"template": t.ref, "name": "dev", "cpu": 4, "ram_mb": 8192}
+try:
+    c = client.computers.create(**original)
+except ConflictError as error:
+    delay, token = preparation_retry(error)
+    time.sleep(delay)
+    c = client.computers.create(**original, template_transfer=token)
+```
+
+The async equivalent uses the same original arguments and validation:
+
+```python
+import asyncio
+from mandala_computer import ConflictError
+
+original = {"template": t.ref, "name": "dev", "cpu": 4, "ram_mb": 8192}
+try:
+    c = await client.computers.create(**original)
+except ConflictError as error:
+    delay, token = preparation_retry(error)
+    await asyncio.sleep(delay)
+    c = await client.computers.create(**original, template_transfer=token)
+```
+
+A second refusal is surfaced in both examples so the caller can inspect the
+new state and decide whether another bounded continuation is appropriate.
+
 **The namespace is your account.** `metadata.namespace` has to be your account
 id — anything else is a `PermissionDeniedError`, `system` included — and this SDK
 does not rewrite it, because publishing a ref that is not the one in your file
@@ -295,15 +387,35 @@ normally share an image, which is what makes a repeated build cheap;
 `start(doc, no_reuse=True)` builds again even when an image already carries this
 document's build digest.
 
-**A build that declares its own family is not launchable yet.** The fleet does
-not advertise a family it built rather than shipped, so a create naming such a
-ref is refused with a `400` — a bare `APIError`, and a permanent answer: the
-message says in words that retrying the create changes nothing and that what
-would change it is publishing a new version. Deliberately not a `503`, which
-arrives as `UnavailableError` and reads to a retry loop as an answer worth
-waiting for. A `503` on this path still means the case that does come good: a
-shipped family whose only holder is unreachable. Publishing the document is
-worth doing anyway — it claims the ref, and it is what `builds.start()` takes.
+After a successful build, launch the published template with
+`client.computers.create(template=t.ref)`. A pinned template version selects
+the latest successful image built from that exact document; an unpinned ref
+first selects the newest published template version. Existing computers keep
+their original image when a later build becomes available.
+
+A create may need to prepare that image before it can launch. Follow the
+[template preparation guidance](#your-own-templates) for a
+`template_image_preparing` response: inspect its state and error, then make a
+deliberate continuation with the returned delay and token and all original
+create arguments. For other image refusals, inspect the response before deciding
+whether to rebuild or retry.
+
+Two of those refusals never clear, and both arrive as a `400` — a bare
+`APIError` rather than the `UnavailableError` a `503` becomes, because a retry
+loop reads a `503` as an answer worth waiting for and these are not. A document
+that builds into a family this account may not build into is one: no hypervisor
+will launch it, and what changes the answer is publishing a new version, not
+sending the create again. A document that builds nothing and names an account
+family is the other: a create is served only from the families that ship with
+the product.
+
+The refusals beside them mean something else. A `409` — `ConflictError` — says
+no verified image for this exact document is available yet: finish the build,
+or restore an image that has gone missing or is still being verified. A `503`
+— `UnavailableError` — says no hypervisor has an image for that template *right
+now*, which is the one to retry as it stands. A create can answer `503` for
+capacity as well, and that one is worth a smaller size rather than only a
+wait.
 
 Everything here has an async twin: `await client.templates.publish(doc)`,
 `await client.builds.wait(build.id)`, and `async for p in client.builds.events(...)`.
@@ -322,6 +434,22 @@ c.start()  # resumes it; ~1s, not a boot
 c.stop()  # discards the session instead
 ```
 
+`start(resume_only=True)` resumes a saved session without cold-booting a stopped
+computer. If no saved session remains, the request succeeds and the computer
+stays stopped. The method refreshes and returns the computer; check its state
+when you need to know whether it is running. The async client accepts the same
+keyword. Omit it (or pass `False`) for the ordinary start behavior.
+
+After a stopped no-op, do not chain `wait_until_running()` or `wait_for_guest()`.
+Both reject a stopped computer the platform reports it is holding nothing for,
+which is the ordinary case here; where it reports nothing at all they wait
+instead, and spend the whole timeout. Call ordinary `start()` if you intend to
+boot the computer.
+
+This option requires platform support for `resume_only`. Older servers may
+ignore the parameter and cold-boot a stopped computer; the SDK cannot infer
+support from a successful response.
+
 `stop()` asks the guest to shut down and gives it time to. `stop(force=True)`
 skips the asking and pulls the power — the equivalent of holding the button in.
 It is what to reach for when a guest will not come down on its own, and it loses
@@ -340,8 +468,12 @@ next: `screenshot()` keeps answering, while `clipboard()` starts raising
 `ConflictError`, because a suspended computer has no clipboard to read. Drive
 the desktop, or accept the resume.
 
-`wait_until_running()` raises rather than spinning if it finds a suspended
-computer, because that state does not resolve on its own — `start()` is the fix.
+`wait_until_running()` raises rather than spinning if it finds a suspended or
+stopped computer **that nobody is starting**, because that state does not
+resolve on its own — `start()` is the fix. One whose start the platform has
+already admitted is waited for: a boot reads as stopped and a resume as
+suspended until the guest process exists, so those two statuses do not say on
+their own whether anything is coming.
 
 ### Showing somebody the desktop
 
@@ -843,8 +975,8 @@ on_clipboard = c.clipboard()  # "" is an empty clipboard
 `set_clipboard()` takes at most 64 KiB of UTF-8; `clipboard()` returns at most
 128 KiB. They are different bounds on different channels, and the read is
 **refused rather than truncated** past its own — half a password is not less of
-an answer, it is a wrong one that looks completely normal. Empty text and a NUL
-are refused here, before the request goes out.
+an answer, it is a wrong one that looks completely normal. Empty text clears the
+clipboard; a NUL is refused here, before the request goes out.
 
 The platform confirms the write by reading the selection back before it
 answers, so `set_clipboard()` returning means the desktop is *holding* the text
@@ -854,10 +986,12 @@ rather than that a command ran.
 an `APIError.reason`: `contention` and `starting` clear on their own, while
 `unavailable` and `unsupported` require a different action. `is_transient()`
 therefore answers `True` for the first pair and `False` for the second. A
-stopped or suspended computer is `unavailable`; start it instead of retrying
-the clipboard request. If an older platform response has no recognised reason,
-the SDK preserves the historical `ConflictError` fallback of `True`, so code
-that must support unclassified responses should verify the computer state and
+response classified as `unavailable` requires starting the computer or otherwise
+restoring access, rather than retrying unchanged. Read the returned reason:
+being suspended alone does not determine the classification. If an older
+platform response has no recognised reason, the SDK preserves the historical
+`ConflictError` fallback of `True`, so code that must support unclassified
+responses should verify the computer state and
 keep its retry loop bounded.
 
 Two others worth knowing. A **400** never clears: a computer built from a golden
@@ -916,10 +1050,17 @@ if not result.finished:
 **It runs on your own Anthropic key**, passed as `model_key` and sent on that
 one request as `X-Model-Key`. The platform never stores one, never bills you for
 it, and will not fall back to anything — so the key is a per-call argument
-rather than something the client holds. Every step is a model call plus a
-screenshot on that key, which is why `max_steps` bounds spending as much as it
-bounds the loop. It is a whole number from 1 to 100 — the platform's ceiling,
-which the SDK refuses past rather than spending a round trip to be told.
+rather than something the client holds.
+
+`max_steps` bounds the loop, and bounds your Anthropic spend only loosely. A
+step is one **action on the desktop**, not one exchange with the model, and the
+two do not line up in either direction: one model reply may ask for several
+actions and spends a step on each, while a reply that asks for none — or a
+paused turn, resubmitted — costs tokens and no step at all. Nor does every step
+take a screenshot; a `bash` call or a cursor read does not. Size the run from
+this; size the bill from your own key. It defaults to 20 and is a whole number
+up to 100 — the platform's ceiling, which the SDK refuses past rather than
+spending a round trip to be told.
 
 **The computer must already be running.** This route will not start one for you:
 starting is billable, and it is not a decision to make on your behalf because
@@ -962,6 +1103,15 @@ eight stays an account of eight steps rather than only a message — the spend i
 on a key the platform never meters, and the clicks are still on the desktop.
 `agent_stream()` hands the same record over as an `AgentFailed` event.
 
+`agent_once()` can be stopped the same way, and it arrives differently. The API
+rechecks authorization before each further model call and before each tool, so a
+key revoked, a role dropped, an account suspended or a plan downgraded mid-run
+ends that one request with a 401, a 403 or a 402 rather than with a body — after
+steps that already ran on the desktop and already cost model tokens. Where the
+refusal says how far the run got, `e.agent` carries it there too. What it is not
+is a reason to send the request again: the credential, the role or the plan has
+to change first, and `is_transient()` answers `False` for all three.
+
 ```python
 import mandala_computer as mc
 
@@ -1094,15 +1244,35 @@ times out and a nominated tree never armed, the error says so.
 
 **Match on what `hello` gives back, not on what you sent.** The host normalises
 a nomination — a trailing slash and a `.` segment are cleaned away — and the
-cleaned form is what every event carries in `ev.watch`. `stream.watching` is
-where the answer is, and it carries the half a client gets wrong:
+cleaned form is what every event carries in `ev.watch`. The cleaned nomination
+is where the answer is, and it carries the half a client gets wrong — through
+`on_connect`, which is handed the state as the connection opens, or from
+`stream.watching` once it has:
 
 ```python
-with closing(c.events(watch=["/home/user/out", "/srv/build"])) as stream:
-    for tree in stream.watching or []:
+from contextlib import closing
+from mandala_computer import Hello
+
+
+def show_watches(hello: Hello) -> None:
+    for tree in hello.watching or []:
         print(tree.path, tree.armed)
+
+
+with closing(c.events(watch=["/home/user/out/", "/srv/build"], on_connect=show_watches)) as stream:
+    for ev in stream:
+        if ev.type == "file.changed" and ev.path:
+            print(ev.watch, ev.kind, ev.path)
 ```
 
+Iteration opens the connection and calls `show_watches` with the initial,
+normalised watch state before yielding events. The loop then receives every
+event, including the first; interrupt it when finished, and `closing` releases
+the connection. The callback runs again if the stream reconnects. `on_connect`
+rather than reading `stream.watching` before the loop, because nothing has
+connected yet at that point: read from the stream first and `watching` is
+`None`, which is not the same statement as "nothing armed".
+
 `armed` is whether the tree is *already being watched*. A watch is not live the
 moment the nomination is accepted — the guest has to be asked, and on a computer
 nobody has opened a terminal on the host installs the watcher first — and inotify
@@ -1247,21 +1417,31 @@ def handle(headers: dict[str, str], raw: bytes) -> int:
     if not verify(secret, headers, raw):
         return 401
     event = json.loads(raw)
-    ...
+    ...  # atomically persist the delivery id and enqueue new work durably
     return 200
 ```
 
 `verify` checks the signature against the raw bytes and refuses a
-`webhook-timestamp` more than 300 seconds from your clock. What it cannot do
-for you: remember each `webhook-id` you accept for at least that long and
-refuse a repeat. Retries carry the same id and a fresh signature, so that is
-what makes a delivery processed once. A secret of the wrong shape, or a body
-handed over as text, is a `ValueError` rather than a quiet `False` — neither is
-something a forged request can cause.
-
-Acknowledge with a 2xx *before* doing the work. An attempt is cut at ten
-seconds and counted as a failure; anything else is retried, eight attempts over
-about fourteen hours, and then the delivery is `exhausted` — visible, never
+`webhook-timestamp` more than 300 seconds from your clock. This checks freshness,
+not whether you already handled the delivery. A captured attempt can remain
+valid for up to twice the tolerance after its earliest acceptance, because the
+check accepts timestamps on either side of your clock. Retries also carry the
+same `webhook-id` with a fresh timestamp and signature.
+
+Keep delivery ids in durable storage for the full redelivery horizon your
+receiver supports, with a margin, and cover that captured-attempt validity
+window too. Atomically record the id with the durable enqueue or business
+operation so concurrent requests and crashes cannot admit duplicate work.
+Acknowledge an already recorded delivery without enqueueing it again. A
+retention period alone does not guarantee exactly-once processing; downstream
+work must also handle retries idempotently. A secret of the wrong shape, or a
+body handed over as text, is a `ValueError` rather than a quiet `False` — neither
+is something a forged request can cause.
+
+Acknowledge with a 2xx after that durable acceptance, before doing slow work.
+An attempt is cut at ten seconds and counted as a failure; anything else is
+retried, eight attempts over about fourteen hours, and then the delivery is
+`exhausted` — visible, never
 silently dropped:
 
 ```python
@@ -1291,12 +1471,23 @@ public address — a private, loopback or link-local one is a 400 at create.
 - `wait_until_built()` — a cloned computer's disk has been copied. Only clones
   need this; it returns at once for anything else.
 - `wait_until_running()` — the VM is up. The guest OS is still booting. Raises
-  rather than waiting out the timeout on a failed build or a suspended session,
-  neither of which becomes "running" on its own.
+  rather than waiting out the timeout on a failed build, or on a suspended,
+  stopped or still-building computer the platform is holding nothing for — none
+  of which becomes "running" on its own. A start it HAS admitted is waited for,
+  since a boot reads as stopped and a resume as suspended until the guest
+  process exists; so is a memory-snapshot fork, which reserves its RAM at the
+  start of its disk copy and resumes itself at the end of it while reporting
+  `building` throughout.
 - `wait_for_guest()` — the guest agent answers. Linux and Windows both; the probe
-  is `exit 0`, which bash and cmd.exe both have as a builtin. A failed start or
-  stopped computer is reported immediately. A suspended computer is different:
-  the probe is an `exec()`, so it resumes the session as use normally does.
+  is `exit 0`, which bash and cmd.exe both have as a builtin. A failed start, or
+  a stopped computer nobody is starting, is reported immediately. A suspended
+  computer is different: the probe is an `exec()`, so it resumes the session as
+  use normally does.
+
+Both waits read `running_ram_mb` to tell those apart, and treat its ABSENCE as
+unknown rather than as zero: a host too old to report it, or one that could not
+be reached, has not said nothing is coming. Waiting there costs a timeout;
+refusing would cost a machine.
 
 The last of those is about the agent, not the desktop, and the agent answers
 first — on Windows by a wide margin, since it runs in session 0 and replies
@@ -1765,6 +1956,20 @@ c.write_file("/home/user/app/.env", "API_TOKEN=hunter2\n")
 report = c.read_file("/home/user/report.csv")
 ```
 
+`read_file()` answers **bytes**, because a guest file is not promised to be
+text and decoding one that is not would put replacement characters at the SDK
+boundary for every caller, including the one reading a tarball. When you know
+it is text, `read_text_file()` is the same request with the decode done:
+
+```python
+hostname = c.read_text_file("/etc/hostname")
+```
+
+That decode is `errors="replace"`, so it never raises on a file that turns out
+not to be text — the same bargain `ExecResult.stdout_text` makes, and
+acceptable for the same reason: the caller asked for text, and the bytes are
+one call away.
+
 Guest paths are absolute; a relative path is refused before the request is
 made, because nothing about a transfer runs in a shell with a working
 directory. A transfer resumes a suspended computer, like any other use.
@@ -1863,6 +2068,20 @@ this SDK refuses before it sends anything does not — see [below](#refused-befo
 | `ConnectionInterruptedError` | the request was dispatched and the answer was lost; do not replay a create |
 | `TimeoutError` | a `wait_*` helper gave up, or a request outran its budget |
 
+**401, 403 and 402 can arrive at the end of a wait, not only at the start.**
+Authorization is not settled once per request: the API rechecks it after the
+waits inside a call and before each further piece of work, so a key revoked, a
+membership removed, a role dropped, an account suspended or a plan downgraded
+while a call was in flight comes back as one of those three even though the same
+call was authorized when it was sent. Two consequences worth writing code for.
+None of the three is a transport failure — `is_transient()` answers `False`, and
+repeating the request unchanged gets the same answer. And the refusal is about
+the credential rather than the resource: a 401 here does not mean the computer is
+gone. Where the work is a durable write the API refuses before writing, so a
+`403` on a create, a move, a webhook or a template publish leaves nothing behind;
+the exception is the agent loop, whose completed steps stand (see
+[Letting the platform drive](#letting-the-platform-drive)).
+
 <a name="refused-before-it-was-sent"></a>
 **An argument refused before it was sent is not a `MandalaError`.** Nothing left
 the process when you get one, and there is no status behind it to name: text
@@ -1906,10 +2125,12 @@ length in `size`, which is the whole point of the status: you asked about a file
 whose length you did not know, and the number comes back with the refusal
 instead of behind another request. See [Files](#files).
 
-`RateLimitError` is the only refusal that says how long to wait:
-`retry_after` carries the `Retry-After` header in seconds. Every route on this
-surface is metered, including ones that go on to answer 404 — the meter runs
-before the routing does — so a burst of anything counts against the same budget.
+`APIError.retry_after` carries a valid `Retry-After` header in seconds, including
+on `RateLimitError` and template preparation refusals. It is `None` when that
+metadata is absent or malformed; a delay alone does not make an operation safe
+to retry. Every route on this surface is metered, including ones that go on to
+answer 404 — the meter runs before the routing does — so a burst of anything
+counts against the same budget.
 That budget is generous, in the low thousands of requests a minute even at the
 bottom of the range, so hitting it usually means a poll loop with no sleep in it
 rather than real load.
@@ -1962,10 +2183,10 @@ that creates deserves a look first.
 
 `is_transient(err)` is that rule as a function, and it answers for the riskiest
 caller — code wrapping an arbitrary call, possibly a `create`. It says yes to
-`ConflictError` (minus `MoveRequiredError`), `RateLimitError`, `UnavailableError`
-and `ConnectionError` (minus `ConnectionInterruptedError`), and no to everything
-above whose outcome is unknown, 502 and 504 included. The same four classes, and
-only those, answer yes in the TypeScript and MCP SDKs.
+`ConflictError` (except `MoveRequiredError` and `template_image_preparing`),
+`RateLimitError`, `UnavailableError` and `ConnectionError` (except
+`ConnectionInterruptedError`), and no to everything above whose outcome is
+unknown, 502 and 504 included.
 
 The `wait_*` helpers do not ask it. They replay idempotent reads under a
 deadline you set, so they ride out every 5xx — a hypervisor briefly away during
@@ -1985,15 +2206,18 @@ clears itself: something is in flight that the operation cannot run alongside
 a disk still being copied, a snapshot being taken, a delete already under way, a
 guest agent that has not finished coming up, or a suspend committed to the
 computer a moment before your call. Waiting and retrying is the fix; changing
-the request is not.
-
-Two do not clear. `MoveRequiredError` is one, and it has a class you can catch.
-The other is a clipboard refusal on a stopped or suspended computer: waiting
-will not start it, so `start()` is the fix. Current platform responses classify
-that refusal with `APIError.reason == "unavailable"`, and `is_transient()`
-answers `False`; `contention` and `starting` answer `True`. An absent or unknown
-reason is deliberately treated as unclassified and falls back to the exception
-type, so a legacy `ConflictError` still answers `True`. If you support such
+the request is not. Template preparation is an exception: inspect its state
+and error, then deliberately continue with the returned token and the original
+create arguments when appropriate, as shown above.
+
+Some require a different action. `MoveRequiredError` is one, and it has a class
+you can catch. For clipboard refusals, read `APIError.reason`:
+`unavailable` and `unsupported` make `is_transient()` answer `False`, while
+`contention` and `starting` answer `True`. A suspended computer's read is refused,
+but its status alone does not determine the reason; follow the returned
+classification. An absent or unknown reason is deliberately treated as
+unclassified and falls back to the exception type, so a legacy `ConflictError`
+still answers `True`. If you support such
 responses, check the computer state and keep the retry loop bounded.
 
 A retry loop on it terminates because it has a deadline, not because of any
@@ -2093,11 +2317,13 @@ matter how far behind the client falls, so closing a gap means deleting a line
 from `UNIMPLEMENTED` rather than nobody noticing.
 
 A mirror nobody compares is a comment, though. `scripts/check_surface.py` does
-the comparison against the platform's real route table whenever a checkout of
-the platform is available to it (next door, or wherever `MANDALA_PLATFORM_REPO`
-points — a maintainer's setup, not something a contributor needs), and says so
-and exits 0 when it is not. The suite runs it too: `pytest` skips it where the
-platform is not checked out and fails on drift where it is.
+the comparison against the platform's published surface manifest — a file the
+platform generates from its own tables and commits like a lockfile — whenever a
+checkout of the platform is available to it (next door, or wherever
+`MANDALA_PLATFORM_REPO` points — a maintainer's setup, not something a
+contributor needs), and says so and exits 0 when it is not. A manifest it cannot
+read is a failure, never a comparison of nothing. The suite runs it too: `pytest`
+skips it where the platform is not checked out and fails on drift where it is.
 
 Response objects keep the raw payload in `.raw`, so a server that starts
 returning more fields does not break older clients. `.raw` is evidence rather