castle-web-cli 0.4.174 → 0.4.176

package/dist/agent-failures.d.ts

@@ -9,6 +9,8 @@ export interface AgentFailure {
     suggestion?: string;
     resetAtMs?: number;
     castleCreditsExhausted?: boolean;
+    castleCreditsInsufficient?: boolean;
+    castleSpendLimit?: boolean;
 }
 export declare function failureForStatus(status: number, body: string, model?: string): AgentFailure | undefined;
 export declare function classifyProviderError(text: string | undefined, model?: string): AgentFailure | undefined;

package/dist/agent-failures.js

@@ -46,8 +46,35 @@ export function failureForStatus(status, body, model) {
         return config("bad-key");
     if (status === 402)
         return config("no-credits");
-    if (status === 403)
+    if (status === 403) {
+        // Castle's proxy deliberately uses provider-shaped 403s for its own spend
+        // and model gates. A request-size reservation can refuse while the account
+        // still has a small positive balance, so pre-flight cannot catch this case.
+        // Keep the matches tied to the proxy's Castle-specific copy: a provider's
+        // ordinary permission/content 403 must continue to read as a refusal.
+        if (/Castle AI request[^.]*balance can(?:not|'t) cover|add credits at castle\.xyz\/credits/i.test(body)) {
+            return {
+                kind: "limit",
+                detail,
+                model,
+                verbose: `HTTP ${status}: ${body}`,
+                castleCreditsInsufficient: true,
+            };
+        }
+        if (/model\s+.+\s+(?:isn['’]t|is not) available on this Castle account/i.test(body)) {
+            return config("model-not-allowed");
+        }
+        if (/Castle AI spending limit reached/i.test(body)) {
+            return {
+                kind: "limit",
+                detail,
+                model,
+                verbose: `HTTP ${status}: ${body}`,
+                castleSpendLimit: true,
+            };
+        }
         return config("flagged");
+    }
     if (status === 429 || status >= 500) {
         return { kind: "transient", detail, model, verbose: `HTTP ${status}: ${body}` };
     }
@@ -178,9 +205,15 @@ export function failureCopy(opts) {
         case "config":
             return `${configCopy(opts.failure)}${tasksNote}`;
         case "limit":
+            if (opts.failure.castleCreditsInsufficient) {
+                return `Not enough Castle AI credits for this request — get more at castle.xyz/credits${tasksNote}`;
+            }
             if (opts.failure.castleCreditsExhausted) {
                 return `Out of Castle AI credits — get more at castle.xyz/credits${tasksNote}`;
             }
+            if (opts.failure.castleSpendLimit) {
+                return `Castle AI spending limit reached — check your balance at castle.xyz/credits${tasksNote}`;
+            }
             return `Daily Castle AI limit reached${resetsClause(opts.failure.resetAtMs)}. Runs on your own API key or login aren't limited.${tasksNote}`;
         case "transient":
             return `OpenRouter is busy right now and I couldn't get through. Send that again in a moment.${tasksNote}`;

package/dist/agent-prompts.js

@@ -35,6 +35,7 @@ Hard rules:
 - IMPORTS ARE YOURS, and they are the one exception to the rule above. Run \`castle-web list-decks --kind kits\` (also \`mine\` and \`saved\`) to see what this deck can import, and \`castle-web add-import <deckIdOrUrl>\` to add one -- both directly, not through a task. Do NOT claim you can list or import anything until you have actually run these; do not describe imports you have not looked at. \`list-decks\` prints one deck per line starting with the id \`add-import\` takes, and marks the ones this deck already has. A pasted castle.xyz deck link works in place of an id. Everything else about a deck's files still goes to task agents.
 - Imported files are READ-ONLY, which is what to say when the user asks whether they can change something a kit or another import gave them, or why an edit to one did not stick: the deck takes its own version of that one file -- a fork, stored beside the import and used in its place -- and that version is what runs. Forking is how their own data and code changes override an import's, and a task agent does it; the tradeoff, worth saying plainly, is that a file done this way stops picking up changes when the import itself is updated, so it stays to the few files the change actually needs. Often it does not come to a fork at all, which is the better thing to say first: a kit picks up the deck's own behaviors and systems, so new logic is usually just a new file in the deck.
 - You are the fast lane: get to your final reply as quickly as possible. When the user reports something broken, do NOT dig into the code to diagnose it first -- spawn a task whose job is to investigate AND fix it. Only read deck files when your reply itself needs them (answering a question about the deck, grounding a claim -- never make things up); never read as pre-work before spawning a task, and never read files just to learn conventions already covered by the Quick reference.${playtest ? `\n${PLAYTEST_ROUTER_RULE}` : ""}
+- When you point the user at a file, a line, or a tunable value, write it as a link they can tap: \`[label](game.js)\` for a file, \`[label](game.js#L108)\` for a line, \`[label](game.js#params)\` for a file's tunable values and \`[label](game.js#params:enemySpeed)\` for ONE of them (the key exactly as it is written in that file's \`PARAMS\` object -- \`player.speed\` for a nested one). The label is your own words for the thing; the path must be exact and must be a file this deck actually has, or it renders as plain text. A bare \`game.js#108\` in a sentence links too. Cite a line number ONLY when you have read that file with numbered lines -- any deck contents in this prompt carry none, so never count them yourself; link the file or its params instead when you are unsure.
 - Launch a SET of small steps the user tests one by one -- a pipeline, never one big task they wait on, never untestable fragments. One interacting mechanic = one task (paddle + ball + bricks = one playable core, not three). First step = the smallest genuinely playable thing; later steps build it out. Match breadth to ambition ("basic" = a few steps; "go wild" = many). You're optimizing the user's taste and feedback -- more small testable steps = more points where they steer it into something theirs.
 - The whole goal: every piece of work TESTABLE in actual gameplay ASAP. Start every task as early as possible and run them in PARALLEL. Do NOT break tasks down by which files they touch, and never add \`after:\` just to avoid two tasks editing the same file -- tasks make surgical edits and overlap fine. The only real dependency between tasks is INFORMATION: a task is blocked only when it needs a fact it does not yet have.
 - Dissolve those information-dependencies with a CONTRACT decided up front, instead of serializing tasks. Before spawning, pin the shared names the tasks will agree on -- scene file names, behavior names, drawing file names, tags -- and give each parallel task the exact names it must CREATE or REFERENCE. Pinned names must be EXACT filenames, extension included -- \`drawings/ship.sprite\` in a kit deck (the kit's CLAUDE.md names the format), \`drawings/ship.svg\` in a bare one. A bare deck has no kit to define a default art format or loader, so its contract must also state the format and loading approach every consumer will use. Then they all run at once and converge to a working game with NO follow-up wiring task: the scene task places actors referencing behaviors and drawings by their agreed names before those files even exist; the behavior tasks create those behavior names; the drawing tasks create those drawing files. (Art: pin an exact drawing filename like \`drawings/ship.sprite\` up front -> the scene task points an actor at it while another task draws it, in parallel; no place-it-later task.) Fall back to a separate waiting wire-in task (\`after:\` the maker, on the least possible) ONLY when a task truly needs another's actual produced output, not just its agreed name. Working out this breakdown -- what to parallelize, which names to pin up front -- is the core of your job and differs per game.
@@ -992,7 +993,7 @@ phase: wiring the paddle to touch
 
   - \`avatar\` -- what you're doing RIGHT NOW, exactly one of: \`thinking\` (figuring out the plan), \`reading\` (looking through files), \`building\` (writing game logic), \`painting\` (making or editing art/visuals), \`playing\` (trying it in the game).
   - \`phase\` -- a SHORT, plain-language line for this moment ("wiring the paddle to touch", "drawing the flag"). No file or code names. Update \`avatar\` and \`phase\` together each time your stage changes -- a few times across the task, not every turn. (You may also include \`progress: NN\` here, but the progress file above is the primary progress channel.)
-- Before finishing, write ${opts.notesPath}: a tiny test guide for the PLAYER -- AT MOST 2-3 bullets (markdown \`- \` lines), each ONE short phrase: what to try and what should happen. NO code, NO API or "integration contract" detail, and no tour of how you built it -- that part is for you, not them. But DO name a file or a value where the user could act on it: a number they might want changed is worth naming, and worth naming the way they would find it ("enemy speed -- \`spawnRate\` in game.js"). Occasionally one bullet may run a little longer, but default to terse. Mention a blocker only if you hit one. The user reads this verbatim to check your work.${wrapUp}
+- Before finishing, write ${opts.notesPath}: a tiny test guide for the PLAYER -- AT MOST 2-3 bullets (markdown \`- \` lines), each ONE short phrase: what to try and what should happen. NO code, NO API or "integration contract" detail, and no tour of how you built it -- that part is for you, not them. But DO name a file or a value where the user could act on it: a number they might want changed is worth naming, and worth naming the way they would find it, as a link they can tap: "enemy speed -- [spawnRate](game.js#params:spawnRate)" when it is an entry in that file's \`PARAMS\` object, "[the spawn loop](game.js#L42)" for a place in the code (a line number only from a numbered read of the file). Occasionally one bullet may run a little longer, but default to terse. Mention a blocker only if you hit one. The user reads this verbatim to check your work.${wrapUp}
 - If you are truly blocked, write the blocker to the notes file and stop rather than guessing wildly.
 - Never touch files under .castle/ other than ${opts.plan ? "those three paths" : "those two paths"}. (The version store lives there too, but you never edit it by hand -- \`castle-web save-version\` writes it for you.)`;
 }

package/dist/agent.js

@@ -31,7 +31,7 @@ import { applyPlanOps, buildRouterPromptParts, buildTaskPrompt, parsePlanOps, pl
 import { readCastleJson } from './castleJson.js';
 import { checkOpenrouterKey, checkOpenrouterModel, openrouterCatalogEntry, primeOpenrouterCatalog, } from './openrouter-catalog.js';
 import { classifyProviderError, failureCopy, setReaderTimeZone, } from './agent-failures.js';
-import { castleCreditsExhausted, fetchAiCredits, fetchBudget, meteringHeaders, newAgentSessionId, reportCursorRun, spendableMicros, withCustomHeaders, } from './metering.js';
+import { castleCreditsExhausted, createRefreshQueue, fetchAiCredits, fetchBudget, meteringHeaders, newAgentSessionId, reportCursorRun, spendableMicros, withCustomHeaders, } from './metering.js';
 import { anthropicKeyHelperCommand, claudeHasSavedLogin, cursorAuthPath, cursorHasUserLogin, resolveAnthropicAuth, userKey, ANTHROPIC_CREDENTIAL_ENV, ANTHROPIC_PROXY_ENV, CASTLE_USER_KEYS_PATH, } from './byo-auth.js';
 import { accountsSnapshot, loginProviderFor, watchCredentials, writeCredential, } from './byo-accounts.js';
 import { cancelLogin, logout, startLogin, submitLoginCode } from './byo-login.js';
@@ -2101,19 +2101,24 @@ function createUsageFeed(opts) {
     let latest = null;
     let credits = null;
     let budgetPolls = 0;
-    async function refreshAsync(refreshCredits = false) {
+    async function readUsage(refreshCredits = false) {
         if (!opts.castlePaid()) {
             credits = null;
-            publishUsage(null);
-            return;
+            return null;
         }
-        const [budget, nextCredits] = await Promise.all([
-            fetchBudget(),
-            refreshCredits ? fetchAiCredits() : Promise.resolve(credits),
-        ]);
-        if (refreshCredits)
-            credits = nextCredits;
-        publishUsage(usageFrame(budget, credits));
+        // Budget is the authoritative spendable amount and its read can force a
+        // stale proxy gate to sync after a purchase. Read credits second so the
+        // descriptive fields (plan, rate, reload state) describe that same or a
+        // newer account snapshot instead of racing ahead of the gate refresh.
+        const budget = await fetchBudget();
+        if (refreshCredits) {
+            const nextCredits = await fetchAiCredits();
+            // Once the richer field has loaded, a transient GraphQL failure should
+            // not erase it and fall the UI back to the legacy daily presentation.
+            if (nextCredits)
+                credits = nextCredits;
+        }
+        return usageFrame(budget, credits);
     }
     function publishUsage(next) {
         if (JSON.stringify(next ?? null) === JSON.stringify(latest ?? null))
@@ -2121,13 +2126,18 @@ function createUsageFeed(opts) {
         latest = next;
         opts.broadcast({ type: 'usage', usage: next });
     }
-    const refresh = () => void refreshAsync(true);
+    // Focus, host relay, popover-open and run-finished can all arrive together.
+    const refreshQueue = createRefreshQueue({ read: readUsage, publish: publishUsage });
+    const requestRefresh = (withCredits) => {
+        void refreshQueue.request(withCredits);
+    };
+    const refresh = () => requestRefresh(true);
     const stopRunWatch = onAgentRunFinished(refresh);
     const timer = setInterval(() => {
         if (!opts.hasClients())
             return;
         budgetPolls += 1;
-        void refreshAsync(budgetPolls % 5 === 0);
+        requestRefresh(budgetPolls % 5 === 0);
     }, USAGE_POLL_MS);
     timer.unref?.();
     refresh();

package/dist/ide.d.ts

@@ -1,6 +1,8 @@
 import * as http from 'http';
 import { Duplex } from 'stream';
 import { COVER_FILE } from './localPaths.js';
+/** Cache only Vite's content-fingerprinted executable, style, and font output. */
+export declare function shellAssetCacheControl(asset: string): string;
 export declare const IDE_ASSET_PREFIX = "/__castle/ide/";
 export declare const PTY_WS_PATH = "/__castle/pty";
 export declare const VENDOR_PREFIX = "/__castle/vendor/";

package/dist/ide.js

@@ -51,6 +51,13 @@ const SHELL_MIME = {
     '.ttf': 'font/ttf',
     '.map': 'application/json; charset=utf-8',
 };
+const IMMUTABLE_SHELL_ASSET = /^assets\/[^/\\]+-[A-Za-z0-9_-]{8}\.(?:css|js|woff2?|ttf)$/;
+/** Cache only Vite's content-fingerprinted executable, style, and font output. */
+export function shellAssetCacheControl(asset) {
+    return IMMUTABLE_SHELL_ASSET.test(asset)
+        ? 'public, max-age=31536000, immutable'
+        : 'no-store';
+}
 // Does the deck serve this root-level file itself? Vite serves both the deck
 // root and its `public/` dir at `/`, so either location counts.
 function deckHasFile(deckDir, name) {
@@ -97,7 +104,10 @@ function serveShellFile(res, asset) {
     }
     res.writeHead(200, {
         'content-type': SHELL_MIME[path.extname(filePath)] ?? 'application/octet-stream',
-        'cache-control': 'no-store',
+        // These built assets are platform-global bytes. The shell HTML and all
+        // unversioned files stay no-store because only the Vite hash makes a URL
+        // safe to retain across CLI updates.
+        'cache-control': shellAssetCacheControl(asset),
     });
     fs.createReadStream(filePath).pipe(res);
     return true;
@@ -366,6 +376,49 @@ function filterImportedFiles(deckDir, imported) {
     }
     return out;
 }
+// The deck's files as the Files panel sees them. Each deck curates its own: the
+// importing deck's visible/hidden paths name its own dirs (a kit's name scenes/,
+// drawings/ ...), so applying them to imports would hide every import by
+// omission -- an import is instead filtered by the config of the deck it came
+// from, which is the deck that knows which of its files are worth showing.
+function curatedDeckFiles(deckDir) {
+    const listed = listDeckFiles(deckDir);
+    const own = listed.filter((f) => !isImportPath(f));
+    return [
+        ...filterOwnFiles(own, readEditorConfig(deckDir)),
+        ...filterImportedFiles(deckDir, listed.filter(isImportPath)),
+    ].sort((a, b) => a.localeCompare(b));
+}
+// The source extensions a `PARAMS` object can be read out of -- the same ones
+// the shell parses as JS/TS. Not a kit's vocabulary: `export const PARAMS` is a
+// JavaScript declaration, not a file type somebody declared.
+const PARAMS_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx']);
+// Deliberately looser than the shell's parser, which also accepts a `const
+// PARAMS` that is never exported. A prefilter that were TIGHTER than the parser
+// would drop files the panel can actually edit; the shell re-parses each
+// candidate and discards the ones that only look like a match.
+const PARAMS_DECLARATION = /\bconst\s+PARAMS\b/;
+// Which of the deck's files declare params. Scanning here rather than in the
+// browser because a physics-2d deck carries a hundred-plus files under
+// `imports/`, and reading each one over HTTP to open a panel is the wrong cost.
+function filesDeclaringParams(deckDir) {
+    const out = [];
+    for (const rel of curatedDeckFiles(deckDir)) {
+        if (!PARAMS_EXTS.has(path.extname(rel).toLowerCase()))
+            continue;
+        const resolved = resolveDeckPath(deckDir, rel);
+        if (!resolved.ok)
+            continue;
+        try {
+            if (PARAMS_DECLARATION.test(fs.readFileSync(resolved.abs, 'utf8')))
+                out.push(rel);
+        }
+        catch {
+            /* raced a delete, or not readable -- it simply has no params to offer */
+        }
+    }
+    return out;
+}
 // Read a raw (binary) request body, refusing anything over `limit`. Uploads are
 // arbitrary device files, so the cap is enforced as bytes arrive rather than
 // after buffering the whole thing.
@@ -859,21 +912,12 @@ function handleFilesApi(deckDir, req, res, reqPath, restart, invalidate) {
         // toggle) -- still minus the always-ignored dirs (node_modules/.castle/...),
         // just without the deck's visible/hidden path curation.
         const url = new URL(req.url ?? '/', 'http://localhost');
-        const listed = listDeckFiles(deckDir);
-        let files = listed;
-        if (url.searchParams.get('all') !== '1') {
-            // Each deck curates its own files. The importing deck's visible/hidden
-            // paths name its own dirs (a kit's name scenes/, drawings/ ...), so
-            // applying them to imports would hide every import by omission -- an
-            // import is instead filtered by the config of the deck it came from, which
-            // is the deck that knows which of its files are worth showing.
-            const own = listed.filter((f) => !isImportPath(f));
-            files = [
-                ...filterOwnFiles(own, readEditorConfig(deckDir)),
-                ...filterImportedFiles(deckDir, listed.filter(isImportPath)),
-            ].sort((a, b) => a.localeCompare(b));
-        }
-        sendJson(res, 200, { files });
+        const all = url.searchParams.get('all') === '1';
+        sendJson(res, 200, { files: all ? listDeckFiles(deckDir) : curatedDeckFiles(deckDir) });
+        return true;
+    }
+    if (action === 'params') {
+        sendJson(res, 200, { files: filesDeclaringParams(deckDir) });
         return true;
     }
     if (action === 'read') {

package/dist/metering.d.ts

@@ -66,6 +66,17 @@ export interface AiCredits {
     };
 }
 export declare function spendableMicros(budget: CastleBudget): number | null;
+/**
+ * Coalesce asynchronous refresh triggers without letting an older read finish
+ * after and overwrite a newer one. `withFullState` is sticky across queued
+ * calls: a cheap poll cannot downgrade a pending user-requested full refresh.
+ */
+export declare function createRefreshQueue<T>(opts: {
+    read: (withFullState: boolean) => Promise<T>;
+    publish: (value: T) => void;
+}): {
+    request: (withFullState: boolean) => Promise<void>;
+};
 export declare function castleCreditsExhausted(budget: CastleBudget, credits: AiCredits | null): boolean;
 /** Rich credit state, or null when ghost/proxy cannot provide the new field. */
 export declare function fetchAiCredits(): Promise<AiCredits | null>;

package/dist/metering.js

@@ -120,6 +120,39 @@ export function spendableMicros(budget) {
         return null;
     return Math.max(0, budget.limitMicros - budget.usedMicros);
 }
+/**
+ * Coalesce asynchronous refresh triggers without letting an older read finish
+ * after and overwrite a newer one. `withFullState` is sticky across queued
+ * calls: a cheap poll cannot downgrade a pending user-requested full refresh.
+ */
+export function createRefreshQueue(opts) {
+    let queued = false;
+    let queuedFullState = false;
+    let active = null;
+    const request = (withFullState) => {
+        queued = true;
+        queuedFullState ||= withFullState;
+        if (active)
+            return active;
+        active = (async () => {
+            while (queued) {
+                const fullState = queuedFullState;
+                queued = false;
+                queuedFullState = false;
+                const value = await opts.read(fullState);
+                // If another trigger arrived while this read was in flight, its result
+                // is already the one the caller wants. Skip the older intermediate
+                // frame instead of flashing it before the trailing refresh completes.
+                if (!queued)
+                    opts.publish(value);
+            }
+        })().finally(() => {
+            active = null;
+        });
+        return active;
+    };
+    return { request };
+}
 const EXHAUSTED_BALANCE_CREDITS = 50;
 export function castleCreditsExhausted(budget, credits) {
     if (!budget.blocked || credits?.plan !== "credits")

package/dist/platformDoc.js

@@ -53,7 +53,7 @@ export function everyDeckBullets(deckDir) {
         "- Do not reload the deck after an edit. Nothing auto-reloads: the person applies your changes when they are ready, from the Play panel's restart button or a panel's own reload control. `npm run restart` reloads every open panel at once and breaks their flow — only when asked.",
         "- The deck can define its own editors: declare a file type in `castle.json` (`editor.fileTypes`: ext, label, icon, and an `editors/` module) and the Files panel opens that type in it — whole recipe under `## Editors` in the deck's guide (its kit's `CLAUDE.md` under `imports/`). Editors under `imports/` are read-only; add or fork, don't edit.",
         '- An editor is for content FILES the creator keeps coming back to (catalogs, dialogue, level tables) that nothing already opens. One-off or generated data stays code.',
-        "- **Put the values someone would tune while playtesting in a `PARAMS` object**: `export const PARAMS = { jumpHeight: 4.2, coyoteTime: 0.08 };` near the top of the file that uses them. Every `.js` / `.jsx` / `.ts` / `.tsx` file has a Params view beside its Code view that renders those values as fields -- a number scrubs, a boolean toggles, a `'#rrggbb'` string opens a color picker -- and writes the edit back into the file. That is how a creator tunes a game on a phone without putting a cursor inside an expression. Nested one level deep (`player: { speed: 5 }`) renders as a group; a value that is an expression (`speed: BASE * 2`) still shows, read-only.",
+        "- **Put the values someone would tune while playtesting in a `PARAMS` object**: `export const PARAMS = { jumpHeight: 4.2, coyoteTime: 0.08 };` near the top of the file that uses them. The Parameters panel lists every file in the deck that has one and renders their values as fields -- a number scrubs, a boolean toggles, a `'#rrggbb'` string opens a color picker -- and writes the edit back into the file. It edits every file's params in one place, so nobody has to remember which file a setting lives in, and a file that has params says so above its code with a way in. That is how a creator tunes a game on a phone without putting a cursor inside an expression. Nested one level deep (`player: { speed: 5 }`) renders as a group; a value that is an expression (`speed: BASE * 2`) still shows, read-only.",
         '- **This is for the handful of numbers someone would actually reach for between playtests, not every constant in the file.** A `PARAMS` with sixty keys is a wall nobody can scan, which is how a creator stops opening the pane at all. A magic number that only ever has one right value is not a param.',
         "- **Read them through the object where they are used** -- `PARAMS.jumpHeight`, not `const { jumpHeight } = PARAMS` at module load. A destructured copy is taken once when the module loads and can never track a later change, so keeping the read at the use site is what leaves a tuned value able to reach the running deck.",
         MODE_BULLET,

package/dist/serve.js

@@ -266,6 +266,7 @@ const EDIT_CONTENT_READ_ENDPOINTS = new Set([
     '/__castle/files/read',
     '/__castle/files/info',
     '/__castle/files/list',
+    '/__castle/files/params',
     '/__castle/files/forks',
 ]);
 export function isAllowedContentFilesRequest(role, method, reqPath) {
@@ -596,6 +597,15 @@ function lockExistingImports(projectDir) {
         }
     }
 }
+function importPinsFingerprint(projectDir) {
+    try {
+        const config = JSON.parse(fs.readFileSync(path.join(projectDir, 'castle.json'), 'utf8'));
+        return JSON.stringify(config.imports ?? {});
+    }
+    catch {
+        return null;
+    }
+}
 export async function serve(dir, options = {}) {
     const projectDir = path.resolve(dir);
     if (!fs.existsSync(projectDir)) {
@@ -642,11 +652,18 @@ export async function serve(dir, options = {}) {
     //
     // Also skipped when CASTLE_NO_AUTO_UPDATE is set (local kit development:
     // keep hand-synced imports/ instead of pulling published kits).
+    let importsChangedAtStartup = false;
     if (!existingServe(projectDir)) {
+        const importsBeforeUpdate = importPinsFingerprint(projectDir);
         // A failure to check must never keep the deck from opening.
-        await autoUpdateImports(projectDir).catch((e) => {
+        const updated = await autoUpdateImports(projectDir).catch((e) => {
             console.warn(`auto-update: skipped -- ${e instanceof Error ? e.message : String(e)}`);
+            return [];
         });
+        // Comparing pins as well as the returned list preserves the invalidation
+        // if a later step throws after one or more imported trees were replaced.
+        importsChangedAtStartup =
+            updated.length > 0 || importsBeforeUpdate !== importPinsFingerprint(projectDir);
     }
     // Start pulling the headless browser now, in the background.
     //
@@ -815,6 +832,13 @@ export async function serve(dir, options = {}) {
     playtestHolder.run = (req) => agentServer.runPlaytestFor(req);
     const vite = await createViteServer({
         root: projectDir,
+        // Vite's cached optimizer metadata keys package/lock/config inputs, not the
+        // source of an imported deck. A serve-start auto-update can therefore add
+        // bare imports while leaving Vite convinced its old pre-bundle is current.
+        // Force only that startup's cold optimization: unchanged serves keep the
+        // warm cache, while the first page after replaced import source never has
+        // to recover from an outdated optimized-dependency response (HMR is off).
+        ...(importsChangedAtStartup ? { optimizeDeps: { force: true } } : {}),
         plugins: [
             castlePlugin(security, ideServer, agentServer, options.host),
             forksOverlayPlugin(),