@joystack/cli 0.1.54 → 0.1.56

package/CHANGELOG.md

@@ -14,6 +14,85 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.56] - 2026-10-22
+
+### Added
+
+- `joystack relay reply <note id> <text>` answers a note the creator sent
+  you from the running game; the wake message prints the exact command. The
+  answer shows under their note even when your edit reloaded the page
+  before you replied, or the dev server restarted.
+- `joystack dev` writes a start that failed in any browser playing your game, a phone on your wifi included, to `.joystack/dev/last.log` as one block naming the file and line.
+- `joystack dev` serves a page opened with `?fresh=<token>` with every file under a new address, so nothing of it comes from the browser's cache; the failed-start card's Reload opens the game so.
+
+### Changed
+
+- `joystack dev` needs engine 0.2.49 or later for the note, picks and
+  replies: on an older engine they do nothing until `npx joystack update`.
+- `joystack dev` runs the engine's rebuilt relay, on one route. Each pick
+  the creator makes in the game or on the Assets page is a line in
+  `.joystack/dev/last.log` for you, and a page can ask whether this server
+  takes picks. Nothing a phone on the wifi or a `--share` tester does on
+  the game's page reaches you: the dev server refuses it.
+- A page `joystack dev` serves may be framed by the same server under its
+  other loopback name (`localhost` and `127.0.0.1`, on the same port), and
+  still by no other site.
+- `joystack assets` asks the running `joystack dev` who a note would wake
+  over the same relay as the page.
+- In the Joystack maker, the line `joystack assets <id> --export` prints for a `.glb` that left something out now carries it as a title, `![Car](….glb "simplified copy: …")`; the chat marks that model a simplified copy and says what was left out when it is tapped. Copy the line as printed.
+
+### Removed
+
+- `joystack relay publish` and `joystack relay tail`. Answer a note with
+  `joystack relay reply <note id> <text>`, the command its wake message
+  prints, and read what the creator picked in `.joystack/dev/last.log`.
+
+### Fixed
+
+- A trait file that imports `three` (for its `view()`) now builds: `joystack dev` and `joystack publish` used to fail with `Could not resolve "three"`, and the page showed "The game has an error". The room now gets the same copy of three as the page.
+- `joystack lint` and `joystack test` check your game on the engine its `package.json` names, installing it first as `joystack dev` does. After a merge that changed the engine, they used to check it on the engine still installed and could pass it on code it no longer runs. If that engine cannot be installed (no network, and never downloaded on this machine), they fail and say so rather than checking on another engine.
+
+## [0.1.55] - 2026-10-22
+
+### Added
+
+- `joystack assets <id> --export` and `joystack assets --export <file.js>`
+  write an asset as files to `.joystack/exports/`: a model as `.glb` and a
+  picture, a sound as `.wav`, a 2D asset as `.png` (`--set`, `--tag`,
+  `--out`, `--stage`). Needs engine 0.2.48 or later.
+- `joystack shot <script.mjs>` runs a short Playwright script of your
+  agent's against the running game and writes the pictures it takes with
+  `shot(name)` to `.joystack/shots/`. The script is handed a page already
+  open on the game at a phone's size, under a player name of its own, and the
+  world handle `openPage` gives a smoke; it is checked before anything starts,
+  the page opens only once the dev server has finished updating after an edit,
+  each step (a click, a `game.waitFor`) waits at most 5 seconds, the run stops,
+  saying so, if the game updates under it, and it fails if the game throws
+  while it runs. In a multiplayer game the page joins the game's one room,
+  beside anyone playing it.
+
+### Changed
+
+- In the Joystack maker, `joystack dev` says the game is ready to play on
+  your page and that there is no link to give, and the dev server's log
+  lists no addresses, so the agent no longer hands you one you cannot open.
+- `joystack dev` names every file of your game and the engine by its
+  content, so a browser keeps what has not changed between loads: opening
+  the game again after an edit downloads only the files the edit touched.
+
+### Fixed
+
+- Under `joystack dev`, each of your entity files runs once: it used to run
+  twice, once for your game's imports and once for the engine's.
+- In Safari, a game page `joystack dev` reloads after an edit downloads only
+  the files the edit touched: it used to download every file again.
+- When your game does not build, the page `joystack dev` serves in its place
+  now shows the error's own message, not the line of code that threw it, and
+  answers with status 500, so a check that fetches the game sees it failed.
+- `joystack test` no longer fails with `ENOENT` in `.joystack/frozen/` when
+  `joystack dev` is running: looking for your tests, it never opens
+  `.joystack/`, `node_modules/` or `overrides/`.
+
 ## [0.1.54] - 2026-10-21
 
 ### Changed

