castle-web-cli 0.4.169 → 0.4.170

package/dist/agent.js

@@ -24,6 +24,7 @@ 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';
@@ -2218,7 +2219,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 +2262,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 +2282,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 +2624,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 +3001,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 {
@@ -3148,7 +3148,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 +3624,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 });
@@ -3860,7 +3860,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);
@@ -4028,7 +4028,17 @@ 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 });
     persistPendingSends(ctx);

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

@@ -39,6 +39,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 +51,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
@@ -146,6 +148,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 +211,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 +326,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" };
 }

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>;

package/dist/headlessCover.js

@@ -54,7 +54,7 @@ const CARD_SELECTOR = "#castle-card, [data-castle-card]";
 export async function captureCoverHeadless(opts) {
     const remoteGrant = contentGrantFromBrowserUrl(opts.serveUrl);
     if (remoteGrant) {
-        return captureCoverRemote(remoteGrant, opts.outPath);
+        return captureCoverRemote(remoteGrant, opts.outPath, opts.remoteBudgetMs ?? REMOTE_CAPTURE_BUDGET_MS, opts.signal);
     }
     // A manager we made is a manager we must close. `withBrowser` deliberately
     // leaves the browser RUNNING so the next call reuses it -- right for the
@@ -94,8 +94,9 @@ export async function captureCoverHeadless(opts) {
             await manager.shutdown().catch(() => undefined);
     }
 }
-async function captureCoverRemote(contentGrant, outPath) {
-    const signal = AbortSignal.timeout(REMOTE_CAPTURE_BUDGET_MS);
+async function captureCoverRemote(contentGrant, outPath, budgetMs, callerSignal) {
+    const budgetSignal = AbortSignal.timeout(Math.max(1, budgetMs));
+    const signal = callerSignal ? AbortSignal.any([budgetSignal, callerSignal]) : budgetSignal;
     try {
         const result = await api.runBrowserJob(contentGrant, { kind: 'cover' }, signal);
         const pngBase64 = result.pngBase64;
@@ -117,10 +118,11 @@ async function captureCoverRemote(contentGrant, outPath) {
         if (signal.aborted) {
             return {
                 ok: false,
-                error: `remote cover gave up after ${REMOTE_CAPTURE_BUDGET_MS / 1000}s`,
+                outcome: 'timed_out',
+                error: `remote cover gave up after ${budgetMs / 1000}s`,
             };
         }
-        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+        return { ok: false, outcome: 'capture_failed', error: error instanceof Error ? error.message : String(error) };
     }
 }
 // Resolve with `work`, or with null if the budget runs out first. The loser is

package/dist/ide.js

@@ -482,6 +482,15 @@ function handleVersionRestore(deckDir, req, res, restart) {
         }
     });
 }
