@looop-games/cli 0.1.23 → 0.1.25

package/CHANGELOG.md

@@ -14,6 +14,43 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.25] - 2026-08-01
+
+### Fixed
+
+- `looop dev` now rebuilds and restarts the multiplayer room when you edit a
+  file the room depends on — your primitives and their helpers, entity data
+  (`entities/`), components, and `overrides/`. Before, only the page reloaded:
+  the room kept adjudicating with your pre-edit code and pre-edit spawned
+  entities until you killed and relaunched the stack, so a change could look
+  like it did nothing. Room state resets on such an edit (the world reseeds
+  when the page rejoins); if the rebuild fails, the previous room keeps
+  running and the error is printed. This also means a game that gains its
+  first primitive while `dev` is running now gets its own room server
+  immediately, instead of silently staying on the stock one.
+- `looop dev` could keep running your pre-edit code after you changed a file,
+  with no error anywhere — the game just looked like your change did nothing.
+  Import URLs are now stamped so that editing any file renames the URL of every
+  module that (directly or indirectly) imports it, which forces the browser to
+  refetch the changed part of the game on the next reload instead of silently
+  reusing what it had cached.
+
+## [0.1.24] - 2026-08-01
+
+### Changed
+
+- `looop update` now always installs Looop's version of the skill files and
+  the `AGENTS.md` managed block, and removes retired ones — even where they
+  were changed locally. Before, an edited file was kept and silently stopped
+  receiving updates forever; one unnoticed agent edit could freeze a skill
+  out of every future release. Nothing is lost when this happens: the update
+  marks each such file `OVERWROTE`, saves the previous copy in
+  `.looop/backup-<version>/` (git has it too), and the `/update-looop` skill
+  walks you through keeping anything that mattered. Guidance you want kept
+  belongs in `AGENTS.md` below the managed block, where updates never touch
+  it. Repos already stuck with a frozen skill heal themselves on their next
+  update — no action needed.
+
 ## [0.1.23] - 2026-08-01
 
 ### Changed

package/lib/agent-surface.mjs

@@ -23,26 +23,41 @@
 //
 // The one contract everything here serves:
 //
-//     an update reaches a pre-existing repo without touching anything
-//     user-owned.
+//     an update always lands Looop's surface, and never loses the
+//     creator's content — anything it replaces or removes is backed up
+//     and reported.
 //
-// So ownership is tracked explicitly, in `.looop/agent-surface.json` — the
-// hash of every file WE wrote. On each run a file is one of:
+// Ownership is by PATH (note hx3kd9): a path the artifact ships belongs to the
+// platform and always converges to the artifact's version. On each run a file at
+// a shipped path is one of:
 //
-//   ours, unmodified  (hash matches what we recorded)  → replace with the new
-//   ours, edited      (hash differs)                   → KEEP theirs, warn
-//   never ours        (no record, but on disk)         → KEEP theirs, warn
-//   not on disk                                        → place ours
-//   retired upstream                                   → remove, if still ours
+//   content already equal to the incoming  → heal the record, silently
+//   ours, unmodified (hash == recorded)    → replace with the new
+//   anything else on disk                  → back it up, replace, report lossy
+//   not on disk                            → place ours
+//   retired upstream / orphaned            → remove (backup + lossy when the
+//                                            content didn't match the record)
 //
-// A skill we never placed is never even enumerated, so a creator's own skills
-// are invisible to this code by construction. `AGENTS.md` is the exception that
-// proves the rule: the managed block between the markers is ours to rewrite;
-// everything outside them (their title, their instructions below the end
-// marker) is theirs and is spliced back untouched.
+// There is deliberately no keep-theirs outcome. The old model kept edited
+// files and "shadowed" the incoming version — which permanently froze a file
+// out of every future update after a single (usually agent-made, usually
+// unnoticed) edit, breaking the harness for that repo silently (fb_3a0bea).
+// The hash record in `.looop/agent-surface.json` is therefore not an ownership
+// gate anymore: it is a change DETECTOR, kept so the report can say "this had
+// local content" honestly instead of warning on every write. `lossy` is that
+// report; `looop update` narrates it and the /update-looop skill asks the
+// creator what to do with each lost edit.
+//
+// A skill we never ship is never even enumerated, so a creator's own skills
+// are invisible to this code by construction. `AGENTS.md` is the sanctioned
+// home for creator additions: the managed block between the markers is ours to
+// rewrite; everything outside them (their title, their instructions below the
+// end marker) is theirs and is spliced back untouched — and when the markers
+// themselves have been deleted, the block is re-appended below their content
+// rather than contesting any of it.
 import { createHash } from 'node:crypto';
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
 
 export const SURFACE_DIR = 'agent-surface';
 export const LOCAL_MANIFEST = '.looop/agent-surface.json';
