@looop-games/cli 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -14,6 +14,46 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.14] - 2026-07-13
+
+> How to write a room primitive — the folder, the filename-is-type rule, and
+> subclassing an engine primitive — is a change to the engine's room library, so
+> it lives in the engine changelog (`looop changelog`), not here. This file is
+> only the `looop` command itself.
+
+### Changed
+- `looop dev` and `looop publish` now **refuse an override the room server cannot
+  run**, naming the file and what to do instead. Copying a room internal
+  (`host-core.js`, `primitives/effects.js`, …) into `overrides/` used to be
+  accepted in silence and then simply never run on the server — your browser and
+  the room quietly ran different code. The only override the server honours is a
+  primitive, so that is now the only one the commands accept.
+
+### Fixed
+- `looop dev` now runs **your game's own server primitives**. It always ran the
+  engine's stock room server instead, so a primitive you wrote worked once you
+  published but not on your own machine — which is the worst way round, because
+  you could only find the difference after shipping. `looop dev` and `looop
+  publish` now decide the same way whether your game has a server of its own.
+
+## [0.1.13] - 2026-07-12
+
+### Fixed
+- **`looop update` deleted your engine.** The engine is not an npm package — it
+  installs without a record in `package.json`, so *any* `npm install` in your game
+  treats it as junk and removes it. `looop update` then updated the `looop` command
+  itself with an npm install — **after** putting the engine in place — and wiped it
+  out every time. The update said it succeeded; `node_modules/@looop-games/engine`
+  was gone. Everything that reads the engine then failed, and re-running
+  `looop update` cheerfully said "already up to date" and fixed nothing.
+
+  The engine is now the last thing installed, and an update that finds it missing
+  puts it back (from the local cache — instant, no download). If you hit this, one
+  `npx looop update` repairs it.
+- `looop lint` said "this engine ships no rules yet" when the real problem was that
+  the engine was not installed at all — sending you to `looop update`, the one
+  command that could not help. It now tells you which of the two it is.
+
 ## [0.1.12] - 2026-07-12
 
 ### Added

package/lib/bundle-primitives.mjs

@@ -16,24 +16,32 @@
 // duplicate the room runtime and, worse, let a primitive smuggle its own room
 // class past the setInterval/park cost boundary. Keeping it external means the
 // worker's room code is always ours.
-import { existsSync } from 'node:fs';
+import { assertNoOverrideCycle, PRIMITIVES_DIR, SERVER_BARREL, renderBarrel, scanPrimitives } from './primitives.mjs';
+import { shadowResolvePlugin } from './shadow-resolve.mjs';
 import { join } from 'node:path';
 