package/bin/joystack.mjs

@@ -38,7 +38,9 @@ Usage:
   joystack dev --no-reload      ...frozen as it is now: saves reach nobody until you restart it
   joystack assets [<id>]       Browse and drive your models, sounds and assets on their own
   joystack assets <id> --sheet  Draw a view sheet of a 3D asset to .joystack/sheets/ (--help: options)
+  joystack assets <id> --export  Export an asset as files: a model as .glb and a picture, a sound as .wav (--help: options)
   joystack assets --json [<id>…]  Print each asset's parameters, measured stats and flags as JSON
+  joystack shot <script.mjs>    Run a short Playwright script on the running game; its shot(name) calls write pictures to .joystack/shots/ (--help)
   joystack lane <name>          Open an isolated copy of the game to experiment in, safely
   joystack land <name>          Put a lane's work into the game, then remove the lane
   joystack test [aspect]        Run targeted checks (no aspect: conservative full run)
@@ -60,8 +62,7 @@ Usage:
   joystack replay profile [<id>] --ticks <a-b>
                               Which functions ran in those ticks, as a table
   joystack feedback             Send reports + replies under notes/feedback/; pull outcomes back in
-  joystack relay publish <name> [<json>]  Put an event on the running game's relay, as the agent (agent.replied …)
-  joystack relay tail [<pattern>…]  Print the running game's relay events as they happen, one JSON line each
+  joystack relay reply <note id> <text>  Answer a note the creator sent you from the running game
   joystack login                Authenticate this machine as your Joystack player account
   joystack logout [--all]       Sign out: revoke the token (--all: on every machine)
   joystack whoami               Show who this machine publishes as
@@ -134,6 +135,23 @@ try {
         process.stdout.write(`${safeJson(out)}\n`);
         break;
       }