+// A curated deck hides anything not covered by editor.visiblePaths. Writes,
+// moves, and uploads already mkdir parent dirs; they also have to register the
+// dest folder or a new path lands on disk and stays invisible in Files.
+function ensureFileParentVisible(deckDir, rel) {
+    const dir = path.posix.dirname(rel);
+    if (dir === '.')
+        return ensureVisibleGlob(deckDir, rel, rel);
+    return ensureVisiblePath(deckDir, dir);
+}
 function handleFilesWrite(deckDir, req, res) {
     withMutationPath(deckDir, req, res, (target, body) => {
         if (typeof body.contents !== 'string') {
@@ -490,7 +499,8 @@ function handleFilesWrite(deckDir, req, res) {
         try {
             fs.mkdirSync(path.dirname(target.abs), { recursive: true });
             fs.writeFileSync(target.abs, body.contents, 'utf8');
-            sendJson(res, 200, { ok: true, path: target.rel });
+            const visiblePathAdded = ensureFileParentVisible(deckDir, target.rel);
+            sendJson(res, 200, { ok: true, path: target.rel, visiblePathAdded });
         }
         catch (err) {
             sendFailure(res, 'write', target.rel, err);
@@ -571,10 +581,7 @@ function handleFilesUpload(deckDir, req, res) {
         catch (err) {
             return sendFailure(res, 'upload', target.rel, err);
         }
-        const dir = path.posix.dirname(target.rel);
-        const visiblePathAdded = dir === '.'
-            ? ensureVisibleGlob(deckDir, target.rel, target.rel)
-            : ensureVisiblePath(deckDir, dir);
+        const visiblePathAdded = ensureFileParentVisible(deckDir, target.rel);
         sendJson(res, 200, { ok: true, path: target.rel, visiblePathAdded });
     }, (err) => {
         if (err instanceof RangeError)
@@ -703,7 +710,8 @@ function handleFilesRename(deckDir, req, res) {
         try {
             fs.mkdirSync(path.dirname(to.abs), { recursive: true });
             fs.renameSync(from.abs, to.abs);
-            sendJson(res, 200, { ok: true, path: to.rel });
+            const visiblePathAdded = ensureFileParentVisible(deckDir, to.rel);
+            sendJson(res, 200, { ok: true, path: to.rel, visiblePathAdded });
         }
         catch (err) {
             sendFailure(res, 'rename', from.rel, err);

package/dist/index.js

@@ -62,6 +62,10 @@ function readPositionals() {
     }
     return out;
 }
+function readImportFileArgs() {
+    const positionals = readPositionals();
+    return { deckDir: path.resolve(positionals[1] ?? '.'), relPosix: positionals[0] ?? '' };
+}
 function getFlagValue(flag) {
     const idx = args.indexOf(flag);
     return idx >= 0 ? args[idx + 1] : undefined;
@@ -89,7 +93,7 @@ function getServeSocketPort(dir) {
 }
 function usage() {
     console.log(`Usage:
-  castle-web init <dir> [--kit NAME]   (kits: physics-2d (default), physics-3d, none)
+  castle-web init <dir> [--deck-id ID] [--card-id ID] [--kit NAME]   (kits: physics-2d (default), physics-3d, none)
   castle-web init <dir> --remix <deckId> [--deck-id ID] [--card-id ID]   (starts from a published deck instead of a kit)
   castle-web serve [dir] [--port PORT] [--host HOST] [--open] [--detach]
   castle-web restart [--port PORT]
@@ -130,7 +134,7 @@ async function main() {
         case 'init': {
             const dir = findPositionalDir();
             if (dir === '.') {
-                console.error('Usage: castle-web init <dir> [--kit NAME | --remix DECK_ID]');
+                console.error('Usage: castle-web init <dir> [--deck-id ID] [--card-id ID] [--kit NAME | --remix DECK_ID]');
                 process.exit(1);
             }
             const kit = getFlagValue('--kit');
@@ -177,8 +181,8 @@ async function main() {
         }
         case 'fork-import-file': {
             // `castle-web fork-import-file <imports/...> [dir]`
-            const positionals = readPositionals();
-            const result = forkImportFile(path.resolve(positionals[1] ?? '.'), positionals[0] ?? '');
+            const { deckDir, relPosix } = readImportFileArgs();
+            const result = forkImportFile(deckDir, relPosix);
             if (!result.ok) {
                 console.error(result.error);
                 process.exit(1);
@@ -187,8 +191,8 @@ async function main() {
             break;
         }
         case 'revert-import-file': {
-            const positionals = readPositionals();
-            const result = revertImportFile(path.resolve(positionals[1] ?? '.'), positionals[0] ?? '');
+            const { deckDir, relPosix } = readImportFileArgs();
+            const result = revertImportFile(deckDir, relPosix);
             if (!result.ok) {
                 console.error(result.error);
                 process.exit(1);

package/dist/init.d.ts

@@ -19,7 +19,7 @@ export declare function init(dir: string, opts?: {
     serve?: boolean;
     /** Remix this published deck instead of starting from a kit. */
     remixOf?: string;
-    /** The identity the server already minted for a remix. */
+    /** The identity the server already minted for this new deck. */
     deckId?: string;
     cardId?: string;
 }): Promise<void>;

package/dist/init.js

@@ -55,7 +55,7 @@ if (!(await mountEditorRoute())) startGame(initCard());
 // Registry version of castle-web-sdk to inject when scaffolding from a
 // globally-installed castle-web (not from inside the workspace). Bumped
 // alongside cli/sdk version bumps.
-const PUBLISHED_SDK_VERSION = '0.4.26';
+const PUBLISHED_SDK_VERSION = '0.4.27';
 // Range, not a pin: `castle-web-fonts` is its own package precisely so a tenth
 // face can ship without a cli release, and a caret range means an existing
 // deck's next install picks it up. Nothing here has to move when it does.
@@ -651,6 +651,16 @@ export async function init(dir, opts = {}) {
     else {
         scaffoldFromKitImport(kit, projectDir);
     }
+    if (!opts.remixOf && (opts.deckId || opts.cardId)) {
+        // Apply server identity before install/version 1, so retries and a restore
+        // to the original scaffold cannot allocate a second deck or card.
+        const configPath = path.join(projectDir, 'castle.json');
+        writeJsonFile(configPath, {
+            ...readJsonFile(configPath),
+            ...(opts.deckId ? { deckId: opts.deckId } : {}),
+            ...(opts.cardId ? { cardId: opts.cardId } : {}),
+        });
+    }
     if (!opts.remixOf) {
         console.log(`Created project in ${projectDir}/${bare ? '' : ` (from kit "${kit}")`}`);
     }

package/dist/remix.js

@@ -1,9 +1,7 @@
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
-import { nanoid } from 'nanoid';
 import * as api from './api.js';
-import { runTar } from './save-deck.js';
+import { downloadSourceArchive, runTar } from './save-deck.js';
 // Scaffolding a deck from another published deck, for `init --remix`.
 // Dropped from the copied castle.json. `autoUpdateWhenImported` is the parent's
 // promise to ITS importers, which a remix hasn't made.
@@ -34,17 +32,7 @@ export async function fetchParentSource(parentDeckId) {
         console.error(`Deck ${parentDeckId} has no saved source to remix. Only decks saved by the web CLI can be remixed.`);
         process.exit(1);
     }
-    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());
-    console.log(`Archive: ${(buf.length / 1024).toFixed(1)}KB (updated ${source.updatedAt})`);
-    // Read and untarred out of, never moved out of: in a sandbox the deck is on a
-    // different filesystem from tmp, and a rename across that is EXDEV.
-    const archivePath = path.join(os.tmpdir(), `castle-remix-${nanoid(8)}.tar.gz`);
-    fs.writeFileSync(archivePath, buf);
+    const archivePath = await downloadSourceArchive(source, 'castle-remix');
     // `./castle.json`, because archiveSource packs with `-C <dir> .`.
     const text = await runTar(['-xzOf', archivePath, './castle.json'], { capture: true });
     return { archivePath, castleJson: parseJson(text) };

package/dist/save-deck.d.ts

@@ -1,10 +1,13 @@
+import * as api from './api.js';
 export declare const SOURCE_ARCHIVE_EXCLUDES: string[];
 export declare const SAVE_STAGE_TELEMETRY_PREFIX = "CASTLE_SAVE_TELEMETRY ";
+export declare const SAVE_COVER_SELECTION_TELEMETRY_PREFIX = "CASTLE_SAVE_COVER_SELECTION ";
 export type SaveStage = 'bundle' | 'cover' | 'scene_upload_config' | 'scene_upload' | 'content_publish' | 'server_publish' | 'source_archive' | 'source_upload_config' | 'source_upload' | 'source_commit';
 export declare function runTar(args: string[], opts?: {
     capture?: boolean;
 }): Promise<string>;
 export declare function archiveSource(projectDir: string): Promise<Buffer>;
+export declare function downloadSourceArchive(source: api.WebDeckSource, namePrefix: string): Promise<string>;
 export type SaveVisibility = 'unlisted' | 'private';
 export interface SaveDeckOptions {
     title?: string;