-// The primitives barrel — same path the endpoint detects a server-backed game
-// by (SERVER_PRIMITIVES_PATH in game-server-deploy.ts).
-export const PRIMITIVES_ENTRY = '_local/primitives/index.js';
+// The bundled barrel's path in the upload — the same path the endpoint detects a
+// server-backed game by (SERVER_PRIMITIVES_PATH in game-server-deploy.ts).
+// The creator never writes it; the CLI generates it from the directory scan.
+export const PRIMITIVES_ENTRY = SERVER_BARREL;
 
 // The module name the generated worker entry imports the runtime from; every
 // engine import in the primitives bundle is rewritten to this.
 export const ENGINE_ARTIFACT_MODULE = './rooms-runtime.js';
 
 export async function bundlePrimitives(projectDir, { esbuildImpl } = {}) {
-  const entry = join(projectDir, PRIMITIVES_ENTRY);
-  if (!existsSync(entry)) {
+  // The barrel is GENERATED, not authored. A creator adds a primitive by adding
+  // a file to `overrides/shared/ui/room/primitives/` — there is no list to keep
+  // in sync, and therefore no way for the list and the folder to disagree.
+  const primitives = scanPrimitives(projectDir); // throws on a reserved index.js
+  if (!primitives.length) {
     throw new Error(
-      `no server primitives to bundle — ${PRIMITIVES_ENTRY} not found (this is not a server-backed game)`,
+      `no server primitives to bundle — ${PRIMITIVES_DIR}/ is empty (this is not a server-backed game)`,
     );
   }
+  const engineShared = join(projectDir, 'node_modules/@looop-games/engine/shared');
+  assertNoOverrideCycle(primitives, projectDir, engineShared);
+
   const esbuild = esbuildImpl ?? (await import('esbuild'));
 
   // Every engine specifier the primitives import, captured for reporting.
@@ -56,7 +64,16 @@ export async function bundlePrimitives(projectDir, { esbuildImpl } = {}) {
   };
 
   const result = await esbuild.build({
-    entryPoints: [entry],
+    // No entry file on disk: the generated barrel is fed straight in, resolved
+    // against the game root so `./overrides/...` means what it says. Same shape
+    // the dev room server uses (lib/room-server.mjs) — one contract, two builds.
+    stdin: {
+      contents: renderBarrel(primitives),
+      resolveDir: projectDir,
+      sourcefile: 'looop-primitives.js',
+      loader: 'js',
+    },
+    absWorkingDir: projectDir,
     bundle: true,
     write: false,
     format: 'esm',
@@ -70,7 +87,19 @@ export async function bundlePrimitives(projectDir, { esbuildImpl } = {}) {
     // Inline WASM as bytes so the bundle stays ONE self-contained module — no
     // extra CompiledWasm part to thread through the 3-module upload.
     loader: { '.wasm': 'binary' },
-    plugins: [enginePlugin],
+    plugins: [
+      // An override's relative imports fall through to the engine, as they do in
+      // the browser — and here the engine is EXTERNAL, so they land on the
+      // release's pre-bundled runtime rather than being inlined. That is what
+      // makes `import { PlayerBody } from './engine.js'` work inside an override.
+      shadowResolvePlugin({
+        projectDir,
+        sharedDir: engineShared,
+        engineExternal: ENGINE_ARTIFACT_MODULE,
+        onEngineHit: (spec) => externals.push(spec),
+      }),
+      enginePlugin,
+    ],
   });
 
   return { source: result.outputFiles[0].text, externals };

package/lib/dev.mjs

@@ -17,6 +17,8 @@ import { createStaticServer } from './static-server.mjs';
 import { createLlmShim, DEFAULT_API_BASE } from './llm-shim.mjs';
 import { getToken, getApiBase } from './config.mjs';
 import { portsFor, portInUse, killPort, lanIp } from './ports.mjs';
+import { assertNoInertOverride, scanPrimitives } from './primitives.mjs';
+import { buildDevRoomServer, DEV_OVERRIDES_DIR } from './room-server.mjs';
 
 // Resolve the partykit CLI entry from OUR dependencies (the game never
 // declares partykit; it rides @looop-games/cli). partykit's `exports` map hides
@@ -36,27 +38,14 @@ export function partykitBin() {
   }
 }
 
-// Per-game server parity: a game shipping its own
-// `partykit.json` runs its OWN server in dev — partykit gets the game folder
-// as cwd, resolving the game's `main` entry (which imports the room server
-// from the installed engine). Without one, the bundle's shared room server
-// runs, exactly as before. A config whose `main`
-// doesn't exist is ignored LOUDLY — a dead file must not take dev's
-// multiplayer down with it.
-export function partykitCwdFor(project, engine, warn = console.warn) {
-  const configPath = join(project.dir, 'partykit.json');
-  if (existsSync(configPath)) {
-    try {
-      const config = JSON.parse(readFileSync(configPath, 'utf8'));
-      const main = config?.main ?? 'server.js';
-      if (existsSync(join(project.dir, main))) return project.dir;
-      warn(`partykit.json found but its main (${main}) doesn't exist — running the shared room server instead`);
-    } catch (err) {
-      warn(`partykit.json is unreadable (${err.message}) — running the shared room server instead`);
-    }
-  }
-  return engine.roomServerDir;
-}
+// Per-game server parity: a game with primitives of its own
+// (overrides/shared/ui/room/primitives/) runs its OWN room server in dev, built
+// from those classes. Without them, the engine's stock room server runs.
+//
+// The predicate is `isServerBacked` — the SAME one publish uses. It used to be
+// "does a partykit.json exist", which nothing in this CLI ever creates, so dev
+// and publish disagreed and a creator's primitive ran in production but not on
+// their own machine. One question, one answer, both commands.
 
 export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP === '1', log = console.log } = {}) {
   const project = findProject(cwd);
@@ -67,6 +56,22 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
   const children = [];
   const servers = [];
 
+  // The game's own server code, if any. Built BEFORE any server binds a port —
+  // both because a malformed primitives folder should fail before we start
+  // taking over ports, and because this generates the merged browser registry
+  // the static server is about to mount. Building it after would leave a window
+  // where the page loads and predicts with the engine's classes instead.
+  //
+  // The inert-override check runs FIRST, before the scan. An override of, say,
+  // `primitives/effects.js` is a room-runtime file that merely happens to live in
+  // the primitives folder — scanned first, it would be reported as "a primitive
+  // with no default export", which is true and useless. Checked first, the
+  // creator is told the actual problem: the server cannot take this file.
+  assertNoInertOverride({ projectDir: project.dir, engine });
+  const serverPrimitives = scanPrimitives(project.dir);
+  const roomServerCwd = await buildDevRoomServer({ projectDir: project.dir, engine });
+  const ownServer = roomServerCwd !== engine.roomServerDir;
+
   const stop = () => {
     for (const c of children) {
       // partykit is npx-style: node wrapper forks workerd. Kill the tree.
@@ -88,14 +93,24 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
     log(`→ static      :${ports.static}  (in use — killing to take over)`);
     await killPort(ports.static);
   }
-  // overrides/shared/… (Slice 2, Q1): the game's first-class engine
-  // modifications mount ahead of the bundle and shadow it per-file — the same
-  // shadowing the publish resolve step applies in production.
+  // overrides/shared/… : the game's engine modifications mount ahead of the
+  // bundle and shadow it per-file — the same shadowing the publish resolve step
+  // applies in production.
+  //
+  // Two override layers, in precedence order:
+  //   1. GENERATED (.looop/overrides/shared) — the merged primitive registry the
+  //      CLI writes for a game with server primitives, so the client predicts
+  //      with the game's classes. It goes first because it shadows a file
+  //      (primitives/index.js) the creator is not allowed to write themselves.
+  //   2. THE CREATOR'S (overrides/shared) — everything they wrote.
+  // Then the engine. First mount that HAS the file wins (static-server.mjs).
+  const generatedOverridesDir = join(project.dir, DEV_OVERRIDES_DIR);
   const overridesDir = join(project.dir, 'overrides', 'shared');
   const staticServer = createStaticServer({
     slug: project.slug,
     mounts: [
       { url: `/games/${project.slug}/`, dir: project.dir },
+      { url: '/shared/', dir: generatedOverridesDir },
       { url: '/shared/', dir: overridesDir },
       { url: '/shared/', dir: engine.sharedDir },
     ],
@@ -113,12 +128,10 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
       log(`→ multiplayer :${ports.mp}  (in use — killing to take over)`);
       await killPort(ports.mp);
     }
-    const pkCwd = partykitCwdFor(project, engine, (m) => log(`[partykit] ${m}`));
-    const ownServer = pkCwd === project.dir;
     const pk = spawn(
       process.execPath,
       [partykitBin(), 'dev', '--port', String(ports.mp), '--persist', join(tmpdir(), `looop-partykit-${ports.mp}`)],
-      { cwd: pkCwd, stdio: ['ignore', 'pipe', 'pipe'], detached: true },
+      { cwd: roomServerCwd, stdio: ['ignore', 'pipe', 'pipe'], detached: true },
     );
     pk.stdout.on('data', () => {});
     pk.stderr.on('data', (d) => {
@@ -126,7 +139,9 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
       if (/error/i.test(s)) log(`[partykit] ${s.trim()}`);
     });
     children.push(pk);
-    log(`→ multiplayer :${ports.mp}  (partykit on ${ownServer ? "this game's OWN server" : "the bundle's room-server"}, pid ${pk.pid})`);
+    log(
+      `→ multiplayer :${ports.mp}  (partykit on ${ownServer ? `this game's OWN server — ${serverPrimitives.map((p) => p.type).join(', ')}` : "the engine's room server"}, pid ${pk.pid})`,
+    );
   }
 
   // ─── platform services shim ───

package/lib/lint.mjs

@@ -38,17 +38,23 @@ async function loadFromProject(projectDir) {
 }
 
 // The shareable config, out of the installed engine artifact.
+//
+// The two ways this can come up empty are DIFFERENT problems with different
+// fixes, and conflating them sends people in a circle: the first version of this
+// said "engine ships no rules — run looop update" when the engine was not
+// installed at all, so `looop update` was the one command that could never help.
+// Say which it is.
 async function loadRulesFromEngine(projectDir) {
   let engineDir;
   try {
     ({ dir: engineDir } = resolveEngine(projectDir));
   } catch {
-    return null; // no engine installed yet — `looop dev` installs it
+    return { configs: null, why: 'no-engine' };
   }
   const entry = join(engineDir, 'eslint', 'index.js');
-  if (!existsSync(entry)) return null; // engine predates the rules
+  if (!existsSync(entry)) return { configs: null, why: 'engine-too-old' };
   const mod = await import(pathToFileURL(entry).href);
-  return mod.configs ?? mod.default?.configs ?? null;
+  return { configs: mod.configs ?? mod.default?.configs ?? null, why: 'ok' };
 }
 
 export async function lintCmd({
@@ -68,10 +74,19 @@ export async function lintCmd({
     return { ok: true, skipped: true, errorCount: 0, warningCount: 0 };
   }
 
-  const configs = await loadRules(project.dir);
+  const { configs, why } = await loadRules(project.dir);
   if (!configs) {
-    log('⚠️  looop lint: this engine ships no rules yet — skipping.');
-    log('   Get the latest engine (it carries them): looop update');
+    if (why === 'no-engine') {
+      // The engine is not on disk. Usually it was PRUNED: it installs with
+      // `npm install --no-save`, so npm has no record of it and any later
+      // `npm install` in this game deletes it. It is not lost — it is cached.
+      log('⚠️  looop lint: the Looop engine is not installed in this game — skipping.');
+      log('   (A plain `npm install` removes it; it is cached, so putting it back is instant.)');
+      log('   Restore it with:  looop update');
+    } else {
+      log('⚠️  looop lint: your engine is older than the Looop rules — skipping.');
+      log('   Get an engine that carries them:  looop update');
+    }
     return { ok: true, skipped: true, errorCount: 0, warningCount: 0 };
   }
 

package/lib/primitives.mjs

@@ -0,0 +1,345 @@
+// The game's own server primitives — discovery, and the registry the CLI
+// generates from them.
+//
+// THE ONE RULE
+//
+//   A file at `overrides/shared/<engine path>` IS that engine file, for this
+//   game. And `shared/ui/room/primitives/**` is the only part of it the SERVER
+//   runs; everything else under `overrides/shared/` is browser-only.
+//
+// That collapses what used to be two mechanisms with two folders and two mental
+// models (`overrides/shared/…` for the browser, `_local/primitives/index.js` for
+// the server) into one. It also collapses two *actions* into one: the engine has
+// a `player-body.js` and does not have a `gravity-well.js`, so overriding and
+// adding are the same act — put a file at the path. The creator never has to
+// know which one they're doing.
+//
+// FILENAME IS THE TYPE NAME. `gravity-well.js` → `{ type: 'gravity-well' }` in a
+// world spec. A folder with an `index.js` works too (that's how the engine ships
+// `intelligent-npc`). There is no barrel to maintain and no `extraPrimitives`
+// argument to remember — forgetting that argument used to make the CLIENT
+// predict with the ENGINE's class while the SERVER ran the creator's, so the two
+// disagreed every tick and the game rubber-banded. It can't happen now: the
+// registry is generated from the directory, for both sides, from this one scan.
+//
+// `index.js` in the primitives dir is RESERVED — it IS the generated registry.
+// A hand-written one would shadow the engine's and silently unregister every
+// engine primitive, so we reject it loudly instead.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+// The one path that is server code. Mirrors the engine's own layout, because
+// that is the whole point — this is `shared/ui/room/primitives/`, for this game.
+export const PRIMITIVES_DIR = 'overrides/shared/ui/room/primitives';
+
+// The two files the CLI GENERATES for a game with primitives. Neither is ever
+// hand-written, neither is in the creator's git.
+//
+//   SERVER_BARREL  — the `extraPrimitives` map the room's GameRoom subclass
+//                    hands to the host. Bundled into the per-game Worker at
+//                    publish; esbuilt into the dev room server by `looop dev`.
+//                    It also IS the publish endpoint's server-backed detector.
+//
+//   BROWSER_REGISTRY — a shadow of the engine's primitive registry, merged:
+//                    `{ ...engine, ...the game's }`. It is what lets the CLIENT
+//                    predict with the game's own classes without a
+//                    `createRoom({ extraPrimitives })` argument. It shadows
+//                    index.js, which is a one-line re-export of engine.js
+//                    precisely so this merge is possible (a shadow cannot import
+//                    the file it replaces).
+export const SERVER_BARREL = '_looop/primitives.js';
+export const BROWSER_REGISTRY = `${PRIMITIVES_DIR}/index.js`;
+
+// Emitted by the engine build (packages/engine/build.mjs): the DERIVED set of
+// `/shared/...` modules a game may NOT override — the room-runtime bundle closure
+// minus catalogued primitives minus the browser-registry seam. The build does the
+// derivation once; this guard and the publish endpoint (resolvePublish) both read
+// the same file, so there is no second copy to drift.
+export const SERVER_RESERVED_MANIFEST = 'room-server/server-reserved.json';
+
+// A primitive's source is `<type>.js` or `<type>/index.js`. Anything else next
+// to it — tests, a README, a helper module a primitive imports — is not one.
+const IS_TEST = /\.(test|smoke)\.(js|mjs)$/;
+
+// `export default class Foo {}` / `export default Foo` / `export { Foo as default }`.
+const HAS_DEFAULT_EXPORT = /^\s*export\s+default\b|^\s*export\s*\{[^}]*\bas\s+default\b/m;
+
+function isPrimitiveFile(name) {
+  return name.endsWith('.js') && !IS_TEST.test(name) && name !== 'index.js';
+}
+
+// → [{ type, module }], sorted by type. `module` is the game-root-relative path
+// to the class file, always POSIX-separated (it goes into generated source).
+//
+// Sorted because the output is bundled and content-hashed at publish, and a
+// release is immutable: an unstable order would mean an unstable hash for
+// bytes that never changed.
+export function scanPrimitives(projectDir) {
+  const root = join(projectDir, PRIMITIVES_DIR);
+  if (!existsSync(root)) return [];
+
+  const found = [];
+  for (const name of readdirSync(root)) {
+    const abs = join(root, name);
+
+    if (statSync(abs).isDirectory()) {
+      if (existsSync(join(abs, 'index.js'))) {
+        found.push({ type: name, module: `${PRIMITIVES_DIR}/${name}/index.js` });
+      }
+      continue;
+    }
+
+    if (name === 'index.js') {
+      throw new Error(
+        `${PRIMITIVES_DIR}/index.js is reserved — it is the primitive registry, and Looop generates it for you.\n` +
+          'Delete it. Every .js file in that folder is registered automatically, using its filename as the type name\n' +
+          "(so `gravity-well.js` is `{ type: 'gravity-well' }` in your world spec).",
+      );
+    }
+
+    if (isPrimitiveFile(name)) {
+      // Every top-level .js here IS a primitive — the filename is the type name,
+      // so there is nowhere for a plain helper module to hide. Catch it now, in
+      // the creator's own words, rather than as an esbuild error about a missing
+      // default export in a barrel they never wrote and cannot see.
+      if (!HAS_DEFAULT_EXPORT.test(readFileSync(abs, 'utf8'))) {
+        throw new Error(
+          `${PRIMITIVES_DIR}/${name} has no default export, so it cannot be a primitive.\n` +
+            'A primitive is `export default class { ... }`, and its filename is its type name.\n' +
+            `If ${name} is a HELPER your primitive imports, move it out of this folder — anywhere else in\n` +
+            `your game works, or a subfolder here (e.g. ${PRIMITIVES_DIR}/lib/${name}), which is not scanned.`,
+        );
+      }
+      found.push({ type: name.slice(0, -3), module: `${PRIMITIVES_DIR}/${name}` });
+    }
+  }
+
+  found.sort((a, b) => (a.type < b.type ? -1 : a.type > b.type ? 1 : 0));
+  return found;
+}
+
+// Does this game run its own code on the server? The ONE predicate — `dev` and
+// `publish` both ask it, so a game can never be server-backed in one and not the
+// other. (They used to disagree: publish looked for `_local/primitives/index.js`
+// while dev looked for a `partykit.json` that nothing ever created, so a
+// creator's primitive ran in production and silently did not run in dev.)
+export function isServerBacked(projectDir) {
+  return scanPrimitives(projectDir).length > 0;
+}
+
+// The one cycle shadowing makes possible, caught in the creator's own words.
+//
+// A NEW primitive may subclass an engine one — that is the RECOMMENDED way to
+// change a primitive's behaviour, because you keep taking engine updates to the
+// base and write only what differs:
+//
+//   // overrides/shared/ui/room/primitives/terrain-walk.js      ← a NEW name
+//   import { PlayerBody } from './engine.js';
+//   export default class TerrainWalk extends PlayerBody { … }
+//
+// A file that OVERRIDES `player-body` cannot do the same, and the reason is not
+// obvious: `engine.js` imports `./player-body.js`, and that specifier now resolves
+// to the game's own file. engine.js → your file → engine.js. In the browser that
+// surfaces as "Cannot access 'PlayerBody' before initialization" at boot, which
+// tells the creator nothing about what they actually did wrong.
+//
+// So: overriding a primitive in place is a FORK — self-contained, no engine.js.
+// Want to subclass? Give it a new name. That is what this error says.
+export function assertNoOverrideCycle(primitives, projectDir, sharedDir) {
+  const engineDir = join(sharedDir, 'ui', 'room', 'primitives');
+  for (const p of primitives) {
+    const shadowsEngine =
+      existsSync(join(engineDir, `${p.type}.js`)) || existsSync(join(engineDir, p.type, 'index.js'));
+    if (!shadowsEngine) continue;
+    if (!IMPORTS_ENGINE_JS.test(readFileSync(join(projectDir, p.module), 'utf8'))) continue;
+
+    throw new Error(
+      `${p.module} overrides the engine's '${p.type}' primitive AND imports './engine.js' — that is a cycle.\n` +
+        `engine.js imports './${p.type}.js', which is now YOUR file, which imports engine.js.\n` +
+        '\n' +
+        'Two ways out:\n' +
+        `  • Subclass instead of overriding — rename your file (e.g. my-${p.type}.js), keep the\n` +
+        `    './engine.js' import, and use { type: 'my-${p.type}' } in your world spec. You keep\n` +
+        '    taking engine updates to the base class. This is usually what you want.\n' +
+        `  • Or keep the name and make it a FORK — drop the './engine.js' import and write the\n` +
+        `    primitive self-contained. It stops receiving engine updates, like any override.`,
+    );
+  }
+}
+
+// A real `import … from './engine.js'` STATEMENT — line-anchored, and not inside
+// a comment.
+//
+// The first version of this was just /from ['"]\.\/engine\.js['"]/, which happily
+// matched the sentence "…import the base from './engine.js'" in a code COMMENT and
+// refused to build a primitive that was doing nothing wrong. A guard that fires on
+// prose is worse than no guard: it cries wolf, and the next person turns it off.
+const IMPORTS_ENGINE_JS = /^(?!\s*(?:\/\/|\*|\/\*))\s*import\b[^\n]*?\bfrom\s*['"]\.\/engine\.js['"]/m;
+
+// The generated registry, as source. Imported by the dev room server and bundled
+// into the per-game worker at publish; both feed it to `GameRoom.extraPrimitives()`.
+//
+// Paths are relative to the GAME ROOT — the barrel is written to `.looop/` but
+// esbuild is given the game root as its resolve base, so `./overrides/...`
+// resolves the same in dev and at publish.
+export function renderBarrel(primitives) {
+  const lines = [
+    '// GENERATED by the Looop CLI from ' + PRIMITIVES_DIR + '/ — do not edit, do not commit.',
+    '//',
+    '// Every .js file in that folder is a server primitive, registered under its',
+    '// filename. Add one by adding a file; there is nothing else to wire up.',
+    '',
+  ];
+  primitives.forEach((p, i) => {
+    lines.push(`import P${i} from './${p.module}';`);
+  });
+  lines.push('');
+  lines.push('export const extraPrimitives = {');
+  primitives.forEach((p, i) => {
+    lines.push(`  '${p.type}': P${i},`);
+  });
+  lines.push('};');
+  lines.push('');
+  return lines.join('\n');
+}
+
+// The BROWSER half: a shadow of the engine's primitive registry, merged.
+//
+// This is what lets the CLIENT predict with the game's own classes. Without it,
+// the server runs the creator's primitive while the client predicts with the
+// ENGINE's class of the same name — they disagree every tick and the game
+// rubber-bands. That used to be the creator's problem to remember
+// (`createRoom({ extraPrimitives })`); now it is nobody's, because the platform
+// generates it.
+//
+// It is written to `overrides/shared/ui/room/primitives/index.js`, which shadows
+// the engine's `index.js` — a deliberate one-line re-export of `engine.js` that
+// exists ONLY so this merge is possible. A shadow cannot import the file it
+// replaces (that's a cycle), so it reaches the engine's list through `engine.js`,
+// which nothing shadows.
+//
+// The served path this registry (and the engine's) lives at — `PRIMITIVES_DIR`
+// with the game-repo `overrides/` prefix stripped. Imports below are keyed to
+// THIS, absolutely.
+const SERVED_PRIMITIVES_DIR = `/${PRIMITIVES_DIR.replace(/^overrides\//, '')}`;
+
+// Every import here is ABSOLUTE `/shared/...`, NOT relative — and that is
+// load-bearing. This file is a shared module served content-addressed: in
+// production it lands at `/_shared/<hash>/shared/ui/room/primitives/index.js`
+// and `/shared/...` specifiers resolve through the game's import map. A RELATIVE
+// `./engine.js` would instead resolve against that hashed URL — same hash prefix
+// → the SAME (index.js) bytes come back, whose `default` export doesn't exist →
+// the client predictor never loads and the game boots broken in prod while
+// working in dev (where `/shared/` is served live and relative happens to work).
+// So the generated file is born absolute, like every other shared module.
+//   '/shared/ui/room/primitives/engine.js'  → not shadowed → the engine's list
+//   '/shared/ui/room/primitives/beacon.js'  → shadowed     → the game's primitive
+export function renderBrowserRegistry(primitives) {
+  const lines = [
+    '// GENERATED by the Looop CLI from ' + PRIMITIVES_DIR + '/ — do not edit, do not commit.',
+    '//',
+    "// This shadows the engine's primitive registry and merges your primitives",
+    '// into it, so the client predicts your movement with YOUR code — the same',
+    '// code the room is running. There is nothing to wire up in your game.',
+    '',
+    `import { PRIMITIVES as ENGINE } from '${SERVED_PRIMITIVES_DIR}/engine.js';`,
+  ];
+  primitives.forEach((p, i) => {
+    // Sibling paths INSIDE the shadowed folder — strip the repo-relative prefix.
+    const rel = p.module.slice(PRIMITIVES_DIR.length + 1);
+    lines.push(`import P${i} from '${SERVED_PRIMITIVES_DIR}/${rel}';`);
+  });
+  lines.push('');
+  lines.push('export const PRIMITIVES = {');
+  // ...ENGINE FIRST: a game primitive sharing an engine primitive's name must
+  // WIN. Reverse these and an override would be silently clobbered by the engine.
+  lines.push('  ...ENGINE,');
+  primitives.forEach((p, i) => {
+    lines.push(`  '${p.type}': P${i},`);
+  });
+  lines.push('};');
+  lines.push('');
+  return lines.join('\n');
+}
+
+// ── The silent no-op, made loud ──────────────────────────────────────────────
+//
+// Shadowing is a BROWSER mechanism: the dev server and the published import map
+// serve the game's copy of `/shared/<path>` instead of the engine's. The room
+// SERVER never resolves `/shared/...` at all — it runs `rooms-runtime.js`, which
+// esbuild bundled at engine-build time, long before this game existed.
+//
+// So shadowing a file that is inside that bundle gets you a SPLIT BRAIN: your
+// browser runs your copy, the room keeps running the engine's, the two disagree
+// every tick, and nothing anywhere says why. Before this guard the entire class
+// was accepted in silence — the file uploaded, served, and simply never ran on
+// the server.
+//
+// The one exception is a primitive CLASS. That is the supported case, and the
+// reason it works is that the CLI does NOT rely on shadowing to get it there: it
+// bundles the class into the game's own room server and injects it through
+// `extraPrimitives`, so both sides run the same code.
+//
+// WHY THE LIST IS DERIVED, NOT WRITTEN
+//
+// The closure is deep and it moves: server.js → runtime.js → host-core.js →
+// tags.js, body-integration.js, wallet-credit.js, room-identity.js,
+// cannon-physics.js … and `/shared/ui/jump/jump.js`, which nobody would ever
+// have guessed belongs on a hand-written list. A list that is 90% right is worse
+// than none: the 10% it misses is a guard that silently stopped guarding. So the
+// engine build emits the exact set (metafile closure minus catalogued primitives
+// minus the browser-registry seam) and we read it — the same file the publish
+// endpoint reads, so the CLI's answer and the server's cannot diverge.
+function reservedModules(engine) {
+  const manifest = join(engine.dir, SERVER_RESERVED_MANIFEST);
+  // A game pinned to an engine released before this guard existed has no
+  // manifest. That engine also has no override support worth guarding, so skip
+  // the check rather than refusing to build.
+  if (!existsSync(manifest)) return null;
+  try {
+    return new Set(JSON.parse(readFileSync(manifest, 'utf8')));
+  } catch {
+    return null;
+  }
+}
+
+// Walk the game's authored overrides — `overrides/shared/**` — yielding the
+// engine path each one claims to be (`/shared/ui/room/host-core.js`).
+function* authoredOverrides(projectDir) {
+  const root = join(projectDir, 'overrides', 'shared');
+  if (!existsSync(root)) return;
+  const walk = function* (dir, rel) {
+    for (const name of readdirSync(dir)) {
+      const abs = join(dir, name);
+      const next = rel ? `${rel}/${name}` : name;
+      if (statSync(abs).isDirectory()) yield* walk(abs, next);
+      else if (name.endsWith('.js') && !IS_TEST.test(name)) yield { abs, shared: `/shared/${next}` };
+    }
+  };
+  yield* walk(root, '');
+}
+
+export function assertNoInertOverride({ projectDir, engine }) {
+  const reserved = reservedModules(engine);
+  if (!reserved) return;
+
+  for (const { shared } of authoredOverrides(projectDir)) {
+    if (!reserved.has(shared)) continue; // overridable (primitive or browser-only)
+
+    const rel = shared.replace('/shared/', '');
+    throw new Error(
+      `overrides/shared/${rel} cannot be overridden — the room server runs this file, and it CANNOT take your copy.\n` +
+        '\n' +
+        'Your override would reach the browser but not the room: the server runs a runtime that was\n' +
+        'bundled before your game existed. Your client and the room would then be running different\n' +
+        'code, disagreeing every tick, with nothing to tell you why. So this is an error, not a warning.\n' +
+        '\n' +
+        'What you CAN override on the server is a primitive — a file in\n' +
+        `  ${PRIMITIVES_DIR}/<name>.js\n` +
+        'Those are bundled into your game\'s own room server, so they run on BOTH sides.\n' +
+        '\n' +
+        'If you need behaviour this file has, put it in a primitive and use that instead.\n' +
+        'If you think the engine itself should change here, send it with `looop feedback`.',
+    );
+  }
+}

package/lib/publish.mjs

@@ -16,7 +16,14 @@ import { findProject } from './project.mjs';
 import { ensureEngine } from './engine.mjs';
 import { getToken, getApiBase } from './config.mjs';
 import { DEFAULT_API_BASE } from './llm-shim.mjs';
-import { bundlePrimitives, PRIMITIVES_ENTRY } from './bundle-primitives.mjs';
+import { bundlePrimitives } from './bundle-primitives.mjs';
+import {
+  BROWSER_REGISTRY,
+  SERVER_BARREL,
+  assertNoInertOverride,
+  renderBrowserRegistry,
+  scanPrimitives,
+} from './primitives.mjs';
 
 export const PLAY_BASE = 'https://play.looop.games';
 
@@ -68,15 +75,37 @@ export async function publish({
     throw new Error('this game has no index.html at its root — publish needs an entry page.');
   }
 
-  // Server-backed game: its primitives can
-  // import npm packages + WASM the platform's bundler-less endpoint can't
-  // resolve, so we bundle them HERE (engine marked external) and send the
-  // single self-contained module in place of the raw barrel. The endpoint
-  // assembles the worker from it + our generated entry + the release runtime.
-  if (files.has(PRIMITIVES_ENTRY)) {
+  // Server-backed game — it has primitives of its own. The SAME predicate `looop
+  // dev` uses (isServerBacked), so a game can never be server-backed in one and
+  // not the other. It used to be "does the upload contain _local/primitives/
+  // index.js" here and "does a partykit.json exist" there, and they disagreed:
+  // a creator's primitive ran in production and silently not on their machine.
+  //
+  // Two files are GENERATED into the upload; neither is in the creator's git:
+  //
+  //   the SERVER barrel — bundled here, not at the endpoint (a Pages Function has
+  //     no bundler, and real primitives import npm packages and WASM). The engine
+  //     is marked external and rewritten to the release's pre-bundled runtime, so
+  //     the worker's room code is always ours.
+  //
+  //   the BROWSER registry — shadows the engine's primitive registry, merged, so
+  //     the CLIENT predicts with the game's classes too. Without it the server
+  //     runs the creator's primitive while the client predicts with the engine's
+  //     class of the same name, and the game rubber-bands. That used to be the
+  //     creator's job to remember (`createRoom({ extraPrimitives })`).
+  // Refuse to SHIP an override the server can never honour. dev catches this
+  // first, but publish must not trust that dev ran: the whole failure mode we
+  // are killing is an override that uploads, serves, and silently never runs.
+  assertNoInertOverride({ projectDir: project.dir, engine });
+  const serverPrimitives = scanPrimitives(project.dir); // throws on a reserved index.js
+  if (serverPrimitives.length) {
     const { source, externals } = await bundlePrimitives(project.dir);
-    files.set(PRIMITIVES_ENTRY, Buffer.from(source, 'utf8'));
-    log(`Bundled server primitives (${(source.length / 1024).toFixed(0)} KB, engine external${externals.length ? `: ${[...new Set(externals)].length} module(s)` : ''}).`);
+    files.set(SERVER_BARREL, Buffer.from(source, 'utf8'));
+    files.set(BROWSER_REGISTRY, Buffer.from(renderBrowserRegistry(serverPrimitives), 'utf8'));
+    const names = serverPrimitives.map((p) => p.type).join(', ');
+    log(
+      `Bundled server primitives — ${names} (${(source.length / 1024).toFixed(0)} KB, engine external${externals.length ? `: ${[...new Set(externals)].length} module(s)` : ''}).`,
+    );
   }
 
   const meta = { slug: targetSlug, entry: 'index.html', engineVersion: engine.version, files: {} };

package/lib/room-server.mjs

@@ -0,0 +1,166 @@
+// The dev room server — the half of "you can run your own code on the server"
+// that was never built.
+//
+// `looop publish` has always assembled a per-game Worker from a creator's
+// primitives. `looop dev` never did: it picked its room server by looking for a
+// `partykit.json`, a file nothing in the creator CLI writes, so it always fell
+// through to the engine's stock room server (whose `extraPrimitives()` returns
+// null). The creator's primitive was skipped with an `unknown primitive` warning
+// swallowed in partykit's stderr, while the client predicted it anyway. The
+// mechanic worked in production and not on the creator's machine — which is the
+// worst way round, because they only discover it after shipping.
+//
+// So: when a game has primitives, we generate a partykit project for it and
+// point dev at that instead.
+//
+// WHY WE BUNDLE IT OURSELVES. A creator's primitive imports engine helpers the
+// way everything else in a game does — `import { runEffect } from
+// '/shared/ui/room/primitives/effects.js'`. That leading `/shared/` is a
+// dev-server alias, not a path on disk, and partykit's bundler has never heard
+// of it. So we esbuild the room server here with a plugin that resolves
+// `/shared/*` to the installed engine, and hand partykit one self-contained
+// module. (The publish path solves the same problem differently: it marks those
+// imports EXTERNAL and rewrites them to the release's pre-bundled
+// `rooms-runtime.js`, because the publish endpoint is a Worker with no bundler.
+// Same seam, two deliveries.)
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  assertNoOverrideCycle,
+  isServerBacked,
+  renderBarrel,
+  renderBrowserRegistry,
+  scanPrimitives,
+} from './primitives.mjs';
+import { shadowResolvePlugin } from './shadow-resolve.mjs';
+
+// Build output, not source: gitignored by the scaffold and skipped by publish's
+// file collection. The creator never opens it.
+export const DEV_ROOM_SERVER_DIR = '.looop/room-server';
+
+// The generated BROWSER registry lands here, and `looop dev` mounts it at
+// `/shared/` AHEAD of both the creator's own overrides/ and the engine — so the
+// client's primitive registry is `{ ...engine, ...the game's }`.
+//
+// It cannot live in the creator's `overrides/shared/` for two reasons:
+// `index.js` there is RESERVED (a hand-written one would silently unregister
+// every engine primitive), and a build artifact has no business in their repo.
+// At publish the same bytes are injected straight into the upload, so neither
+// path ever touches their git.
+export const DEV_OVERRIDES_DIR = '.looop/overrides/shared';
+
+// Resolve the `/shared/...` dev alias to the installed engine. Everything a
+// primitive imports through it — and the room server itself — comes from the
+// exact engine version this game is pinned to.
+function engineAliasPlugin(sharedDir) {
+  return {
+    name: 'looop-shared-alias',
+    setup(build) {
+      build.onResolve({ filter: /^\/shared\// }, (args) => ({
+        path: join(sharedDir, args.path.slice('/shared/'.length)),
+      }));
+      // Workers-runtime built-ins are provided at execution; never bundle them.
+      build.onResolve({ filter: /^cloudflare:/ }, (args) => ({ path: args.path, external: true }));
+    },
+  };
+}
+
+// The room the game actually gets: the engine's room class, subclassed to hand
+// the host the creator's primitives through the `extraPrimitives()` seam the
+// engine already reads (server.js). Identical in shape to what the publish
+// endpoint generates for the per-game Worker — one contract, two builders.
+function renderEntry(primitives) {
+  return [
+    renderBarrel(primitives),
+    "import LooopRoom from '/shared/ui/room/server.js';",
+    '',
+    'export default class GameRoom extends LooopRoom {',
+    '  extraPrimitives() { return extraPrimitives; }',
+    '}',
+    '',
+  ].join('\n');
+}
+
+// → the cwd to run partykit in. The engine's stock room server when the game has
+// no primitives of its own; a freshly-built one when it does.
+//
+// Throws if the primitives dir is malformed (e.g. a hand-written index.js) —
+// dev must not quietly serve a room that is missing the creator's code.
+export async function buildDevRoomServer({ projectDir, engine, esbuildImpl }) {
+  const primitives = scanPrimitives(projectDir); // throws on a reserved index.js
+  if (!primitives.length) {
+    // Not server-backed (any more). A PREVIOUS run may have generated a room
+    // server and a registry shadow; both must go, or dev keeps mounting a stale
+    // `.looop/overrides/shared/.../index.js` that imports a primitive the creator
+    // has since deleted — an ES-import 404 that stops the whole room library
+    // loading. The mount is unconditional (dev.mjs), so the cleanup has to be too.
+    rmSync(join(projectDir, DEV_ROOM_SERVER_DIR), { recursive: true, force: true });
+    rmSync(join(projectDir, DEV_OVERRIDES_DIR), { recursive: true, force: true });
+    return engine.roomServerDir;
+  }
+  assertNoOverrideCycle(primitives, projectDir, engine.sharedDir);
+
+  const esbuild = esbuildImpl ?? (await import('esbuild'));
+  const outDir = join(projectDir, DEV_ROOM_SERVER_DIR);
+  mkdirSync(outDir, { recursive: true });
+
+  await esbuild.build({
+    // No entry file on disk: the barrel + subclass are fed straight in, resolved
+    // against the game root, so `./overrides/...` means what it says and no
+    // machine-specific absolute path can leak into the output.
+    stdin: {
+      contents: renderEntry(primitives),
+      resolveDir: projectDir,
+      sourcefile: 'looop-room-server.js',
+      loader: 'js',
+    },
+    outfile: join(outDir, 'server.js'),
+    bundle: true,
+    format: 'esm',
+    // workerd is browser-shaped, and so is the engine's own room runtime build.
+    platform: 'browser',
+    target: 'esnext',
+    legalComments: 'none',
+    conditions: ['workerd', 'worker'],
+    loader: { '.wasm': 'binary' },
+    absWorkingDir: projectDir,
+    plugins: [
+      // Shadowing, for the bundler: an override's relative imports fall through
+      // to the engine exactly as they do in the browser. This is what lets an
+      // override subclass the primitive it overrides (`import { PlayerBody }
+      // from './engine.js'`) — it cannot import its own path.
+      shadowResolvePlugin({ projectDir, sharedDir: engine.sharedDir }),
+      engineAliasPlugin(engine.sharedDir),
+    ],
+  });
+
+  writeFileSync(
+    join(outDir, 'partykit.json'),
+    JSON.stringify(
+      {
+        $schema: 'https://www.partykit.io/schema.json',
+        name: 'looop-dev',
+        main: 'server.js',
+        compatibilityDate: '2024-09-23',
+      },
+      null,
+      2,
+    ) + '\n',
+  );
+
+  // The BROWSER half. Building the room server fixes the SERVER; without this
+  // the client would still predict with the ENGINE's class of the same name,
+  // disagree with the server every tick, and rubber-band. Served by dev at
+  // `/shared/ui/room/primitives/index.js`, shadowing the engine's. Its imports
+  // are ABSOLUTE `/shared/...` (see renderBrowserRegistry) so they resolve the
+  // same in dev (static mount fall-through) and in production (the import map):
+  //   /shared/ui/room/primitives/engine.js  → not shadowed → the engine's list
+  //   /shared/ui/room/primitives/beacon.js  → shadowed     → the game's primitive
+  const registryDir = join(projectDir, DEV_OVERRIDES_DIR, 'ui/room/primitives');
+  mkdirSync(registryDir, { recursive: true });
+  writeFileSync(join(registryDir, 'index.js'), renderBrowserRegistry(primitives));
+
+  return outDir;
+}
+
+export { isServerBacked };

package/lib/shadow-resolve.mjs

@@ -0,0 +1,85 @@
+// Shadowing, for the BUNDLER.
+//
+// `overrides/shared/<engine path>` works in the browser because the dev server
+// (and, in production, the import map) resolves each `/shared/...` request
+// against the game's overrides FIRST and the engine SECOND — per file. A game's
+// override sits at the engine's own URL, so its neighbours resolve to the engine's.
+//
+// esbuild has no such notion. It resolves relative imports against the real
+// filesystem, where the game's overrides folder holds only the one or two files
+// the creator actually wrote. So this:
+//
+//   // overrides/shared/ui/room/primitives/player-body.js
+//   import { PlayerBody } from './engine.js';     // ← the escape hatch
+//
+// resolves in the browser (engine.js is right there at /shared/ui/room/primitives/)
+// and dies in the bundler ("Could not resolve ./engine.js") — the game's folder
+// has no engine.js, and never will: it's the engine's.
+//
+// That import is not incidental. It is the ONLY way an override can subclass the
+// primitive it overrides — it cannot import its own path, which is itself — and
+// "change one method" is the most common reason to override anything. So the
+// bundler has to learn the same fall-through the servers already do:
+//
+//   a relative import from inside overrides/shared/…
+//     → the game's file, if it has one
+//     → otherwise the engine's file at the mirrored path
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+const OVERRIDES_ROOT = join('overrides', 'shared');
+
+// esbuild hands us importer paths with symlinks already resolved, while the
+// project dir arrives as the caller spelled it. On macOS that alone is enough to
+// break the comparison below — a temp dir is `/var/…` to us and `/private/var/…`
+// to esbuild — and the fall-through would silently never fire, leaving the
+// creator with "Could not resolve ./engine.js" and no idea why.
+function realOrSelf(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p; // doesn't exist yet — compare as given
+  }
+}
+
+// Is `file` inside the game's overrides/shared/ tree?
+function underOverrides(file, overridesRoot) {
+  const rel = relative(overridesRoot, file);
+  return rel !== '' && !rel.startsWith('..') && !rel.startsWith(sep);
+}
+
+// engineExternal: at PUBLISH the engine is never bundled in — it is marked
+// external and rewritten to the release's pre-bundled `rooms-runtime.js`, so the
+// worker's room code is always ours. Pass the module specifier to rewrite to.
+// In DEV we build the whole room server ourselves, so the engine's real file on
+// disk is exactly what we want.
+export function shadowResolvePlugin({ projectDir, sharedDir, engineExternal = null, onEngineHit = () => {} }) {
+  const overridesRoot = realOrSelf(join(projectDir, OVERRIDES_ROOT));
+
+  return {
+    name: 'looop-shadow-resolve',
+    setup(build) {
+      build.onResolve({ filter: /^\.{1,2}\// }, (args) => {
+        if (!args.importer) return null;
+        // Everything below is computed in real-path space, so the overrides-root
+        // comparison and the shadow mapping can't disagree about the same file.
+        const importer = realOrSelf(args.importer);
+        if (!underOverrides(importer, overridesRoot)) return null;
+
+        const candidate = resolve(dirname(importer), args.path);
+
+        // The game has this file — its own primitive, its own helper. Use it.
+        if (existsSync(candidate)) return { path: candidate };
+
+        // It doesn't. In the browser this would have fallen through to the
+        // engine, so do the same here: map the path back across the shadow.
+        const rel = relative(overridesRoot, candidate);
+        const engineFile = join(sharedDir, rel);
+        if (!existsSync(engineFile)) return null; // let esbuild report it honestly
+
+        onEngineHit(`/shared/${rel.split(sep).join('/')}`);
+        return engineExternal ? { path: engineExternal, external: true } : { path: engineFile };
+      });
+    },
+  };
+}

package/lib/update.mjs

@@ -97,19 +97,52 @@ export async function update({
         .sort((a, b) => compareVersions(b.version, a.version))
     : null;
 
+  // ── The `looop` command FIRST, before the engine lands ─────────────────────
+  //
+  // Order is load-bearing, and getting it wrong deleted the engine. The engine is
+  // not an npm package — it installs with `npm install --no-save`, so npm has no
+  // record of it and treats it as extraneous. ANY later `npm install` in the game
+  // prunes it. syncCli runs exactly such an install (`--save-dev` the new CLI), so
+  // running it AFTER the engine install wiped the engine every single time: the
+  // update reported success and left node_modules/@looop-games/engine gone. The
+  // next `looop lint` then found no engine at all (caught on a real game).
+  //
+  // So: do every npm install that this command is going to do BEFORE the engine
+  // is put on disk, and let the engine be the last thing to land.
+  //
+  // Wrapped: syncCli is already fail-soft, and a bug in it must not stop the
+  // engine update that is the point of this command.
+  let cli;
+  try {
+    cli = await syncCliFn({ projectDir: project.dir, log });
+  } catch (err) {
+    cli = { updated: false, error: err };
+  }
+
   let engineDir = null;
   let updated = false;
 
   if (from === latest) {
-    log(`✅ Engine ${latest} — already up to date.`);
     // Reconcile anyway. A repo can sit on the latest engine and STILL have an
     // out-of-date surface: one scaffolded before this mechanism existed has
     // never had its skills adopted, and would otherwise wait forever for a
     // release it already has.
     try {
       engineDir = resolveEngine(project.dir).dir;
+      log(`✅ Engine ${latest} — already up to date.`);
     } catch {
-      engineDir = null; // engine not installed yet — the next `dev` fetches it
+      // Pinned to the latest, but NOT on disk. The pin is a claim about what this
+      // game runs; node_modules is the truth, and they disagree — because a plain
+      // `npm install` (the creator's own, or ours above) prunes the engine, which
+      // npm never recorded. "Already up to date" while the engine is missing is a
+      // lie that leaves every engine-reading command broken, and re-running update
+      // could never fix it. Put it back — from the local cache, so this is fast and
+      // works offline.
+      log(`Engine ${latest} is pinned but missing from node_modules — reinstalling it.`);
+      const engine = await ensure(project.dir, { apiBase, log, fetchImpl });
+      engineDir = engine.dir ?? null;
+      log('');
+      log(`✅ Engine ${latest} — restored.`);
     }
   } else {
     // Rewrite the pin first; ensureEngine honors it (download → install → pin).
@@ -125,21 +158,18 @@ export async function update({
   if (!surface.skipped) report(log, surface.engineVersion ?? latest, surface);
 
   // The third lane: the `looop` command itself (see self-update.mjs). The skills
-  // we just reconciled ship WITH the engine and can name any command they like —
-  // riven ended up on an engine whose skills say `looop changelog` while its CLI
-  // was four versions too old to have it. So update moves this too.
+  // we reconciled ship WITH the engine and can name any command they like — a real
+  // game ended up on an engine whose skills say `looop changelog` while its CLI was
+  // four versions too old to have it. So update moves this too.
   //
-  // Wrapped: syncCli is already fail-soft, but a bug in it must not undo an
-  // engine update that has already landed on disk.
-  let cli;
-  try {
-    cli = await syncCliFn({ projectDir: project.dir, log });
-    reportCli(log, cli);
-  } catch (err) {
-    cli = { updated: false, error: err };
+  // It already RAN, at the top: its npm install has to happen before the engine
+  // lands or it prunes it. This is only the report.
+  if (cli?.error) {
     log('');
-    log(`   The looop command could not be updated (${err.message}).`);
+    log(`   The looop command could not be updated (${cli.error.message}).`);
     log('   Your engine and skills are up to date. Retry with: npm update @looop-games/cli');
+  } else {
+    reportCli(log, cli);
   }
 
   if (updated) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@looop-games/cli",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Looop game development CLI — dev server, login, and publishing for standalone Looop games.",
   "type": "module",
   "license": "Apache-2.0",