@homie-rocks/studio 0.54.0 → 0.56.0

package/CHANGELOG.md

@@ -17,6 +17,72 @@ 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**
+
+Studios start faster and serve files straight from Cloudflare, background work and Stripe events go through retrying queues so nothing is lost, and the runtime follows Cloudflare's published practice.
+
+### Changed
+
+- Deploy with D1 primary fallback when replication is unavailable; only install needed schedules, explain account cron limits, and preserve retired-source, HEAD and concept-page protections.
+- Deliver mutations and verified Stripe webhooks through retryable Queues. Store PaymentIntent ids before follow-up, recover lost responses using the original idempotency key, and retain uncertain payments for review.
+- Batch cold metadata, use causally consistent D1 sessions, bake catalogues, route public assets first, isolate subscription objects and load rendering modules at their entry points. Index MCP expiry and deliver catalogue notifications in background work.
+- Split request routing, runtime helpers, Table, Lobby, room chat, controls and wire validation into modules without changing behavior.
+- Skip unchanged analytics counters and watermarks, paginate rollups by UTC day, and show delayed counts in owner statistics.
+- Set `stats.analytics: true` in studio.json to count page activity with Analytics Engine and hourly, replay-safe D1 rollups that preserve historical totals. Owner statistics explain ingestion lag and sampling.
+
+### Fixed
+
+- Weight Analytics Engine page counts by the sample interval, preserving historical totals and retry-safe corrections under sampling.
+- Stop queued Stripe reconciliation database operations and provider calls after lease renewal fails or the lease expires, leaving the event pending for retry.
+- Preserve live MCP OAuth and webhook dedupe rows during cleanup by using Unix seconds throughout MCP storage; reclaim idle guests occasionally on guest creation even without a studio cron.
+- Recover verified Stripe intake from D1 after queue failures, renew reconciliation leases, preserve replay API versions, report stuck deliveries, and isolate scheduled maintenance failures. Resume partial queue setup with clear CI token permission guidance.
+- Confine Chrome debugging pipes to CI with protocol deadlines matching launch deadlines; preserve owner CLI flags and capture child stderr, exits, shared-memory availability and concurrent Chrome processes in CI artifacts.
+
+### Upgrade notes
+
+- Existing restricted Stripe keys need Products and Prices Read for expanded checkout/subscription lines. Shop-only keys also need Subscriptions Read, Invoices Read and Customer portal Write for renewal verification and subscription management. Update both test and live keys in Stripe before deploying. Expanded objects require their own permissions: https://docs.stripe.com/stripe-apps/reference/permissions.
+
 ## [0.54.0] - 2026-10-15
 
 **Plugin 0.54.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/background-queue.mjs

@@ -0,0 +1,31 @@
+import {readStudio,writeStudio,workerDir} from './studio.mjs';
+import {cloudflareAuth} from './brain-probe.mjs';
+import {join} from 'node:path';
+export const backgroundQueues=worker=>({work:worker.slice(0,48)+'-background',dead:worker.slice(0,48)+'-background-dlq'});
+/** Names reserve this studio's queues. An interrupted pre-deploy creation has no
+ * bindings yet; inspect structured API records before resuming that reservation. */
+export async function ensureBackgroundQueues(root,run,{accountId,fetchFn=fetch,headers}={}) {
+  const studio=readStudio(root),names=backgroundQueues(studio.cloudflare.worker);
+  accountId??=process.env.CLOUDFLARE_ACCOUNT_ID??studio.cloudflare.accountId;
+  for(const name of [names.dead,names.work]) {
+    if(readStudio(root).cloudflare.created?.includes('queue:'+name))continue;
+    const result=run(['queues','create',name]);
+    if(result.code!==0) {
+      headers??=await cloudflareAuth({bin:join(root,'node_modules/.bin/wrangler'),cwd:workerDir(root),exec:async(_bin,args)=>{const r=run(args);return {code:r.code,stdout:r.stdout??r.out};}});
+      const permission='The deployment token needs Account > Queues > Edit on this account. Add that permission to the CI/Workers Builds token (or sign in again with Wrangler), then retry deploy.';
+      if(!headers||!accountId)throw new Error(permission);
+      const response=await fetchFn(`https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/queues?name=${encodeURIComponent(name)}`,{headers,signal:AbortSignal.timeout(15000)});
+      if(response.status===401||response.status===403)throw new Error(permission);
+      const body=await response.json();
+      if(!response.ok||body.success===false)throw new Error(`Could not inspect queue ${name} (HTTP ${response.status}). ${permission}`);
+      const queue=body.result?.find(q=>q.queue_name===name);
+      if(!queue)throw new Error(`Could not create queue ${name}. ${permission} Wrangler: ${result.out?.trim().split('\n').slice(-4).join(' ')}`);
+      const producers=queue.producers??[],consumers=queue.consumers??[];
+      if((queue.producers_total_count??producers.length)>producers.length||(queue.consumers_total_count??consumers.length)>consumers.length||
+        producers.some(p=>p.type!=='worker'||p.script!==studio.cloudflare.worker)||consumers.some(c=>c.type!=='worker'||(c.script_name??c.script)!==studio.cloudflare.worker))
+        throw new Error(`Queue ${name} is bound to another producer or consumer; it must belong exclusively to this studio`);
+    }
+    const latest=readStudio(root);
+    writeStudio(root,{...latest,cloudflare:{...latest.cloudflare,created:[...new Set([...(latest.cloudflare.created??[]),'queue:'+name])].sort()}});
+  }
+}