+      // `--export`: the asset as files, made headless (assets-export.mjs).
+      if (rest.includes('--export')) {
+        const { assetsExport, parseExportArgs, EXPORT_HELP } = await import('../lib/assets-export.mjs');
+        if (rest.includes('--help')) {
+          console.log(EXPORT_HELP);
+          break;
+        }
+        try {
+          await assetsExport({ ...parseExportArgs(rest), startDev: dev });
+        } catch (err) {
+          // An error here may quote the game's own text, so every line of it
+          // is made printable before it reaches the terminal.
+          console.error(`joystack assets: ${printableLines(err?.message ?? err)}`);
+          process.exit(1);
+        }
+        process.exit(0);
+      }
       // `--sheet`: draw a view sheet headless and write it to disk, instead
       // of opening the page (assets-sheet.mjs).
       if (rest.includes('--sheet')) {
@@ -186,6 +204,25 @@ try {
       process.on('SIGTERM', shutdown);
       break;
     }
+    case 'shot': {
+      // A Playwright script of the agent's own, run on the running game
+      // (lib/shot/).
+      const { shot: runShot, parseShotArgs, SHOT_HELP } = await import('../lib/shot/shot.mjs');
+      if (rest.includes('--help') || !rest.length) {
+        console.log(SHOT_HELP);
+        break;
+      }
+      try {
+        await runShot({ ...parseShotArgs(rest), startDev: dev });
+      } catch (err) {
+        // The runner has already said what went wrong; anything else here may
+        // quote the game's own text (its build error), so every line of it is
+        // made printable before it reaches the terminal.
+        if (!err?.reported) console.error(`joystack shot: ${printableLines(err?.message ?? err)}`);
+        process.exit(err?.exitCode ?? 1);
+      }
+      process.exit(0);
+    }
     case 'relay': {
       const { relayCommand, RELAY_HELP } = await import('../lib/relay/cli.mjs');
       const dirAt = rest.indexOf('--dir');

package/lib/assets-export.mjs

@@ -0,0 +1,210 @@
+// `joystack assets <id> --export` and `joystack assets --export <file.js>`:
+// one asset as files someone else can open, made by the Assets page headless
+// from the asset as the game builds it (shared/ui/assets/export/).
+//
+//   joystack assets car --export                 .joystack/exports/car.glb + car.png
+//   joystack assets car --export --set armor=2 --tag heavy
+//                                                .joystack/exports/car-heavy.glb + .png
+//   joystack assets engine-hum --export          .joystack/exports/engine-hum.wav
+//   joystack assets --export art/car-v2.js       .joystack/exports/car-v2.glb + .png
+//
+// The last form is a scratch module: a file in the asset format (the mount
+// and apply a declared asset's module has) that is not declared in assets.js,
+// so a version of a model can be made, exported and thrown away, leaving
+// nothing in the game.
+//
+// In the maker (JOYSTACK_MAKER set), it also prints the line that shows the
+// result in the agent's reply, which is how the person sees it there.
+
+import { mkdirSync } from 'node:fs';
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { findProject } from './project.mjs';
+import { ASSETS_PAGE_PATH } from './assets-page.mjs';
+import { gpuArgs } from './smoke-gpu-preload.mjs';
+import { engineTooOld, loadDriver, loadPlaywright, parseSet, printable, safeName, stackOrigin, stateFolderIn, writeReplacing } from './assets-sheet.mjs';
+import { makerDraft } from './maker.mjs';
+
+export const EXPORT_HELP = `joystack assets <id> --export [--set <k=v,…>] [--tag <name>] [--out <dir>] [--port <n>]
+joystack assets --export <file.js> [--stage <stage>] [--set <k=v,…>] [--tag <name>] [--out <dir>] [--port <n>]
+
+  Exports one asset as files: a 3D model as <name>.glb and a picture of it
+  <name>.png, a sound as <name>.wav, any other asset as <name>.png. Written to
+  .joystack/exports/ unless --out names a folder. An outline drawn as a
+  back-face hull and toon paint are converted so the .glb looks the same in
+  any glTF viewer; what it still cannot carry (a shader of the asset's own,
+  particles, reflections, glows, motion made in code, …) is named on a
+  "left out:" line, and in the maker the reply line marks the model a
+  simplified copy.
+
+  <file.js>        a scratch module: a file in the asset format that is not
+                   declared in assets.js, exported as it is (its stage is
+                   three unless --stage names another). For trying versions
+                   of an asset without adding them to the game.
+  --set k=v,…      export it at these parameter values. A value outside what
+                   the asset declares is an error that names the range.
+  --tag <name>     added to the file names, e.g. --tag v2
+  --out <dir>      where to write
+
+  Uses the dev stack already running for this game, or starts one for the
+  length of the command. Needs playwright in the game (npm i -D playwright).`;
+
+const SWITCHES = new Set(['--export', '--help']);
+const SCRATCH = /\.(m?js)$/i;
+// The id a scratch module has on the Assets page (shared/ui/assets/index.html).
+const SCRATCH_ID = '_scratch';
+
+// The arguments after `joystack assets`, read for the export mode.
+export function parseExportArgs(rest = []) {
+  const opts = { id: undefined, module: null, stage: null, sets: [], tag: null, out: null, port: null };
+  let named;
+  for (let i = 0; i < rest.length; i += 1) {
+    const a = rest[i];
+    const value = () => {
+      const v = rest[i + 1];
+      if (v == null || v.startsWith('--')) throw new Error(`${a} needs a value.\n\n${EXPORT_HELP}`);
+      i += 1;
+      return v;
+    };
+    if (a === '--sheet' || a === '--json') throw new Error(`--export and ${a} are two different outputs; ask for one.\n\n${EXPORT_HELP}`);
+    if (a === '--set') opts.sets.push(value());
+    else if (a === '--tag') opts.tag = value();
+    else if (a === '--out') opts.out = value();
+    else if (a === '--stage') opts.stage = value();
+    else if (a === '--port') {
+      const p = Number(value());
+      if (!Number.isInteger(p) || p <= 0 || p > 65535) throw new Error('--port needs a port number');
+      opts.port = p;
+    } else if (a.startsWith('--')) {
+      if (!SWITCHES.has(a)) throw new Error(`joystack assets --export has no option ${a}.\n\n${EXPORT_HELP}`);
+    } else if (named === undefined) named = a;
+    else throw new Error(`joystack assets --export exports one asset; got "${named}" and "${a}".\n\n${EXPORT_HELP}`);
+  }
+  if (!named) throw new Error(`Name the asset or the file: joystack assets <id> --export, or joystack assets --export <file.js>\n\n${EXPORT_HELP}`);
+  if (SCRATCH.test(named)) opts.module = named;
+  else opts.id = named;
+  if (opts.stage && !opts.module) throw new Error('--stage is for a scratch module; a declared asset names its own stage in assets.js');
+  return { ...opts, values: parseSet(opts.sets) };
+}
+
+// A scratch module's path inside the game, with forward slashes, or an error.
+export function scratchPath(projectDir, file, cwd) {
+  const full = resolve(cwd, file);
+  const rel = relative(projectDir, full);
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`${file} is not inside this game; a scratch module has to be, so the dev server can serve it`);
+  }
+  return rel.split(sep).join('/');
+}
+
+// The line that shows an exported file in the agent's reply in the maker: a
+// markdown image of the model's .glb (its picture is found beside it), the
+// sound or the picture. The path is written with forward slashes, since a
+// backslash in markdown escapes the character after it.
+//
+// A .glb that leaves something out (`left`, the export's sentences) carries
+// them as the image's title, `"simplified copy: …"`, and the maker's chat
+// marks the model so, with what was left out on a tap, one item per
+// sentence: the chat splits the title on ";", so a sentence's own becomes a
+// comma. A model with nothing left out has no title.
+export function replyLine(label, path, left = []) {
+  const alt = String(label).replace(/[[\]\n]/g, ' ').trim() || 'Asset';
+  path = path.split(sep).join('/');
+  const where = /[\s()<>]/.test(path) ? `<${path}>` : path;
+  const said = /\.glb$/i.test(path) ? left.map((l) => String(l).replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/"/g, "'").replace(/;/g, ',').replace(/\s+/g, ' ').trim()).filter(Boolean) : [];
+  return `![${alt}](${where}${said.length ? ` "simplified copy: ${said.join('; ')}"` : ''})`;
+}
+
+const lines = (problems) => problems.map((p) => printable(`  ✗ ${p.key}=${p.requested}: ${p.key} ${p.reason}`)).join('\n');
+
+// Where the Assets page is opened for the export, and the name its files take.
+function pageFor({ projectDir, id, module, stage, cwd }) {
+  const query = new URLSearchParams({ _thumbs: '0' });
+  if (!module) {
+    query.set('_item', id);
+    return { query, name: id };
+  }
+  const path = scratchPath(projectDir, module, cwd);
+  query.set('_item', SCRATCH_ID);
+  query.set('_module', path);
+  if (stage) query.set('_stage', stage);
+  return { query, name: basename(path, extname(path)) };
+}
+
+// The page's ids hold the asset asked for, or the error that says why not.
+function mustHold(ids, { id, module, errors }) {
+  const want = module ? SCRATCH_ID : id;
+  if (Array.isArray(ids) && ids.includes(want)) return;
+  if (module) throw new Error(`${printable(module)} did not load as an asset${errors.length ? `: ${printable(errors.join('; '))}` : ''}`);
+  const declared = Array.isArray(ids) ? ids.filter((x) => x !== SCRATCH_ID).map(printable).join(', ') : '';
+  throw new Error(`there is no asset "${printable(id)}" in this game's assets.js. Declared: ${declared || '(none)'}`);
+}
+
+// Each exported file written under `base` in `outDir`: { glb?, png?, wav? }.
+function writeFiles(made, outDir, base) {
+  const files = {};
+  for (const [key, file] of Object.entries(made.files)) {
+    files[key] = join(outDir, `${base}.${key}`);
+    writeReplacing(files[key], file.bytes);
+  }
+  return files;
+}
+
+// What was written, what a file left out, and in the maker the reply line.
+function report({ files, made, label, projectDir, errors, env, log }) {
+  const shown = (p) => (p.startsWith(`${projectDir}${sep}`) ? p.slice(projectDir.length + 1) : p);
+  const main = files.glb ?? files.wav ?? files.png;
+  log(`\n  📦 ${printable(label)} → ${shown(main)}`);
+  if (files.glb && files.png) log(`     its picture → ${shown(files.png)}`);
+  for (const l of made.left ?? []) log(`     left out: ${printable(l)}`);
+  if (made.clips?.length) log(`     clips: ${made.clips.map(printable).join(', ')}`);
+  if (errors.length) log(`  ⚠ the page reported: ${printable(errors.join('; '))}`);
+  if (makerDraft(env)) log(`     To show it in your reply, write: ${replyLine(label, shown(main), main === files.glb ? made.left ?? [] : [])}`);
+}
+
+// The game's Assets page driver, or the one a test gives, refused when the
+// game's engine is too old to export.
+async function driverFor(projectDir, given) {
+  const driver = given ?? await loadDriver(projectDir, 'joystack assets --export');
+  if (typeof driver.exportAsset !== 'function') throw engineTooOld('joystack assets --export', projectDir);
+  return driver;
+}
+
+// A headless browser from the game's own Playwright.
+async function launch(projectDir) {
+  const { chromium } = await loadPlaywright(projectDir, 'an asset is exported');
+  return chromium.launch({ args: gpuArgs() });
+}
+
+// Export one asset. `startDev` starts a dev stack when none is running for
+// the game. `origin`, `browser` and `headless` are for a caller that already
+// has them (a test), as in assetsSheet. `env` decides whether the maker's
+// line is printed.
+export async function assetsExport({
+  cwd = process.cwd(), id, module, stage, values = {}, tag, out, port, startDev, log = console.log, origin, browser, headless, env = process.env,
+} = {}) {
+  const project = findProject(cwd);
+  const { query, name } = pageFor({ projectDir: project.dir, id, module, stage, cwd });
+  let started = null;
+  if (!origin) ({ origin, started } = await stackOrigin({ cwd, projectDir: project.dir, port, startDev }));
+  let ownBrowser = null;
+  try {
+    const driver = await driverFor(project.dir, headless);
+    if (!browser) browser = ownBrowser = await launch(project.dir);
+    const insp = await driver.openAssetsPage({ browser, url: `${origin}${ASSETS_PAGE_PATH}?${query}`, viewport: { width: 1280, height: 800 } });
+    try {
+      mustHold(await insp.ids(), { id, module, errors: insp.errors });
+      const made = await driver.exportAsset(insp, { values });
+      if (made.problems) throw new Error(`these values would not apply as given, so nothing was exported:\n${lines(made.problems)}`);
+      const outDir = out ? resolve(cwd, out) : stateFolderIn(project.dir, 'exports');
+      mkdirSync(outDir, { recursive: true });
+      const files = writeFiles(made, outDir, `${safeName(name)}${tag ? `-${safeName(tag)}` : ''}`);
+      report({ files, made, label: module ? name : made.label, projectDir: project.dir, errors: insp.errors, env, log });
+      return { files, kind: made.kind, left: made.left ?? [] };
+    } finally {
+      await insp.close();
+    }
+  } finally {
+    if (ownBrowser) await ownBrowser.close();
+    await started?.stop();
+  }
+}

package/lib/assets-json.mjs

@@ -62,7 +62,7 @@ export function parseJsonArgs(rest = []) {
   let port = null;
   for (let i = 0; i < rest.length; i += 1) {
     const a = rest[i];
-    if (a === '--sheet') throw new Error(`--json and --sheet are two different outputs; ask for one.\n\n${JSON_HELP}`);
+    if (a === '--sheet' || a === '--export') throw new Error(`--json and ${a} are two different outputs; ask for one.\n\n${JSON_HELP}`);
     if (a === '--port') {
       const v = rest[i + 1];
       if (v == null || v.startsWith('--')) throw new Error(`--port needs a value.\n\n${JSON_HELP}`);

package/lib/assets-page.mjs

@@ -51,8 +51,9 @@ export function hasDeclaredAssets(projectDir) {
 // argument that is not a flag" turns 8210 into the thing to open — on the one
 // command whose entire job is opening the right asset.
 // The `--set`, `--tag`, `--out` and `--against` of `joystack assets <id> --sheet`
-// are among them (assets-sheet.mjs).
-export const VALUED_FLAGS = new Set(['--port', '--set', '--tag', '--out', '--against']);
+// are among them (assets-sheet.mjs), and the `--stage` of `--export`
+// (assets-export.mjs).
+export const VALUED_FLAGS = new Set(['--port', '--set', '--tag', '--out', '--against', '--stage']);
 
 export function itemArg(rest = []) {
   for (let i = 0; i < rest.length; i += 1) {
@@ -164,22 +165,36 @@ export async function openAssets({
 }
 
 // The agent a running stack would wake (`'Claude Code'`), or null when none
-// is listening or the stack cannot say. Loopback only, with the header the
-// status route requires.
-function stackAgent(port, timeoutMs = HEALTH_TIMEOUT_MS) {
+// is listening or the stack cannot say: the relay's `server.agent`
+// (relay/relay.mjs), asked on loopback with the origin of a page the stack
+// served, which is what it takes from a program on this machine.
+export function stackAgent(port, timeoutMs = HEALTH_TIMEOUT_MS) {
+  return loopbackJson({
+    port, path: '/__joystack/relay', timeoutMs,
+    headers: { Origin: `http://127.0.0.1:${port}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name: 'server.agent' }),
+  }).then((out) => (out?.ok ? out.value ?? null : null));
+}
+
+// What a route of a dev stack on this machine answers, as JSON, or null when
+// it answers anything but a 200 with JSON, or nothing in `timeoutMs`. Asked of
+// 127.0.0.1 under its own Host, which is what the stack's same-origin checks
+// accept: a GET, or a POST of `body`.
+export function loopbackJson({ port, path, headers = {}, body = null, timeoutMs = HEALTH_TIMEOUT_MS }) {
   return new Promise((resolve) => {
-    const req = http.get({
-      host: '127.0.0.1', port, path: '/__joystack/relay/status', timeout: timeoutMs,
-      headers: { Host: `127.0.0.1:${port}`, 'X-Joystack-Agent-UI': '1' },
+    const req = http.request({
+      host: '127.0.0.1', port, path, method: body === null ? 'GET' : 'POST', timeout: timeoutMs,
+      headers: { Host: `127.0.0.1:${port}`, ...headers },
     }, (res) => {
-      let body = '';
+      let text = '';
       res.setEncoding('utf8');
-      res.on('data', (d) => { if (body.length < 65536) body += d; });
+      res.on('data', (d) => { if (text.length < 65536) text += d; });
       res.on('end', () => {
-        try { resolve(res.statusCode === 200 ? JSON.parse(body).agent ?? null : null); } catch { resolve(null); }
+        try { resolve(res.statusCode === 200 ? JSON.parse(text) : null); } catch { resolve(null); }
       });
     });
     req.on('timeout', () => { req.destroy(); resolve(null); });
     req.on('error', () => resolve(null));
+    req.end(body ?? undefined);
   });
 }

package/lib/assets-sheet.mjs

@@ -41,7 +41,7 @@ import { gpuArgs } from './smoke-gpu-preload.mjs';
 import { printable } from './printable.mjs';
 import { stateDirName } from './legacy-names.mjs';
 
-export const SHEET_HELP = `joystack assets <id> --sheet [--set <k=v,…>] [--tag <name>] [--out <dir>] [--against <sheet.json>]
+export const SHEET_HELP = `joystack assets <id> --sheet [--set <k=v,…>] [--tag <name>] [--out <dir>] [--against <sheet.json>] [--port <n>]
 
   Draws a view sheet of one 3D asset: front, side, back and top at one scale
   with a ruler, a three-quarter view, the in-game view when assets.js declares
@@ -185,13 +185,16 @@ export function writeReplacing(path, data, { suffix = () => randomBytes(8).toStr
   }
 }
 
-// The default sheets folder, created inside the game. `.joystack` and
-// `.joystack/sheets` must each be a real folder, never a link (even one that
-// points inside the game today), and the folder must resolve inside the game
-// once it exists.
-export function sheetsDirIn(projectDir) {
+// The default sheets folder, created inside the game.
+export const sheetsDirIn = (projectDir) => stateFolderIn(projectDir, 'sheets');
+
+// A folder in the game's state folder (`.joystack/<name>`), created when it
+// is missing. `.joystack` and the folder must each be a real folder, never a
+// link (even one that points inside the game today), and the folder must
+// resolve inside the game once it exists.
+export function stateFolderIn(projectDir, name) {
   let dir = projectDir;
-  for (const part of [stateDirName(projectDir), 'sheets']) {
+  for (const part of [stateDirName(projectDir), name]) {
     dir = join(dir, part);
     const shown = relative(projectDir, dir);
     let st = null;
@@ -207,7 +210,7 @@ export function sheetsDirIn(projectDir) {
   const real = realpathSync(dir);
   const rel = relative(realpathSync(projectDir), real);
   if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
-    throw new Error(`${stateDirName(projectDir)}/sheets in this game leads outside it (to ${printable(real)}); remove the link, or choose a folder with --out`);
+    throw new Error(`${stateDirName(projectDir)}/${name} in this game leads outside it (to ${printable(real)}); remove the link, or choose a folder with --out`);
   }
   return dir;
 }
@@ -264,6 +267,19 @@ export async function loadPlaywright(projectDir, why = 'a view sheet is drawn')
 
 const lines = (problems) => problems.map((p) => printable(`  ✗ ${p.key}=${p.requested}: ${p.key} ${p.reason}`)).join('\n');
 
+// The origin of the dev stack running for the game, or of one started for the
+// length of a command when none is (`started`, to stop afterwards; null when
+// one was already running). The one started has no room server unless `mp`:
+// a sheet needs none, a picture of a multiplayer game does.
+export async function stackOrigin({ cwd, projectDir, port = null, startDev = null, mp = false }) {
+  const stack = await findRunningStack({ projectDir, port });
+  if (stack) return { origin: stack.origin, started: null };
+  if (!startDev) throw new Error('no dev stack is running for this game');
+  const quiet = [];
+  const started = await startDev({ cwd, port: port ?? undefined, watch: false, reload: false, noMp: !mp, log: (l) => quiet.push(l) });
+  return { origin: new URL(started.url).origin, started };
+}
+
 // Draw one sheet. `startDev` starts a dev stack (dev() in the CLI) when none
 // is running for the game. `origin`, `browser` and `headless` are for a caller
 // that already has them (a test): an origin skips looking for a stack, a
@@ -274,18 +290,10 @@ export async function assetsSheet({
 } = {}) {
   const earlier = against ? readEarlierSheet(resolve(cwd, against)) : null;
   let project = null;
-  let stack = null;
   let started = null;
   if (!origin) {
     project = findProject(cwd);
-    stack = await findRunningStack({ projectDir: project.dir, port });
-    if (!stack) {
-      if (!startDev) throw new Error('no dev stack is running for this game');
-      const quiet = [];
-      started = await startDev({ cwd, port: port ?? undefined, watch: false, reload: false, noMp: true, log: (l) => quiet.push(l) });
-      stack = { origin: new URL(started.url).origin };
-    }
-    origin = stack.origin;
+    ({ origin, started } = await stackOrigin({ cwd, projectDir: project.dir, port, startDev }));
   }
   if (!project && !(headless && browser)) project = findProject(cwd);
   const base = `${safeName(id)}${tag ? `-${safeName(tag)}` : ''}-sheet`;

package/lib/dev.mjs

@@ -83,7 +83,8 @@ export async function waitForRoomServer(port, { timeoutMs = 30_000, intervalMs =
 // answer, both commands.
 
 // `share` opens a public link to the stack for testers (share.mjs); `openShare`
-// replaces the tunnel for tests.
+// replaces the tunnel for tests. `announce: false` prints no address: the
+// Joystack maker, which serves the game on the person's own page.
 export async function dev(opts = {}) {
   // An interactive `joystack dev` (watch on, the default) also writes
   // everything it prints to .joystack/dev/last.log, so an agent that started
@@ -114,14 +115,18 @@ export async function dev(opts = {}) {
 //
 // `shareIsOwner` is for a host that serves the share link to the creator
 // alone and keeps everyone else off the dev tools' routes (the Joystack
-// maker): a relay event sent through the link then counts as one from this
+// maker): a relay request sent through the link then counts as one from this
 // machine, so it can wake the agent and read its reply.
 //
+// `agentFeed: false` turns off the relay's feed for Claude Code (the lines
+// relay/relay.mjs writes to the log, and `server.picks`), for a host whose
+// page takes the picks itself (the Joystack maker).
+//
 // `pollMs` is how often, in milliseconds, the game's files are compared for
 // changes the operating system's events miss (live-versions.mjs); left unset
 // it is that module's default of one second. Tests pass a shorter one so a
 // save is acted on sooner.
-async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP === '1', watch = true, reload = true, share = false, openShare = openTunnel, log = console.log, agentSession = null, shareIsOwner = false, devLogPath = null, pollMs } = {}, onFailure) {
+async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP === '1', watch = true, reload = true, share = false, openShare = openTunnel, log = console.log, agentSession = null, shareIsOwner = false, agentFeed = true, devLogPath = null, pollMs, announce = true } = {}, onFailure) {
   const project = findProject(cwd);
   // Q4 revision: the engine is not an npm dependency — install/refresh it from
   // the platform's login-gated registry (no-op when the pinned version is in).
@@ -334,6 +339,7 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
     engineVersion: engine.version ?? null, // stamped on recorded sessions
     agentSession, // woken by a note sent on the relay from this machine
     shareIsOwner, // and by one sent through the share link, when it is the creator's alone
+    agentFeed, // the relay's feed for Claude Code, off where the page's host takes the picks itself (the maker)
     mounts: mountsFor(codeDir),
     ...(first ? { fixedBuild: first.build } : {}),
     versions: live ? {
@@ -575,24 +581,28 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
   const ip = lanIp();
   log('');
   log('────────────────────────────────────────────────────────────');
-  log(`✅ ${project.slug} ready. Open:`);
-  log(`   ${url}`);
-  if (ip) log(`   📱  http://${ip}:${ports.static}/games/${project.slug}/index.html   (phone / LAN)`);
+  // `announce: false`: the Joystack maker shows the game on the person's own
+  // page, so nothing here is an address anyone could open, and an address in
+  // this output (which an agent reads in .joystack/dev/last.log) is one it
+  // would hand over.
+  log(announce ? `✅ ${project.slug} ready. Open:` : `✅ ${project.slug} ready.`);
+  if (announce) log(`   ${url}`);
+  if (announce && ip) log(`   📱  http://${ip}:${ports.static}/games/${project.slug}/index.html   (phone / LAN)`);
   // Only when this game declares assets (inspect.mjs). A line printed on every
   // single boot is a line nobody reads by the third one, and the tool it points
   // at is then invisible exactly when it would have helped.
-  if (hasDeclaredAssets(project.dir)) {
+  if (announce && hasDeclaredAssets(project.dir)) {
     log(`   🔍  ${assetsPageUrl(url)}   (your models, sounds and assets, one at a time)`);
   }
   if (devLogPath) log(`   📄  ${relative(project.dir, devLogPath).split(sep).join('/')}   (everything this server prints, for reading later)`);
   if (share) {
-    log('');
-    log('→ share       opening a public link (cloudflared)…');
+    if (announce) log('');
+    if (announce) log('→ share       opening a public link (cloudflared)…');
     tunnel = await openShare({ port: ports.static }); // a failure stops the stack (see dev)
     staticServer.setShareHost(tunnel.hostname);
-    for (const line of shareBanner({ url: tunnel.url, gamePath: `/games/${project.slug}/index.html`, resolved: tunnel.resolved, frozen: live && !reload })) log(line);
+    if (announce) for (const line of shareBanner({ url: tunnel.url, gamePath: `/games/${project.slug}/index.html`, resolved: tunnel.resolved, frozen: live && !reload })) log(line);
     tunnel.exited.then(() => {
-      if (!stopped) log('⚠ the share link stopped working (cloudflared exited). Restart `joystack dev --share` for a new one.');
+      if (!stopped && announce) log('⚠ the share link stopped working (cloudflared exited). Restart `joystack dev --share` for a new one.');
     });
   }
   log('────────────────────────────────────────────────────────────');

package/lib/engine.mjs

@@ -76,8 +76,9 @@ function npmInstallTarball(projectDir, tgzPath) {
  *
  * The moment those doors are wanted is the moment somebody runs a test file by
  * hand, which is not a moment any CLI command is watching — so they are left
- * behind in advance, by whatever ran last. `create` and `dev` come through
- * here; `joystack test` does not, and writes them itself (test-cmd.mjs).
+ * behind in advance, by whatever ran last. `create`, `dev`, `lint` and `test`
+ * come through here (the checks by ensureNamedEngine); `joystack test` also
+ * writes them itself (test-cmd.mjs).
  */
 export async function ensureEngine(projectDir, opts = {}) {
   const engine = await installEngine(projectDir, opts);
@@ -85,6 +86,38 @@ export async function ensureEngine(projectDir, opts = {}) {
   return engine;
 }
 
+/**
+ * The engine a check runs on (`joystack lint`, `joystack test`): the one the
+ * game's package.json names, installed first when node_modules holds another.
+ * `git merge` of an engine update rewrites the `joystack.engine` pin and leaves
+ * node_modules, which git ignores, on the old engine; a check that resolved the
+ * installed copy would pass the game on code it no longer runs.
+ *
+ * It costs two small file reads when the named engine is already installed.
+ * Otherwise it is `ensureEngine`: it installs from the download cache
+ * (`~/.joystack/cache`) when this machine downloaded that release before, and
+ * needs the network and a sign-in only for a release it never had. A game with
+ * no pin is left on what is installed, and null is returned: a check never
+ * picks an engine for a game, `create` and `dev` do. Throws, with the reason,
+ * when the named engine cannot be installed.
+ */
+export async function ensureNamedEngine(projectDir, { ensure = ensureEngine, log = console.log } = {}) {
+  if (!readEnginePin(projectDir)) return null;
+  // A check runs unattended (an agent's lint or test): it never opens the
+  // sign-in flow and waits on a person, as `dev` does.
+  const loginFn = async () => { throw new Error('this machine is not signed in to Joystack: run `npx joystack login`, or `npx joystack dev`, which signs in and installs it'); };
+  return ensure(projectDir, { log, loginFn });
+}
+
+// The line a check prints when the engine its game names could not be
+// installed, so that neither lint nor test passes a game on another engine.
+export function namedEngineFailure(projectDir, error) {
+  let installed = null;
+  try { installed = resolveEngine(projectDir).version; } catch { /* none installed */ }
+  return `your game names engine ${readEnginePin(projectDir)} in package.json, and it could not be installed `
+    + `(${installed ? `this game has ${installed}` : 'no engine is installed'}): ${error?.message ?? error}`;
+}
+
 async function installEngine(
   projectDir,
   {