privateer-agent 0.12.38 → 0.12.40

package/extensions/privateer-gate.ts

@@ -25,6 +25,7 @@ import { makeSaveCargoTool } from "../src/tools/cargo.ts";
 import { makeChartTools } from "../src/tools/charts.ts";
 import { makeSaveAttachmentTool } from "../src/tools/saveAttachment.ts";
 import { AttachmentStore, type StoredAttachment } from "../src/util/attachmentStore.ts";
+import { resolveMentions, searchFiles } from "../src/util/fileMentions.ts";
 import { makeExtensionsControl } from "../src/remote/extensionsControl.ts";
 import { makeSkillsControl } from "../src/remote/skillsControl.ts";
 import { agentDir } from "../src/config/paths.ts";
@@ -48,7 +49,9 @@ const allowedOutsideRoots: string[] = [];
 // SECOND prompt arriving while Pi is still processing — which throws "Agent is already
 // processing" and wedges the session. This happens in normal use when the app drops
 // (backgrounded → socket suspended) and re-sends its prompt on reconnect. Mirrors the
-// REPL's `turnActive` guard. Set on a successful sendUserMessage, cleared on agent_end.
+// REPL's `turnActive` guard. Claimed as soon as a prompt is accepted — ahead of the
+// mention expansion, which reads files and so opens a window a second prompt could
+// slip through — released again if the send fails, cleared on agent_end.
 let remoteTurnActive = false;
 
 let piRef: any = null;
