@homie-rocks/studio 0.55.0 → 0.56.0

package/CHANGELOG.md

@@ -17,6 +17,45 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.56.0] - 2026-10-15
+
+**Plugin 0.56.0**
+
+Studios scale with hibernating rooms, add custom routes with built-in access checks, and deploy reliably with background queue handlers.
+
+### Added
+
+- Studio Worker `useRoutes` hook for custom APIs, well-known files and callbacks, after Homie's matched routes and before Worker asset fallback, with response security headers.
+- Public `isOwner(request, env)` and `hasRole(request, env, app, role)` authorization helpers using existing live session and app access checks.
+- Secret capabilities may use `self` for the runtime studio origin, with origin and redirect restrictions retained.
+
+### Changed
+
+- Renew relay sequence epochs whenever a Gate opens a link, probe the room after a missed round start, refill quiet games across all matching pools, and coalesce peak increases without writing unchanged room reports.
+- Recover Gate relay transport failures with ordered backoff and bounded output queues; remove dead sessions so players can reconnect. Keep idle heartbeats at the edge through long breaks, exclude transport telemetry from session writes, and retain only QA markers from relay user agents. Match quiet public games in one pool, spread bursts through leased shard routing, and calculate daily peaks from concurrent shard totals.
+- Close failed room restores, detect unanswered clock pings, preserve live Gate multiplexing, bound crowd session storage, and avoid unchanged idle writes. Restore watcher rate limits without replay, shard matchmaking, and paginate aggregated room summaries.
+- Add an opt-in rules-host round-idle contract: finish both scoring-settlement ticks, persist the next-round deadline, and resume without simulating idle time.
+- Store Lobby rooms as SQLite rows and deliver room summaries through Queues. Hibernate player and watch sockets, including Gates and server-rule rooms, between settled rounds. Retain logical sessions and moderation state, detach idle relay streams, and restore complete world headers without repeating admission.
+
+### Fixed
+
+- Custom studio Workers that wrap only `fetch` now inherit missing toolkit queue and scheduled handlers in the generated entry, so background queue consumers attach during deploy. Custom handlers remain intact.
+- Deploy failures retain Wrangler's real error and context with secrets redacted, instead of showing only the last six lines.
+- Custom route role checks enforce fresh app launch gates. Custom Worker asset routes preserve generated authorization paths; same-origin mutation protection is exported and documented with reserved `/api/custom/*` paths and app cookie scope.
+- Custom `assets.run_worker_first` entries cannot exclude paths with `!`; the build refuses them so private app files always stay behind their access checks.
+- Late link subscriptions no longer trigger rules-view reconnect recovery; throwing listeners still return their unsubscribe function.
+- MCP publishing and its preflight use the connector's directory. Wrangler sign-in checks stop immediately when logged out and retry refresh collisions without blocking the event loop, including CLI status.
+- Scaffold, local database and login regression tests use OS temporary directories and work from the package test command.
+- New studios leave directory listing opt-in; existing explicit directory choices are preserved.
+- Deploy and storage sign-in checks retry shared Wrangler OAuth refresh races with bounded backoff and report the original diagnostic, distinguishing authentication from temporary check failures.
+- Room-link listeners immediately receive current state, so wall UIs mounted after welcome do not stay on “Connecting to Homie.”
+- Local dev refuses to serve until migrations and function registration succeed, preserving first-notice delivery on a fresh database.
+
+### Upgrade notes
+
+- `net.on('link', listener)` now calls the listener synchronously on subscription with `why: 'subscribe'` and `prev === state`, then reports changes as before.
+- Custom routes and authorization examples are in `packages/studio/docs/custom-routes.md` (the installed package uses `docs/custom-routes.md`).
+
 ## [0.55.0] - 2026-10-15
 
 **Plugin 0.55.0**

package/README.md

@@ -8,6 +8,8 @@ to its own Cloudflare account with Wrangler. The homie.rocks directory lists the
 
 Apps are one morphing screen, its roles and its parts: a customer phone, a staff tablet and a wall can share a 3D scene without rounds or scores. `homie-studio app new welcome` creates a working welcome queue in `apps/welcome/`; install its declared dependencies, build, then use `dev --lan` and the printed Wi-Fi address. `check welcome --url <origin>` proves a shared action and reconnect across three screens. Staff permissions, lasting D1 records, public QR/link helpers and customer standalone builds use the existing studio machinery. See [the app guide](apps/APPS.md).
 
+For studio-specific JSON APIs, well-known files and OAuth callbacks, see [custom Worker routes and authorization](docs/custom-routes.md).
+
 Most people never run this by hand: the Homie plugin for Claude Code, Codex and Grok does,
 and the person approves Cloudflare once in their browser.
 

package/bin/homie-studio.mjs

