@homie-rocks/studio 0.12.0 → 0.13.0

package/lib/office.mjs

@@ -0,0 +1,172 @@
+/**
+ * `homie-studio office` — the studio's back office from the studio folder (worker/office.mjs says what it is).
+ *
+ *   homie-studio office [--url <site>]                 every live room of every game and who is in it, now
+ *   homie-studio office link [--to <path>]             a one-time link that signs the owner's browser in (the office,
+ *                                                      or --to /<game>/play: a private game on the owner's phone)
+ *   homie-studio office key [--hours 1]                an office key for the Homie MCP's owner tools (studio_office,
+ *                                                      room_kick, room_announce, room_close, game_launch_state)
+ *   homie-studio office announce "<text>" [--game <id>] [--room <code>] [--seconds 30]
+ *   homie-studio office invite <game> [--label "<who>"] [--uses 1|<n>|any] [--count 1] [--days <n>]
+ *   homie-studio office launch <game> private|invite|public [--remixable on|off] [--max <n>|game]
+ *   homie-studio office kick <game> <room> <seat number | name> [--minutes 10]
+ *   homie-studio office close <game> <room> [--minutes 10] [--reopen]
+ *   homie-studio office revoke                         every office key ends; every play ticket and pending ask too
+ *
+ * THE PROOF OF OWNERSHIP IS THE STUDIO'S OWN CLOUDFLARE LOGIN, as for the stats: a key is minted here and only its
+ * SHA-256 goes into the studio's D1. Looking, announcing and inviting happen at once. Kick, mute, closing a room and
+ * a game's launch state, remix switch or room size are only ASKED for here: the answer is a one-time sign-in link
+ * that opens the ask in the owner's own browser, where one tap does it (the AI that ran this cannot).
+ */
+import { readStudio } from './studio.mjs';
+import { runner } from './cloudflare.mjs';
+import { drop, loopback, mint, siteOf } from './stats.mjs';
+
+const HOUR = 3600_000;
+const GAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
+
+/** Call the studio's office API with a key that lives ten minutes and is dropped as soon as the answer is in. */
+async function withKey(root, url, fn) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, why: 'this studio has no live site yet: `npm run deploy` first, or give --url http://127.0.0.1:8787 for `npm run dev`' };
+  const local = loopback(site);
+  const k = mint(root, studio, 'office', 10 * 60_000, { local });
+  if (!k.ok) return { ok: false, why: /no such table: stats_keys/.test(k.why) ? k.why : k.why };
+  try {
+    const call = async (path, body = null) => {
+      const res = await fetch(`${site}${path}`, {
+        method: body ? 'POST' : 'GET',
+        headers: { authorization: `Bearer ${k.key}`, accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) },
+        ...(body ? { body: JSON.stringify(body) } : {}), signal: AbortSignal.timeout(20_000),
+      });
+      const out = await res.json().catch(() => ({ ok: false, message: `${site}${path} answered ${res.status}` }));
+      return { status: res.status, ...out };
+    };
+    return await fn(call, { studio, site, local });
+  } catch (error) {
+    return { ok: false, why: `could not reach ${site}: ${error.message}` };
+  } finally { drop(root, studio, k.hash, { local }); }
+}
+
+/** A one-time sign-in link for the owner's browser that lands on `to` (30 minutes). */
+function signinTo(root, url, to) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, why: 'this studio has no live site yet: `npm run deploy` first' };
+  const k = mint(root, studio, 'signin', 30 * 60_000, { local: loopback(site) });
+  if (!k.ok) return k;
+  return { ok: true, site, link: `${site}/_studio/signin?k=${k.key}${to && to !== '/_studio/stats' ? `&to=${encodeURIComponent(to)}` : ''}`, expiresAt: k.expiresAt };
+}
+
+const askedFor = (root, url, r, command) => {
+  if (!r.ok) return { ok: false, command, why: r.message ?? r.why ?? `the studio said ${r.error ?? r.status}` };
+  if (r.needs !== 'owner' || !r.ask) return { ok: true, command, done: true, result: r, message: r.what ? `Done: ${r.what}` : 'Done.' };
+  const link = signinTo(root, url, `/_studio/confirm/${r.ask.id}`);
+  return {
+    ok: true, command, asked: true, ask: r.ask, what: r.ask.what,
+    link: link.ok ? link.link : r.ask.confirm,
+    use: `Waiting for the owner: ${r.ask.what} Give the owner this link to open in their own browser: it signs that browser in (once, within 30 minutes) and shows the ask with one button. It lasts 15 minutes; nothing happens unless the owner taps.`,
+  };
+};
+
+export async function officeShow(root, { url } = {}) {
+  const r = await withKey(root, url, (call) => call('/_studio/api/office'));
+  if (!r.ok) return { ok: false, command: 'office', why: r.why ?? r.message ?? 'the office did not answer' };
+  return { command: 'office', ...r, ok: true };
+}
+
+export function officeLink(root, { url, to } = {}) {
+  const target = to && /^\/[A-Za-z0-9_/-]{1,80}$/.test(String(to)) ? String(to) : '/_studio/office';
+  const r = signinTo(root, url, target);
+  if (!r.ok) return { ok: false, command: 'office link', why: r.why };
+  return {
+    ...r, command: 'office link', to: target,
+    use: 'Give this link to the studio\'s owner to open in their own browser: it works once, within 30 minutes, and keeps that browser signed in as the owner for 30 days (the office, the stats, and the owner\'s tools inside their own games). It is theirs alone; do not post it anywhere.',
+  };
+}
+
+export function officeKey(root, { url, hours } = {}) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, command: 'office key', why: 'this studio has no live site yet: `npm run deploy` first' };
+  const h = Math.max(1, Math.min(24 * 30, Math.floor(Number(hours) || 1)));
+  const k = mint(root, studio, 'office', h * HOUR, { local: loopback(site) });
+  if (!k.ok) return { ok: false, command: 'office key', why: k.why };
+  return {
+    ok: true, command: 'office key', site, key: k.key, expiresAt: k.expiresAt, hours: h,
+    use: `Pass { "site": "${site}", "key": "<this key>" } to the Homie MCP's owner tools (studio_office, room_announce, room_kick, room_close, game_launch_state). With it the AI sees the live rooms, announces and makes invites; a kick, a closed room or a launch state change is only asked for, and the owner confirms it with one tap. It also reads the stats (studio_stats). It ends at ${k.expiresAt}; \`homie-studio office revoke\` ends it sooner. Never paste it anywhere else.`,
+  };
+}
+
+export async function officeAnnounce(root, text, { url, game, room, seconds } = {}) {
+  if (!String(text ?? '').trim()) return { ok: false, command: 'office announce', why: 'usage: homie-studio office announce "<text>" [--game <id>] [--room <code>]' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/announce', { text, ...(game ? { game } : {}), ...(room ? { room } : {}), ...(seconds ? { seconds: Number(seconds) } : {}) }));
+  return r.ok ? { ok: true, command: 'office announce', ...r, message: `Announced to ${r.people ?? 0} people in ${r.rooms ?? 0} room(s).` } : { ok: false, command: 'office announce', why: r.message ?? r.why };
+}
+
+export async function officeInvite(root, game, { url, label, uses, count, days } = {}) {
+  if (!GAME.test(String(game ?? ''))) return { ok: false, command: 'office invite', why: 'usage: homie-studio office invite <game> [--label "<who>"] [--uses 1|<n>|any] [--count 1]' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/invites', {
+    game, ...(label ? { label } : {}), uses: uses === 'any' ? 'any' : uses ? Number(uses) : 1, ...(count ? { count: Number(count) } : {}), ...(days ? { days: Number(days) } : {}),
+  }));
+  if (!r.ok) return { ok: false, command: 'office invite', why: r.message ?? r.why };
+  return { ok: true, command: 'office invite', game, launch: r.launch, invites: r.invites, note: r.launch === 'invite' ? null : `${game} is ${r.launch} now: invites let people in once it is an invite-only beta (homie-studio office launch ${game} invite).` };
+}
+
+export async function officeLaunch(root, game, state, { url, remixable, max } = {}) {
+  if (!GAME.test(String(game ?? '')) || (state !== undefined && state !== null && !['private', 'invite', 'public'].includes(state))) {
+    return { ok: false, command: 'office launch', why: 'usage: homie-studio office launch <game> private|invite|public [--remixable on|off] [--max <n>|game]' };
+  }
+  const body = { game, ...(state ? { launch: state } : {}), ...(remixable !== undefined ? { remix: remixable === 'on' || remixable === true } : {}), ...(max !== undefined ? { maxPlayers: max === 'game' ? null : Number(max) } : {}) };
+  const r = await withKey(root, url, (call) => call('/_studio/api/game', body));
+  return askedFor(root, url, r, 'office launch');
+}
+
+export async function officeKick(root, game, room, who, { url, minutes } = {}) {
+  if (!GAME.test(String(game ?? '')) || !room || who === undefined) return { ok: false, command: 'office kick', why: 'usage: homie-studio office kick <game> <room> <seat number | name> [--minutes 10]' };
+  const r = await withKey(root, url, async (call) => {
+    const office = await call('/_studio/api/office');
+    const g = (office.games ?? []).find((x) => x.id === game);
+    const rm = (g?.rooms ?? []).find((x) => x.room === room || x.label.toLowerCase() === String(room).toLowerCase());
+    if (!rm) return { ok: false, message: `nobody is in ${room} of ${game} now (homie-studio office lists the rooms)` };
+    const seat = /^\d+$/.test(String(who)) ? Number(who) - 1 : null;
+    const c = rm.clients.find((x) => (seat !== null && x.seat === seat) || String(x.name).toLowerCase() === String(who).toLowerCase());
+    if (!c) return { ok: false, message: `no "${who}" in ${rm.label} (seats are numbered from 1)` };
+    return call('/_studio/api/kick', { game, room: rm.room, id: c.id, minutes: Number(minutes) || 10 });
+  });
+  return askedFor(root, url, r, 'office kick');
+}
+
+export async function officeClose(root, game, room, { url, minutes, reopen } = {}) {
+  if (!GAME.test(String(game ?? '')) || !room) return { ok: false, command: 'office close', why: 'usage: homie-studio office close <game> <room> [--minutes 10] [--reopen]' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/close', { game, room, minutes: Number(minutes) || 10, reopen: Boolean(reopen) }));
+  return askedFor(root, url, r, 'office close');
+}
+
+/** Every office key ends, and the office secret is made anew: every play ticket and every signed control ends with it. */
+export function officeRevoke(root, { url } = {}) {
+  const { studio, site } = siteOf(root, url);
+  const local = site ? loopback(site) : false;
+  const w = runner(root, studio.cloudflare?.accountId && !local ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
+  const res = w(['d1', 'execute', studio.cloudflare.d1, local ? '--local' : '--remote', '--command', "DELETE FROM stats_keys WHERE kind = 'office'; DELETE FROM meta WHERE key = 'office_key'; UPDATE office_asks SET state = 'expired' WHERE state = 'pending';"]);
+  return res.code === 0
+    ? { ok: true, command: 'office revoke', site, message: 'Every office key has ended, and every play ticket and pending ask with it (a browser let into a private or invite-only game gets a new ticket the next time it opens the game). Invite passes and the owner\'s signed-in browsers stay; `homie-studio stats revoke` ends those sessions.' }
+    : { ok: false, command: 'office revoke', why: res.out.trim().split('\n').slice(-3).join(' ') };
+}
+
+/** One line per room for a person (the CLI's print). */
+export function officeLines(r) {
+  const lines = [`${r.studio}: ${r.playing ? `${r.playing} playing now` : 'nobody playing right now'} (${r.site})`];
+  const now = r.now ?? Date.now();
+  const mins = (ms) => `${Math.max(0, Math.round(ms / 60000))} min`;
+  for (const g of r.games ?? []) {
+    lines.push(`  ${g.name} (${g.id}): ${g.launch}${g.launch === 'public' ? '' : ' (not listed)'}, ${g.remix ? 'remixable' : 'source closed'}, rooms of ${g.maxPlayers}${g.maxSet ? ` (the game's own: ${g.seats})` : ''}`);
+    for (const i of (g.invites ?? []).filter((x) => x.open)) lines.push(`    invite ${i.code}${i.label ? ` (${i.label})` : ''}: ${i.uses}${i.maxUses ? ` of ${i.maxUses}` : ''} used · ${i.link}`);
+    if (!g.rooms.length) lines.push('    no live rooms');
+    for (const rm of g.rooms) {
+      const round = rm.round ? `round ${rm.round.n} ${rm.round.phase}` : 'no round';
+      lines.push(`    ${rm.label}${rm.public ? '' : ' (named)'}: ${rm.players}/${rm.max} players, ${rm.bots} bots, ${round}, up ${rm.openedAt ? mins(now - rm.openedAt) : '?'}${rm.closedUntil ? `, CLOSED for ${mins(rm.closedUntil - now)}` : ''}`);
+      for (const c of rm.clients) lines.push(`      ${c.seat !== null ? `seat ${c.seat + 1}` : 'watching'}: ${c.name} · ${c.device}${c.role === 'host' ? ' · host' : ''} · ${c.as}${c.muted ? ' · muted' : ''} · here ${mins(now - c.joinedAt)}`);
+      for (const b of rm.bans ?? []) lines.push(`      kicked: ${b.name} (back in ${mins(b.until - now)})`);
+    }
+  }
+  return lines;
+}

package/lib/progress.mjs

@@ -57,6 +57,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, sta
 import { extname, join } from 'node:path';
 import { refreshCodexFile } from './codex.mjs';
 import { readStudio, siteUrl } from './studio.mjs';
+import { request, whyRefused } from './net.mjs';
 
 export const PROGRESS_KIND = 'homie-studio-progress';
 export const PROGRESS_DIR = join('.studio', 'progress');
@@ -89,19 +90,10 @@ const keyPath = (root, id) => join(dir(root), `${id}.key`);
 const currentPath = (root) => join(dir(root), 'current');
 const loopback = (url) => { try { return ['127.0.0.1', 'localhost', '[::1]'].includes(new URL(url).hostname); } catch { return false; } };
 
-/*
- * A CLAUDE CODE CLOUD SESSION WHOSE NETWORK BLOCKS THE DIRECTORY. The default "Trusted" network reached homie.rocks
- * in a real cloud session (2026-10-01); a stricter one makes the session's proxy answer 403 with
- * `x-deny-reason: host_not_allowed`. Then, and only then, say which setting lets the card follow the build,
- * instead of "did not answer"; the build itself goes on with its local feed.
- */
+/** Kept for callers of 0.11.0: whether an answer is the proxy refusing the host (lib/net.mjs says the rest). */
 export function networkWhy(res, at) {
-  if (res?.status === 403 && /host_not_allowed/i.test(res.headers?.get?.('x-deny-reason') ?? '')) {
-    let host = at;
-    try { host = new URL(at).host; } catch { /* as given */ }
-    return `this Claude Code cloud environment's network does not reach ${host}. In claude.ai/code, open the environment's settings, set Network access to Custom, add ${host} (keep "Also include default list of common package managers"), and start a new session; until then the build goes on with its local feed only`;
-  }
-  return null;
+  const r = whyRefused(res, null, '', at);
+  return r.needs === 'network' ? r.why : null;
 }
 
 /** The studio's live address for the card: an https origin (or this computer's own dev site), else null. */
@@ -154,23 +146,24 @@ async function pushDoc(root, id) {
   let key = null;
   try { key = readFileSync(keyPath(root, id), 'utf8').trim(); } catch { return null; }
   const { shared, ...body } = doc;
-  const res = await fetch(`${shared.directory}/api/studio/progress/${shared.build}`, {
+  const sent = await request(`${shared.directory}/api/studio/progress/${shared.build}`, {
     method: 'PUT',
     headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json', 'user-agent': 'homie-studio' },
     body: JSON.stringify({ ...body, build: shared.build }),
-    signal: AbortSignal.timeout(8000),
-  });
-  const blocked = networkWhy(res, shared.directory);
-  if (blocked) {
-    mutateDoc(root, id, (d) => { d.shared = { ...d.shared, ended: true }; pushLog(d, `The Claude app cannot follow this build: ${blocked}`); });
-    return null;
-  }
-  if (res.status === 404 || res.status === 410) {
-    // The shared copy ended (24 hours, or the directory dropped it): keep the local feed, stop sending.
-    mutateDoc(root, id, (d) => { d.shared = { ...d.shared, ended: true }; });
+  }, { timeout: 8000 });
+  if (!sent.ok) {
+    if (sent.status === 404 || sent.status === 410 || sent.needs === 'network') {
+      // The shared copy ended (24 hours, or the directory dropped it), or the proxy refuses the directory: keep the
+      // local feed, stop sending, and say why in its log.
+      mutateDoc(root, id, (d) => { d.shared = { ...d.shared, ended: true }; pushLog(d, `The Claude app's card stopped following this build: ${sent.why}`); });
+      return null;
+    }
+    // Anything else (a slow answer, a refused write): the next write tries again; the log keeps what happened once.
+    mutateDoc(root, id, (d) => { if (d.shared && d.shared.lastError !== sent.why) { d.shared = { ...d.shared, lastError: sent.why }; pushLog(d, `Sending to the card failed: ${sent.why}`); } });
     return null;
   }
-  const reply = await res.json().catch(() => null);
+  const reply = sent.body;
+  if (readFeed(root, id)?.shared?.lastError) mutateDoc(root, id, (d) => { delete d.shared.lastError; });
   if (reply?.stop) {
     mutateDoc(root, id, (d) => {
       if (!d.stop?.requested) { d.stop = { requested: true, at: now(), by: 'person' }; pushLog(d, 'Stop pressed in the Claude app; stopping at the next safe point.'); }
@@ -468,36 +461,38 @@ export async function startProgress(root, { what = 'game', id, title, budget, un
   writeAtomic(currentPath(root), `${build}\n`);
   let shared = null;
   let why = null;
+  let failure = {};
   if (share) {
     const at = String(directory || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
     if (!/^https:\/\//.test(at) && !(/^http:\/\//.test(at) && loopback(at))) why = `the directory ${at} is not https`;
     else {
-      try {
-        // A build the chat opened is attached (once); otherwise a new one is opened here.
-        const res = await fetch(attach ? `${at}/api/studio/progress/${attach}/attach` : `${at}/api/studio/progress`, {
-          method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': 'homie-studio' },
-          body: JSON.stringify({ what, id: id ?? null, title: doc.title, studio: doc.studio }), signal: AbortSignal.timeout(10_000),
-        });
-        const body = await res.json().catch(() => null);
-        if (!res.ok && networkWhy(res, at)) why = networkWhy(res, at);
-        else if (res.ok && body?.ok && REMOTE_ID.test(String(body.build)) && /^hbk_[a-f0-9]{48}$/.test(String(body.key))) {
-          // The chat named the build: its title is the one the person saw.
-          if (attach && body.title && !title) mutateDoc(root, build, (d) => { d.title = plain(body.title, LIMITS.title); });
-          writeFileSync(keyPath(root, build), `${body.key}\n`, { mode: 0o600 });
-          try { chmodSync(keyPath(root, build), 0o600); } catch { /* not on this filesystem */ }
-          shared = { build: body.build, directory: at, expiresAt: body.expiresAt ?? null };
-          mutateDoc(root, build, (d) => { d.shared = { build: body.build, directory: at }; });
-          schedule(root, build, { soon: true });
-          heartbeat(root, build, true);
-        } else why = body?.message ?? `${at} answered ${res.status}`;
-      } catch (error) { why = `${at} did not answer (${error?.message ?? error})`; }
+      // A build the chat opened is attached (once); otherwise a new one is opened here.
+      const sent = await request(attach ? `${at}/api/studio/progress/${attach}/attach` : `${at}/api/studio/progress`, {
+        method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': 'homie-studio' },
+        body: JSON.stringify({ what, id: id ?? null, title: doc.title, studio: doc.studio }),
+      });
+      const body = sent.body;
+      if (sent.ok && REMOTE_ID.test(String(body?.build)) && /^hbk_[a-f0-9]{48}$/.test(String(body?.key))) {
+        // The chat named the build: its title is the one the person saw.
+        if (attach && body.title && !title) mutateDoc(root, build, (d) => { d.title = plain(body.title, LIMITS.title); });
+        writeFileSync(keyPath(root, build), `${body.key}\n`, { mode: 0o600 });
+        try { chmodSync(keyPath(root, build), 0o600); } catch { /* not on this filesystem */ }
+        shared = { build: body.build, directory: at, expiresAt: body.expiresAt ?? null };
+        mutateDoc(root, build, (d) => { d.shared = { build: body.build, directory: at }; });
+        schedule(root, build, { soon: true });
+        heartbeat(root, build, true);
+      } else {
+        // As it is: the directory's own answer (its status and message) or the connection's error, never a guess.
+        why = sent.ok ? `${at} answered without a build and key` : sent.why;
+        failure = { ...(sent.status ? { status: sent.status } : {}), ...(sent.code ? { code: sent.code } : {}), ...(sent.needs ? { needs: sent.needs } : {}) };
+      }
     }
   }
   if (attach && !shared) {
     // Attaching is the point of `progress attach`: without it, say why and leave no open feed behind.
     rmSync(docPath(root, build), { force: true });
     rmSync(currentPath(root), { force: true });
-    return { ok: false, command: 'progress attach', build: attach, why: `could not attach to ${attach}: ${why}` };
+    return { ok: false, command: 'progress attach', build: attach, ...failure, why: `could not attach to ${attach}: ${why}` };
   }
   return {
     ok: true, command: attach ? 'progress attach' : 'progress start', build, file: join(PROGRESS_DIR, `${build}.json`), what, id: id ?? null, title: readFeed(root, build)?.title ?? doc.title,

package/lib/repo.mjs

@@ -0,0 +1,51 @@
+/**
+ * WHICH GITHUB REPOSITORY THIS STUDIO IS. The Claude app's hand-off opens Claude Code on it, so it must be the
+ * studio's own: never the engine and template repository (homie-rocks/homie) that Cloudflare's "Deploy to
+ * Cloudflare" copied the studio from, and never a guess.
+ *
+ * In order:
+ *   1. HOMIE_REPO, a build variable naming it;
+ *   2. studio.json `github` (`setup attach` writes it, and the person may);
+ *   3. the checkout's git remotes, origin first. A Workers Builds checkout, a Claude Code cloud session (its remote
+ *      goes through the session's own git proxy) and a person's clone all carry one. Only owner/name is kept,
+ *      never a token in the URL.
+ *
+ * A deploy hands it to the live Worker as a variable (HOMIE_REPO), never into a public file. The Worker tells its
+ * directory alongside its claim, so the setup card can open the right repository.
+ */
+import { spawnSync } from 'node:child_process';
+import { readStudio } from './studio.mjs';
+
+export const REPO = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9._-]{1,100}$/;
+/** The engine and template repository: a studio is never this. */
+export const ENGINE_REPO = 'homie-rocks/homie';
+
+/** owner/name in a git remote URL (https, ssh, a proxy's /git/owner/name path), without any credentials; or null. */
+export function repoFromUrl(url) {
+  const s = String(url ?? '').trim().replace(/\.git$/, '').replace(/\/+$/, '');
+  if (!s) return null;
+  const m = /[/:]([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9._-]{1,100})$/.exec(s);
+  return m ? studioRepo(`${m[1]}/${m[2]}`) : null;
+}
+
+/** A studio repository slug, or null (not a slug, or the engine repository). */
+export function studioRepo(value) {
+  const r = String(value ?? '').trim();
+  return REPO.test(r) && r.toLowerCase() !== ENGINE_REPO ? r : null;
+}
+
+/** This studio's repository: HOMIE_REPO, studio.json `github`, else its git remotes (origin first). */
+export function repoOf(root, { env = process.env } = {}) {
+  const named = studioRepo(env.HOMIE_REPO);
+  if (named) return named;
+  try { const s = studioRepo(readStudio(root).github); if (s) return s; } catch { /* no studio.json */ }
+  const git = (args) => spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: 5000 });
+  const origin = git(['remote', 'get-url', 'origin']);
+  if (origin.status === 0) { const r = repoFromUrl(origin.stdout); if (r) return r; }
+  const all = git(['config', '--get-regexp', '^remote\\..*\\.url$']);
+  for (const line of (all.status === 0 ? all.stdout : '').split('\n')) {
+    const r = repoFromUrl(line.split(/\s+/)[1]);
+    if (r) return r;
+  }
+  return null;
+}

package/lib/scaffold.mjs

@@ -25,6 +25,7 @@ import { dirname, join, relative, resolve } from 'node:path';
 import { STUDIO_VERSION, packageSpec } from './version.mjs';
 import { STATS_MIGRATION, STATS_MIGRATION_FILE } from '../worker/stats.mjs';
 import { PLAYERS_MIGRATION, PLAYERS_MIGRATION_FILE } from '../worker/players.mjs';
+import { OFFICE_MIGRATION, OFFICE_MIGRATION_FILE } from '../worker/office-schema.mjs';
 import { themeFile } from './site.mjs';
 import { PACKAGE_ROOT } from './studio.mjs';
 
@@ -222,6 +223,28 @@ studio's pinned copy, never a registry lookup of the bare name.
   Cloudflare, Chrome, ffmpeg, GitHub, ElevenLabs, fal), what each unlocks, and the exact fix. Optional ones never
   block anything.
 
+## Running live games (the back office)
+
+- The owner runs the studio's live games from \`/_studio/office\` (\`npx --no-install homie-studio office link\` gives
+  the owner a one-time sign-in link): every live room of every game, who is in it (handles; accounts once players
+  sign in), bots, the round and uptime, refreshing by itself; Kick (that player cannot come back to that room for
+  the minutes chosen), Mute (their chat and emotes reach nobody), Announce (one line every player sees), Close a
+  room; and per game: launch state, Remixable, players per room and invites.
+- **Launch states:** \`private\` (only the owner, signed in; \`office link --to /<id>/play\` signs the owner's phone
+  in), \`invite\` (an invite-only beta: \`office invite <id>\` makes invite links and codes, each for one browser or
+  as many as \`--uses\` says), \`public\` (the default; listed). A game that is not public is in no list and not in
+  the directory manifest, so the directory drops it the next time it reads the studio. A new game stays private
+  from its first deploy with \`"launch": "private"\` in its game.json. **Remixable** publishes or withdraws its source.
+- The owner is recognised in their own games: signed in, their play page has a small Owner button (tap a player:
+  Mute, Kick; Announce). Nobody else's page has it.
+- **From the AI:** \`npx --no-install homie-studio office\` lists who is playing now; \`office announce "<text>"\` and
+  \`office invite <id>\` happen at once; \`office kick\`, \`office close\` and \`office launch\` only ASK, and print a
+  one-time link that opens the ask in the owner's own browser, where one tap does it. An ask is not done until the
+  owner tapped. \`office key\` gives a key for the Homie MCP's owner tools (\`studio_office\`, \`room_announce\`,
+  \`room_kick\`, \`room_close\`, \`game_launch_state\`), which ask the same way; never paste a key anywhere else.
+- A game can listen (\`NETPLAY.md\` section 15): \`net.on('announce', …)\`, \`net.isMuted(seat)\` to hide a muted
+  player's chat, and \`net.pickPlayer(seat)\` when a player is clicked (the owner's page opens their card).
+
 ## Rules
 
 - Keys stay in the providers' own logins (Wrangler, ElevenLabs, fal) or the OS
@@ -397,6 +420,7 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
     'site/migrations/0001_studio.sql': MIGRATION,
     [`site/migrations/${STATS_MIGRATION_FILE}`]: STATS_MIGRATION,
     [`site/migrations/${PLAYERS_MIGRATION_FILE}`]: PLAYERS_MIGRATION,
+    [`site/migrations/${OFFICE_MIGRATION_FILE}`]: OFFICE_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
   };
@@ -466,6 +490,18 @@ export function ensureStatsMigration(root) {
   return `site/migrations/${STATS_MIGRATION_FILE}`;
 }
 
+/**
+ * A studio made before 0.13.0 has no back-office migration (worker/office.mjs): add it, so the next
+ * `d1 migrations apply` makes its tables. Returns the file it wrote, or null when it was there.
+ */
+export function ensureOfficeMigration(root) {
+  const file = join(root, 'site', 'migrations', OFFICE_MIGRATION_FILE);
+  if (existsSync(file)) return null;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, OFFICE_MIGRATION);
+  return `site/migrations/${OFFICE_MIGRATION_FILE}`;
+}
+
 /**
  * A studio made before 0.12.0 has no players migration (player accounts and cloud saves, saves/SAVES.md): add it,
  * so the next `d1 migrations apply` makes the tables. Returns the file it wrote, or null when it was there.
@@ -480,7 +516,12 @@ export function ensurePlayersMigration(root) {
 
 /** Every migration the template owns that this studio lacks, added: the files written (deploy and dev say so). */
 export function ensureMigrations(root) {
-  return [ensureStatsMigration(root), ensurePlayersMigration(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root)].filter(Boolean);
+}
+
+/** What a migration file the template added is for, in a few words (deploy and dev say it). */
+export function migrationWord(file) {
+  return /players/.test(file) ? 'player accounts and cloud saves' : /office/.test(file) ? 'the back office: launch states, invites, the owner\'s controls' : 'the studio\'s own stats: counts, never tracks';
 }
 
 /**

package/lib/setup.mjs

@@ -13,43 +13,32 @@
  * A setup id is single use per repository: a second attach from the same repository answers the same; another
  * repository is refused.
  */
-import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { configNames } from './cloudflare.mjs';
-import { networkWhy } from './progress.mjs';
+import { request } from './net.mjs';
+import { ENGINE_REPO, repoOf } from './repo.mjs';
 import { CONNECT_BAND, agentsMd, readme, slugify, templateReadme } from './scaffold.mjs';
 import { configPath, readStudio, writeLocal, writeStudio } from './studio.mjs';
 import { STUDIO_VERSION } from './version.mjs';
 
 const SETUP_ID = /^hs_[a-f0-9]{32}$/;
 
-/** owner/repo of this checkout's GitHub remote (a Claude Code cloud session's remote goes through its own proxy). */
-export function repoOf(root) {
-  const r = spawnSync('git', ['remote', 'get-url', 'origin'], { cwd: root, encoding: 'utf8', timeout: 5000 });
-  if (r.status !== 0) return null;
-  const url = r.stdout.trim().replace(/\.git$/, '').replace(/\/+$/, '');
-  const m = /[/:]([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9._-]{1,100})$/.exec(url);
-  return m ? `${m[1]}/${m[2]}` : null;
-}
-
 export async function setupAttach(root, id, { homie } = {}) {
   if (!SETUP_ID.test(String(id ?? ''))) return { ok: false, command: 'setup attach', why: 'attach to the setup id the Claude app\'s setup card showed: hs_ and 32 hex digits' };
   const studio = readStudio(root);
   const directory = String(homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
   const repo = repoOf(root);
-  let res; let body = null;
-  try {
-    res = await fetch(`${directory}/api/studio/setup/${id}/attach`, {
-      method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': `homie-studio/${STUDIO_VERSION}` },
-      body: JSON.stringify({ repo, studio: { name: studio.name, slug: studio.slug, template: studio.template === true }, version: STUDIO_VERSION }),
-      signal: AbortSignal.timeout(10_000),
-    });
-    body = await res.json().catch(() => null);
-  } catch (error) { return { ok: false, command: 'setup attach', why: `${directory} did not answer (${error?.message ?? error})` }; }
-  const blocked = networkWhy(res, directory);
-  if (blocked) return { ok: false, command: 'setup attach', needs: 'network', why: blocked };
-  if (!res.ok || !body?.ok) return { ok: false, command: 'setup attach', why: body?.message ?? `${directory} answered ${res.status}` };
+  if (!repo) {
+    return { ok: false, command: 'setup attach', needs: 'repository', why: `this checkout names no GitHub repository of its own (its git remote is missing, or is ${ENGINE_REPO}, Homie's engine and template, which a studio never is). Run this in the studio's own repository, the one Cloudflare's Deploy to Cloudflare made, or name it in studio.json as "github": "<owner>/<name>"` };
+  }
+  const sent = await request(`${directory}/api/studio/setup/${id}/attach`, {
+    method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': `homie-studio/${STUDIO_VERSION}` },
+    body: JSON.stringify({ repo, studio: { name: studio.name, slug: studio.slug, template: studio.template === true }, version: STUDIO_VERSION }),
+  });
+  // What went wrong, as it is: the directory's own answer, or the connection's error. Never a guess at the network.
+  if (!sent.ok) return { ok: false, command: 'setup attach', repo, ...(sent.status ? { status: sent.status } : {}), ...(sent.code ? { code: sent.code } : {}), ...(sent.needs ? { needs: sent.needs } : {}), why: sent.why };
+  const body = sent.body;
 
   const renamed = [];
   const name = typeof body.name === 'string' && body.name.trim() ? body.name.trim().slice(0, 60) : null;
@@ -78,6 +67,9 @@ export async function setupAttach(root, id, { homie } = {}) {
     const band = join(root, 'site', 'partials', 'home.html');
     if (existsSync(band) && readFileSync(band, 'utf8') === CONNECT_BAND) { rmSync(band); renamed.push('site/partials/home.html (removed)'); }
   }
+  // The repository goes into studio.json, so the next deploy (and Workers Builds) tells the live Worker which it is.
+  const now = readStudio(root);
+  if (now.github !== repo) { writeStudio(root, { ...now, github: repo }); if (!renamed.includes('studio.json')) renamed.push('studio.json'); }
   if (body.site) writeLocal(root, { url: body.site, connectedAt: new Date().toISOString() });
   return {
     ok: true, command: 'setup attach', setup: id, repo, site: body.site ?? null, name: name ?? studio.name, renamed,

package/lib/stats.mjs

@@ -48,7 +48,7 @@ export function mint(root, studio, kind, ttlMs, { local }) {
   return { ok: true, key, hash, expiresAt: new Date(now + ttlMs).toISOString() };
 }
 
-function drop(root, studio, hash, { local }) {
+export function drop(root, studio, hash, { local }) {
   const w = runner(root, studio.cloudflare?.accountId && !local ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
   w(['d1', 'execute', studio.cloudflare.d1, local ? '--local' : '--remote', '--command', `DELETE FROM stats_keys WHERE hash = '${hash}';`]);
 }

package/lib/template-history.json

@@ -223,6 +223,55 @@
      "## Beta": "9d02638207a26e73"
     }
    }
+  },
+  "0.12.1": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "games/README.md": "5e5e942baa7e0372",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "f14d641159480e6c",
+     "## Commands (all through the pinned CLI in node_modules)": "3a3d3bef7e8d1a50",
+     "## The site": "7d3525ba39b7f262",
+     "## Making games": "63069b31c87a2aa2",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
+  },
+  "0.13.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "games/README.md": "5e5e942baa7e0372",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "f14d641159480e6c",
+     "## Commands (all through the pinned CLI in node_modules)": "3a3d3bef7e8d1a50",
+     "## The site": "7d3525ba39b7f262",
+     "## Making games": "63069b31c87a2aa2",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Running live games (the back office)": "f0566f07cff04113",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
   }
  }
 }

package/lib/upgrade.mjs

@@ -170,11 +170,14 @@ export function upgradePlan(root, { history = readHistory() } = {}) {
     }
     const have = sections(mine);
     const tsecs = sections(want);
+    const adding = new Set();
     for (const [k, t] of tsecs.entries()) {
       const at = have.find((s) => s.heading === t.heading);
       if (!at) {
-        // After the nearest template section before it that the studio has; else before the first one after it.
-        const before = tsecs.slice(0, k).reverse().find((p) => have.some((s) => s.heading === p.heading));
+        // After the nearest template section before it that the studio has (or that this plan adds just before it, so
+        // two new sections in a row keep the template's order); else before the first one after it.
+        const before = tsecs.slice(0, k).reverse().find((p) => have.some((s) => s.heading === p.heading) || adding.has(p.heading));
+        adding.add(t.heading);
         const after = before ? null : tsecs.slice(k + 1).find((p) => have.some((s) => s.heading === p.heading));
         changes.push({ file: rel, kind: 'add-section', section: t.heading, what: `new section ${t.heading === INTRO ? 'intro' : `"${t.heading}"`}`, after: before?.heading ?? null, before: after?.heading ?? null, text: t.text });
         continue;