package/lib/build.mjs

@@ -1,3 +1,4 @@
+import {staticHeaders} from './static-assets.mjs';
 import {verifiedMcpConfig,publicMcpSetup} from './shop-mcp.mjs';
 import { directoryUrl } from '../worker/directory-choice.mjs';
 import { domainOrigin } from './studio.mjs';
@@ -741,6 +742,8 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
     const image = await playerImage(catalogue, game, dist, log);
     if (image) game.playerImage = image;
   }
+  const headerPath = join(dist, '_headers');
+  writeFileSync(headerPath, staticHeaders(existsSync(headerPath) ? readFileSync(headerPath, 'utf8') : '', {concept: studio.concept === true}));
   writeFileSync(join(dist, 'games.json'), `${JSON.stringify(catalogue, null, 2)}\n`);
   // What this build made, for whatever runs next (a deploy says which games it changes; a script checks the live
   // site against it): per game its digest, its bundle and chunks, and whether it differs from the build before.
@@ -761,7 +764,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   await beforePublish();
   const hosted = (await rulesBuild()).writeRules(root, ruled, all.filter((g) => rulesOf.get(g.id)?.host === 'server').map((g) => g.id));
   log('Building site Worker…');
-  await (await import('./worker-build.mjs')).buildWorker(root, esbuild);
+  await (await import('./worker-build.mjs')).buildWorker(root, esbuild, { catalogue, posts: posts.map(p => ({ ...p })) });
   // All of it is there: now, and only now, it becomes site/dist (lib/stage.mjs).
   const swapped = swapIn(dist, live);
   return {

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,6 @@
+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';
 import { roomLayout } from '../worker/gate.mjs';
 import {workerEntry} from './worker-build.mjs';
@@ -51,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 };
@@ -65,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) {
@@ -101,6 +128,12 @@ function parseJson(text) {
 export function explainCloudflare(out, accountId = null) {
   const text = String(out ?? '');
   const dash = accountId ? `https://dash.cloudflare.com/${accountId}` : 'https://dash.cloudflare.com';
+  if (/queue.*(?:permission|authentication|forbidden|unauthori)|(?:permission|authentication|forbidden|unauthori).*queue/is.test(text)) {
+    return {needs:'queues-permission',why:'The deployment token needs Account > Queues > Edit on this account. Update the CI/Workers Builds token permissions, then retry deploy.'};
+  }
+  if (/(?:cron|schedule).*?(?:limit|maximum|exceed)|(?:limit|maximum|exceed).*?(?:cron|schedule)/i.test(text)) {
+    return { needs: 'cron-limit', why: 'This account has reached its Cron Trigger limit (5 on Workers Free). Remove unused triggers from other Workers in the Cloudflare dashboard, or upgrade the account plan, then retry deploy. Required studio schedules have been retained.' };
+  }
   if (/\b10034\b|verify your email/i.test(text)) {
     return { needs: 'cloudflare-verify-email', why: `Cloudflare needs this account's email address verified before it runs a Worker. Ask the person to open the verification email from Cloudflare (or ${dash}/profile and "Send verification email"), click it. The AI resumes deployment after verification.` };
   }
@@ -210,6 +243,9 @@ export function deployPlan(root) {
       { kind: 'Durable Object', name: 'Table', what: hosted.length ? `one per public room: the netplay relay (seats, snapshots), and for ${hosted.map((h) => h.id).join(', ')} the game's own rules, which run here and nowhere else` : 'one per public room: the netplay relay (seats, host, snapshots); runs no game code', state: 'declared by the Worker' },
       ...hosted.map((h) => ({ kind: 'Game rules', name: h.id, what: `One full ${h.seats}-player room activates ${h.objects} objects (${h.layout.gates > 1 ? `${h.layout.gates} Gates, the room and its diagnostics` : 'the room'}): approximately ${h.gbSeconds} GB-seconds/hour before Lobby activity. Player input/ping alone contributes ${h.requests} request units/hour; relay frames and receipts, HTTP and storage are additional. Occupancy, batching and account usage determine the bill.`, state: 'in the Worker' })),
       { kind: 'Durable Object', name: 'Lobby', what: 'one per game: puts strangers who press Play into the same room', state: 'declared by the Worker' },
+      ...['Gate','Concentrator','AppRecordHub','EventHub'].map(name=>({kind:'Durable Object',name,what:name==='Gate'?'room transport and diagnostics':name==='Concentrator'?'compatibility for existing studios':'independent live subscriptions',state:'declared by the Worker'})),
+      ...Object.values(backgroundQueues(cf.worker)).map(name=>({kind:'Queue',name,what:'durable background delivery with retries and a dead-letter queue',state:mark('queue:'+name)})),
+      ...(studio.stats?.analytics===true ? [{kind:'Analytics Engine',name:`${cf.worker.replace(/-/g,'_')}_visits`,what:'page counts, rolled into historical D1 totals hourly',state:'bound by the Worker'}] : []),
       storage
         ? { kind: 'R2 bucket', name: storage, what: 'the studio\'s big media: songs and videos over the size studio.json media.r2Over names (1 MiB unless set) or that git leaves out, uploaded and checked by SHA-256 before the site stops carrying them, served at their same addresses', state: 'exists (this studio made it)', plan: 'R2 (payment method on the account; 10 GB-month free)' }
         : { kind: 'R2 bucket', name: null, what: 'none: a new studio needs no storage. `homie-studio storage add` adds it later, for large media only', state: 'not created', plan: null },
@@ -251,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) {
@@ -384,8 +421,10 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   step(`Cron triggers: ${(readConfig(root)?.triggers?.crons??[]).join("; ")||"none (remove toolkit triggers)"}`);
   if (routes) step(`kept the studio's own route${routes.length === 1 ? '' : 's'} in wrangler.jsonc: ${routes.map((r) => r.pattern).join(', ')}`);
   for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
+  try {await ensureBackgroundQueues(root,w,{accountId,...(fetchFn?{fetchFn}:{})});for(const key of readStudio(root).cloudflare.created??[])created.add(key);} catch(error) {return refuse(error.message);}
   const migrate = w(['d1', 'migrations', 'apply', cf.d1, '--remote']);
   if (migrate.code !== 0) return refuse(`D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
+  try {const replication=await enableReadReplication(root,w,{accountId,databaseId:db.uuid,...(fetchFn?{fetchFn}:{})});step(replication.enabled?'D1 read replication enabled':`D1 uses the primary: ${replication.reason}`);} catch(error) {step(`D1 uses the primary: ${error.message}`);}
   step('D1 migrations applied');
   const subscriptions=w(['d1','execute',cf.d1,'--remote','--command',(await import('./functions-build.mjs')).functionDeploymentSQL(root)]);
   if(subscriptions.code!==0)return refuse('Could not register studio functions',subscriptions.out);
@@ -400,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' } };
@@ -473,7 +512,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
 
   // studio.json keeps what is safe to commit: names, ids, the custom domain; never the workers.dev address.
   const { url: _url, deployedAt: _at, ...kept } = cf;
-  const next = { ...kept, ...(cf.url && !isWorkersDev(cf.url) ? { url: cf.url } : {}), accountId, d1Id: db.uuid, r2: cf.r2 ?? null, created: [...created].sort() };
+  const next = { ...kept, ...(cf.url && !isWorkersDev(cf.url) ? { url: cf.url } : {}), accountId, d1Id: db.uuid, r2: cf.r2 ?? null, created: [...new Set([...created,...(readStudio(root).cloudflare.created??[])])].sort() };
   writeStudio(root, { ...readStudio(root), cloudflare: next });
   return {
     ok: true, command: 'deploy', url, mcp: url ? `${url}/mcp` : null, connectAI: url ? `${url}/_studio/office/connections` : null, ...(workersDev ? { workersDev, local: LOCAL_STATE } : {}), worker: cf.worker, d1: cf.d1, r2, account: accountId, announced, steps,
@@ -604,6 +643,7 @@ export async function ciDeploy(root, { log = () => {}, wrangler = null } = {}) {
   const refuse = (why, out) => ({ ok: false, command: 'deploy', ci: true, ...(explainCloudflare(out) ?? { why }), steps });
   if (!existsSync(join(root, 'site', 'dist', 'games.json'))) return { ok: false, command: 'deploy', ci: true, why: 'nothing is built: the build command is `npm run build` (homie-studio build), and it runs before this', steps };
   for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
+  try {await ensureBackgroundQueues(root,w);} catch(error) {return refuse(error.message);}
   const apply = () => w(['d1', 'migrations', 'apply', names.binding, '--remote']);
   let migrate = apply();
   const first = migrate.code !== 0 && /not found|could(?:n't| not) find|does not exist|no database|database_id/i.test(migrate.out);
@@ -623,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');
@@ -633,6 +673,7 @@ export async function ciDeploy(root, { log = () => {}, wrangler = null } = {}) {
     step('D1 migrations applied (the database was created with this first deploy)');
     const registered=register();if(registered.code!==0)return refuse('Could not register studio functions',registered.out);
   }
+  try {const replication=await enableReadReplication(root,w);step(replication.enabled?'D1 read replication enabled':`D1 uses the primary: ${replication.reason}`);} catch(error) {step(`D1 uses the primary: ${error.message}`);}
   // The live address, from what Wrangler printed (a custom domain in studio.json wins).
   const workersDev = /https:\/\/[a-z0-9.-]+\.workers\.dev/i.exec(dep.out)?.[0] ?? null;
   let url = null;
@@ -668,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 });
@@ -703,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/read-replication.mjs

@@ -0,0 +1,26 @@
+import {cloudflareAuth} from './brain-probe.mjs';
+import {readConfig} from './routes.mjs';
+import {readStudio,workerDir} from './studio.mjs';
+import {join} from 'node:path';
+/** Enable replicas on this studio's database using the same login as deployment.
+ * A missing account/id (first Workers Builds provisioning) is retried next deploy.
+ * Auth failures are reported; the primary-first runtime remains consistent.
+ */
+export async function enableReadReplication(root, run, {accountId, databaseId, fetchFn=fetch}={}) {
+  const studio=readStudio(root);
+  accountId??=process.env.CLOUDFLARE_ACCOUNT_ID??studio.cloudflare?.accountId;
+  databaseId??=readConfig(root)?.d1_databases?.find(db=>db.binding==='DB')?.database_id;
+  if (!accountId || !databaseId) return {enabled:false,reason:'database provisioning has not supplied its account and id'};
+  if (process.env.HOMIE_STUDIO_WARM==='0') return {enabled:false,reason:'offline test'};
+  try {
+  const headers=await cloudflareAuth({bin:join(root,'node_modules/.bin/wrangler'),cwd:workerDir(root),exec:async(_bin,args)=>{const r=run(args);return {code:r.code,stdout:r.stdout??r.out};}});
+  if (!headers) return {enabled:false,reason:'Cloudflare authentication unavailable'};
+  const url=`https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/d1/database/${encodeURIComponent(databaseId)}`;
+  const response=await fetchFn(url,{method:'PATCH',headers:{...headers,'content-type':'application/json'},body:JSON.stringify({read_replication:{mode:'auto'}}),signal:AbortSignal.timeout(15000)});
+  const body=await response.json();
+  if(!response.ok||body.success===false||body.result?.read_replication?.mode!=='auto')throw new Error(`Could not enable D1 read replication (HTTP ${response.status}); the deployment login needs D1 Edit`);
+  return {enabled:true};
+  } catch (error) {
+    return {enabled:false,reason:`D1 uses the primary; read replication could not be enabled: ${error.message}`};
+  }
+}