castle-web-cli 0.4.169 → 0.4.171

package/dist/agent-prompts.d.ts

@@ -90,6 +90,7 @@ export declare function userTurnInstruction(opts: {
     messages: string[];
     interruptedDraft?: string;
     attachments?: string[];
+    files?: string[];
 }): string;
 export declare function buildTaskPrompt(opts: {
     deckLabel: string;

package/dist/agent-prompts.js

@@ -882,6 +882,9 @@ export function userTurnInstruction(opts) {
         // while the CLI backends open the saved files themselves.
         parts.push(`The user attached image file(s), saved in the deck at: ${opts.attachments.join(", ")}. If the images are not already visible in this message, open them with your read tool. Take them into account; pass the paths along to task agents that need them.`);
     }
+    if (opts.files && opts.files.length > 0) {
+        parts.push(`The user pointed at these deck files: ${opts.files.join(", ")}. Read them with your read tool if you need them to reply. When you spawn a task one of these files concerns, name that path in that task's prompt so the agent reads it; do not mention it to tasks it does not concern.`);
+    }
     return parts.join("\n\n");
 }
 export function buildTaskPrompt(opts) {

package/dist/agent.js

@@ -18,12 +18,14 @@ import { execFileSync, spawn } from 'child_process';
 import { quickReferenceFor } from './platformDoc.js';
 import { IMPORTS_DIR } from './imports.js';
 import { isSameOriginUpgrade } from './wsOrigin.js';
+import { resolveDeckPath } from './ide.js';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { nanoid } from 'nanoid';
 import { WebSocketServer } from 'ws';
 import { rawDataToString } from './rawData.js';
+import { atomicWriteFileSync } from './atomicFile.js';
 import { AGENT_ATTACHMENT_PREFIX, AGENT_PLAYTEST_PREFIX, PLAN_FILE } from './localPaths.js';
 import { applyPlanOps, buildRouterPrompt, buildTaskPrompt, parsePlanOps, planOpenQuestionLines, truncateToBytes, userTurnInstruction, CLAUDE_TASK_SYSTEM_REMINDER, } from './agent-prompts.js';
 import { readCastleJson } from './castleJson.js';
@@ -615,6 +617,9 @@ const RESULT_SUMMARY_CHARS = 600;
 // TRANSCRIPT_BYTE_BUDGET in agent-prompts.ts), so this term needs its own bound.
 const PLAN_BYTE_BUDGET = 8 * 1024;
 const MAX_ATTACHMENTS = 6;
+// @-mentioned files are path references, so the only cost is instruction bytes
+// -- but a client is not the one to decide how many the router is told about.
+const MAX_MESSAGE_FILES = 12;
 const MAX_ATTACHMENT_BYTES = 8 * 1024 * 1024;
 const TERMINAL_STATUSES = ['done', 'failed', 'interrupted'];
 function nowIso() {
@@ -2218,7 +2223,7 @@ async function runAgentTurn(opts) {
 }
 // -- task store ---------------------------------------------------------------
 function persistTaskFile(tasksDir, task) {
-    fs.writeFileSync(path.join(tasksDir, task.id, 'task.json'), JSON.stringify(task, null, 2) + '\n');
+    atomicWriteFileSync(path.join(tasksDir, task.id, 'task.json'), JSON.stringify(task, null, 2) + '\n');
 }
 // The task index: one row per task this deck has ever spawned, addressed by the
 // plan item it advanced. It is the complete address book (step 2 searches it by
@@ -2261,18 +2266,17 @@ function writeTaskIndex(tasksDir, tasks) {
     catch {
         /* no index yet -- writing it below is the change */
     }
-    const tmp = `${file}.tmp`;
     try {
         // Written aside and renamed: a running task agent may be reading this file
         // at any moment, and a torn read is a claims board with rows missing.
-        fs.writeFileSync(tmp, body);
-        fs.renameSync(tmp, file);
+        atomicWriteFileSync(file, body);
     }
     catch (err) {
         console.error(`[tasks] could not write ${TASK_INDEX_FILE}: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-// Tasks left "running" by a dead serve are as finished as they will get. A
+// Tasks left "running" or "waiting" by a dead serve are as finished as they
+// will get. They are interrupted rather than scheduled again on boot. A
 // persisted "blocked" task is left as-is: it is not "waiting", so maybeStart
 // never reconsiders it and it can't wedge or auto-start; it just sits on the
 // board (blockedBy intact) until the router stops it, same as before restart.
@@ -2282,7 +2286,7 @@ function loadTasks(tasksDir) {
         const rec = readJsonFile(path.join(tasksDir, entry, 'task.json'));
         if (!rec)
             continue;
-        if (rec.status === 'running') {
+        if (rec.status === 'running' || rec.status === 'waiting') {
             rec.status = 'interrupted';
             rec.updatedAt = nowIso();
             persistTaskFile(tasksDir, rec);
@@ -2624,9 +2628,9 @@ async function runTaskAgentIn(ctx, task) {
 // (by skipping the slot free) nor crash the serve.
 function startTask(ctx, task) {
     const dir = path.join(ctx.tasksDir, task.id);
-    fs.writeFileSync(path.join(dir, 'progress'), '0\n');
+    atomicWriteFileSync(path.join(dir, 'progress'), '0\n');
     if (!fs.existsSync(path.join(dir, 'notes.md')))
-        fs.writeFileSync(path.join(dir, 'notes.md'), '');
+        atomicWriteFileSync(path.join(dir, 'notes.md'), '');
     task.status = 'running';
     task.startedAt = nowIso();
     ctx.touch(task);
@@ -3001,7 +3005,7 @@ function saveAttachments(attachmentsDir, messageId, images) {
         const fileName = `${messageId}-${index}.${ext}`;
         try {
             fs.mkdirSync(attachmentsDir, { recursive: true });
-            fs.writeFileSync(path.join(attachmentsDir, fileName), Buffer.from(match[2], 'base64'));
+            atomicWriteFileSync(path.join(attachmentsDir, fileName), Buffer.from(match[2], 'base64'));
             saved.push(fileName);
         }
         catch {
@@ -3010,6 +3014,20 @@ function saveAttachments(attachmentsDir, messageId, images) {
     }
     return saved;
 }
+// Deck-relative paths a client @-mentioned, keeping only the ones that name a
+// real place in this deck. Nothing is read here: the paths travel as references
+// and whoever needs the contents opens them.
+function validMessageFiles(deckDir, files) {
+    if (!Array.isArray(files))
+        return [];
+    const kept = [];
+    for (const entry of files.slice(0, MAX_MESSAGE_FILES)) {
+        const resolved = resolveDeckPath(deckDir, entry);
+        if (resolved.ok && !kept.includes(resolved.rel))
+            kept.push(resolved.rel);
+    }
+    return kept;
+}
 // Cap on the failure detail shown in a board row -- just enough for the
 // router to reason about what went wrong, not the full crash dump.
 const ERROR_PREVIEW_CHARS = 200;
@@ -3148,7 +3166,7 @@ function createMessageLog(messagesPath, broadcast, welcomeMessage, forClient) {
         .filter((m) => m.text.trim() !== '' || m.role === 'user')
         .map((m) => (m.status === 'streaming' ? { ...m, status: 'done' } : m));
     function persist() {
-        fs.writeFileSync(messagesPath, JSON.stringify(messages, null, 2) + '\n');
+        atomicWriteFileSync(messagesPath, JSON.stringify(messages, null, 2) + '\n');
     }
     if (messages.length === 0) {
         messages.push({
@@ -3624,7 +3642,7 @@ function applyAgentSettings(incoming, ctx) {
     }
     if (changes.length === 0)
         return;
-    fs.writeFileSync(ctx.settingsPath, serializeAgentSettings(settings));
+    atomicWriteFileSync(ctx.settingsPath, serializeAgentSettings(settings));
     // The value is saved and broadcast IMMEDIATELY -- validation never gates a
     // write. The verdict follows in a second frame once the catalog answers.
     ctx.broadcast({ type: 'settings', settings });
@@ -3814,7 +3832,7 @@ function startChildRegistry(registryPath, groups) {
 // messages.json was committed by a prior drain (its turn ran, finished or
 // not -- a logged message is considered handled), so re-queueing it would
 // double-deliver. Order is preserved.
-function loadRecoverableSends(pendingPath, committedIds) {
+function loadRecoverableSends(deckDir, pendingPath, committedIds) {
     const stored = readJsonFile(pendingPath);
     if (!Array.isArray(stored))
         return [];
@@ -3829,6 +3847,11 @@ function loadRecoverableSends(pendingPath, committedIds) {
                 id: item.id,
                 text: item.text,
                 attachments: item.attachments.filter((a) => typeof a === 'string'),
+                // Re-validated rather than trusted: enqueue is where a path earns its
+                // place, and a mirror on disk is not evidence it ever did. A build that
+                // predates @-mentions wrote no files at all, which is a send worth
+                // recovering for its words, not a malformed one.
+                files: validMessageFiles(deckDir, item.files),
             });
         }
     }
@@ -3860,7 +3883,7 @@ function reclaimInFlightSends(pendingSends, inFlightSends) {
 // Mirror the in-memory queue to disk. Called on every mutation (enqueue,
 // drain, cancel, recover) so a restart never loses an unsent queued message.
 function persistPendingSends(ctx) {
-    fs.writeFileSync(ctx.pendingPath, JSON.stringify(ctx.state.pendingSends, null, 2) + '\n');
+    atomicWriteFileSync(ctx.pendingPath, JSON.stringify(ctx.state.pendingSends, null, 2) + '\n');
 }
 function computeQueuedSnippets(pendingSends) {
     return pendingSends.map((p) => p.text.trim()).filter(Boolean);
@@ -3918,11 +3941,12 @@ function startRouterTurn(ctx, instruction, attachments = []) {
 }
 // Commit each drained send to the message log (skipping ones already logged
 // -- see PendingSend.logged -- so a re-carried send doesn't double its user
-// bubble) and collect the instruction pieces: message texts and attachment
-// paths, in drain order.
+// bubble) and collect the instruction pieces: message texts, attachment paths
+// and @-mentioned file paths, in drain order.
 function commitDrainedSends(drained, log) {
     const texts = [];
     const attachmentPaths = [];
+    const filePaths = [];
     for (const item of drained) {
         if (!item.logged) {
             const message = {
@@ -3934,6 +3958,8 @@ function commitDrainedSends(drained, log) {
             };
             if (item.attachments.length > 0)
                 message.attachments = item.attachments;
+            if (item.files.length > 0)
+                message.files = item.files;
             log.add(message);
         }
         if (item.text.trim())
@@ -3941,8 +3967,12 @@ function commitDrainedSends(drained, log) {
         for (const name of item.attachments) {
             attachmentPaths.push(path.join('.castle', 'agent', 'attachments', name));
         }
+        for (const file of item.files) {
+            if (!filePaths.includes(file))
+                filePaths.push(file);
+        }
     }
-    return { texts, attachmentPaths };
+    return { texts, attachmentPaths, filePaths };
 }
 // Drain the queue into the log as real user messages and start one follow-up
 // turn addressing them all (a burst batches into a single turn). A pending
@@ -3958,7 +3988,7 @@ function maybeStartRouterQueueTurn(ctx) {
     // Kept so a fold or manual interrupt of THIS turn can hand these sends back
     // to reclaimInFlightSends if it dies before producing anything visible.
     state.inFlightSends = drained;
-    const { texts, attachmentPaths } = commitDrainedSends(drained, ctx.log);
+    const { texts, attachmentPaths, filePaths } = commitDrainedSends(drained, ctx.log);
     // The queue is now committed to messages.json; clear its durable mirror.
     persistPendingSends(ctx);
     const draft = state.pendingInterruptedDraft;
@@ -3969,6 +3999,7 @@ function maybeStartRouterQueueTurn(ctx) {
         messages: texts,
         interruptedDraft: draft || undefined,
         attachments: attachmentPaths,
+        files: filePaths,
     }), attachmentPaths);
 }
 // The turn settled: clear the busy flag, broadcast it, then flush anything
@@ -4017,7 +4048,7 @@ function safeClientMessageId(clientId) {
         return null;
     return /^[A-Za-z0-9_-]{1,32}$/.test(clientId) ? clientId : null;
 }
-function handleQueueUserMessage(ctx, text, images, clientId) {
+function handleQueueUserMessage(ctx, text, images, files, clientId) {
     const { state } = ctx;
     // Mid-run: queue (don't interrupt). It shows as a queued row in the
     // composer and flushes when the current turn settles. Idle: start now.
@@ -4028,9 +4059,24 @@ function handleQueueUserMessage(ctx, text, images, clientId) {
     // The id is the SENDER's when it supplied one: the client shows the message
     // the moment you hit send, and reusing that row's id means the echo lands on
     // the same row rather than beside it as a duplicate.
-    const id = safeClientMessageId(clientId) ?? nanoid(8);
+    const sentId = safeClientMessageId(clientId);
+    // seenClientIds dies with the process; the client's stored copy of an
+    // unacknowledged message does not, so a resend can outlive a restart and
+    // arrive at a serve that never witnessed the first delivery. The log and
+    // the queue did: either holding the id means this send already landed.
+    if (sentId !== null &&
+        (ctx.messages.some((m) => m.id === sentId) ||
+            state.pendingSends.some((p) => p.id === sentId))) {
+        return;
+    }
+    const id = sentId ?? nanoid(8);
     const attachments = saveAttachments(ctx.attachmentsDir, id, images);
-    state.pendingSends.push({ id, text, attachments });
+    state.pendingSends.push({
+        id,
+        text,
+        attachments,
+        files: validMessageFiles(ctx.deckDir, files),
+    });
     persistPendingSends(ctx);
     if (state.routerRunning) {
         // The new send was just pushed above, so folding now (which unshifts the
@@ -4111,11 +4157,11 @@ function createRouterQueue(deps) {
     };
     // Restart recovery: re-enqueue sends that never reached the message log,
     // so an interrupted serve resumes them exactly once instead of losing them.
-    ctx.state.pendingSends.push(...loadRecoverableSends(ctx.pendingPath, new Set(deps.messages.map((m) => m.id))));
+    ctx.state.pendingSends.push(...loadRecoverableSends(ctx.deckDir, ctx.pendingPath, new Set(deps.messages.map((m) => m.id))));
     persistPendingSends(ctx);
     maybeStartRouterQueueTurn(ctx);
     return {
-        handleUserMessage: (text, images, clientId) => handleQueueUserMessage(ctx, text, images, clientId),
+        handleUserMessage: (text, images, files, clientId) => handleQueueUserMessage(ctx, text, images, files, clientId),
         interruptRouter: () => interruptRouterQueue(ctx),
         cancelQueued: (index) => cancelQueuedSend(ctx, index),
         isRunning: () => ctx.state.routerRunning,
@@ -4308,7 +4354,7 @@ export function createAgentServer(opts) {
             broadcast({ type: 'message-picker', id, pickerAnswers: msg.pickerAnswers });
         }
         if (text.trim())
-            routerQueue.handleUserMessage(text.trim(), undefined);
+            routerQueue.handleUserMessage(text.trim(), undefined, undefined);
     }
     function handleTaskAck(id, rejected) {
         taskStore.acknowledge(id, rejected);
@@ -4394,7 +4440,7 @@ export function createAgentServer(opts) {
                 if (!duplicate) {
                     if (clientId !== null)
                         rememberClientId(clientId);
-                    routerQueue.handleUserMessage(typeof msg.text === 'string' ? msg.text.trim() : '', msg.images, clientId ?? undefined);
+                    routerQueue.handleUserMessage(typeof msg.text === 'string' ? msg.text.trim() : '', msg.images, msg.files, clientId ?? undefined);
                 }
                 if (clientId !== null) {
                     if (socket.readyState === socket.OPEN) {

package/dist/atomicFile.d.ts

@@ -0,0 +1,29 @@
+import * as fs from 'fs';
+export interface AtomicFileOps {
+    closeSync(fd: number): void;
+    fchmodSync(fd: number, mode: number): void;
+    fsyncSync(fd: number): void;
+    linkSync(existingPath: string, newPath: string): void;
+    lstatSync(file: string): fs.Stats;
+    openSync(file: string, flags: number, mode?: number): number;
+    renameSync(oldPath: string, newPath: string): void;
+    unlinkSync(file: string): void;
+    writeFileSync(file: number, data: string | NodeJS.ArrayBufferView): void;
+}
+export interface AtomicWriteOptions {
+    /** Installed mode. Existing destinations keep their mode when omitted. */
+    mode?: number;
+    /** Install only when the destination does not already exist. */
+    exclusive?: boolean;
+}
+/** Reserved sibling temporary names that checkpoint capture must exclude. */
+export declare const ATOMIC_TEMP_FILE_RE: RegExp;
+/**
+ * Replace a regular file without exposing partial bytes to readers.
+ *
+ * The temporary is unique, exclusively created beside the destination, synced
+ * before rename, and cannot follow a pre-planted temporary symlink. The parent
+ * directory is synced after rename so the new name is durable.
+ */
+export declare function createAtomicFileWriter(ops: AtomicFileOps): (file: string, content: string | NodeJS.ArrayBufferView, options?: AtomicWriteOptions) => void;
+export declare const atomicWriteFileSync: (file: string, content: string | NodeJS.ArrayBufferView, options?: AtomicWriteOptions) => void;

package/dist/atomicFile.js

@@ -0,0 +1,120 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+function lstatIfPresent(ops, file) {
+    try {
+        return ops.lstatSync(file);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function checkedDestination(ops, file) {
+    const stat = lstatIfPresent(ops, file);
+    if (stat?.isSymbolicLink())
+        throw new Error(`Refusing to replace symlink: ${file}`);
+    return stat;
+}
+function uniqueTempPath(file) {
+    return path.join(path.dirname(file), `.castle-atomic-${process.pid}-${crypto.randomBytes(12).toString('hex')}.tmp`);
+}
+/** Reserved sibling temporary names that checkpoint capture must exclude. */
+export const ATOMIC_TEMP_FILE_RE = /^\.castle-atomic-[1-9]\d*-[0-9a-f]{24}\.tmp$/;
+/**
+ * Replace a regular file without exposing partial bytes to readers.
+ *
+ * The temporary is unique, exclusively created beside the destination, synced
+ * before rename, and cannot follow a pre-planted temporary symlink. The parent
+ * directory is synced after rename so the new name is durable.
+ */
+export function createAtomicFileWriter(ops) {
+    return function atomicWriteFileSync(file, content, options = {}) {
+        const existing = checkedDestination(ops, file);
+        if (existing && !existing.isFile())
+            throw new Error(`Refusing to replace non-file: ${file}`);
+        const mode = options.mode ?? (existing ? existing.mode & 0o777 : 0o666);
+        const setExactMode = options.mode !== undefined || existing !== null;
+        const temp = uniqueTempPath(file);
+        let tempExists = false;
+        let fd = null;
+        let directoryFd = null;
+        let failure;
+        try {
+            const flags = fs.constants.O_WRONLY |
+                fs.constants.O_CREAT |
+                fs.constants.O_EXCL |
+                (fs.constants.O_NOFOLLOW ?? 0);
+            fd = ops.openSync(temp, flags, mode);
+            tempExists = true;
+            ops.writeFileSync(fd, content);
+            // A new file with no requested mode keeps the mode produced by open +
+            // process umask. Replacements preserve their old mode, and explicit
+            // modes (the version store's 0444 files) are exact.
+            if (setExactMode)
+                ops.fchmodSync(fd, mode);
+            ops.fsyncSync(fd);
+            ops.closeSync(fd);
+            fd = null;
+            // Catch ordinary accidental symlink replacement. The containing
+            // directory must still be trusted against a hostile rename race.
+            checkedDestination(ops, file);
+            if (options.exclusive) {
+                // link(2) is the portable no-replace primitive: exactly one competing
+                // writer can install this name. The temporary is then removed while
+                // the installed hard link keeps the fully synced inode.
+                ops.linkSync(temp, file);
+                ops.unlinkSync(temp);
+                tempExists = false;
+            }
+            else {
+                ops.renameSync(temp, file);
+                tempExists = false;
+            }
+            // Windows does not permit opening directories this way. The rename is
+            // still atomic there, but only Unix deployments get directory-entry
+            // durability across a power loss.
+            if (process.platform !== 'win32') {
+                directoryFd = ops.openSync(path.dirname(file), fs.constants.O_RDONLY);
+                ops.fsyncSync(directoryFd);
+                ops.closeSync(directoryFd);
+                directoryFd = null;
+            }
+        }
+        catch (error) {
+            failure = error;
+        }
+        if (fd !== null) {
+            try {
+                ops.closeSync(fd);
+            }
+            catch (error) {
+                failure ??= error;
+            }
+        }
+        if (directoryFd !== null) {
+            try {
+                ops.closeSync(directoryFd);
+            }
+            catch (error) {
+                failure ??= error;
+            }
+        }
+        if (tempExists) {
+            try {
+                ops.unlinkSync(temp);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    failure ??= error;
+            }
+        }
+        if (failure) {
+            throw failure instanceof Error
+                ? failure
+                : new Error('Atomic file operation failed', { cause: failure });
+        }
+    };
+}
+export const atomicWriteFileSync = createAtomicFileWriter(fs);

package/dist/castle-host/host.js

@@ -24,6 +24,7 @@ const COMMAND_NAMES = [
     "leaderboard.save",
     "leaderboard.show",
     "user.getCurrent",
+    "user.get",
     "time.getServerTime",
     "pass.has",
     "pass.offer",
@@ -39,6 +40,7 @@ const COMMAND_NAMES = [
     "cauldronStorage.boardSubmit",
     "cauldronStorage.boardTop",
     "cauldronStorage.boardGet",
+    "lifecycle.restoreState",
 ];
 // Platform/capability commands: NOT serviced by graphqlFetch. They're dispatched
 // to the host's optional platformHandler (mobile renders native UI; web shows an
@@ -50,6 +52,7 @@ const PLATFORM_COMMAND_NAMES = [
     "portal.open",
     "portal.prefetch",
     "haptics.play",
+    "lifecycle.restoreState",
 ];
 // Mirrors CASTLE_LEADERBOARD_PAYLOAD_VERSION in leaderboardPanel.ts. Duplicated
 // rather than imported because every import here has to stay type-only; bump
@@ -118,6 +121,8 @@ function runCommand(ctx, command, params, caps) {
             return leaderboardShow(ctx, params, caps);
         case "user.getCurrent":
             return Promise.resolve(userGetCurrent(ctx));
+        case "user.get":
+            return userGet(params, gql);
         case "time.getServerTime":
             return timeGetServerTime(gql);
         case "pass.has":
@@ -146,6 +151,7 @@ function runCommand(ctx, command, params, caps) {
         case "portal.open":
         case "portal.prefetch":
         case "haptics.play":
+        case "lifecycle.restoreState":
             return runPlatformCommand(ctx, command, params, caps);
     }
 }
@@ -208,6 +214,8 @@ async function runPlatformCommand(ctx, command, params, caps) {
             return portalPrefetch(ctx, params, caps);
         case "haptics.play":
             return hapticsPlay(ctx, params, caps);
+        case "lifecycle.restoreState":
+            return lifecycleRestoreState(ctx, caps);
         default:
             return unavailableOutcome();
     }
@@ -321,6 +329,38 @@ function normalizeHapticsOutcome(value) {
     }
     return { status: "unavailable" };
 }
+// Hand back whatever the host kept for this deck the last time it unloaded it.
+// Unlike pass/portal, an absent deckId is `unavailable` rather than a thrown
+// MISSING_DECK_ID: a deck asking to resume must never have to catch — an unsaved
+// deck, a host with no store, and a host with nothing kept all read the same.
+async function lifecycleRestoreState(ctx, caps) {
+    if (!caps.platformHandler || !ctx.deckId)
+        return { status: "unavailable" };
+    const outcome = await caps.platformHandler("lifecycle.restoreState", { deckId: ctx.deckId }, ctx);
+    return normalizeRestoreStateOutcome(outcome);
+}
+function normalizeRestoreStateOutcome(value) {
+    const record = typeof value === "object" && value !== null
+        ? value
+        : {};
+    const status = record.status;
+    const valid = [
+        "restored",
+        "none",
+        "unavailable",
+    ];
+    if (typeof status !== "string" || !valid.includes(status)) {
+        return { status: "none" };
+    }
+    if (status !== "restored") {
+        return { status: status };
+    }
+    // A "restored" with no string state would reach the deck as a resume with
+    // nothing to resume from, which JSON.parse would then throw on.
+    return typeof record.state === "string"
+        ? { status: "restored", state: record.state }
+        : { status: "none" };
+}
 function unavailableOutcome() {
     return { status: "unavailable" };
 }
@@ -632,6 +672,56 @@ function userGetCurrent(ctx) {
         user: { userId: ctx.userId, username: ctx.username, isAnonymous: ctx.isAnonymous === true },
     };
 }
+// One user's public profile, or null when there is no such user. The photo and
+// frame are fetched here and handed over as data: urls, since a deck's CSP
+// allows no image host and the host is outside it.
+async function userGet(params, gql) {
+    const userId = asString(params.userId, "userId", "user.get");
+    const data = await graphql(gql, USER_QUERY, { userId }, "user.get");
+    const user = data.user;
+    if (!user?.userId || !user.username)
+        return { user: null };
+    const [photoUrl, frameUrl] = await Promise.all([
+        imageDataUrl(user.photo?.avatarUrl),
+        imageDataUrl(user.photoFrame?.smallFrameUrl),
+    ]);
+    return {
+        user: {
+            userId: user.userId,
+            username: user.username,
+            isAnonymous: user.isAnonymous === true,
+            photoUrl,
+            frameUrl,
+            color: asOptionalString(user.usernameStyle?.color),
+        },
+    };
+}
+// An image as a data: url, or null when there is none or the fetch fails. A
+// missing avatar is not an error for the deck.
+async function imageDataUrl(url) {
+    if (typeof url !== "string" || url.length === 0 || typeof fetch !== "function") {
+        return null;
+    }
+    try {
+        const response = await fetch(url);
+        if (!response.ok)
+            return null;
+        const type = response.headers.get("content-type") ?? "image/png";
+        return `data:${type};base64,${base64(new Uint8Array(await response.arrayBuffer()))}`;
+    }
+    catch {
+        return null;
+    }
+}
+// `btoa` takes a binary string, built here in chunks small enough for
+// `fromCharCode` to spread.
+function base64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 8192) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + 8192));
+    }
+    return btoa(binary);
+}
 async function timeGetServerTime(gql) {
     const data = await graphql(gql, SERVER_TIME_QUERY, {}, "time.getServerTime");
     return {
@@ -1079,6 +1169,24 @@ const PASSES_FOR_DECK_QUERY = `
     }
   }
 `;
+const USER_QUERY = `
+  query CastleUserProfile($userId: ID!) {
+    user(userId: $userId) {
+      userId
+      username
+      isAnonymous
+      photo {
+        avatarUrl
+      }
+      photoFrame {
+        smallFrameUrl
+      }
+      usernameStyle {
+        color
+      }
+    }
+  }
+`;
 const SERVER_TIME_QUERY = `
   query CastleServerTime {
     serverTime {

package/dist/get-deck.js

@@ -4,7 +4,7 @@ import * as path from 'path';
 import { nanoid } from 'nanoid';
 import * as api from './api.js';
 import { normalizeDeckPackageJson } from './normalize.js';
-import { archiveSource, runTar, SOURCE_ARCHIVE_EXCLUDES } from './save-deck.js';
+import { archiveSource, downloadSourceArchive, runTar, SOURCE_ARCHIVE_EXCLUDES, } from './save-deck.js';
 import { readCastleJson } from './castleJson.js';
 // Refreshing a deck already in the target replaces its source, so a file deleted
 // upstream actually disappears here -- untarring over the old tree would leave it
@@ -87,16 +87,7 @@ export async function getDeck(dir, options = {}) {
         }
     }
     // Everything that can fail over the network happens before anything is deleted.
-    console.log(`Fetching ${source.archiveUrl}`);
-    const res = await fetch(source.archiveUrl, { signal: AbortSignal.timeout(60000) });
-    if (!res.ok) {
-        throw new Error(`Archive fetch failed: HTTP ${res.status}`);
-    }
-    const buf = Buffer.from(await res.arrayBuffer());
-    const sizeKB = buf.length / 1024;
-    console.log(`Archive: ${sizeKB.toFixed(1)}KB (updated ${source.updatedAt})`);
-    const tmpFile = path.join(os.tmpdir(), `castle-get-${nanoid(8)}.tar.gz`);
-    fs.writeFileSync(tmpFile, buf);
+    const tmpFile = await downloadSourceArchive(source, 'castle-get');
     try {
         if (refreshing) {
             // A corrupt archive discovered mid-extract would find the old source already

package/dist/headlessCover.d.ts

@@ -1,6 +1,7 @@
 import { type PlaytestBrowserManager } from "./native/playtest-browser.js";
 export interface HeadlessCoverResult {
     ok: boolean;
+    outcome?: 'succeeded' | 'timed_out' | 'capture_failed';
     outPath?: string;
     error?: string;
     installedMs?: number;
@@ -10,4 +11,7 @@ export declare function captureCoverHeadless(opts: {
     outPath: string;
     manager?: PlaytestBrowserManager;
     onProgress?: (message: string) => void;
+    /** Remaining caller budget after content-grant discovery; defaults to the fixed remote cap. */
+    remoteBudgetMs?: number;
+    signal?: AbortSignal;
 }): Promise<HeadlessCoverResult>;