@@ -973,7 +973,7 @@ async function main() {
   }
   if (cmd === 'status') {
     const studio = readStudio(root);
-    return { ok: true, command: 'status', root, studio, site: siteUrl(root, studio), games: listGames(root).map((g) => g.id), cloudflareSignedIn: Boolean(wranglerBin(root) && whoami(root)) };
+    return { ok: true, command: 'status', root, studio, site: siteUrl(root, studio), games: listGames(root).map((g) => g.id), cloudflareSignedIn: Boolean(wranglerBin(root) && await whoami(root)) };
   }
   if (cmd === 'upgrade') {
     const plan = upgradePlan(root);

package/docs/custom-routes.md

@@ -0,0 +1,72 @@
+# Studio Worker routes
+
+In `site/src/worker.mjs`, register one handler at module evaluation. Keep the
+existing exports and registrations. Do not wrap the default export's `fetch`.
+
+```js
+import {useRoutes, isOwner, hasRole, requireSameOrigin} from '@homie-rocks/studio/worker';
+
+useRoutes(async (request, env, ctx) => {
+  const url = new URL(request.url);
+  if (url.pathname === '/.well-known/example.json') {
+    return Response.json({name: 'My studio'});
+  }
+  if (url.pathname === '/api/custom/refresh') {
+    if (request.method !== 'POST') return new Response('POST required', {status:405});
+    const refused = requireSameOrigin(request);
+    if (refused) return refused;
+    if (!(await isOwner(request, env))) return new Response('Unauthorized', {status: 401});
+    // Validate input, then perform the owner-authorized mutation here.
+    return Response.json({ok: true});
+  }
+  // Return undefined or null to continue to the studio's static assets / 404.
+});
+```
+
+Homie's matched routes always take precedence, including its office, OAuth,
+MCP, discovery, app and game routes, and their authorization refusals. Use a
+separate namespace under `/api/custom/`, such as `/api/custom/callbacks/provider` for your OAuth callback;
+`/oauth/*` belongs to Homie. Unmatched requests reach your handler before static
+assets inside the Worker. Cloudflare normally serves existing public static files
+without invoking the Worker. If a custom route must override such a file, put
+`{"assets":{"run_worker_first":true}}` in the studio's `wrangler.custom.json`;
+build/deploy preserves that setting. To intercept only selected files, use
+`{"assets":{"run_worker_first":["/feed.json"]}}`. These paths are unioned with
+Homie's generated `/games/*`, `/_studio/*`, `/_site/*` and per-app paths. Those
+paths must reach the Worker to enforce private app authorization; custom arrays
+(including empty arrays) or `false` cannot remove them. Exclusion patterns (starting with `!`) are refused at build, because they would take those paths out from behind their access checks. A second `useRoutes` call replaces the handler; `useRoutes(null)` removes
+it. Register configuration only, never request data, at module scope.
+
+The handler may return a `Response`, `null` or `undefined`. Errors propagate as
+Worker errors. Responses keep streaming and pass through Homie's normal HTML
+security headers, concept-mode handling and database change delivery. Custom
+responses also receive `X-Content-Type-Options: nosniff` and a default
+`Referrer-Policy: strict-origin-when-cross-origin`. WebSocket upgrades are preserved.
+Use `ctx.waitUntil(promise)` for work that must finish after the response.
+
+`await isOwner(request, env)` recognizes the live owner session issued by passkey
+sign-in (including expiry and revocation), configured owner player accounts, and
+trusted owner tool identity. Read/office bearer keys alone do not make a browser
+the owner. `await hasRole(request, env, appId, roleName)` uses the app's declared
+role and existing access checks: public roles permit visitors; private roles
+require the same private link or handoff session and live grants as the app.
+Unknown apps and roles return false. The explicit role argument takes precedence
+over query parameters. These helpers authorize identity; custom mutations must
+also validate the request method, Origin/CSRF protection, input and OAuth state.
+
+`requireSameOrigin(request)` reuses the studio's browser Origin checks and returns
+`null` on success or a 403 `Response` to return immediately. Use it with an explicit
+POST (or other mutation method) check before cookie-authorized changes.
+
+Use `/api/custom/*` for studio-owned endpoints: `api` is reserved from game and app
+IDs, so future experiences cannot take over that namespace. An app handoff cookie
+is scoped to `/<app>/`; the browser does **not** send it to `/custom-api/...` or
+`/api/custom/...`. For app role mutations, use the built-in `/<app>/api/app/records/*`
+endpoints or an app tool with its existing grant checks. A studio-wide custom
+endpoint can use the owner session; do not broaden app cookies or assume a handoff
+cookie will authorize `hasRole` outside its app path. Private/invite launches
+also require launch access even for a declared anonymous visitor role.
+
+For function HTTP calls whose destination is `self`, use direct `/api/` endpoints
+such as `/api/custom/refresh`, not page URLs that redirect. Self calls use
+`redirect:'error'`; a redirect fails instead of forwarding credentials.

package/guides/app/SKILL.md

@@ -365,3 +365,10 @@ Authoritative bookings/inventory are server-side `defineTool` actions with stric
 Initialise text controls and navigation before 3D rendering. Catch renderer creation failures inside the scene section; keep fallback text in normal flow, never over navigation. Add a navigation need and run `homie-studio check <id> --webgl-failure --shots .checks/no-webgl` to prove the controls work without WebGL.
 
 On TV, reserve `--homie-join-inset-bottom/right` (or the configured corner's top/left) plus a gap; `body.homie-join-visible` and `--homie-join-x/y/width/height` describe the shell card in the app frame too. See `node_modules/@homie-rocks/studio/docs/toolkit-place-patterns.md` for layout and text-first examples, connector setup and diagnostics.
+
+For studio-owned HTTP routes, read
+`node_modules/@homie-rocks/studio/docs/custom-routes.md`. Register with `useRoutes`
+and use `/api/custom/*` (game/app IDs cannot claim `api`). App handoff cookies are
+scoped to `/<app>/` and do not reach `/custom-api/...`; use built-in app record
+endpoints or app tools for role-authorized mutations. Use direct `/api/` endpoints
+for function `self` calls, which use `redirect:'error'`.

package/guides/playtest/scripts/playtest.mjs

@@ -542,17 +542,19 @@ async function soundSession(base, game, out, seconds, gameJson) {
   } finally { await close(h); }
 }
 
-/** A round with one person playing hard (a computer) and one doing nothing (a phone), both strangers in the public room. */
+/** A round with one person playing hard (a computer) and one doing nothing (a phone), in the same public room. */
 async function playSession(base, game, out, roundSeconds, gameJson) {
   const profile = actionProfile(gameJson, 'desk');
   const actions = newActions(profile);
   const active = await launch('desk', `${base}/${game}/play`);
-  const idle = await launch('phone', `${base}/${game}/play`);
+  let idle;
   try {
     const seat = async (h) => { const until = Date.now() + 45_000; while (Date.now() < until) { const s = await shell(h); if (s?.room && s.seat !== null && s.seat !== undefined && s.role) return s; await sleep(300); } return null; };
-    const [sa, si] = await Promise.all([seat(active), seat(idle)]);
+    const sa = await seat(active);
+    idle = await launch('phone', `${base}/${game}/play${sa?.room ? `?room=${encodeURIComponent(sa.room)}` : ''}`);
+    const si = await seat(idle);
     if (!sa || !si) { row('play', 'FAIL', { why: 'a browser never got a seat in 45 s' }); return; }
-    if (sa.room !== si.room) { row('play', 'FAIL', { why: `the two browsers landed in different rooms (${sa.room}, ${si.room}): two strangers who press Play must meet` }); return; }
+    if (sa.room !== si.room) { row('play', 'FAIL', { why: `the two browsers landed in different rooms (${sa.room}, ${si.room}): the invitation must join the same room` }); return; }
     const since = Date.now();
     // Only a round that STARTS after both are seated counts: a newcomer takes a bot's place mid-round and inherits
     // its body and score, so the round already running says nothing about how these two played.
@@ -597,7 +599,7 @@ async function playSession(base, game, out, roundSeconds, gameJson) {
       results: rowsR.map((x) => ({ place: x.place, score: x.score, bot: x.bot, who: x.seat === sa.seat ? 'the active player' : x.seat === si.seat ? 'the idle player' : x.bot ? 'a bot' : 'another person' })),
       scoreSamples: scores.filter((_, k) => k % 5 === 0).slice(0, 40), shot: 'play-round-over.png',
     });
-  } finally { await close(active); await close(idle); }
+  } finally { await close(active); if (idle) await close(idle); }
 }
 
 /** The studio's own checks, run as the creator would: the owner tests (port check) and the two-stranger round. */