@@ -100,9 +115,27 @@ function pruneEmptyDirs(projectDir, dest) {
   }
 }
 
+// Whether everything on disk at `dest` (a file, or a whole skill folder) still
+// matches the hashes recorded for it. Distinguishes a clean retire/orphan
+// removal from one that destroys real local content — only the latter earns a
+// backup and a `lossy` report. A file with no record at all counts as
+// non-matching: content we can't vouch for is content to preserve.
+function contentMatchesRecord(abs, dest, placed) {
+  if (!statSync(abs).isDirectory()) {
+    return placed[dest] !== undefined && sha(readFileSync(abs)) === placed[dest];
+  }
+  const entries = readdirSync(abs, { recursive: true, withFileTypes: true }).filter((e) => e.isFile());
+  if (!entries.length) return true; // an empty folder holds nothing to lose
+  return entries.every((e) => {
+    const file = join(e.parentPath, e.name);
+    const rel = join(dest, relative(abs, file));
+    return placed[rel] !== undefined && sha(readFileSync(file)) === placed[rel];
+  });
+}
+
 // Splice the artifact's managed block into the repo's AGENTS.md, preserving
 // everything outside the markers. Returns null when the creator's file has no
-// markers — they rewrote Layer 0 themselves, so it is theirs now.
+// markers; the caller then re-appends the block below their content.
 function spliceManaged(current, incoming) {
   const cs = current.indexOf(START);
   const ce = current.indexOf(END);
@@ -122,7 +155,7 @@ function spliceManaged(current, incoming) {
  */
 export function reconcileAgentSurface(projectDir, engineDir, { log = console.log } = {}) {
   const result = {
-    placed: [], removed: [], shadowed: [], backups: [],
+    placed: [], removed: [], lossy: [], backups: [],
     adopted: false, skipped: false, engineVersion: null, backupDir: null,
   };
   const surface = join(engineDir, SURFACE_DIR);
@@ -166,19 +199,22 @@ export function reconcileAgentSurface(projectDir, engineDir, { log = console.log
 
     // ── retired entries: remove what upstream dropped. This is the half that
     //    makes a RENAME possible on a repo that already exists — without it a
-    //    replaced skill would linger next to its replacement forever. ─────────
+    //    replaced skill would linger next to its replacement forever, still
+    //    loaded by the creator's agent as live guidance. Removal is
+    //    unconditional (the path is Looop's); content that doesn't match
+    //    the record is preserved in the backup and reported lossy. ───────────
     for (const rel of manifest.retired ?? []) {
       const dest = target(rel);
       if (!dest) continue;
       const abs = join(projectDir, dest);
       if (!existsSync(abs)) continue;
 
-      const owned = Object.keys(placed).some((p) => p === dest || p.startsWith(`${dest}/`));
-      if (!owned && !adopt) {
-        result.shadowed.push(dest);
-        continue;
+      if (adopt) {
+        backup(dest); // no record to compare — preserve, but don't accuse
+      } else if (!contentMatchesRecord(abs, dest, placed)) {
+        backup(dest);
+        result.lossy.push(dest);
       }
-      if (adopt) backup(dest);
       rmSync(abs, { recursive: true, force: true });
       for (const p of Object.keys(placed)) {
         if (p === dest || p.startsWith(`${dest}/`)) delete placed[p];
@@ -201,12 +237,16 @@ export function reconcileAgentSurface(projectDir, engineDir, { log = console.log
 
       if (dest === 'AGENTS.md') {
         // The markers ARE the contract: inside is ours, outside is theirs.
-        const next = exists
-          ? spliceManaged(current.toString('utf8'), desired.toString('utf8'))
-          : desired.toString('utf8');
+        const desiredStr = desired.toString('utf8');
+        let next = exists ? spliceManaged(current.toString('utf8'), desiredStr) : desiredStr;
         if (next === null) {
-          result.shadowed.push(dest);
-          continue;
+          // Their file has no markers — they (or their agent) rewrote Layer 0.
+          // The block must still land, but everything they wrote is theirs, so
+          // it is re-appended below their content, touching none of it.
+          const is = desiredStr.indexOf(START);
+          const ie = desiredStr.indexOf(END);
+          if (is === -1 || ie === -1) continue; // artifact itself has no block — nothing to land
+          next = current.toString('utf8').replace(/\s*$/, '\n\n') + desiredStr.slice(is, ie + END.length) + '\n';
         }
         if (exists && current.toString('utf8') === next) continue;
         writeFileSync(abs, next);
@@ -217,16 +257,21 @@ export function reconcileAgentSurface(projectDir, engineDir, { log = console.log
 
       if (exists) {
         const now = sha(current);
-        if (now === recorded) {
-          if (now === sha(desired)) continue; // already current
-        } else if (recorded === undefined && adopt) {
-          if (now !== sha(desired)) backup(dest);
-        } else {
-          // Either they edited ours, or it was never ours. Both are theirs.
-          result.shadowed.push(dest);
-          placed[dest] = recorded ?? now;
+        if (now === sha(desired)) {
+          // Content already equal — including the frozen-record case where a
+          // local edit was independently upstreamed (fb_3a0bea). Nothing to
+          // write, nothing lost; heal the record so future updates apply.
+          placed[dest] = now;
           continue;
         }
+        if (adopt) {
+          backup(dest); // no record to compare — preserve, but don't accuse
+        } else if (now !== recorded) {
+          // Edited ours, or never ours — either way real local content is
+          // about to be replaced: preserve it and report it for the ask flow.
+          backup(dest);
+          result.lossy.push(dest);
+        }
       }
 
       mkdirSync(dirname(abs), { recursive: true });
@@ -251,8 +296,10 @@ export function reconcileAgentSurface(projectDir, engineDir, { log = console.log
       const abs = join(projectDir, dest);
       if (existsSync(abs)) {
         if (sha(readFileSync(abs)) !== placed[dest]) {
-          result.shadowed.push(dest); // they changed it — it's theirs now
-          continue;
+          // They changed it — the retirement still lands, the content survives
+          // in the backup and the caller asks the creator about it.
+          backup(dest);
+          result.lossy.push(dest);
         }
         rmSync(abs, { force: true });
         pruneEmptyDirs(projectDir, dest);

package/lib/dev.mjs

@@ -19,6 +19,7 @@ import { getToken, getApiBase } from './config.mjs';
 import { resolvePorts, portInUse, killPort, lanIp } from './ports.mjs';
 import { assertNoInertOverride, scanPrimitives } from './primitives.mjs';
 import { buildDevRoomServer, DEV_OVERRIDES_DIR } from './room-server.mjs';
+import { createFileWatcher, createRoomReloader } from './room-reload.mjs';
 
 // Resolve the partykit CLI entry from OUR dependencies (the game never
 // declares partykit; it rides @looop-games/cli). partykit's `exports` map hides
@@ -90,7 +91,7 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
   // 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 { cwd: roomServerCwd, inputs: roomInputs } = await buildDevRoomServer({ projectDir: project.dir, engine });
   const ownServer = roomServerCwd !== engine.roomServerDir;
 
   const stop = () => {
@@ -153,20 +154,115 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
       log(`→ multiplayer :${ports.mp}  (our stale server — reclaiming)`);
       await killPort(ports.mp);
     }
-    const pk = spawn(
-      process.execPath,
-      [partykitBin(), 'dev', '--port', String(ports.mp), '--persist', join(tmpdir(), `looop-partykit-${ports.mp}`)],
-      { cwd: roomServerCwd, stdio: ['ignore', 'pipe', 'pipe'], detached: true },
-    );
-    pk.stdout.on('data', () => {});
-    pk.stderr.on('data', (d) => {
-      const s = String(d);
-      if (/error/i.test(s)) log(`[partykit] ${s.trim()}`);
-    });
-    children.push(pk);
+    const spawnMp = (cwd) => {
+      const pk = spawn(
+        process.execPath,
+        [partykitBin(), 'dev', '--port', String(ports.mp), '--persist', join(tmpdir(), `looop-partykit-${ports.mp}`)],
+        { cwd, stdio: ['ignore', 'pipe', 'pipe'], detached: true },
+      );
+      pk.stdout.on('data', () => {});
+      pk.stderr.on('data', (d) => {
+        const s = String(d);
+        if (/error/i.test(s)) log(`[partykit] ${s.trim()}`);
+      });
+      // A spawn that fails (ENOENT, EMFILE) emits 'error' and never 'exit';
+      // without a listener the event throws and takes the stack down.
+      pk.on('error', (err) => log(`[partykit] failed to start: ${err.message}`));
+      children.push(pk);
+      return pk;
+    };
+    const killMp = async (pk) => {
+      const idx = children.indexOf(pk);
+      if (idx !== -1) children.splice(idx, 1);
+      if (pk.pid == null) return; // never started — nothing to reap, and 'exit' will never fire
+      const exited = new Promise((resolveExit) => {
+        if (pk.exitCode !== null || pk.signalCode !== null) return resolveExit();
+        pk.once('exit', resolveExit);
+        pk.once('error', resolveExit);
+      });
+      try {
+        process.kill(-pk.pid, 'SIGTERM');
+      } catch {
+        try {
+          pk.kill('SIGTERM');
+        } catch {
+          /* gone */
+        }
+      }
+      // partykit is a node wrapper forking workerd; if the tree ignores TERM,
+      // escalate — the port must be free before the replacement binds it.
+      const hardKill = setTimeout(() => {
+        try {
+          process.kill(-pk.pid, 'SIGKILL');
+        } catch {
+          /* gone */
+        }
+      }, 2000);
+      hardKill.unref();
+      await exited;
+      clearTimeout(hardKill);
+      // The parent's exit is not the port's release: workerd is a separate
+      // process in the group and can hold the listening socket a beat longer.
+      // A replacement that binds too early dies on EADDRINUSE — killing a
+      // working room and leaving nothing. Wait until the port is actually free.
+      const deadline = Date.now() + 5000;
+      while ((await portInUse(ports.mp)) && Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 100));
+      }
+    };
+    const pk = spawnMp(roomServerCwd);
     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})`,
     );
+
+    // The room bundle is frozen at build time, so the static watcher's page
+    // reload is only half the contract: an edit to anything the room runs on
+    // (entity data, a room override, a server sim) must also rebuild the room
+    // and restart its child, or the creator playtests against pre-edit
+    // adjudication with everything looking live — a failure `looop test` is
+    // structurally blind to, because it boots fresh stacks.
+    //
+    // The watch set is the bundle's own input list (covers every file the room
+    // actually imports, wherever it lives) plus the room-shaped game trees for
+    // files that don't exist yet — a first primitive, a new entity, a new room
+    // override. overrides/ is deliberately scoped to its room subtree: editing
+    // a purely client-side override must not restart the room and reset its
+    // state mid-playtest.
+    let roomWatcher = null;
+    let roomCwd = roomServerCwd;
+    const reloader = createRoomReloader({
+      build: () => buildDevRoomServer({ projectDir: project.dir, engine }),
+      spawnChild: spawnMp,
+      killChild: killMp,
+      log,
+      onRebuilt: (built) => {
+        roomWatcher?.setFiles(built.inputs);
+        // A rebuild can flip which server the game runs on (first primitive
+        // added, last one removed) — say so, or the startup line misleads for
+        // the rest of the session.
+        if (built.cwd !== roomCwd) {
+          roomCwd = built.cwd;
+          log(
+            `→ multiplayer :${ports.mp}  (now on ${roomCwd === engine.roomServerDir ? "the engine's room server" : "this game's OWN server"})`,
+          );
+        }
+      },
+    });
+    reloader.attach(roomServerCwd, pk);
+    roomWatcher = createFileWatcher({
+      files: roomInputs,
+      dirs: ['entities', 'components', 'overrides/shared/ui/room'].map((d) => join(project.dir, d)),
+      onChange: reloader.onChange,
+    });
+    // stop() (e.g. `looop test` tearing down its stack) must also stop the
+    // reloader: a rebuild in flight would otherwise spawn a replacement room
+    // child AFTER the children list was killed — a leaked detached process.
+    servers.push({
+      close: () => {
+        reloader.stop();
+        roomWatcher.close();
+      },
+    });
   }
 
   // ─── platform services shim ───

package/lib/inject.mjs

@@ -5,10 +5,10 @@
 //     (classic scripts, so globals exist before any module runs) + the ONE
 //     platform-layer module tag. New platform features are added to
 //     shared/platform/platform.js FEATURES — never here.
-//   * ?v=<mtime> rewriting on <script src> and JS imports busts Chrome's
+//   * ?v=<stamp> rewriting on <script src> and JS imports busts Chrome's
 //     sticky module cache on edit.
-import { statSync } from 'node:fs';
-import { join, dirname, normalize } from 'node:path';
+import { readFileSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
 
 // MUST match builder/functions/_shared/serve-identity.ts DEV_IDENTITY.
 export const DEV_IDENTITY = { userId: 'dev-local-user', name: 'Dev', color: '#38bdf8' };
@@ -39,36 +39,137 @@ const JS_IMPORT_RE = /(\b(?:from|import)\s*\(?\s*)(['"])([^'"\n]+?)\2/g;
 // Match <script src="X"> in HTML.
 const HTML_SCRIPT_RE = /(<script\b[^>]*?\bsrc\s*=\s*["'])([^"']+?)(["'])/gi;
 
-// Resolve `relPath` and return `<relPath>?v=<mtime-seconds>` or null.
-// `resolveUrl(urlPath)` maps an absolute URL path through the server's mounts.
-function versionedPath(relPath, { baseDir, resolveUrl, allowBareRelative = false }) {
-  if (/^(https?:)?\/\//.test(relPath) || relPath.startsWith('data:') || relPath.startsWith('blob:')) return null;
-  if (relPath.includes('?') || relPath.includes('#')) return null;
-  if (!/\.(js|mjs)$/.test(relPath)) return null;
-  let target;
-  if (relPath.startsWith('/')) target = resolveUrl(relPath);
-  else if (relPath.startsWith('.')) target = normalize(join(baseDir, relPath));
-  else if (allowBareRelative) target = normalize(join(baseDir, relPath));
-  else return null; // bare module specifier
-  if (!target) return null;
+// A spec that can never name a local file the server would stamp: absolute
+// URLs, data:/blob:, and anything already carrying a query or fragment.
+function isExternalSpec(spec) {
+  return (
+    /^(https?:)?\/\//.test(spec) ||
+    spec.startsWith('data:') ||
+    spec.startsWith('blob:') ||
+    spec.includes('?') ||
+    spec.includes('#')
+  );
+}
+
+// Resolve an import specifier the way the BROWSER does — against the importing
+// module's URL — returning an absolute URL path, or null for bare/external
+// specs. Stamping must live in URL space because that is where module identity
+// lives: an engine file's relative sibling import can be shadowed by the
+// game's overrides mount, so the file the URL serves is not the file that sits
+// next to the importer on disk.
+function resolveSpecToUrl(spec, baseUrl, { allowBareRelative = false } = {}) {
+  if (isExternalSpec(spec)) return null;
+  if (spec.startsWith('/')) return spec;
+  if (!spec.startsWith('.') && !allowBareRelative) return null; // bare module specifier
+  try {
+    return new URL(spec, 'http://x' + baseUrl).pathname;
+  } catch {
+    return null;
+  }
+}
+
+// The version stamp is the max mtime over the module's TRANSITIVE static
+// import closure, not the file's own mtime. Module identity is the full URL,
+// and a browser may reuse a cached body for an unchanged URL across reloads
+// (Chrome's memory cache does not honor no-store for same-URL subresources).
+// A per-target stamp renames only the edited file's URL — its importers' URLs
+// stay put, so a reloading page reassembles the whole pre-edit graph from
+// cache with zero requests and no error anywhere. Stamping the closure renames
+// every URL on the path from the entry (which a navigation always re-fetches),
+// so no URL-keyed cache can serve stale bytes.
+//
+// The parse cache stores RAW specifiers keyed by file path + mtime; resolution
+// happens per walk, because the same file's specs resolve differently through
+// different mount tables (two servers in one process must not contaminate each
+// other). Boundary: only string-literal static/dynamic imports are seen —
+// import(expr) and new URL(...) are runtime-computed and stay unstamped.
+const parseCache = new Map(); // abs fs path -> { mtimeMs, specs: string[] }
+
+function fileInfo(path) {
+  let st;
   try {
-    const mtime = Math.floor(statSync(target).mtimeMs / 1000);
-    return `${relPath}?v=${mtime}`;
+    st = statSync(path);
   } catch {
     return null;
   }
+  const hit = parseCache.get(path);
+  if (hit && hit.mtimeMs === st.mtimeMs) return hit;
+  const specs = [];
+  if (/\.(js|mjs)$/.test(path)) {
+    let text = null;
+    try {
+      text = readFileSync(path, 'utf8');
+    } catch {
+      /* unreadable: stamp from its own mtime alone */
+    }
+    if (text !== null) {
+      for (const m of text.matchAll(JS_IMPORT_RE)) {
+        if (!isExternalSpec(m[3])) specs.push(m[3]);
+      }
+    }
+  }
+  const info = { mtimeMs: st.mtimeMs, specs };
+  parseCache.set(path, info);
+  return info;
+}
+
+// Walk in URL space: each node is a URL path, mapped to bytes through the
+// server's mount table. `memo` (shared across one rewrite pass) short-circuits
+// only entry nodes — a spec repeated in one body — not intermediates.
+function closureStampUrl(urlPath, resolveUrl, memo) {
+  if (memo?.has(urlPath)) return memo.get(urlPath);
+  let max = 0;
+  const seen = new Set();
+  const stack = [urlPath];
+  while (stack.length) {
+    const u = stack.pop();
+    if (seen.has(u)) continue;
+    seen.add(u);
+    const fs = resolveUrl(u);
+    if (!fs) continue;
+    const info = fileInfo(fs);
+    if (!info) continue;
+    if (info.mtimeMs > max) max = info.mtimeMs;
+    for (const spec of info.specs) {
+      const child = resolveSpecToUrl(spec, u);
+      if (child) stack.push(child);
+    }
+  }
+  const stamp = max ? Math.floor(max) : null;
+  memo?.set(urlPath, stamp);
+  return stamp;
+}
+
+// Resolve `relPath` and return `<relPath>?v=<closure-stamp>` or null. Stamped
+// extensions include .json: entity/config data is imported by games, and its
+// URL must rename on edit exactly like a module's.
+//
+// `baseUrl` + `resolveUrl` are REQUIRED for stamping: there is deliberately no
+// disk-space fallback. Resolving a relative spec beside the importer on disk
+// stamps the wrong file whenever a mount shadows it (the overrides mechanism),
+// which silently re-opens the staleness hole. No serving context → no stamp.
+function versionedPath(relPath, { baseUrl, resolveUrl, allowBareRelative = false, memo }) {
+  if (!/\.(js|mjs|json)$/.test(relPath)) return null;
+  if (baseUrl == null || !resolveUrl) return null;
+  const urlTarget = resolveSpecToUrl(relPath, baseUrl, { allowBareRelative });
+  if (!urlTarget) return null;
+  if (!resolveUrl(urlTarget)) return null; // nothing serves it — leave the spec alone
+  const stamp = closureStampUrl(urlTarget, resolveUrl, memo);
+  return stamp === null ? null : `${relPath}?v=${stamp}`;
 }
 
-export function rewriteJsImports(text, { baseDir, resolveUrl }) {
+export function rewriteJsImports(text, { baseUrl, resolveUrl }) {
+  const memo = new Map();
   return text.replace(JS_IMPORT_RE, (whole, prefix, quote, path) => {
-    const v = versionedPath(path, { baseDir, resolveUrl });
+    const v = versionedPath(path, { baseUrl, resolveUrl, memo });
     return `${prefix}${quote}${v ?? path}${quote}`;
   });
 }
 
-export function rewriteHtmlScripts(html, { baseDir, resolveUrl }) {
+export function rewriteHtmlScripts(html, { baseUrl, resolveUrl }) {
+  const memo = new Map();
   return html.replace(HTML_SCRIPT_RE, (whole, prefix, path, suffix) => {
-    const v = versionedPath(path, { baseDir, resolveUrl, allowBareRelative: true });
+    const v = versionedPath(path, { baseUrl, resolveUrl, allowBareRelative: true, memo });
     return `${prefix}${v ?? path}${suffix}`;
   });
 }

package/lib/room-reload.mjs

@@ -0,0 +1,168 @@
+// Room hot-reload for `looop dev`.
+//
+// The room bundle (room-server.mjs) is frozen at build time and partykit runs
+// it as-is, so an edit to a room-authoritative file — entity data, an override,
+// a server sim, a manifest — reaches the client (page reload) but not the room
+// unless something rebuilds it. This module is that something: a poll watcher
+// over the bundle's actual inputs plus the room-shaped game trees, and a
+// reloader that rebuilds and restarts the partykit child on change.
+//
+// Restarting the child drops the room's in-memory world on purpose: the state
+// was seeded from pre-edit files, and the page reload the static watcher
+// already fires makes the next join reseed from the fresh ones. A rebuild that
+// FAILS must never take the working room down with it — the creator gets the
+// old room and a loud message, not a dead stack.
+import { readdirSync, statSync } from 'node:fs';
+import { extname, join } from 'node:path';
+
+// Extensions that can be a room input when watching a whole dir. Explicit
+// files (bundle metafile inputs) are watched regardless of extension.
+const ROOM_EXTS = new Set(['.js', '.mjs', '.json', '.wasm']);
+
+function snapshot(files, dirs) {
+  const out = new Map();
+  for (const f of files) {
+    try {
+      out.set(f, statSync(f).mtimeMs);
+    } catch {
+      out.set(f, -1); // a vanished input is a change too
+    }
+  }
+  const walk = (dir) => {
+    let names;
+    try {
+      names = readdirSync(dir);
+    } catch {
+      return; // the tree may not exist yet — its first file appearing is a change
+    }
+    for (const name of names) {
+      if (name.startsWith('.') || name === 'node_modules') continue;
+      const p = join(dir, name);
+      let st;
+      try {
+        st = statSync(p);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) walk(p);
+      else if (ROOM_EXTS.has(extname(name).toLowerCase())) out.set(p, st.mtimeMs);
+    }
+  };
+  for (const d of dirs) walk(d);
+  return out;
+}
+
+function differs(a, b) {
+  if (a.size !== b.size) return true;
+  for (const [k, v] of a) if (b.get(k) !== v) return true;
+  return false;
+}
+
+export function createFileWatcher({ files = [], dirs = [], intervalMs = 400, onChange = null }) {
+  // Two independent baselines: the explicit file list (which setFiles swaps
+  // between rebuilds) and the dir walk (which setFiles must never touch). One
+  // merged map couldn't tell a dropped input apart from a dir-walk entry.
+  let watchedFiles = [...files];
+  const watchedDirs = [...dirs];
+  let fileSnap = snapshot(watchedFiles, []);
+  let dirSnap = snapshot([], watchedDirs);
+  const oneShots = [];
+  const timer = setInterval(() => {
+    const nextFiles = snapshot(watchedFiles, []);
+    const nextDirs = snapshot([], watchedDirs);
+    if (differs(fileSnap, nextFiles) || differs(dirSnap, nextDirs)) {
+      fileSnap = nextFiles;
+      dirSnap = nextDirs;
+      while (oneShots.length) oneShots.pop()();
+      // Fire-and-forget on purpose, but a rejection out of the handler must
+      // not become an unhandled rejection that takes the dev stack down.
+      try {
+        Promise.resolve(onChange?.()).catch(() => {});
+      } catch {
+        /* handler threw synchronously — the handler owns its own reporting */
+      }
+    }
+  }, intervalMs);
+  timer.unref();
+  return {
+    setFiles(next) {
+      // Swap the file LIST without rebaselining mtimes: an edit that landed
+      // after the last poll (mid-rebuild, before this call) must still diff
+      // on the next tick. Only genuinely new paths get a fresh stat; entries
+      // already tracked keep their last-observed mtime.
+      const merged = new Map();
+      for (const f of next) {
+        if (fileSnap.has(f)) merged.set(f, fileSnap.get(f));
+        else merged.set(f, snapshot([f], []).get(f));
+      }
+      watchedFiles = [...next];
+      fileSnap = merged;
+    },
+    onNextChange(fn) {
+      oneShots.push(fn);
+    },
+    close() {
+      clearInterval(timer);
+    },
+  };
+}
+
+export function createRoomReloader({ build, spawnChild, killChild, log, onRebuilt = null }) {
+  let current = null; // { cwd, child }
+  let running = false;
+  let dirty = false;
+  let stopped = false;
+
+  async function onChange() {
+    if (stopped) return;
+    if (running) {
+      dirty = true;
+      return;
+    }
+    running = true;
+    try {
+      do {
+        dirty = false;
+        let built;
+        try {
+          built = await build();
+        } catch (err) {
+          log(`✗ room rebuild failed — the running room still serves your PREVIOUS code:\n${err.message}`);
+          continue;
+        }
+        // stop() may race any await in here (`looop test` tearing the stack
+        // down, SIGINT): once stopped, spawning would leak a detached room
+        // child forever. The check must repeat AFTER the kill too — killChild
+        // waits for the child's exit and can take seconds (SIGTERM, then the
+        // SIGKILL escalation), which is the widest window a stop() can land in.
+        if (stopped) return;
+        try {
+          await killChild(current.child);
+          if (stopped) return;
+          const child = spawnChild(built.cwd);
+          current = { cwd: built.cwd, child };
+        } catch (err) {
+          log(`✗ room restart failed — fix the cause, then edit any room file to retry:\n${err.message}`);
+          continue;
+        }
+        onRebuilt?.(built);
+        log('→ room server rebuilt and restarted (room state reseeds on the next join)');
+      } while (dirty && !stopped);
+    } finally {
+      running = false;
+    }
+  }
+
+  return {
+    attach(cwd, child) {
+      current = { cwd, child };
+    },
+    onChange,
+    stop() {
+      stopped = true;
+    },
+    get current() {
+      return current;
+    },
+  };
+}

package/lib/room-server.mjs

@@ -24,7 +24,7 @@
 // `rooms-runtime.js`, because the publish endpoint is a Worker with no bundler.
 // Same seam, two deliveries.)
 import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join, relative } from 'node:path';
+import { dirname, isAbsolute, join, relative } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import {
   assertNoOverrideCycle,
@@ -141,8 +141,11 @@ function renderEntry(primitives, entityComponents) {
   ].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.
+// → `{ cwd, inputs }`: 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 — plus the absolute paths of every file bundled into it. The room
+// bundle is frozen at build time, so `inputs` is what dev watches to know the
+// running room no longer matches the files on disk.
 //
 // 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.
@@ -157,7 +160,7 @@ export async function buildDevRoomServer({ projectDir, engine, esbuildImpl }) {
     // 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;
+    return { cwd: engine.roomServerDir, inputs: [] };
   }
   assertNoOverrideCycle(primitives, projectDir, engine.sharedDir);
 
@@ -165,7 +168,7 @@ export async function buildDevRoomServer({ projectDir, engine, esbuildImpl }) {
   const outDir = join(projectDir, DEV_ROOM_SERVER_DIR);
   mkdirSync(outDir, { recursive: true });
 
-  await esbuild.build({
+  const result = 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.
@@ -184,6 +187,7 @@ export async function buildDevRoomServer({ projectDir, engine, esbuildImpl }) {
     legalComments: 'none',
     conditions: ['workerd', 'worker'],
     loader: { '.wasm': 'binary' },
+    metafile: true,
     absWorkingDir: projectDir,
     plugins: [
       // Shadowing, for the bundler: an override's relative imports fall through
@@ -227,7 +231,13 @@ export async function buildDevRoomServer({ projectDir, engine, esbuildImpl }) {
     rmSync(join(projectDir, DEV_OVERRIDES_DIR), { recursive: true, force: true });
   }
 
-  return outDir;
+  // Metafile inputs are relative to absWorkingDir (the game root); the stdin
+  // entry (keyed by its `sourcefile` name, no file on disk) is excluded.
+  const inputs = Object.keys(result.metafile?.inputs ?? {})
+    .filter((p) => p !== 'looop-room-server.js' && !p.startsWith('<'))
+    .map((p) => (isAbsolute(p) ? p : join(projectDir, p)));
+
+  return { cwd: outDir, inputs };
 }
 
 export { isServerBacked };

package/lib/static-server.mjs

@@ -149,8 +149,7 @@ export function createStaticServer({
 
   function serveHtml(res, fsPath, urlPath, query) {
     let html = readFileSync(fsPath, 'utf8');
-    const baseDir = join(fsPath, '..');
-    html = rewriteHtmlScripts(html, { baseDir, resolveUrl });
+    html = rewriteHtmlScripts(html, { baseUrl: urlPath, resolveUrl });
     // Mirror the production /g/<slug> entry injection — only when the resolved
     // engine actually ships the platform layer (transition shim, same as
     // dev_server.py _engine_has_platform).
@@ -173,11 +172,11 @@ export function createStaticServer({
     sendBody(res, 200, html, MIME['.html']);
   }
 
-  function serveJs(res, fsPath) {
+  function serveJs(res, fsPath, urlPath) {
     const raw = readFileSync(fsPath);
     let body;
     try {
-      body = rewriteJsImports(raw.toString('utf8'), { baseDir: join(fsPath, '..'), resolveUrl });
+      body = rewriteJsImports(raw.toString('utf8'), { baseUrl: urlPath, resolveUrl });
     } catch {
       body = raw;
     }
@@ -244,7 +243,7 @@ export function createStaticServer({
     const ext = extname(fsPath).toLowerCase();
     try {
       if (ext === '.html') return serveHtml(res, fsPath, urlPath, reqUrl.searchParams);
-      if (ext === '.js' || ext === '.mjs') return serveJs(res, fsPath);
+      if (ext === '.js' || ext === '.mjs') return serveJs(res, fsPath, urlPath);
       sendBody(res, 200, readFileSync(fsPath), MIME[ext] ?? 'application/octet-stream');
     } catch {
       res.writeHead(500, { 'Content-Type': 'text/plain' });

package/lib/update.mjs

@@ -22,19 +22,39 @@ import { fetchStatus, landedIn } from './feedback-sync.mjs';
 // The report is the point. A creator reading this must be able to answer, with
 // no further digging: what changed, was any of it mine, and what do I do now.
 function report(log, engineVersion, surface) {
-  const { placed = [], removed = [], shadowed = [], backups = [], backupDir } = surface;
-  if (!placed.length && !removed.length && !shadowed.length) {
+  const { placed = [], removed = [], lossy = [], backups = [], backupDir, adopted } = surface;
+  if (!placed.length && !removed.length && !lossy.length) {
     log('   Your skills and instructions were already current.');
     return;
   }
 
   log('');
   log(`Looop also updated this game's skills and instructions to match engine ${engineVersion}:`);
-  for (const f of placed) log(`   updated     ${f}`);
-  for (const f of removed) log(`   removed     ${f}   (retired by Looop)`);
-  for (const f of shadowed) log(`   KEPT YOURS  ${f}   (you changed it — we left it alone)`);
+  for (const f of placed) {
+    if (lossy.includes(f)) log(`   OVERWROTE   ${f}   (it had local changes — see below)`);
+    else log(`   updated     ${f}`);
+  }
+  for (const f of removed) {
+    if (lossy.includes(f)) log(`   removed     ${f}   (retired by Looop — it had local changes, see below)`);
+    else log(`   removed     ${f}   (retired by Looop)`);
+  }
+  for (const f of lossy) {
+    if (!placed.includes(f) && !removed.includes(f)) log(`   OVERWROTE   ${f}   (it had local changes — see below)`);
+  }
+
+  if (lossy.length) {
+    // The overwrite is the contract (Looop's files always land — a kept edit
+    // used to freeze the file out of every future update), but the content is
+    // never gone: name both recovery routes and the one place local guidance
+    // is safe from updates.
+    log('');
+    log('   Files marked OVERWROTE had local changes that Looop replaced. Nothing is');
+    log(`   lost: recover them with \`git diff\`${backupDir ? `, or from ${backupDir}` : ''}.`);
+    log('   Guidance you want to keep belongs in AGENTS.md, below the managed block —');
+    log('   updates never touch anything there.');
+  }
 
-  if (backups.length) {
+  if (adopted && backups.length) {
     // On adoption we cannot tell an untouched old platform file from one the
     // creator edited — there is no ownership record to compare against, which
     // is precisely why we're adopting. Most of these are just the previous

package/package.json

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