@@ -149,7 +152,7 @@ async function switchModelRemote(spec: string): Promise<void> {
     const ok = await piRef?.setModel?.(model);
     if (ok === false) { relay?.sendNotice(`No API key for ${p} — can't switch to ${sp}.`); return; }
     currentSpec = sp;
-    relay?.sendContext({ model: currentSpec, version: agentVersion() }); // banner follows
+    relay?.sendContext({ model: currentSpec, cwd: process.cwd(), version: agentVersion() }); // banner follows
     relay?.sendNotice(`model → ${sp}`);
   } catch (e) {
     relay?.sendNotice(`Couldn't switch model: ${(e as Error).message}`);
@@ -344,6 +347,12 @@ const bridge = new RemoteBridge({
       relay?.sendNotice("busy — a turn is already running; wait for it to finish.");
       return;
     }
+    // Claim the turn BEFORE the awaits below, not after the send. Expanding mentions
+    // reads files, so the send is no longer synchronous with this callback — a second
+    // prompt arriving in that window would pass the guard above and land Pi with two
+    // turns. Released again on any failure path, so a refused send can't wedge the
+    // bridge; the success path leaves it set until agent_end.
+    remoteTurnActive = true;
     // Fold any files the app sent since the last prompt into a reference note so the
     // model knows they exist and can save_attachment them.
     const atts = sinceLastPrompt;
@@ -352,14 +361,32 @@ const bridge = new RemoteBridge({
       ? `\n\n[Files attached from the app: ${atts.map((a) => `#${a.n} ${a.name} (${a.mediaType})`).join(", ")}. ` +
         `Use the save_attachment tool with the ref number to write one to disk.]`
       : "";
-    try {
-      piRef?.sendUserMessage?.(text + note); // drive a turn in Pi's TUI
-      remoteTurnActive = true; // cleared on agent_end
-    } catch (e) {
-      // A synchronous "already processing" (or any send failure) must not wedge the
-      // bridge — surface it and stay idle so the next prompt still works.
-      relay?.sendNotice(`couldn't start turn: ${(e as Error).message}`);
-    }
+    void (async () => {
+      try {
+        // Expand any `@path` mentions into appended <file> blocks + image attachments,
+        // resolved against this terminal's cwd (constrained to the cwd subtree). The
+        // REPL (src/cli/chat.ts) and the desktop session (agentSession.ts) both do this;
+        // the shipped TUI did not, so the one surface with no Tab key — a phone driving
+        // this terminal — was the only one where `@file` did nothing at all.
+        const cwd = process.cwd();
+        const mentions = await resolveMentions(text, cwd);
+        if (mentions.skipped.length) {
+          relay?.sendNotice(`Couldn't attach: ${mentions.skipped.join(", ")} (must be a file inside ${cwd})`);
+        }
+        const body = mentions.text + note;
+        // Images ride as content parts — pi's sendUserMessage takes the same
+        // {type:"image",data,mimeType} shape resolveMentions already emits, so a
+        // mentioned screenshot reaches the model as a real attachment, not a path.
+        piRef?.sendUserMessage?.(
+          mentions.images.length ? [{ type: "text", text: body }, ...mentions.images] : body,
+        ); // drive a turn in Pi's TUI
+      } catch (e) {
+        // An "already processing" (or any send/expansion failure) must not wedge the
+        // bridge — surface it and stay idle so the next prompt still works.
+        remoteTurnActive = false;
+        relay?.sendNotice(`couldn't start turn: ${(e as Error).message}`);
+      }
+    })();
   },
   onInterrupt: () => {}, // Pi owns interrupt; best-effort no-op
   // The app asked to end remote access from its side — stop the relay locally too so
@@ -383,10 +410,23 @@ const bridge = new RemoteBridge({
     // terminal, and advertise the slash commands for the composer's autocomplete.
     setRemoteState("connected");
     relay?.sendSnapshot([{ kind: "notice", text: "Privateer terminal connected." }]);
-    relay?.sendContext({ model: currentSpec, version: agentVersion() });
+    // cwd rides along here (home-collapsed on the way out, see RelayClient.sendContext).
+    // Without it the app's composer shows no working-directory strip at all — and that
+    // strip is the only place a driver can see which folder the prompts they type are
+    // reading, writing and `@`-mentioning against.
+    relay?.sendContext({ model: currentSpec, cwd: process.cwd(), version: agentVersion() });
     relay?.sendCommands(advertiseCommands());
   },
   onAttachment: (file) => sinceLastPrompt.push(attachments.register(file)),
+  // The app composer is autocompleting an `@file` mention — list the cwd entries
+  // matching the query and reply. Read-only + cwd-constrained (searchFiles never
+  // escapes the subtree); resolution of the picked path happens in onPrompt above.
+  // Unanswered, the app's searchFiles() times out to [] after 4s and the palette
+  // reads "no files" — indistinguishable from an empty project.
+  onFilesSearch: (id, query) => void (async () => {
+    try { bridge.sendFileMatches(id, await searchFiles(query, process.cwd())); }
+    catch { bridge.sendFileMatches(id, []); }
+  })(),
   // Drive the indicator from the relay's own status stream: "connected" → green;
   // its reconnect/retry notices → yellow "connecting…". Ignored once we're off.
   onStatus: (text) => {
@@ -528,7 +568,7 @@ export default function privateerControl(pi: any): void {
   pi.on("model_select", (ev: any) => {
     if (ev?.model) {
       currentSpec = modelSpec(ev.model);
-      relay?.sendContext({ model: currentSpec, version: agentVersion() });
+      relay?.sendContext({ model: currentSpec, cwd: process.cwd(), version: agentVersion() });
     }
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.38",
+  "version": "0.12.40",
   "description": "Privacy-first terminal coding agent — bring your own model across 20 providers (Anthropic, OpenAI, OpenRouter, Google, local Ollama…). Safe-by-default permissions, MCP, sub-agents, workflows, and verifiable TEE inference. Built on the Pi toolkit.",
   "type": "module",
   "license": "MIT",

package/src/auth/accountSessions.ts

@@ -5,9 +5,10 @@
 // only a CLEAN exit revoked it (session_shutdown → revokeLocalSessions). A terminal
 // that dies without running its shutdown hook — SIGKILL, a closed window, a crash,
 // `kill` — leaves its session row alive server-side for the rest of its ~24h TTL. Do
-// that a few times and the next spawn is refused with
-// `429 CHILD_SESSION_CAP: Too many active terminals for this device`, which takes the
-// whole account channel down until the rows age out.
+// that a few times and the account accumulates a pile of live rows nobody owns. (There
+// used to be a per-device cap that refused the next spawn outright, which took the whole
+// account channel down until the rows aged out; it is gone, and this is what keeps the
+// row count sane without one.)
 //
 // The fix is to reclaim an orphan instead of stacking another row on top of it. That
 // needs one bit the credential itself can't tell us: is the terminal that owns it

package/src/auth/privateer.ts

@@ -158,8 +158,9 @@ let _refreshInFlight: Promise<ChildSession> | null = null;
 //
 // That pairing only covers a CLEAN exit, though. A terminal killed without running its
 // shutdown hook leaves its row alive server-side for the full TTL, and the next launch
-// used to spawn another on top of it — enough repeats and the spawn is refused with
-// `429 CHILD_SESSION_CAP`. So every session is also recorded in a pid-keyed registry
+// used to spawn another on top of it — so a few crashes left a pile of live rows nobody
+// owned (which used to be refused outright by a per-device cap the server has since
+// dropped). So every session is also recorded in a pid-keyed registry
 // (auth/accountSessions.ts) and acquireAccountCredential reclaims one whose owning
 // terminal is gone instead of spawning. Keep the registry in step with reality:
 // recordOwnedSession wherever a credential is minted or rotated, forgetOwnedSession
@@ -445,9 +446,8 @@ export async function runDeviceLogin(opts: {
 //
 // A 401 means the parent refresh token is gone — the machine login itself is dead, so
 // clear it and announce (the UI flips to signed-out). EVERY OTHER status used to be
-// reported as an expiry too, which actively misled: the common one is 429
-// `CHILD_SESSION_CAP` ("Too many active terminals for this device. Sign one out and
-// try again"), where /login is not the fix and the credentials are perfectly valid.
+// reported as an expiry too, which actively misled: a rate limit or a server-side
+// refusal is not something /login fixes, and the credentials are perfectly valid.
 // Pass the server's own message through so the user learns what to actually do.
 async function spawnFailure(res: Response): Promise<Error> {
   if (res.status === 401) {

package/src/permissions/classify.ts

@@ -225,6 +225,10 @@ const MEDIA_TITLES: Record<string, string> = {
   video_compose: "Compose video/audio locally",
   media_capabilities: "Read media capabilities",
 };
+// Not in MEDIA_TITLES: they are the same tools, told apart by their arguments
+// rather than their names (see `resuming` below).
+const RESUME_VIDEO_TITLE = "Save a video already generated (nothing further is billed)";
+const RESUME_SPRITE_TITLE = "Save a sprite animation already generated (nothing further is billed)";
 
 export function classifyToolCall(
   toolName: string,
@@ -478,6 +482,18 @@ export function classifyToolCall(
   // even when the output lands neatly in cwd.
   if (MEDIA_TOOLS.has(name)) {
     const compose = name === "video_compose";
+    // A generate_video or generate_sprite RESUME submits nothing and bills nothing —
+    // it goes back to waiting on a job the account has already paid for and writes the
+    // files. So it is an ordinary write, not a billed one: the title must not claim a
+    // charge that isn't happening, and `alwaysAsk` must not make re-prompting the
+    // cheaper path than re-generating. Getting that backwards is what teaches a model
+    // to pay twice — and it costs the most on a sprite, where the alternative to a
+    // resume is a whole second fan-out of up to five video generations.
+    const resumable = name === "generate_video" || name === "generate_sprite";
+    const resuming = resumable && typeof obj.resumeJobId === "string" && !!obj.resumeJobId.trim();
+    const mediaTitle = resuming
+      ? (name === "generate_sprite" ? RESUME_SPRITE_TITLE : RESUME_VIDEO_TITLE)
+      : MEDIA_TITLES[name];
     const inputs = [
       ...(Array.isArray(obj.inputs) ? (obj.inputs as unknown[]).map(str) : []),
       str(obj.input),
@@ -549,13 +565,11 @@ export function classifyToolCall(
     return {
       tool: toolName,
       kind: "write",
-      title: outside
-        ? `${MEDIA_TITLES[name]} outside working directory`
-        : MEDIA_TITLES[name],
+      title: outside ? `${mediaTitle} outside working directory` : mediaTitle,
       detail: `${outputOutside ? absOut : outPath}${inputNote}`,
       protected: isProtectedPath(absOut) || protectedInputs.length > 0,
       outside,
-      alwaysAsk: BILLED_MEDIA_TOOLS.has(name),
+      alwaysAsk: BILLED_MEDIA_TOOLS.has(name) && !resuming,
       path: absOut,
     };
   }

package/src/tools/media.ts

@@ -38,8 +38,9 @@
 // stitch → score → send.
 
 import { Type } from "typebox";
-import { mkdirSync, readFileSync, writeFileSync, existsSync, statSync } from "node:fs";
-import { dirname, extname, isAbsolute, resolve } from "node:path";
+import { mkdirSync, readFileSync, writeFileSync, unlinkSync, existsSync, statSync } from "node:fs";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
 import { apiRequest } from "../auth/privateer.ts";
 
 /** Tool names these definitions register, for allow-list construction. */
@@ -56,18 +57,37 @@ export const MEDIA_TOOL_NAMES = [
 
 // A video job can legitimately take minutes. Bound the wait so a wedged provider
 // doesn't pin an unattended run forever; the job id is reported on timeout so the
-// caller can resume the poll rather than pay for another generation.
-const VIDEO_POLL_TIMEOUT_MS = Number(process.env.PRIVATEER_VIDEO_TIMEOUT_MS) || 12 * 60_000;
+// caller can resume the poll (`resumeJobId`) rather than pay for another generation.
+//
+// TWENTY-FIVE, AND THE RESUME PARAM, ARE ONE FIX. At twelve this was the only
+// surface that gave up on a job at all — the app's own poller (ChatScreen,
+// libraryService) runs on a bare setInterval with no deadline, so the identical
+// job that lands fine in a chat was abandoned in a terminal — and there was
+// nothing to resume WITH: `generate_video` took no job id, so the sentence above
+// described a recovery the tool could not perform. The model's only move was to
+// call generate_video again, which bills a second generation and starts a second
+// wait, which is what "video generation hangs" looks like from the outside.
+//
+// The ceiling stays because an unattended run must not be pinned forever, and 25
+// is not arbitrary: the desktop's turn supervisor abandons a turn whose open tool
+// has been silent for 30 minutes (desktop/src/main/turnSupervisor.ts toolStallMs),
+// and a tool that outlives its own supervisor is abandoned mid-poll with the job
+// uncollected — exactly the failure this is fixing. Keep it under that budget.
+const VIDEO_POLL_TIMEOUT_MS = Number(process.env.PRIVATEER_VIDEO_TIMEOUT_MS) || 25 * 60_000;
 const VIDEO_POLL_INTERVAL_MS = 5_000;
 // A mesh job runs about a minute at the provider's stated typical time, and
 // several for a large face count. Same bounded-wait contract as video: the job
 // id is reported on timeout so the caller can resume the poll rather than pay
 // for a second generation.
 const MESH_POLL_TIMEOUT_MS = Number(process.env.PRIVATEER_MESH_TIMEOUT_MS) || 10 * 60_000;
-// A sprite job renders one clip per BILLED facing, sequentially, so an eight-way
-// set waits on five video generations rather than one. The ceiling is
-// correspondingly generous; as with video, the job id is reported on timeout so
-// the caller can resume the poll rather than pay for another run.
+// A sprite job renders one clip per BILLED facing, so an eight-way set waits on
+// five video generations rather than one. They are SUBMITTED in one pass and
+// render together at the provider (spriteApiHandler submits the whole fan-out
+// before returning the 202), so the wait is roughly one clip's — what is serial
+// is the stage BEFORE it, where the picture is turned to face each direction one
+// edit at a time. The ceiling is correspondingly generous; as with video, the job
+// id is reported on timeout and `resumeJobId` is what goes back to it, so a slow
+// job is never a reason to pay for a second fan-out.
 const SPRITE_POLL_TIMEOUT_MS = Number(process.env.PRIVATEER_SPRITE_TIMEOUT_MS) || 25 * 60_000;
 const SPRITE_POLL_INTERVAL_MS = 6_000;
 const MESH_POLL_INTERVAL_MS = 5_000;
@@ -135,6 +155,15 @@ function readInputImage(cwd: string, p: string): { data: string; mimeType: strin
 interface AccountFailure {
   ok: false;
   message: string;
+  /**
+   * The HTTP status behind the failure, or undefined when the request never got
+   * an answer at all (DNS, reset, offline). A POLLER needs this and a one-shot
+   * caller does not: abandoning a paid job because one poll returned 502 throws
+   * the job away, while retrying a 404 or a 410 forever is just as wrong. The
+   * status is the only thing that separates the two, so it is carried rather
+   * than flattened into the message.
+   */
+  status?: number;
 }
 
 /**
@@ -182,31 +211,31 @@ async function callAccount<T>(
   // by the user (not by the model) — say exactly which switch to change and stop.
   if (code === "ZDR_MEDIA_BLOCKED") {
     return {
-      ok: false,
+      ok: false, status: res.status,
       message:
         (serverMessage || "this account requires Zero Data Retention and the media model has no ZDR endpoint") +
         " — this is a privacy setting only the account owner can change (Settings → Privacy), so do not retry.",
     };
   }
   if (code === "ZDR_KEY_UNAVAILABLE") {
-    return { ok: false, message: serverMessage || "no zero-retention provider key is available right now — try again later" };
+    return { ok: false, status: res.status, message: serverMessage || "no zero-retention provider key is available right now — try again later" };
   }
   if (/DAILY_CAP|LIMIT_REACHED/i.test(code) || res.status === 429) {
-    return { ok: false, message: serverMessage || "the account's daily media allowance is used up — it resets tomorrow" };
+    return { ok: false, status: res.status, message: serverMessage || "the account's daily media allowance is used up — it resets tomorrow" };
   }
   if (res.status === 402 || /INSUFFICIENT|QUOTA|TOP_?UP/i.test(code)) {
-    return { ok: false, message: serverMessage || "the account is out of credit for media generation — top up or upgrade to continue" };
+    return { ok: false, status: res.status, message: serverMessage || "the account is out of credit for media generation — top up or upgrade to continue" };
   }
   if (res.status === 401 || res.status === 403) {
     return {
-      ok: false,
+      ok: false, status: res.status,
       message:
         serverMessage ||
         "this agent is not signed in to a Privateer account (or the plan doesn't include this), so it cannot generate media",
     };
   }
   if (res.status === 400 || res.status === 413) {
-    return { ok: false, message: serverMessage || `Privateer rejected the request${code ? ` (${code})` : ""}` };
+    return { ok: false, status: res.status, message: serverMessage || `Privateer rejected the request${code ? ` (${code})` : ""}` };
   }
   // 503/504 are OUR outage or a provider timing out, not a bad request: an unset
   // provider key, our own balance with that provider, or a slow job. Retrying the same
@@ -214,11 +243,11 @@ async function callAccount<T>(
   // good prompt in the belief it caused this.
   if (res.status === 503 || res.status === 504) {
     return {
-      ok: false,
+      ok: false, status: res.status,
       message: `${serverMessage || "that media service is temporarily unavailable"} — this is on Privateer's side, not the prompt's; try again in a few minutes`,
     };
   }
-  return { ok: false, message: serverMessage || `media generation failed (HTTP ${res.status}${code ? ` ${code}` : ""})` };
+  return { ok: false, status: res.status, message: serverMessage || `media generation failed (HTTP ${res.status}${code ? ` ${code}` : ""})` };
 }
 
 // ── Images ───────────────────────────────────────────────────────────────────
@@ -334,10 +363,18 @@ export const generateVideoToolDefinition = {
     "extracted with video_compose, then start the next from it. Generation takes minutes and this tool " +
     "waits for it. Expensive (roughly $0.10-$1 a clip) and billed to the user's Privateer account, so " +
     "plan the shot before calling. Clip lengths and aspect ratios are model-specific — check " +
-    "media_capabilities first if unsure. Stitch the finished clips with video_compose.",
+    "media_capabilities first if unsure. Stitch the finished clips with video_compose.\n" +
+    "If a call comes back saying the job is still running, DO NOT call this again with the same " +
+    "prompt — that bills a second generation. Call it with `resumeJobId` set to the job id it " +
+    "reported (and the same `path`) to keep waiting on the clip the account has already paid for.",
   parameters: Type.Object({
     prompt: Type.String({ description: "What happens in the shot: subject, action, camera move, style." }),
     path: Type.String({ description: "Where to write the video, relative to cwd or absolute (e.g. 'clips/01-opening.mp4')." }),
+    resumeJobId: Type.Optional(Type.String({
+      description:
+        "Resume waiting on a job already submitted (from a previous call that timed out). " +
+        "Nothing is generated and nothing is billed: it only polls and saves. `prompt` is ignored.",
+    })),
     firstFrame: Type.Optional(Type.String({ description: "Path to an image to use as the opening frame (image-to-video)." })),
     lastFrame: Type.Optional(Type.String({ description: "Path to an image to use as the closing frame. Requires firstFrame." })),
     seconds: Type.Optional(Type.Number({ description: "Clip length in seconds. Only certain values are legal per model — see media_capabilities." })),
@@ -349,7 +386,7 @@ export const generateVideoToolDefinition = {
   async execute(
     _toolCallId: string,
     params: {
-      prompt: string; path: string; firstFrame?: string; lastFrame?: string;
+      prompt: string; path: string; resumeJobId?: string; firstFrame?: string; lastFrame?: string;
       seconds?: number; aspectRatio?: string; resolution?: string; audio?: boolean; model?: string;
     },
     signal?: AbortSignal,
@@ -357,9 +394,18 @@ export const generateVideoToolDefinition = {
     ctx?: { cwd?: string },
   ) {
     const cwd = ctx?.cwd ?? process.cwd();
+    if (!params.path) return text("Error: path is required — say where to save the video.");
+
+    // RESUME. Submit nothing, bill nothing — just go back to waiting on a job the
+    // account has already paid for. Everything below the poll is identical, which
+    // is why the loop lives in awaitVideoJob() rather than being duplicated here.
+    const resumeJobId = String(params.resumeJobId ?? "").trim();
+    if (resumeJobId) {
+      return awaitVideoJob(resumeJobId, cwd, params.path, null, signal);
+    }
+
     const prompt = String(params.prompt ?? "").trim();
     if (!prompt) return text("Error: prompt is required.");
-    if (!params.path) return text("Error: path is required — say where to save the video.");
     if (params.lastFrame && !params.firstFrame) return text("Error: lastFrame needs firstFrame alongside it.");
 
     let firstFrame: { data: string; mimeType: string } | undefined;
@@ -389,45 +435,72 @@ export const generateVideoToolDefinition = {
     const jobId = submitted.data.jobId;
     if (!jobId) return text("Video generation failed: Privateer did not return a job id.");
 
-    // Poll to completion. The account is charged when the provider delivers, so an
-    // abandoned poll still costs money — hence the timeout message names the job id.
-    const deadline = Date.now() + VIDEO_POLL_TIMEOUT_MS;
-    const cancelled = () =>
-      text(`Video job ${jobId} was submitted but the wait was cancelled. It is still running and will still be billed.`);
-    for (;;) {
-      if (signal?.aborted) return cancelled();
-      await sleep(VIDEO_POLL_INTERVAL_MS, signal);
-      // sleep() resolves early on abort, so re-check before spending a request on a
-      // signal that is already dead — otherwise the cancel surfaces as a network error.
-      if (signal?.aborted) return cancelled();
-      const poll = await callAccount<VideoStatusResponse>(`/api/agent/media/videos/${encodeURIComponent(jobId)}`, {
-        method: "GET",
-        signal,
-      });
-      if (!poll.ok) return text(`Video job ${jobId} could not be polled: ${poll.message}`);
+    return awaitVideoJob(jobId, cwd, params.path, submitted.data.model ?? null, signal);
+  },
+};
 
-      const status = String(poll.data.status ?? "").toLowerCase();
-      if (status === "failed") return text(`Video generation failed: ${poll.data.message ?? "the provider reported a failure"}.`);
-      if (status === "completed") {
-        if (!poll.data.data) {
-          // The bytes were handed out on an earlier poll and are not stored anywhere.
-          return text(`Video job ${jobId} already delivered its bytes on an earlier poll; they were not saved. Generate again if the file is missing.`);
-        }
-        const target = abs(cwd, params.path);
-        const ext = extname(target) || extForMime(poll.data.mimeType ?? "", ".mp4");
-        const out = `${target.slice(0, target.length - extname(target).length)}${ext}`;
-        const summary = writeOut(out, Buffer.from(poll.data.data, "base64"));
-        return text(`Generated video with ${poll.data.model ?? submitted.data.model ?? "the account video model"}: ${summary}`);
-      }
-      if (Date.now() > deadline) {
-        return text(
-          `Video job ${jobId} is still ${status || "running"} after ${Math.round(VIDEO_POLL_TIMEOUT_MS / 60000)} minutes. ` +
-            "It will still complete and still be billed; nothing was saved here.",
-        );
+/**
+ * Wait on a submitted video job and write its bytes to `path`.
+ *
+ * Split out of execute() so the RESUME path is the same code rather than a second
+ * copy of it: the bytes are delivered exactly once and are stored nowhere, so a
+ * resume that polled differently from the original wait would be the one place a
+ * paid clip could be dropped.
+ *
+ * `submittedModel` is null on a resume — we did not submit, so we have no model
+ * name of our own. The poll reports one anyway; the fallback only covers a server
+ * that returns neither.
+ */
+async function awaitVideoJob(
+  jobId: string,
+  cwd: string,
+  path: string,
+  submittedModel: string | null,
+  signal?: AbortSignal,
+) {
+  // The account is charged when the provider delivers, so an abandoned poll still
+  // costs money — every exit below names the job id, and `resumeJobId` is what
+  // turns that id back into the file.
+  const deadline = Date.now() + VIDEO_POLL_TIMEOUT_MS;
+  const resumeHint = `Resume it with generate_video { resumeJobId: "${jobId}", path: "${path}" } — that waits on this same clip and bills nothing further.`;
+  const cancelled = () =>
+    text(`Video job ${jobId} is still running and will still be billed; the wait was cancelled. ${resumeHint}`);
+  for (;;) {
+    if (signal?.aborted) return cancelled();
+    await sleep(VIDEO_POLL_INTERVAL_MS, signal);
+    // sleep() resolves early on abort, so re-check before spending a request on a
+    // signal that is already dead — otherwise the cancel surfaces as a network error.
+    if (signal?.aborted) return cancelled();
+    const poll = await callAccount<VideoStatusResponse>(`/api/agent/media/videos/${encodeURIComponent(jobId)}`, {
+      method: "GET",
+      signal,
+    });
+    // A poll that fails is NOT the job failing — the clip is still coming and is
+    // still billed, so this has to point at the resume too. Without that the model
+    // reads a dropped request as a dead job and generates the whole thing again.
+    if (!poll.ok) return text(`Video job ${jobId} could not be polled: ${poll.message}. ${resumeHint}`);
+
+    const status = String(poll.data.status ?? "").toLowerCase();
+    if (status === "failed") return text(`Video generation failed: ${poll.data.message ?? "the provider reported a failure"}.`);
+    if (status === "completed") {
+      if (!poll.data.data) {
+        // The bytes were handed out on an earlier poll and are not stored anywhere.
+        return text(`Video job ${jobId} already delivered its bytes on an earlier poll; they were not saved. Generate again if the file is missing.`);
       }
+      const target = abs(cwd, path);
+      const ext = extname(target) || extForMime(poll.data.mimeType ?? "", ".mp4");
+      const out = `${target.slice(0, target.length - extname(target).length)}${ext}`;
+      const summary = writeOut(out, Buffer.from(poll.data.data, "base64"));
+      return text(`Generated video with ${poll.data.model ?? submittedModel ?? "the account video model"}: ${summary}`);
     }
-  },
-};
+    if (Date.now() > deadline) {
+      return text(
+        `Video job ${jobId} is still ${status || "running"} after ${Math.round(VIDEO_POLL_TIMEOUT_MS / 60000)} minutes. ` +
+          `It will still complete and is already billed — do NOT generate it again. ${resumeHint}`,
+      );
+    }
+  }
+}
 
 function sleep(ms: number, signal?: AbortSignal): Promise<void> {
   return new Promise((resolve_) => {
@@ -1065,6 +1138,44 @@ interface SpriteStatusResponse {
   message?: string;
 }
 
+/**
+ * Is `target` the directory `root` itself, or something inside it?
+ *
+ * Asked through `relative` rather than by comparing string prefixes, because
+ * the obvious `target.startsWith(root + "/")` is WRONG for the one root whose
+ * own spelling already ends in a separator: with root `/`, every entry in a
+ * perfectly ordinary archive resolves to `/thing` and matches no prefix `//`,
+ * so a bundle destined for the filesystem root was rejected entry-by-entry as
+ * an escape attempt. That is not a hypothetical — an agent whose cwd is `/`
+ * (an Electron app opened from the Finder, a daemon started by launchd) and a
+ * `dir` of `.` lands exactly there, and the sprite bundle it had already paid
+ * for was thrown away with a security error that named the wrong problem. The
+ * prefix form is also separator-blind on Windows.
+ */
+export function pathInside(root: string, target: string): boolean {
+  const rel = relative(root, target);
+  return rel === "" || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(".." + sep));
+}
+
+/**
+ * Turn one archive entry name into a path under `root`, or refuse it.
+ *
+ * Separators are normalised first so a `..\\..` written the Windows way is
+ * judged as the traversal it is on every platform. The refusal names the
+ * destination as well as the entry, because the entry name alone is the half
+ * the reader already has: it is WHERE the archive was being unpacked to that
+ * says whether the bundle or the caller's `dir` is the thing at fault.
+ */
+function archiveEntryPath(name: string, root: string): string {
+  const rel = name.split("\\").join("/");
+  const traverses =
+    rel.startsWith("/") || /^[A-Za-z]:/.test(rel) || rel.split("/").some((seg) => seg === "..");
+  if (traverses || !pathInside(root, resolve(root, rel))) {
+    throw new Error(`archive entry "${name}" escapes the destination directory ${root}`);
+  }
+  return rel;
+}
+
 /**
  * Unpack the bundle into a directory.
  *
@@ -1073,10 +1184,10 @@ interface SpriteStatusResponse {
  * payload is already PNG, so deflating it twice buys nothing), which means every
  * entry is a header followed by its bytes verbatim.
  *
- * ZIP-SLIP: entry names come off the wire, so each resolved path is checked to
- * be inside the destination before anything is written. A `..` segment here
- * would let a generated archive write anywhere the agent can reach, which on an
- * unattended run is the user's whole machine.
+ * ZIP-SLIP: entry names come off the wire, so each one is checked to be a plain
+ * relative path landing inside the destination before anything is written. A
+ * `..` segment here would let a generated archive write anywhere the agent can
+ * reach, which on an unattended run is the user's whole machine.
  */
 export function extractStoredZip(zip: Buffer, destDir: string): string[] {
   const written: string[] = [];
@@ -1094,10 +1205,7 @@ export function extractStoredZip(zip: Buffer, destDir: string): string[] {
     if (method !== 0) throw new Error(`archive entry "${name}" is compressed; only stored entries are expected`);
     if (dataAt + size > zip.length) throw new Error(`archive entry "${name}" is truncated`);
 
-    const target = resolve(root, name);
-    if (target !== root && !target.startsWith(root + "/")) {
-      throw new Error(`archive entry "${name}" escapes the destination directory`);
-    }
+    const target = resolve(root, archiveEntryPath(name, root));
     mkdirSync(dirname(target), { recursive: true });
     writeFileSync(target, zip.subarray(dataAt, dataAt + size));
     written.push(name);
@@ -1122,8 +1230,205 @@ export function extractStoredZip(zip: Buffer, destDir: string): string[] {
 export function guessResPath(cwd: string, dir: string): string | undefined {
   const target = resolve(abs(cwd, dir));
   const root = resolve(cwd);
-  if (target === root || !target.startsWith(root + "/")) return undefined;
-  return `res://${target.slice(root.length + 1).split("\\").join("/")}/`;
+  if (target === root || !pathInside(root, target)) return undefined;
+  return `res://${relative(root, target).split("\\").join("/")}/`;
+}
+
+/**
+ * The direction sets the server actually recognises, with what each one yields
+ * and what it bills.
+ *
+ * Kept here as a table rather than trusted to the description, because the
+ * server does not reject an unknown set — `parseSpec` falls back to 'one'. So
+ * `directions: "4"`, `"four-way"` or `"down,left,right,up"` used to be accepted
+ * all the way through, bill one clip, and hand back a single-facing sheet with
+ * no error anywhere: the caller asked for a four-way walk cycle and got one
+ * animation, which reads as the feature being broken rather than the argument
+ * being wrong. The schema is a closed set now and this table is what the
+ * unpacked result is checked against.
+ */
+const SPRITE_DIRECTION_SETS = {
+  one: { animations: 1, billed: 1 },
+  four: { animations: 4, billed: 3 },
+  eight: { animations: 8, billed: 5 },
+} as const;
+type SpriteDirections = keyof typeof SPRITE_DIRECTION_SETS;
+
+/**
+ * Whether a failed poll is worth another try.
+ *
+ * A poll that fails is NOT the job failing — the clips are still rendering at
+ * the provider and are still being paid for. A transport error (no status at
+ * all), a 429 or any 5xx is our side or the network having a bad moment, and the
+ * next poll six seconds later will very likely work; abandoning the job on the
+ * first one throws away up to five video generations the account has already
+ * been charged for, and on this path the bundle is delivered ONCE and stored
+ * nowhere, so there is nothing to go back for. A 404/410/401/402 is the
+ * opposite: the job is gone, already delivered, or was never ours, and waiting
+ * changes nothing.
+ */
+export function spritePollWorthRetrying(status?: number): boolean {
+  return status === undefined || status === 429 || status >= 500;
+}
+
+// How many consecutive failed polls to ride out before giving up. Six seconds
+// apart, so this is a minute of Privateer being unreachable — long enough to
+// cover a deploy or a blip, short enough that a genuinely dead endpoint does not
+// hold an unattended run until the 25-minute ceiling.
+const SPRITE_POLL_FAILURE_BUDGET = 10;
+
+/**
+ * Put the delivered archive somewhere safe before unpacking it.
+ *
+ * Returns the path, or null if even this failed — in which case the caller is
+ * out of options and has to say so. Deliberately the temp directory rather than
+ * the destination: the destination is the thing that may be unwritable or wrong,
+ * and a stray .zip inside a Godot project gets picked up by the import scan.
+ */
+function stashBundle(bundle: Buffer, jobId: string): string | null {
+  try {
+    const path = join(tmpdir(), `privateer-sprite-${jobId.replace(/[^A-Za-z0-9_-]/g, "")}.zip`);
+    writeFileSync(path, bundle);
+    return path;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Wait on a submitted sprite job, unpack the bundle, and describe what landed.
+ *
+ * Split out of `execute` for the reason `awaitVideoJob` is: `resumeJobId` has to
+ * poll EXACTLY as the original call did, and a resume that polled differently
+ * would be the one path nobody exercises until someone's five-clip job is on the
+ * line.
+ *
+ * `expectedAnimations` is the size of the direction set that was asked for, and
+ * is null on a resume (where the request that chose it is gone). When it is
+ * known it is checked against what actually came back — the server packs a sheet
+ * out of whatever facings rendered and silently drops the rest, so a four-way
+ * set whose "up" clip failed returns three animations, bills three, and says
+ * nothing. That sheet is not the one the caller asked for and the .tres does not
+ * contain the animation their GDScript will play.
+ */
+async function awaitSpriteJob(
+  jobId: string,
+  cwd: string,
+  dir: string,
+  expectedAnimations: number | null,
+  billed: number | null,
+  signal?: AbortSignal,
+) {
+  const deadline = Date.now() + SPRITE_POLL_TIMEOUT_MS;
+  // The clips are charged as they land, so an abandoned poll still costs money —
+  // hence every exit below names the job id and says how to get back to it
+  // without paying twice.
+  const resumeHint =
+    `Resume it with generate_sprite { resumeJobId: "${jobId}", dir: "${dir}" } — ` +
+    "that waits on this same job and bills nothing further.";
+  const cancelled = () =>
+    text(
+      `Sprite job ${jobId} was submitted but the wait was cancelled. Its ${billed ?? "queued"} clip(s) are still rendering and will still be billed. ` +
+        resumeHint,
+    );
+
+  let consecutiveFailures = 0;
+
+  for (;;) {
+    if (signal?.aborted) return cancelled();
+    await sleep(SPRITE_POLL_INTERVAL_MS, signal);
+    if (signal?.aborted) return cancelled();
+
+    const poll = await callAccount<SpriteStatusResponse>(
+      `/api/agent/media/sprites/${encodeURIComponent(jobId)}`,
+      { method: "GET", signal },
+    );
+    if (!poll.ok) {
+      if (!spritePollWorthRetrying(poll.status)) {
+        return text(`Sprite job ${jobId} could not be polled: ${poll.message}`);
+      }
+      if (++consecutiveFailures >= SPRITE_POLL_FAILURE_BUDGET || Date.now() > deadline) {
+        return text(
+          `Sprite job ${jobId} could not be polled ${consecutiveFailures} times in a row: ${poll.message}. ` +
+            `The clips are still rendering and are still billed. ${resumeHint}`,
+        );
+      }
+      continue;
+    }
+    consecutiveFailures = 0;
+
+    const status = String(poll.data.status ?? "").toLowerCase();
+    if (status === "failed") {
+      return text(`Sprite generation failed: ${poll.data.error?.message ?? poll.data.message ?? "the provider reported a failure"}.`);
+    }
+    if (status === "completed") {
+      if (!poll.data.zip_base64) {
+        return text(`Sprite job ${jobId} already delivered its bytes on an earlier poll; they were not saved. Generate again if the files are missing.`);
+      }
+      const destination = abs(cwd, dir);
+      const bundle = Buffer.from(poll.data.zip_base64, "base64");
+      // Keep the bytes BEFORE touching them. This poll is the only delivery the
+      // job will ever make — the server stores nothing for the agent path and
+      // the next poll answers "already delivered" — so anything that throws
+      // between here and the last writeFileSync used to destroy up to five
+      // billed clips with no way back. The copy costs a few hundred kilobytes
+      // in the temp directory and is removed the moment the unpack succeeds.
+      const stash = stashBundle(bundle, jobId);
+      let written: string[];
+      try {
+        written = extractStoredZip(bundle, destination);
+      } catch (e) {
+        const why = e instanceof Error ? e.message : String(e);
+        return text(
+          `Sprite job ${jobId} rendered but the bundle could not be unpacked into ${destination}: ${why}. ` +
+            (stash
+              ? `The archive itself was saved to ${stash} — unzip it there; the clips are already paid for and will not be delivered again.`
+              : "The archive could not be saved either, so the clips are lost."),
+        );
+      }
+      if (stash) {
+        try {
+          unlinkSync(stash);
+        } catch {
+          // Cleaning up a copy nobody needs is not worth failing a good unpack over.
+        }
+      }
+
+      const tres = written.find((f) => f.endsWith(".tres"));
+      const anims = poll.data.animations ?? [];
+      const mirrored = anims.filter((a) => a.origin === "mirrored").length;
+      const sheet = poll.data.sheet;
+      const missing = expectedAnimations != null ? expectedAnimations - anims.length : 0;
+
+      const lines = [
+        `Generated sprite animation: ${written.length} files in ${destination}`,
+        sheet ? `Sheet ${sheet.width}x${sheet.height}px, ${sheet.frame_width}x${sheet.frame_height} cells, ${sheet.columns}x${sheet.rows} grid.` : "",
+        anims.length ? `Animations: ${anims.map((a) => a.name).join(", ")}${mirrored ? ` (${mirrored} mirrored, not billed)` : ""}.` : "",
+        // Said out loud rather than left to be counted: a sheet short a facing is
+        // not the sheet that was asked for, and the animation GDScript plays for
+        // that direction is simply not in the resource.
+        missing > 0
+          ? `WARNING: ${missing} of ${expectedAnimations} facings did not render and are NOT in the sheet or the .tres — playing them will fail in Godot. ` +
+            "The facings that did land were billed. Re-run to try for the missing ones."
+          : "",
+        tres ? `Set an AnimatedSprite2D's Sprite Frames to ${poll.data.res_path ?? "res://"}${tres.split("/").pop()}.` : "",
+        "Set the sheet's texture Filter to Nearest in the Import dock, or the pixel art imports blurry.",
+        // Surfaced rather than swallowed: the flat backdrop the clip was asked
+        // for is a prompt the model can ignore, and when it does the key leaves
+        // a rim. The caller can see it here instead of finding it in-game.
+        poll.data.key_residue != null && poll.data.key_residue > 0.08
+          ? `NOTE: the background did not key cleanly (residue ${poll.data.key_residue.toFixed(2)}) — the frames may have a fringe. Re-run, or clean them up before shipping.`
+          : "",
+      ].filter(Boolean);
+      return text(lines.join("\n"));
+    }
+    if (Date.now() > deadline) {
+      return text(
+        `Sprite job ${jobId} is still ${status || "running"} after ${Math.round(SPRITE_POLL_TIMEOUT_MS / 60000)} minutes. ` +
+          `It will still complete and still be billed; nothing was saved here. ${resumeHint}`,
+      );
+    }
+  }
 }
 
 export const generateSpriteToolDefinition = {
@@ -1143,13 +1448,23 @@ export const generateSpriteToolDefinition = {
     "right-facing ones rather than rendered, which is why eight animations cost five clips and not " +
     "eight. Each clip is charged at the account's video rate, so an eight-way set is genuinely " +
     "expensive; say the total to the user before batching characters.\n" +
-    "TWO models are involved, which matters when one of them is down: an IMAGE model turns the " +
-    "picture to face each direction (only for `directions` 'four' and 'eight'), then a VIDEO model " +
-    "renders the motion per facing. `image_model` and `model` override them separately.\n" +
-    "It takes several minutes (the clips render sequentially) and this tool waits. Frame count, cell " +
-    "size and frame rate are chosen here and cost nothing extra. AVAILABILITY: this needs a video " +
-    "decoder on the Privateer API and some deployments do not have one — call media_capabilities and " +
-    "check `sprites.available` before spending, or you will get a clear refusal instead of a sheet. " +
+    "TWO models are involved, which matters when one of them is down AND when you are quoting a " +
+    "price: an IMAGE model turns the picture to face each direction (only for `directions` 'four' " +
+    "and 'eight'), then a VIDEO model renders the motion per facing. `image_model` and `model` " +
+    "override them separately. The turns are billed too, at the image rate — one still per billed " +
+    "facing after the first, so 'four' draws two and 'eight' draws four. They are small beside a " +
+    "clip, but a total that counts only clips is short; media_capabilities reports both numbers " +
+    "per direction set (`billedClips` and `billedTurnStills`).\n" +
+    "It takes several minutes — the picture is turned to face each direction one at a time before " +
+    "anything is billed, then the clips render together — and this tool waits. Frame count, cell " +
+    "size and frame rate are chosen here and cost nothing extra.\n" +
+    "If a call comes back saying the job is still running, or that it could not be polled, DO NOT " +
+    "call this again with the same image and prompt — that bills a whole second fan-out. Call it " +
+    "with `resumeJobId` set to the job id it reported (and the same `dir`) to keep waiting on the " +
+    "clips the account has already paid for.\n" +
+    "AVAILABILITY: this needs a video decoder on the Privateer API and some deployments do not have " +
+    "one — call media_capabilities and check `sprites.available` before spending, or you will get a " +
+    "clear refusal instead of a sheet. " +
     "PRIVACY: video and image models have no zero-retention option, so this is gated the way 3D is — " +
     "a ZDR account must have enabled non-ZDR media.",
   parameters: Type.Object({
@@ -1172,6 +1487,12 @@ export const generateSpriteToolDefinition = {
         "baked into the .tres is derived from it, so running at your Godot project root means the " +
         "resource resolves with nothing to edit.",
     }),
+    resumeJobId: Type.Optional(Type.String({
+      description:
+        "Resume waiting on a job already submitted (from a previous call that timed out or lost its " +
+        "poll). Nothing is generated and nothing is billed: it only polls and unpacks. `image`, " +
+        "`prompt` and every other setting are ignored — pass the same `dir`.",
+    })),
     action: Type.Optional(
       Type.String({
         description:
@@ -1180,12 +1501,16 @@ export const generateSpriteToolDefinition = {
       }),
     ),
     directions: Type.Optional(
-      Type.String({
-        description:
-          "'one' (default, one animation, ONE clip billed), 'four' (down/right/up/left, THREE billed) " +
-          "or 'eight' (adds the diagonals, FIVE billed). Four is the usual choice for a top-down or " +
-          "2.5D character; eight only if the game actually turns that finely.",
-      }),
+      Type.Union(
+        [Type.Literal("one"), Type.Literal("four"), Type.Literal("eight")],
+        {
+          description:
+            "'one' (default, one animation, ONE clip billed), 'four' (down/right/up/left, THREE billed) " +
+            "or 'eight' (adds the diagonals, FIVE billed). Four is the usual choice for a top-down or " +
+            "2.5D character; eight only if the game actually turns that finely. These three words are " +
+            "the only accepted values — not '4', not 'four-way'.",
+        },
+      ),
     ),
     frames: Type.Optional(
       Type.Number({
@@ -1237,7 +1562,7 @@ export const generateSpriteToolDefinition = {
   async execute(
     _toolCallId: string,
     params: {
-      image: string; prompt: string; dir: string; action?: string; directions?: string;
+      image: string; prompt: string; dir: string; resumeJobId?: string; action?: string; directions?: string;
       frames?: number; frame_size?: number; fps?: number; loop?: boolean;
       name?: string; res_path?: string; model?: string; image_model?: string;
     },
@@ -1246,9 +1571,36 @@ export const generateSpriteToolDefinition = {
     ctx?: { cwd?: string },
   ) {
     const cwd = ctx?.cwd ?? process.cwd();
+    if (!params.dir) return text("Error: dir is required — say where to write the sheet and the .tres.");
+
+    // RESUME. Submit nothing, bill nothing — just go back to waiting on a fan-out
+    // the account has already paid for. The direction set that chose the facing
+    // count is gone with the original request, so the short-sheet check is off.
+    const resumeJobId = String(params.resumeJobId ?? "").trim();
+    if (resumeJobId) return awaitSpriteJob(resumeJobId, cwd, params.dir, null, null, signal);
+
     if (!params.image) return text("Error: image is required — sprite generation derives every facing from one picture.");
     if (!params.prompt?.trim()) return text("Error: prompt is required — describe how the character moves.");
-    if (!params.dir) return text("Error: dir is required — say where to write the sheet and the .tres.");
+
+    // Checked rather than passed through: the server CLAMPS a number out of range
+    // and falls back on an unknown direction set, both silently, so a typo comes
+    // back as a sheet that is quietly not the one that was asked for — after the
+    // clips are billed. Refusing costs nothing and names the fix.
+    const directions = (params.directions ?? "one") as SpriteDirections;
+    if (!Object.prototype.hasOwnProperty.call(SPRITE_DIRECTION_SETS, directions)) {
+      return text(`Error: directions must be 'one', 'four' or 'eight' — got ${JSON.stringify(params.directions)}.`);
+    }
+    const ranges: [string, number | undefined, number, number][] = [
+      ["frames", params.frames, 2, 24],
+      ["frame_size", params.frame_size, 8, 512],
+      ["fps", params.fps, 1, 120],
+    ];
+    for (const [label, value, min, max] of ranges) {
+      if (value == null) continue;
+      if (!Number.isFinite(value) || value < min || value > max) {
+        return text(`Error: ${label} must be between ${min} and ${max} — got ${value}.`);
+      }
+    }
 
     let seed: { data: string; mimeType: string };
     try {
@@ -1265,7 +1617,7 @@ export const generateSpriteToolDefinition = {
         prompt: params.prompt,
         ...(params.action ? { action: params.action } : {}),
         ...(params.name ? { name: params.name } : {}),
-        ...(params.directions ? { directions: params.directions } : {}),
+        directions,
         ...(params.frames != null ? { frames: params.frames } : {}),
         ...(params.frame_size != null ? { frame_size: params.frame_size } : {}),
         ...(params.fps != null ? { fps: params.fps } : {}),
@@ -1286,67 +1638,11 @@ export const generateSpriteToolDefinition = {
     const jobId = submitted.data.id;
     if (!jobId) return text("Sprite generation failed: Privateer did not return a job id.");
 
-    const billed = submitted.data.billed_facings;
-    const deadline = Date.now() + SPRITE_POLL_TIMEOUT_MS;
-    // The clips are charged as they land, so an abandoned poll still costs money —
-    // hence every exit below names the job id and says so plainly.
-    const cancelled = () =>
-      text(`Sprite job ${jobId} was submitted but the wait was cancelled. Its ${billed ?? "queued"} clip(s) are still rendering and will still be billed.`);
-
-    for (;;) {
-      if (signal?.aborted) return cancelled();
-      await sleep(SPRITE_POLL_INTERVAL_MS, signal);
-      if (signal?.aborted) return cancelled();
-
-      const poll = await callAccount<SpriteStatusResponse>(
-        `/api/agent/media/sprites/${encodeURIComponent(jobId)}`,
-        { method: "GET", signal },
-      );
-      if (!poll.ok) return text(`Sprite job ${jobId} could not be polled: ${poll.message}`);
-
-      const status = String(poll.data.status ?? "").toLowerCase();
-      if (status === "failed") {
-        return text(`Sprite generation failed: ${poll.data.error?.message ?? poll.data.message ?? "the provider reported a failure"}.`);
-      }
-      if (status === "completed") {
-        if (!poll.data.zip_base64) {
-          return text(`Sprite job ${jobId} already delivered its bytes on an earlier poll; they were not saved. Generate again if the files are missing.`);
-        }
-        const destination = abs(cwd, params.dir);
-        let written: string[];
-        try {
-          written = extractStoredZip(Buffer.from(poll.data.zip_base64, "base64"), destination);
-        } catch (e) {
-          return text(`Sprite job ${jobId} rendered but the bundle could not be unpacked: ${e instanceof Error ? e.message : String(e)}`);
-        }
-
-        const tres = written.find((f) => f.endsWith(".tres"));
-        const anims = poll.data.animations ?? [];
-        const mirrored = anims.filter((a) => a.origin === "mirrored").length;
-        const sheet = poll.data.sheet;
-
-        const lines = [
-          `Generated sprite animation: ${written.length} files in ${destination}`,
-          sheet ? `Sheet ${sheet.width}x${sheet.height}px, ${sheet.frame_width}x${sheet.frame_height} cells, ${sheet.columns}x${sheet.rows} grid.` : "",
-          anims.length ? `Animations: ${anims.map((a) => a.name).join(", ")}${mirrored ? ` (${mirrored} mirrored, not billed)` : ""}.` : "",
-          tres ? `Set an AnimatedSprite2D's Sprite Frames to ${poll.data.res_path ?? "res://"}${tres.split("/").pop()}.` : "",
-          "Set the sheet's texture Filter to Nearest in the Import dock, or the pixel art imports blurry.",
-          // Surfaced rather than swallowed: the flat backdrop the clip was asked
-          // for is a prompt the model can ignore, and when it does the key leaves
-          // a rim. The caller can see it here instead of finding it in-game.
-          poll.data.key_residue != null && poll.data.key_residue > 0.08
-            ? `NOTE: the background did not key cleanly (residue ${poll.data.key_residue.toFixed(2)}) — the frames may have a fringe. Re-run, or clean them up before shipping.`
-            : "",
-        ].filter(Boolean);
-        return text(lines.join("\n"));
-      }
-      if (Date.now() > deadline) {
-        return text(
-          `Sprite job ${jobId} is still ${status || "running"} after ${Math.round(SPRITE_POLL_TIMEOUT_MS / 60000)} minutes. ` +
-            "It will still complete and still be billed; nothing was saved here.",
-        );
-      }
-    }
+    // The server's own count where it gave one, the table's where it did not —
+    // the point of the check is to notice a SHORT sheet, so guessing high would
+    // invent a failure and guessing low would hide one.
+    const expected = submitted.data.animations ?? SPRITE_DIRECTION_SETS[directions].animations;
+    return awaitSpriteJob(jobId, cwd, params.dir, expected, submitted.data.billed_facings ?? null, signal);
   },
 };