package/lib/check.mjs

@@ -203,7 +203,14 @@ export async function check({ webglFailure = false, isolate = true, root = null,
       const ua = await browser.userAgent();
       await page.setUserAgent(`${ua} ${userAgentTag}`);
       const t0 = Date.now();
-      try { await page.goto(play, { waitUntil: 'domcontentloaded', timeout: 90_000 }); } catch (error) {
+      let target = play;
+      if (players.length) {
+        const first = players[0].page;
+        await first.waitForFunction(() => Boolean(window.__shell?.room), {timeout: 90_000});
+        const room = await first.evaluate(() => window.__shell.room);
+        target = `${play}?room=${encodeURIComponent(room)}`;
+      }
+      try { await page.goto(target, { waitUntil: 'domcontentloaded', timeout: 90_000 }); } catch (error) {
         if (cannotAsk) return { ...cannotAsk, play, why: `${cannotAsk.why} (The ${kind.name} browser could not open it either: ${String(error?.message ?? error).split('\n')[0].slice(0, 120)}.)` };
         throw error;
       }

package/lib/cloudflare.mjs

@@ -1,3 +1,4 @@
+import {redactText} from './redact.mjs';
 import {enableReadReplication} from './read-replication.mjs';
 import {ensureBackgroundQueues,backgroundQueues} from './background-queue.mjs';
 import { directoryUrl } from '../worker/directory-choice.mjs';
@@ -53,6 +54,13 @@ import { LOCAL_STATE, configPath, domainOrigin, isRulesGame, isWorkersDev, layou
 
 const ANSI = /\u001b\[[0-9;]*m/g;
 
+/** Keep Wrangler's error and its context; progress/footer lines must not hide it. */
+export function wranglerDeployError(out) {
+  const clean = redactText(String(out ?? '').replace(ANSI, '')).text;
+  const error = clean.search(/(?:^|\n)[^\n]*\[ERROR\]/);
+  return (error >= 0 ? clean.slice(error) : clean).trim();
+}
+
 export function experienceAddresses(root, id, url) {
   const app = listGames(root).find(g => g.id === id)?.kind === 'app';
   return { [app ? 'open' : 'play']: url ? `${url}/${id}/${app ? 'open' : 'play'}` : null, wall: url ? `${url}/${id}/tv` : null };
@@ -67,24 +75,41 @@ export function wranglerBin(root) {
 export function runner(root, env) {
   const bin = wranglerBin(root);
   if (!bin) throw new Error('Wrangler is not installed in this studio yet: run `npm install` in the studio folder first');
-  return (args, { cwd = workerDir(root), input } = {}) => {
+  return (args, { cwd = workerDir(root), input, timeout = 10 * 60_000 } = {}) => {
     const dev = join(workerDir(root), '.wrangler', 'homie-dev.wrangler.json');
     if (args.includes('--local') && !args.includes('--config') && existsSync(dev)) args = [...args, '--config', dev, '--persist-to', join(workerDir(root), '.wrangler', 'state')];
     const res = spawnSync(bin, args, {
       cwd, env: { ...process.env, ...env, WRANGLER_SEND_METRICS: 'false', CI: '1' }, encoding: 'utf8',
-      input, maxBuffer: 64 * 1024 * 1024, timeout: 10 * 60_000,
+      input, maxBuffer: 64 * 1024 * 1024, timeout,
     });
-    const out = `${res.stdout ?? ''}${res.stderr ?? ''}`.replace(ANSI, '');
+    const out = `${res.stdout ?? ''}${res.stderr ?? ''}${res.error ? '\n' + res.error.message : ''}`.replace(ANSI, '');
     return { code: res.status ?? 1, out, stdout: (res.stdout ?? '').replace(ANSI, '') };
   };
 }
 
+/** Retry with fresh Wrangler processes: another studio may be rotating shared OAuth credentials. */
+export async function checkWranglerLogin(root, env = {}, {run = null, sleep = ms => new Promise(resolve => setTimeout(resolve, ms))} = {}) {
+  const bin = run ? null : wranglerBin(root);
+  if (!run && !bin) return {ok:false, needs:'cloudflare-login', why:'Wrangler is not installed in this studio yet: run `npm install` first.'};
+  const w = run ?? (args => wranglerRun(bin, args, {cwd:root, env:{...process.env,...env,WRANGLER_SEND_METRICS:'false',CI:'1'}, timeout:25_000}));
+  let res, data;
+  for (let attempt = 0; attempt < 4; attempt++) {
+    if (attempt) await sleep([200, 600, 1400][attempt - 1] + Math.floor(Math.random() * 100));
+    res = await w(['whoami', '--json'], {cwd: root, timeout: 25_000});
+    try { data = JSON.parse(res.stdout ?? ''); } catch { data = null; }
+    if (res.code === 0 && data?.loggedIn === false) return {ok:false, needs:'cloudflare-login', why:'Wrangler is not signed in. Run `npx wrangler login` and approve once in your browser, then retry.'};
+    if (res.code === 0 && data?.loggedIn === true) return {ok:true, who:{accounts:(data.accounts ?? []).map(a => ({id:a.id,name:a.name})),authType:data.authType}};
+  }
+  const detail = String(res.out ?? '').trim();
+  const expired = data?.loggedIn === false || /(?:refresh token.*(?:expired|invalid)|invalid_grant|not (?:logged|signed) in|authentication error|authenticate request)/i.test(detail);
+  return {ok:false, needs:expired ? 'cloudflare-login' : 'cloudflare-auth-check', why: (expired
+    ? 'Wrangler could not authenticate after four attempts. Run `npx wrangler login`, then retry.'
+    : 'Wrangler could not check sign-in after four attempts. Another process may be refreshing credentials, or Cloudflare may be unreachable. Retry shortly.') + (detail ? '\nWrangler: '+detail : '')};
+}
+
 /** Who Wrangler is signed in as, or null. Never prints a token. */
-export function whoami(root, env = {}) {
-  const w = runner(root, env);
-  const res = w(['whoami', '--json'], { cwd: root });
-  if (res.code !== 0) return null;
-  try { const d = JSON.parse(res.stdout); return d.loggedIn ? { accounts: (d.accounts ?? []).map((a) => ({ id: a.id, name: a.name })), authType: d.authType } : null; } catch { return null; }
+export async function whoami(root, env = {}) {
+  return (await checkWranglerLogin(root, env)).who ?? null;
 }
 
 function parseJson(text) {
@@ -262,12 +287,13 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   const wide = wideRouteRefusal(readConfig(root), studio);
   if (wide) return { ok: false, command: 'deploy', ...wide };
   let routes = keptRoutes(root, studio);
-  const who = whoami(root);
-  if (!who) {
-    if (cf.auth === 'stripe-projects') {
-      return { ok: false, command: 'deploy', needs: 'cloudflare-login', why: 'Wrangler did not accept the Cloudflare token Stripe Projects keeps for this studio (studio.json "auth": "stripe-projects"). Run `stripe projects env --pull` in the studio folder (it rewrites the git-ignored .env from Projects\' vault), then `npm run deploy` again; or sign in the usual way (`npx wrangler login`) and remove "auth" from studio.json.' };
+  const login = await checkWranglerLogin(root);
+  const who = login.who;
+  if (!login.ok) {
+    if (cf.auth === 'stripe-projects' && login.needs === 'cloudflare-login') {
+      return { ok: false, command: 'deploy', needs: 'cloudflare-login', why: login.why + '\nWrangler did not accept the Cloudflare token Stripe Projects keeps for this studio (studio.json "auth": "stripe-projects"). Run `stripe projects env --pull` in the studio folder (it rewrites the git-ignored .env from Projects\' vault), then `npm run deploy` again; or sign in the usual way (`npx wrangler login`) and remove "auth" from studio.json.' };
     }
-    return { ok: false, command: 'deploy', needs: 'cloudflare-login', why: 'Wrangler is not signed in to Cloudflare. Run `npx wrangler login` in the studio folder: it opens Cloudflare in the browser and the person approves once (a free account works, no payment method). Then run `npm run deploy` again.' };
+    return { ...login, command: 'deploy' };
   }
   const accountId = process.env.CLOUDFLARE_ACCOUNT_ID || cf.accountId || (who.accounts.length === 1 ? who.accounts[0].id : null);
   if (!accountId) {
@@ -413,7 +439,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
     step(address.created ? 'registered the account’s workers.dev address automatically' : 'kept the account’s existing workers.dev address');
     dep = w(['deploy', ...(workerEntry(root) ? [workerEntry(root)] : []), ...repoVar(root)]);
   }
-  if (dep.code !== 0) return refuse(`wrangler deploy failed: ${dep.out.trim().split('\n').slice(-6).join(' ')}`, dep.out);
+  if (dep.code !== 0) return refuse(`wrangler deploy failed: ${wranglerDeployError(dep.out)}`, dep.out);
   if (paidReleases(root).length) {
     const bin = wranglerBin(root);
     const uploadOptions = { cwd: workerDir(root), env: { ...process.env, CLOUDFLARE_ACCOUNT_ID: accountId, WRANGLER_SEND_METRICS: 'false', CI: '1' } };
@@ -637,7 +663,7 @@ export async function ciDeploy(root, { log = () => {}, wrangler = null } = {}) {
   }
   const started = Date.now();
   const dep = w(['deploy', ...(workerEntry(root) ? [workerEntry(root)] : []), ...repoVar(root)]);
-  if (dep.code !== 0) return refuse(`wrangler deploy failed: ${dep.out.trim().split('\n').slice(-6).join(' ')}`, dep.out);
+  if (dep.code !== 0) return refuse(`wrangler deploy failed: ${wranglerDeployError(dep.out)}`, dep.out);
   step(`deployed ${names.worker ?? 'the Worker'} in ${Math.round((Date.now() - started) / 1000)} s`);
   const repo = repoOf(root);
   step(repo ? `the live site knows its GitHub repository (${repo}), for the Claude app's hand-off` : 'no GitHub repository found here (no HOMIE_REPO, studio.json "github" or git remote): the Claude app\'s card asks the person which it is');
@@ -683,8 +709,9 @@ export async function storageAdd(root, { log = () => {} } = {}) {
   if (created.has(`r2:${bucket}`)) {
     return { ok: true, command: 'storage add', bucket, already: true, next: ['npm run deploy   (binds it as MEDIA if the live site does not have it yet)'] };
   }
-  const who = whoami(root);
-  if (!who) return { ok: false, command: 'storage add', needs: 'cloudflare-login', why: 'Wrangler is not signed in to Cloudflare. Run `npx wrangler login` first (one approval in the browser).' };
+  const login = await checkWranglerLogin(root);
+  if (!login.ok) return {...login, command:'storage add'};
+  const who = login.who;
   const accountId = process.env.CLOUDFLARE_ACCOUNT_ID || cf.accountId || (who.accounts.length === 1 ? who.accounts[0].id : null);
   if (!accountId) return { ok: false, command: 'storage add', needs: 'cloudflare-account', why: 'This login reaches several Cloudflare accounts; put the studio\'s in studio.json (cloudflare.accountId) first.', accounts: who.accounts };
   const w = runner(root, { CLOUDFLARE_ACCOUNT_ID: accountId });
@@ -718,15 +745,15 @@ export async function storageAdd(root, { log = () => {} } = {}) {
 }
 
 /** One Wrangler command, run without blocking (an upload of a music video takes a while); the last of its words kept. */
-function wranglerRun(bin, args, { cwd, env }) {
+function wranglerRun(bin, args, { cwd, env, timeout }) {
   return new Promise((done) => {
-    const p = spawn(bin, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
-    let out = '';
+    const p = spawn(bin, args, { cwd, env, timeout, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '', stdout = '';
     const keep = (d) => { out = `${out}${d}`.slice(-8000); };
-    p.stdout.on('data', keep);
+    p.stdout.on('data', data => {stdout = `${stdout}${data}`.slice(-65536); keep(data);});
     p.stderr.on('data', keep);
     p.on('error', (e) => done({ code: 1, out: String(e.message) }));
-    p.on('close', (code) => done({ code: code ?? 1, out: out.replace(ANSI, '') }));
+    p.on('close', (code) => done({ code: code ?? 1, out: out.replace(ANSI, ''), stdout: stdout.replace(ANSI, '') }));
   });
 }
 

package/lib/dev.mjs

@@ -347,17 +347,15 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
   if (!bin) return { ok: false, command: 'dev', why: 'run npm install in the studio first' };
   const env = { ...process.env, WRANGLER_SEND_METRICS: 'false', CI: '1', ...(process.stdout.isTTY && !process.env.NO_COLOR ? { FORCE_COLOR: process.env.FORCE_COLOR ?? '1' } : {}) };
   for (const added of ensureMigrations(root)) log(`added ${added} (${migrationWord(added)})`);
-  await new Promise((done) => {
-    const m = spawn(bin, ['d1', 'migrations', 'apply', 'DB', '--local'], { cwd: workerDir(root), env, stdio: ['ignore', 'ignore', 'inherit'] });
-    m.on('close', done);
-    m.on('error', done);
-  });
   const {functionDeploymentSQL}=await import('./functions-build.mjs');
-  const registerFunctions=()=>new Promise(resolve=>{
-    const child=spawn(bin,['d1','execute','DB','--local','--command',functionDeploymentSQL(root)],{cwd:workerDir(root),env,stdio:['ignore','ignore','inherit']});
+  const {prepareLocalDatabase}=await import('./local-database-start.mjs');
+  const runLocal=args=>new Promise(resolve=>{
+    const child=spawn(bin,args,{cwd:workerDir(root),env,stdio:['ignore','ignore','inherit']});
     child.on('close',code=>resolve(code===0));child.on('error',()=>resolve(false));
   });
-  if(!await registerFunctions())return {ok:false,command:'dev',why:'Local function registration failed; fix the D1 error above before serving requests.'};
+  const registerFunctions=()=>runLocal(['d1','execute','DB','--local','--command',functionDeploymentSQL(root)]);
+  const failure=await prepareLocalDatabase({migrate:()=>runLocal(['d1','migrations','apply','DB','--local']),register:registerFunctions});
+  if(failure)return {ok:false,command:'dev',why:failure};
   const origin = `http://127.0.0.1:${port}`;
   const printedOrigin = `http://localhost:${port}`;
   log(`Local site: ${printedOrigin}/  (each game: ${printedOrigin}/<id>/play — open it in two browsers)`);

package/lib/local-database-start.mjs

@@ -0,0 +1,6 @@
+/** Complete local schema and subscriptions before any request can emit an event. */
+export async function prepareLocalDatabase({migrate,register}) {
+  if(!await migrate())return 'Local database migration failed; fix the D1 error above before serving requests.';
+  if(!await register())return 'Local function registration failed; fix the D1 error above before serving requests.';
+  return null;
+}

package/lib/mcp-tools.mjs

@@ -843,7 +843,7 @@ export function toolDefs(ctx, avail = {}) {
         let at = dir;
         if (existsSync(at) && readdirSync(at).some((f) => !['.DS_Store', '.git'].includes(f)) && !existsSync(join(at, 'studio.json'))) at = `${dir}-studio`;
         let made;
-        try { made = newStudio(at, { name, kind: a.kind ?? 'game', install: false, ...(ctx.directory ? { homie: ctx.directory } : {}) }); } catch (error) { return fail(error.message); }
+        try { made = newStudio(at, { name, kind: a.kind ?? 'game', install: false }); } catch (error) { return fail(error.message); }
         ctx.current = made.dir;
         ctx.note(made.dir).earlier = earlier.map((e) => e.path);
         let install = null;
@@ -1258,10 +1258,10 @@ export function toolDefs(ctx, avail = {}) {
         // the directory's read-only count for this site, the parts' lines, and nothing published. Run here, by THIS
         // toolkit, never handed to the studio's pinned one: a 0.31.0 toolkit reads `publish --before` as `publish`.
         if (a.before === true) {
-          const b = await publishBefore(root, { site: a.site ? String(a.site) : undefined });
+          const b = await publishBefore(root, { homie: ctx.directory ?? undefined, site: a.site ? String(a.site) : undefined });
           return ok(b.lines.join('\n'), { kind: 'publish-count', ...publishesSoFar(root), ...b });
         }
-        const r = await cli(ctx, root, 'publish', ['publish', ...(a.site ? ['--site', String(a.site)] : [])]);
+        const r = await cli(ctx, root, 'publish', ['publish', ...(ctx.directory ? ['--homie', ctx.directory] : []), ...(a.site ? ['--site', String(a.site)] : [])]);
         if (!r.ended) return stillRunning(r.job, 'Listing');
         if (r.job.code !== 0) return fail(`Not listed: ${whyOf(r.job)}`, r.result?.publishes ? { kind: 'publish', ok: false, needs: r.result.needs ?? null, publishes: r.result.publishes } : undefined);
         return ok(`Listed: ${r.result?.studioPage ?? r.result?.directory ?? ''}\n${(r.result?.games ?? []).map((g) => `  ${g.name}: ${g.play}`).join('\n')}${r.result?.publishes?.line ? `\n${r.result.publishes.line}` : ''}${partsSaid.length ? `\n${partsSaid.join('\n')}` : ''}`, { kind: 'publish', ...r.result });

package/lib/port-check.mjs

@@ -628,12 +628,13 @@ export async function portCheck({ url, game, root, only = null, shots = null, lo
       }
     }
 
-    /* ---- two fresh browsers meet through the lobby and finish a round */
+    /* ---- a public join and an invited browser finish a round */
     if (want.has('round') && await gate('round')) {
       try {
         const A = await launch('desk');
         const B = await launch('phone');
-        const [oa, ob] = [await open(A, `${base}/${game}/play?name=Desk`), await open(B, `${base}/${game}/play?name=Phone`)];
+        const oa = await open(A, `${base}/${game}/play?name=Desk`);
+        const ob = await open(B, `${base}/${game}/play?name=Phone${oa.shell?.room ? `&room=${encodeURIComponent(oa.shell.room)}` : ''}`);
         if (!oa.ok || !ob.ok) row('round', false, { why: `a browser was never seated (${!oa.ok ? `computer: ${oa.why}` : ''} ${!ob.ok ? `phone: ${ob.why}` : ''})` });
         else if (oa.shell.room !== ob.shell.room) row('round', false, { why: `the two browsers landed in different rooms (${oa.shell.room}, ${ob.shell.room})` });
         else {

package/lib/scaffold.mjs

@@ -152,6 +152,8 @@ the Table/Lobby Durable Objects, on the studio's Cloudflare account), built
 from \`@homie-rocks/studio\`, pinned in \`package.json\`. The homie.rocks
 directory lists its games; homie.rocks does not host them.
 
+For studio-owned HTTP endpoints, read \`node_modules/@homie-rocks/studio/docs/custom-routes.md\` before editing \`site/src/worker.mjs\`. Use the reserved \`/api/custom/*\` namespace and the documented authorization and cookie scopes.
+
 ## Version-matched authoring guides
 
 Before authoring or rewriting a game, read \`node_modules/@homie-rocks/studio/guides/game/SKILL.md\`,

package/lib/template-history.json

@@ -4020,7 +4020,52 @@
    },
    "sections": {
     "AGENTS.md": {
-     "(intro)": "394cbbe934e80722",
+     "(intro)": [
+      "394cbbe934e80722",
+      "af7f2f732505d379"
+     ],
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "c10aa0441ea89702",
+     "## Commands (all through the pinned CLI in node_modules)": "c20d90de21cde0c7",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": "0df5a5fe1833c624",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "8364e05cebefcba4"
+      }
+     }
+    }
+   }
+  },
+  "0.56.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "af7f2f732505d379",
      "## Version-matched authoring guides": "f6261a0e5801b96b",
      "## Layout": "f3a280b8c96cd068",
      "## Apps: one screen, roles and parts": "c10aa0441ea89702",

package/lib/worker-build.mjs

@@ -20,7 +20,10 @@ export async function buildWorker(root,esbuild,metadata=null) {
   // classes in the generated bundle without rewriting the studio's source/customizations.
   const standardRooms=/export\s*\{[^}]*\bTable\b[^}]*\bLobby\b[^}]*\}\s*from\s*['"]@homie-rocks\/studio\/worker['"]/.test(readFileSync(source,'utf8'));
   const lazyRooms=standardRooms?`export {Table,Lobby} from ${JSON.stringify(join(PACKAGE_ROOT,'worker/lazy-objects.mjs'))};\n`:'';
-  const contents=`${lazyRooms}export * from ${JSON.stringify(source)};\nexport { default } from ${JSON.stringify(source)};\nexport { Gate, Concentrator } from ${JSON.stringify(join(PACKAGE_ROOT,'worker/lazy-objects.mjs'))};\nexport {AppRecordHub, EventHub} from ${JSON.stringify(join(PACKAGE_ROOT,'worker/lazy-objects.mjs'))};\n`;
+  // A custom fetch wrapper may predate background delivery. Complete the event
+  // boundary here, preserving explicit studio handlers and leaving source alone.
+  const toolkitEntry=alias['@homie-rocks/studio/worker']==='@homie-rocks/studio/worker/selling'?'worker/selling/index.mjs':'worker/index.mjs';
+  const contents=`${lazyRooms}export * from ${JSON.stringify(source)};\nimport studioWorker from ${JSON.stringify(source)};\nimport toolkitWorker from ${JSON.stringify(join(PACKAGE_ROOT,toolkitEntry))};\nexport default { ...studioWorker, queue: studioWorker.queue ?? toolkitWorker.queue, scheduled: studioWorker.scheduled ?? toolkitWorker.scheduled };\nexport { Gate, Concentrator } from ${JSON.stringify(join(PACKAGE_ROOT,'worker/lazy-objects.mjs'))};\nexport {AppRecordHub, EventHub} from ${JSON.stringify(join(PACKAGE_ROOT,'worker/lazy-objects.mjs'))};\n`;
   const result=await esbuild.build({stdin:{contents,resolveDir:root,sourcefile:'worker.mjs'},entryNames:'worker',absWorkingDir:root,alias,outdir:out,bundle:true,splitting:true,format:'esm',platform:'browser',mainFields:['module','main'],conditions:['workerd','worker','browser'],external:['node:*','cloudflare:*'],target:'es2022',write:false,minify:true,metafile:true,logLevel:'silent',plugins:[{name:'studio-runtime',setup(build){
     if(metadata)build.onLoad({filter:/[/\\]worker[/\\]built-metadata\.mjs$/},()=>({contents:'export default '+JSON.stringify(metadata),loader:'js'}));
     // Merely overriding entry exports still evaluates the barrel's dependencies.

package/lib/worker-config.mjs

@@ -28,6 +28,13 @@ export function updateWorkerConfig(root,generated) {
     writeFileSync(join(root,'wrangler.custom.json'),JSON.stringify(custom,null,2)+'\n');
   }
   const next=merge(base,custom);
+  // Authorization paths are additive: custom assets must never bypass toolkit gates.
+  const requiredRoutes=base.assets?.run_worker_first, customRoutes=custom.assets?.run_worker_first;
+  // A "!" pattern excludes paths from the Worker. Only Homie writes those (static-assets.mjs): a custom one
+  // could take /games/*, /_studio/* or an app's files out from behind their access checks.
+  const exclusions=Array.isArray(customRoutes)?customRoutes.filter(p=>String(p).startsWith('!')):[];
+  if(exclusions.length)throw new Error(`wrangler.custom.json assets.run_worker_first cannot exclude paths (${exclusions.join(', ')}): list only the extra paths your own routes need`);
+  next.assets={...next.assets,run_worker_first:requiredRoutes===true || customRoutes===true ? true : [...new Set([...(Array.isArray(requiredRoutes)?requiredRoutes:[]),...(Array.isArray(customRoutes)?customRoutes:[])])]};
   if(readStudio(root).concept===true)next.assets={...next.assets,run_worker_first:true};
   next.vars={...next.vars,HOMIE_CONCEPT:readStudio(root).concept===true?'1':'0'};
   verifiedMcpConfig(root);

package/netplay/NETPLAY.md

@@ -1591,7 +1591,11 @@ A page stands in one of six places with its room, and the helper says which:
 - **`net.offline` means "not in a room"**, not "no network": it is true for `alone` and `offline`.
   **`net.connected`** is true only while the socket is up and welcomed. The state between them
   (`!net.offline && !net.connected`) is `reconnecting`.
-- **`on('link', (e) => …)`** fires on every change with `{ state, prev, why, hosting, downMs }`.
+- **`on('link', (e) => …)`** immediately calls the listener with the current state
+  (`prev === state`, `why: 'subscribe'`), then fires on every change with `{ state, prev, why, hosting, downMs }`.
+  Ignore `why === 'subscribe'` when triggering reconnect recovery; it initializes
+  UI and does not signal a new connection. Listener errors are isolated, including
+  this immediate call, and `on()` always returns the unsubscribe function.
   `hosting` says this page is running the rules right now. Two pages can both say so for a
   moment: a host that was cut off keeps simulating until its welcome tells it the room moved on,
   and a page that is `alone` hosts its own private round. Before revision 9 neither said