mandala-computer-mcp 0.11.0 → 0.13.0

package/dist/errors.d.ts

@@ -4,10 +4,10 @@
  * The distinctions here are the ones an agent has to act on and cannot infer
  * from prose. A 400 never clears and retrying it burns a turn. A 402 is a plan
  * limit, which no amount of waiting fixes and which the user — not the model —
- * has to resolve. A 409 is the one that is not uniform: most of them are a
- * passing state and worth retrying, and some are a decision about the request
- * that no retry turns into a yes — see {@link ConflictError} and
- * {@link MoveRequiredError}.
+ * has to resolve. A 409 is the one that is not uniform: some of them are a
+ * passing state and worth retrying, which the platform says with a `reason`,
+ * and the rest are a decision about the request that no retry turns into a
+ * yes — see {@link ConflictError} and {@link MoveRequiredError}.
  *
  * Mirrors the mapping in mandala-computer-python's `_exceptions.py`, and
  * deliberately so: two clients disagreeing about what a 402 is means the same
@@ -50,6 +50,13 @@ export declare class APIError extends MandalaError {
      * the caller who arrived a moment earlier heard.
      */
     readonly reason?: string;
+    /**
+     * The platform's machine-readable `code` beside `error`, where it sent one:
+     * `LABEL_TAKEN`, `WORKSPACE_MOVING`, `idempotency_in_progress` and so on.
+     * Top-level only, and only a nonblank string; `undefined` otherwise. Like
+     * `reason`, it is the word to switch on, never the sentence.
+     */
+    readonly code?: string;
     /** Response header first, then the top-level body ID; never an idempotency key. */
     readonly requestId?: string;
     /** The received Allow header, when supplied. */
@@ -108,6 +115,32 @@ export declare function reasonKind(reason: string | undefined): ReasonKind | und
  * platform's "absent means unclassified" contract exists to prevent.
  */
 export declare function reasonAdvice(reason: string | undefined): string | undefined;
+/** Whether a 409 carries a code the platform documents as a passing state. */
+export declare function conflictCodeClears(err: APIError): boolean;
+/**
+ * What to tell a model about a refusal the platform named with a `code`, or
+ * `undefined` for a code with nothing to add. Ahead of {@link statusAdvice} in
+ * the formatter, because these codes are more specific than the status:
+ * `PUBLIC_URLS_BLOCKED` is a 403 that is neither a role nor a suspended
+ * account, and `PUBLIC_URLS_DISABLED` is a 404 that is not a missing computer.
+ */
+export declare function codeAdvice(err: APIError): string | undefined;
+/**
+ * A 409 the platform did not classify: no `reason` this version knows, no code
+ * from {@link codeAdvice} or {@link CODE_CLEARS}, and none of the 409s that
+ * carry their own class and say what they are. Not a passing state
+ * (OPL-5975): the platform says absent means no classification.
+ */
+export declare function unclassifiedConflict(err: unknown): boolean;
+/** What a model is told about an {@link unclassifiedConflict}. */
+export declare const UNCLASSIFIED_CONFLICT_ADVICE = "the platform did not say whether this clears, so treat it as one that does not: do not send it again unchanged. The message usually says what to do instead";
+/**
+ * Whether this is the keyed call's "still running" refusal as the platform
+ * documents it: a 409 with code `idempotency_in_progress` that the retry
+ * predicate calls transient. A permanent word beside the code, or another
+ * status, is not that refusal, and earns no "send it again with this key".
+ */
+export declare function idempotencyInProgress(err: APIError): boolean;
 /** The platform's `code` on a keyed call's own refusals (OPL-5127), or `undefined`. */
 export declare function idempotencyCode(err: APIError): string | undefined;
 /**
@@ -240,8 +273,38 @@ export declare function statusAdvice(status: number | undefined, reason?: string
  * `undefined` for a status with nothing to add, so the caller keeps its own
  * wording. A 401 without `revoked` is left to {@link authenticationAdvice},
  * which already says it cannot tell the account key from the model key.
+ *
+ * The one 402 that is Mandala's own is a run on the account's AI credits that
+ * could not reserve its first model call (OPL-5866), and the platform says so
+ * by naming a top-up page. `topUp` is that page, resolved; given, the 402 is
+ * worded as credits run out rather than as the model provider's billing error,
+ * because the fix is on the Mandala billing page and not on a provider account.
+ */
+export declare function agentRunAdvice(status: number | undefined, reason: string | undefined, tool: string, topUp?: string): string | undefined;
+/**
+ * A run on the account's AI credits refused because they cannot cover it.
+ *
+ * Not the model provider, not the plan and not the computer, and waiting does
+ * not change it: the account's balance is what it is until a person tops it up
+ * or a model key is configured. Said so a model reports it rather than retrying.
+ */
+export declare function creditsExhaustedAdvice(topUp: string, tool: string): string;
+/**
+ * The platform's own fixed words for its AI service failing a run on credits,
+ * over the model provider's status. The provider's text never leaves the
+ * platform on such a run, so this sentence is how the failure is recognised.
+ */
+export declare const FUNDED_UNAVAILABLE = "Mandala AI is unavailable";
+/**
+ * A run on AI credits that the platform's AI service could not serve.
+ *
+ * Its status is the model provider's, answering Mandala's own key, so neither
+ * of the usual readings fits: a 401 or 403 is not the caller's credential or
+ * role, a 404 not the computer, a 413 not the request, a 402 not the plan, and
+ * there is no model key of the caller's to check. Steps already taken stand and
+ * were charged, so running the same prompt again would repeat them.
  */
-export declare function agentRunAdvice(status: number | undefined, reason: string | undefined, tool: string): string | undefined;
+export declare function fundedUnavailableAdvice(tool: string): string;
 /** 401 — the key is missing, malformed, or revoked. */
 export declare class AuthenticationError extends APIError {
     name: string;
@@ -265,9 +328,10 @@ export declare class MethodNotAllowedError extends APIError {
 /**
  * 409 — the thing exists but is in the wrong state for this right now.
  *
- * The one status on this list that is usually temporary: a guest still booting,
- * a guest agent busy with another call, a desktop session that has not come up
- * yet. Worth retrying; the others on this list are not.
+ * The one status on this list that is SOMETIMES temporary: a guest still
+ * booting, a guest agent busy with another call, a desktop session that has not
+ * come up yet. Those are worth retrying, and the platform says so with a
+ * `reason`; one without a word is not (OPL-5975, see {@link isTransient}).
  *
  * USUALLY, and the exception is why {@link MoveRequiredError} exists. Whether a
  * 409 clears is a property of the BODY and not of the status: some describe a
@@ -284,9 +348,11 @@ export declare class MethodNotAllowedError extends APIError {
  * with it. The rest stay here and are told apart by {@link APIError.reason},
  * which is the word the platform added for that purpose (OPL-3898) and the one
  * its own reference now says to switch on — never the sentence, which is prose
- * written for a person and rewritten whenever a better one is. Where no word was
- * sent this class means what it always did, and that fallback is the contract
- * rather than a gap: not every refusal here has an answer yet.
+ * written for a person and rewritten whenever a better one is — or by
+ * {@link APIError.code} where the platform documents a code as passing. Where
+ * neither says so, the refusal is unclassified and {@link isTransient} says no
+ * (OPL-5975): not every refusal here has an answer yet, and an unanswered one
+ * is not a promise that waiting helps.
  */
 export declare class ConflictError extends APIError {
     name: string;
@@ -719,8 +785,10 @@ export declare function errorForStatus(status: number, message: string, body?: u
  * because a number can be added to it without anyone having to say which of the
  * three answers changed. It now reads identically in all three:
  *
- * - {@link ConflictError} — something is in flight that this cannot run
- *   alongside, minus the one that is a decision
+ * - {@link ConflictError} — only where the platform says it is passing: a
+ *   `reason` of `contention` or `starting`, or a code it documents as
+ *   passing (`idempotency_in_progress`, `WORKSPACE_MOVING`). A 409 with
+ *   neither is unclassified and not transient (OPL-5975)
  * - {@link RateLimitError} — a cadence, and the response usually says how long
  * - {@link UnavailableError} — something briefly out of reach, for a GET or
  *   HEAD only. Any change answered 503 may have happened, so it is not
@@ -748,7 +816,7 @@ export declare function errorForStatus(status: number, message: string, body?: u
  * be answered after a change landed. So retry reads freely, and check before
  * repeating anything that creates something.
  *
- * Nor is a status enough on its own to answer it. 409 is the case: most of them
+ * Nor is a status enough on its own to answer it. 409 is the case: some of them
  * are a passing state, and the move offer is a decision that no retry changes,
  * which is why the check below leads with the type rather than the number. If a
  * second such refusal earns a class, it belongs on that line too.
@@ -763,18 +831,16 @@ export declare function errorForStatus(status: number, message: string, body?: u
  * absent word — or one this version does not know — leaves the type answer
  * standing unchanged (OPL-3898).
  *
- * One refusal is known to sit on the wrong side of that fallback, and it stays
- * there deliberately (OPL-3909). A computer runs at most sixteen background
- * commands, and the request for a seventeenth is refused 409 with no `reason` —
- * correctly, since the slots may be held by servers and the platform will not
- * advise a retry it cannot promise. The type answer therefore stands, and it
- * says yes to something that may never clear. The alternative is to read the
- * platform's sentence, which is the exported-contract version of the mistake
- * OPL-3724 removed from three clients: a predicate that changes its answer when
- * somebody rewords a message. So the next step is given where the sentence can
- * be read safely — in `exec`, which knows it asked for a slot and which prints
- * the platform's own words either way — and this predicate is left honest about
- * what it can and cannot tell apart.
+ * And the fallback for a 409 with no word is NO, not yes (OPL-5975). It used
+ * to be yes — "a 409 is usually passing" — and that said yes to every refusal
+ * the platform had not classified: a label that is taken, a computer at its
+ * public URL limit, the webhook cap, an SSH key already registered, the
+ * seventeenth background command (OPL-3909, whose slots may be held by servers
+ * and never free). The platform's reference is explicit that an absent
+ * `reason` is no classification and that treating 409 as uniformly transient
+ * loops forever. So a 409 is transient here only when its word clears or its
+ * code is one the platform documents as passing ({@link conflictCodeClears}),
+ * and the same classification holds in both SDKs.
  */
 export declare function isTransient(err: unknown): boolean;
 /**

package/dist/errors.d.ts.map

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

package/dist/errors.js

@@ -4,10 +4,10 @@
  * The distinctions here are the ones an agent has to act on and cannot infer
  * from prose. A 400 never clears and retrying it burns a turn. A 402 is a plan
  * limit, which no amount of waiting fixes and which the user — not the model —
- * has to resolve. A 409 is the one that is not uniform: most of them are a
- * passing state and worth retrying, and some are a decision about the request
- * that no retry turns into a yes — see {@link ConflictError} and
- * {@link MoveRequiredError}.
+ * has to resolve. A 409 is the one that is not uniform: some of them are a
+ * passing state and worth retrying, which the platform says with a `reason`,
+ * and the rest are a decision about the request that no retry turns into a
+ * yes — see {@link ConflictError} and {@link MoveRequiredError}.
  *
  * Mirrors the mapping in mandala-computer-python's `_exceptions.py`, and
  * deliberately so: two clients disagreeing about what a 402 is means the same
@@ -38,6 +38,13 @@ export class APIError extends MandalaError {
      * the caller who arrived a moment earlier heard.
      */
     reason;
+    /**
+     * The platform's machine-readable `code` beside `error`, where it sent one:
+     * `LABEL_TAKEN`, `WORKSPACE_MOVING`, `idempotency_in_progress` and so on.
+     * Top-level only, and only a nonblank string; `undefined` otherwise. Like
+     * `reason`, it is the word to switch on, never the sentence.
+     */
+    code;
     /** Response header first, then the top-level body ID; never an idempotency key. */
     requestId;
     /** The received Allow header, when supplied. */
@@ -54,6 +61,7 @@ export class APIError extends MandalaError {
         this.body = body;
         this.retryAfterMs = retryAfterMs;
         this.reason = refusalReason(body);
+        this.code = record(body) ? nonblank(body.code) : undefined;
         this.requestId =
             nonblank(metadata?.requestId) ?? (record(body) ? nonblank(body.request_id) : undefined);
         this.allow = nonblank(metadata?.allow);
@@ -117,6 +125,8 @@ const REASON_PERMANENT = new Set([
     'running',
     'name_taken',
     'stale_revision',
+    // An evicted screenshot cannot be recovered by replaying its capture name.
+    'stale_capture',
 ]);
 /**
  * How a refusal the platform classified behaves, or `undefined` for a word this
@@ -188,7 +198,11 @@ export function reasonAdvice(reason) {
             // reason code, not a computer — so it names the call that CAN.
             return 'the computer is not running; if nothing is starting it this will not clear on its own and start_computer is the fix, and if a start is already under way wait_for_computer says so without starting a second one';
         case 'unsupported':
-            return 'this computer cannot do it at all, so do not retry it — the answer is the same forever';
+            // Subject-neutral (OPL-5975). It said "this computer cannot do it at
+            // all … the same forever", and the platform sends this word for refusals
+            // that are about no computer and that a step clears: a workspace that
+            // still holds computers or secrets, a workspace change still unsettled.
+            return 'waiting will not change this answer: either it cannot be done at all, or it needs another step first, which the message names. Do not send it again unchanged; take that step, if there is one, and then send it';
         case 'exists':
             // Only THIS attempt is known to have written nothing: a create-only
             // write whose earlier attempt lost its answer may have written the file
@@ -214,6 +228,108 @@ export function reasonAdvice(reason) {
             return undefined;
     }
 }
+/**
+ * The `code`s that mark a 409 as a passing state when its `reason` does not
+ * say otherwise (OPL-5975), taken from the platform's own words for each:
+ *
+ * - `idempotency_in_progress`: the call with this key is still being carried
+ *   out; send it again shortly for its answer. The platform sends it with
+ *   `reason: "contention"` as well, which already says so; the code is named
+ *   so that it is still read as passing if the word is ever missing.
+ * - `WORKSPACE_MOVING`: the computer's workspace change is unsettled; try
+ *   again once the move has finished. Sent with `reason: "contention"` while
+ *   the move is settling, and `reason: "unsupported"` when it is stuck and
+ *   needs checking — the word, read first, decides those two.
+ *
+ * Every other 409 without a reason the platform documents as passing is NOT
+ * a passing state: the platform says an absent `reason` is no
+ * classification, and a client that treats 409 as uniformly transient "loops
+ * forever on half of them". That includes the ones that carry a code and no
+ * word — `LABEL_TAKEN`, `PUBLIC_URL_LIMIT` — and the ones that carry neither:
+ * the webhook cap, a test of a disabled webhook, an SSH key already
+ * registered, the SSH key limit, the sixteen background-command slots.
+ */
+const CODE_CLEARS = new Set(['idempotency_in_progress', 'WORKSPACE_MOVING']);
+/** Whether a 409 carries a code the platform documents as a passing state. */
+export function conflictCodeClears(err) {
+    return err.code !== undefined && CODE_CLEARS.has(err.code);
+}
+/**
+ * What to tell a model about a refusal the platform named with a `code`, or
+ * `undefined` for a code with nothing to add. Ahead of {@link statusAdvice} in
+ * the formatter, because these codes are more specific than the status:
+ * `PUBLIC_URLS_BLOCKED` is a 403 that is neither a role nor a suspended
+ * account, and `PUBLIC_URLS_DISABLED` is a 404 that is not a missing computer.
+ */
+export function codeAdvice(err) {
+    // Each code on the one status the platform sends it with. The same code on
+    // another status is not the refusal this advice describes, and the status's
+    // own advice — a 401 to 405 is never a retry — is left to speak.
+    if (CODE_STATUS[err.code ?? ''] !== err.status)
+        return undefined;
+    // The word first, as in isTransient: a reason this version knows, beside any
+    // code but WORKSPACE_MOVING (whose advice reads the word itself), is the
+    // more specific answer, and its own advice is given instead.
+    if (err.code !== 'WORKSPACE_MOVING' && reasonKind(err.reason) !== undefined)
+        return undefined;
+    switch (err.code) {
+        case 'LABEL_TAKEN':
+            return 'that label is taken, and this does not clear by waiting. A label is never given to a second account, so one another account has ever held, or one the platform has blocked, reads as taken, as does one a URL of this account holds now (list_public_urls shows those). Choose another label, or leave label out to have one picked';
+        case 'PUBLIC_URL_LIMIT':
+            return 'this computer already has as many public URLs as its plan allows, and this does not clear by waiting. Delete one it no longer needs (list_public_urls), point an existing one at this port with update_public_url, or say the plan is the limit';
+        case 'PUBLIC_URLS_BLOCKED':
+            return 'the platform has turned public URLs off for this computer or this account. It is not a role, a credential or anything wrong with the computer, and neither retrying nor waiting changes it: say so to the user, who can contact support if they think it is a mistake';
+        case 'PUBLIC_URLS_DISABLED':
+            return 'public URLs are not enabled here at all. This is not a missing computer or URL, and waiting does not change it: say that public URLs are unavailable';
+        case 'WORKSPACE_MOVING':
+            // The word decides, as it does in isTransient: `unsupported` is the
+            // stuck change, which a step clears. Otherwise "send it again" is said
+            // only where isTransient agrees — never over a permanent word, a nested
+            // word (which grants no retry), or anything else it calls final.
+            if (err.reason === 'unsupported')
+                return 'this computer\u2019s workspace change is not settled, and waiting alone will not settle it. Repeating the same move_computer_to_workspace call reconciles it, or check the workspace change in the dashboard; then send this again';
+            if (!isTransient(err))
+                return undefined;
+            return 'this computer is being moved to another workspace; this clears once the move has finished, so wait a moment and send it again';
+        default:
+            return undefined;
+    }
+}
+/** The status each code in {@link codeAdvice} arrives with. */
+const CODE_STATUS = {
+    LABEL_TAKEN: 409,
+    PUBLIC_URL_LIMIT: 409,
+    PUBLIC_URLS_BLOCKED: 403,
+    PUBLIC_URLS_DISABLED: 404,
+    WORKSPACE_MOVING: 409,
+};
+/**
+ * A 409 the platform did not classify: no `reason` this version knows, no code
+ * from {@link codeAdvice} or {@link CODE_CLEARS}, and none of the 409s that
+ * carry their own class and say what they are. Not a passing state
+ * (OPL-5975): the platform says absent means no classification.
+ */
+export function unclassifiedConflict(err) {
+    return (err instanceof ConflictError &&
+        !(err instanceof MoveRequiredError) &&
+        !(err instanceof FileExistsError) &&
+        !(err instanceof CreateOnlyConflictError) &&
+        reasonKind(err.reason) === undefined &&
+        !conflictCodeClears(err) &&
+        codeAdvice(err) === undefined &&
+        idempotencyCode(err) === undefined);
+}
+/** What a model is told about an {@link unclassifiedConflict}. */
+export const UNCLASSIFIED_CONFLICT_ADVICE = 'the platform did not say whether this clears, so treat it as one that does not: do not send it again unchanged. The message usually says what to do instead';
+/**
+ * Whether this is the keyed call's "still running" refusal as the platform
+ * documents it: a 409 with code `idempotency_in_progress` that the retry
+ * predicate calls transient. A permanent word beside the code, or another
+ * status, is not that refusal, and earns no "send it again with this key".
+ */
+export function idempotencyInProgress(err) {
+    return (err.status === 409 && idempotencyCode(err) === 'idempotency_in_progress' && isTransient(err));
+}
 /** The platform's `code` on a keyed call's own refusals (OPL-5127), or `undefined`. */
 export function idempotencyCode(err) {
     const code = record(err.body) ? err.body.code : undefined;
@@ -239,6 +355,11 @@ export function idempotencyAdvice(err, tool) {
         : undefined;
     switch (idempotencyCode(err)) {
         case 'idempotency_in_progress':
+            // Only the passing refusal the platform documents: a word beside the
+            // code that does not clear, or another status, is answered by its own
+            // advice instead (Codex, round 4 on #213).
+            if (!idempotencyInProgress(err))
+                return undefined;
             return `the same call with this idempotency_key is still running; wait and call again with the same idempotency_key for its answer${operation ? `, or read get_operation ${operation}` : ''}`;
         case 'idempotency_outcome_unknown':
             return `the platform did not hear how the call with this idempotency_key ended; do not send it again with this key, since the same key answers the same thing. ${resendAfterSpentKey(tool, operation, undefined, tool ? `call ${tool} again` : undefined)}`;
@@ -380,8 +501,7 @@ export function resendOnlyOnceFinal(operation, key, resend = 'send the call agai
 export function keyedOutcomeUnknown(err) {
     return (err instanceof ConnectivityInterruptedError ||
         (err instanceof APIError &&
-            (idempotencyCode(err) === 'idempotency_in_progress' ||
-                (err.status >= 500 && !platformAnsweredFailure(err)))));
+            (idempotencyInProgress(err) || (err.status >= 500 && !platformAnsweredFailure(err)))));
 }
 /**
  * Whether a `5xx` came from the platform itself rather than from a hop in
@@ -465,8 +585,16 @@ export function statusAdvice(status, reason) {
  * `undefined` for a status with nothing to add, so the caller keeps its own
  * wording. A 401 without `revoked` is left to {@link authenticationAdvice},
  * which already says it cannot tell the account key from the model key.
+ *
+ * The one 402 that is Mandala's own is a run on the account's AI credits that
+ * could not reserve its first model call (OPL-5866), and the platform says so
+ * by naming a top-up page. `topUp` is that page, resolved; given, the 402 is
+ * worded as credits run out rather than as the model provider's billing error,
+ * because the fix is on the Mandala billing page and not on a provider account.
  */
-export function agentRunAdvice(status, reason, tool) {
+export function agentRunAdvice(status, reason, tool, topUp) {
+    if (status === 402 && topUp)
+        return creditsExhaustedAdvice(topUp, tool);
     const noReplay = `Do not call ${tool} again with the same task: completed steps were already billed, so read what they did first`;
     if (status === 403 && reason === 'revoked') {
         return `this Mandala account no longer permits the run — a role that changed or an account suspended, not anything wrong with the computer. Nothing you can send changes that, and a new credential does not either: say what was refused and stop. ${noReplay}`;
@@ -485,6 +613,34 @@ export function agentRunAdvice(status, reason, tool) {
         return undefined;
     return `this is the model provider's own status for the configured model key (its ${provider}), not the Mandala plan and not the computer — check the model-provider account${status === 402 ? '' : ' and its status page, and try later'}. ${noReplay}`;
 }
+/**
+ * A run on the account's AI credits refused because they cannot cover it.
+ *
+ * Not the model provider, not the plan and not the computer, and waiting does
+ * not change it: the account's balance is what it is until a person tops it up
+ * or a model key is configured. Said so a model reports it rather than retrying.
+ */
+export function creditsExhaustedAdvice(topUp, tool) {
+    return `this Mandala account's AI credits cannot cover the run — not the model provider, the plan or the computer. Waiting does not change it: a person can top up at ${topUp}, or configure their own model key. Say so and do not call ${tool} again until then`;
+}
+/**
+ * The platform's own fixed words for its AI service failing a run on credits,
+ * over the model provider's status. The provider's text never leaves the
+ * platform on such a run, so this sentence is how the failure is recognised.
+ */
+export const FUNDED_UNAVAILABLE = 'Mandala AI is unavailable';
+/**
+ * A run on AI credits that the platform's AI service could not serve.
+ *
+ * Its status is the model provider's, answering Mandala's own key, so neither
+ * of the usual readings fits: a 401 or 403 is not the caller's credential or
+ * role, a 404 not the computer, a 413 not the request, a 402 not the plan, and
+ * there is no model key of the caller's to check. Steps already taken stand and
+ * were charged, so running the same prompt again would repeat them.
+ */
+export function fundedUnavailableAdvice(tool) {
+    return `the platform's AI service could not serve this run on credits — its model provider answered this status, which is not the computer, your credential or the plan, and there is no key of yours to check. Waiting can clear it. If no step ran, ${tool} can be tried again later; if steps ran, they stand and were charged, so read what they did and send only what is left`;
+}
 /**
  * The platform's one-word classification off a refusal body, or `undefined`.
  *
@@ -527,9 +683,10 @@ export class MethodNotAllowedError extends APIError {
 /**
  * 409 — the thing exists but is in the wrong state for this right now.
  *
- * The one status on this list that is usually temporary: a guest still booting,
- * a guest agent busy with another call, a desktop session that has not come up
- * yet. Worth retrying; the others on this list are not.
+ * The one status on this list that is SOMETIMES temporary: a guest still
+ * booting, a guest agent busy with another call, a desktop session that has not
+ * come up yet. Those are worth retrying, and the platform says so with a
+ * `reason`; one without a word is not (OPL-5975, see {@link isTransient}).
  *
  * USUALLY, and the exception is why {@link MoveRequiredError} exists. Whether a
  * 409 clears is a property of the BODY and not of the status: some describe a
@@ -546,9 +703,11 @@ export class MethodNotAllowedError extends APIError {
  * with it. The rest stay here and are told apart by {@link APIError.reason},
  * which is the word the platform added for that purpose (OPL-3898) and the one
  * its own reference now says to switch on — never the sentence, which is prose
- * written for a person and rewritten whenever a better one is. Where no word was
- * sent this class means what it always did, and that fallback is the contract
- * rather than a gap: not every refusal here has an answer yet.
+ * written for a person and rewritten whenever a better one is — or by
+ * {@link APIError.code} where the platform documents a code as passing. Where
+ * neither says so, the refusal is unclassified and {@link isTransient} says no
+ * (OPL-5975): not every refusal here has an answer yet, and an unanswered one
+ * is not a promise that waiting helps.
  */
 export class ConflictError extends APIError {
     name = 'ConflictError';
@@ -1242,8 +1401,10 @@ export function errorForStatus(status, message, body, retryAfterMs, metadata) {
  * because a number can be added to it without anyone having to say which of the
  * three answers changed. It now reads identically in all three:
  *
- * - {@link ConflictError} — something is in flight that this cannot run
- *   alongside, minus the one that is a decision
+ * - {@link ConflictError} — only where the platform says it is passing: a
+ *   `reason` of `contention` or `starting`, or a code it documents as
+ *   passing (`idempotency_in_progress`, `WORKSPACE_MOVING`). A 409 with
+ *   neither is unclassified and not transient (OPL-5975)
  * - {@link RateLimitError} — a cadence, and the response usually says how long
  * - {@link UnavailableError} — something briefly out of reach, for a GET or
  *   HEAD only. Any change answered 503 may have happened, so it is not
@@ -1271,7 +1432,7 @@ export function errorForStatus(status, message, body, retryAfterMs, metadata) {
  * be answered after a change landed. So retry reads freely, and check before
  * repeating anything that creates something.
  *
- * Nor is a status enough on its own to answer it. 409 is the case: most of them
+ * Nor is a status enough on its own to answer it. 409 is the case: some of them
  * are a passing state, and the move offer is a decision that no retry changes,
  * which is why the check below leads with the type rather than the number. If a
  * second such refusal earns a class, it belongs on that line too.
@@ -1286,18 +1447,16 @@ export function errorForStatus(status, message, body, retryAfterMs, metadata) {
  * absent word — or one this version does not know — leaves the type answer
  * standing unchanged (OPL-3898).
  *
- * One refusal is known to sit on the wrong side of that fallback, and it stays
- * there deliberately (OPL-3909). A computer runs at most sixteen background
- * commands, and the request for a seventeenth is refused 409 with no `reason` —
- * correctly, since the slots may be held by servers and the platform will not
- * advise a retry it cannot promise. The type answer therefore stands, and it
- * says yes to something that may never clear. The alternative is to read the
- * platform's sentence, which is the exported-contract version of the mistake
- * OPL-3724 removed from three clients: a predicate that changes its answer when
- * somebody rewords a message. So the next step is given where the sentence can
- * be read safely — in `exec`, which knows it asked for a slot and which prints
- * the platform's own words either way — and this predicate is left honest about
- * what it can and cannot tell apart.
+ * And the fallback for a 409 with no word is NO, not yes (OPL-5975). It used
+ * to be yes — "a 409 is usually passing" — and that said yes to every refusal
+ * the platform had not classified: a label that is taken, a computer at its
+ * public URL limit, the webhook cap, an SSH key already registered, the
+ * seventeenth background command (OPL-3909, whose slots may be held by servers
+ * and never free). The platform's reference is explicit that an absent
+ * `reason` is no classification and that treating 409 as uniformly transient
+ * loops forever. So a 409 is transient here only when its word clears or its
+ * code is one the platform documents as passing ({@link conflictCodeClears}),
+ * and the same classification holds in both SDKs.
  */
 export function isTransient(err) {
     if (err instanceof APIError && [401, 402, 403, 404, 405].includes(err.status))
@@ -1350,15 +1509,27 @@ export function isTransient(err) {
         // Through the exported classifier rather than the sets directly, so what an
         // embedder is told and what this server does are one answer and not two.
         const kind = reasonKind(err.reason);
-        // A nested run reason can arrive after billed work and grants no new replay permission.
-        if (kind === 'clears' && record(err.body) && typeof err.body.reason === 'string')
-            return true;
+        if (kind === 'clears') {
+            // A nested run reason can arrive after billed work and grants no replay
+            // permission, whatever code sits beside it.
+            if (!(record(err.body) && typeof err.body.reason === 'string'))
+                return false;
+            // The word describes a refusal: a 400 or a 409. On any other status the
+            // status's own answer stands, as in both SDKs.
+            if (err.status === 400 || err.status === 409)
+                return true;
+        }
         if (kind === 'permanent')
             return false;
     }
-    return (err instanceof ConflictError ||
-        err instanceof RateLimitError ||
-        err instanceof ConnectivityError);
+    // A 409 is a passing state only where the platform says so (OPL-5975): a
+    // word that clears, above, or a code it documents as passing. One with
+    // neither is unclassified, and the platform's own reference says a client
+    // treating 409 as uniformly transient loops forever on half of them — a
+    // label that is taken, a computer at its URL limit, a webhook cap.
+    if (err instanceof ConflictError)
+        return conflictCodeClears(err);
+    return err instanceof RateLimitError || err instanceof ConnectivityError;
 }
 /**
  * The same words, a different question: worth POLLING again.