@homie-rocks/studio 0.11.0 → 0.12.1

package/README.md

@@ -72,8 +72,8 @@ site. A game made with Homie's arcade controls that knocks for a Homie box (`/__
 A studio pins one version, so nothing changes until it asks. To take a newer one:
 
 ```sh
-npx -y @homie-rocks/studio@0.11.0 upgrade          # the plan; changes nothing
-npx -y @homie-rocks/studio@0.11.0 upgrade --apply  # after the person agrees
+npx -y @homie-rocks/studio@0.12.1 upgrade          # the plan; changes nothing
+npx -y @homie-rocks/studio@0.12.1 upgrade --apply  # after the person agrees
 npm install && npm run build
 ```
 
@@ -94,6 +94,32 @@ Bots, a late joiner taking a bot's body and a new host after the old one leaves
 the same at 32 as at 4. One address may hold every seat plus four sockets, so a party
 on one Wi-Fi (or strangers behind one carrier's address) fills a room with a TV beside it.
 
+## Player accounts and cloud saves
+
+A game whose progress must last (a character that levels up for days, unlocks, a collection, a hardcore mode)
+keeps it in **saves**, not in its room: a room forgets everything 60 s after its last player leaves.
+
+```json
+{ "id": "my-rpg", "saves": true }
+```
+
+```ts
+import { createSaves } from '@homie-rocks/studio/saves';
+const saves = createSaves({ game: 'my-rpg' });
+const hero = (await saves.get('hero')) ?? newHero();
+await saves.set('hero', hero);                       // on this device at once, in the studio's D1 when online
+saves.stats.add({ kills: 1 });                       // lifetime numbers that outlive any hero
+await saves.fall({ character: hero.name, summary: { level: hero.level }, wipe: true });   // hardcore
+```
+
+Pressing Play needs no account. A player who saves something is a guest on that browser; with a **passkey**
+(Face ID, a fingerprint, a PIN, no password, no email) it becomes an account on this studio only, and the same
+saves follow them to every device they sign in on. Saves are per player and game, versioned (a stale offline
+copy is a conflict, never an overwrite), capped in size, and offline-tolerant. Players see, download and delete
+everything at `/account/`; the owner sees counts (`homie-studio players`) and, through the back office, names,
+never a passkey or an email. The `ember-vale` starter is a small persistent-character game on the same public
+rooms. Everything, including what is stored and the back office's API: [saves/SAVES.md](saves/SAVES.md).
+
 ## The studio's own stats
 
 The site counts, and never tracks: pages opened, Play presses, rooms opened, the most
@@ -116,7 +142,7 @@ studio's own Cloudflare login. `worker/stats.mjs` says exactly what is counted.
 ## Setup status
 
 ```sh
-npx -y @homie-rocks/studio@0.11.0 setup status --connector yes   # before a studio exists
+npx -y @homie-rocks/studio@0.12.1 setup status --connector yes   # before a studio exists
 npx homie-studio setup status                                    # in a studio (also: homie-studio doctor)
 ```
 
@@ -205,9 +231,27 @@ Workers Builds deploys the branch as a Preview; the card's **Publish** opens the
 person's merge is the approval; Workers Builds deploys `main`, and the card says **Live** when the live site's
 manifest lists the change's mark (`homie-studio build` lists the newest marks from `changes/`).
 
-A Claude Code cloud session's default network ("Trusted") does not reach homie.rocks; the toolkit says so, and
-names the setting (the environment's Network access: Custom, add homie.rocks), instead of "did not answer". The
-build goes on with its local feed.
+A Claude Code cloud session sends all its traffic through a proxy (`HTTPS_PROXY`). curl, npm and git use it;
+Node's own `fetch` does not unless Node is started with `NODE_USE_ENV_PROXY=1` (Node.js 22.21 and later). So from
+0.12.1 the CLI restarts itself once with that set whenever a proxy is in the environment. Before that, `setup attach`
+and `progress attach` connected directly, failed the lookup, and said "did not answer", which read like a blocked
+network in a session with full network access. A failed request now says what happened (`lib/net.mjs`):
+
+- the directory's status and its own words (`homie.rocks answered 409: …`);
+- or the connection error's code (ENOTFOUND, ECONNREFUSED, a timeout, an untrusted certificate) and whether the
+  proxy was used.
+
+Only a refusal by the proxy itself (a 403 with `x-deny-reason: host_not_allowed`, or a refused CONNECT) names the
+network setting (the environment's Network access: Custom, add homie.rocks). The build goes on with its local feed.
+
+**The hand-off opens the studio's repository.** The chat's "Start building" and "Build it" open a Claude Code
+session in one repository, and homie.rocks never asks GitHub which one Deploy to Cloudflare made. So the studio's
+Worker tells it: `deploy` (and Workers Builds, which runs it) passes the repository as the Worker's private
+`HOMIE_REPO` variable, from `HOMIE_REPO`, studio.json `github`, or the git remote, in that order (`lib/repo.mjs`;
+Workers Builds sets no repository variable of its own). The Worker says it with its claim, a request Cloudflare
+stamps with the Worker's own zone. It is never in the public manifest. `setup attach` writes it into studio.json
+`github` too. When the directory does not know it, the card asks the person for it. It never opens Homie's engine
+repository (`homie-rocks/homie`), which is also never accepted as a studio's.
 
 The feed is `.studio/progress/<build>.json` (git-ignored). With `--share` the studio's
 directory (studio.json `homie.directory`, homie.rocks by default) keeps a copy for 24
@@ -270,6 +314,7 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `lib/check.mjs` | `check`: two fresh Chrome processes (computer + phone) must share a room and finish a round with both in it, with each one's frame rate; on a busy computer it waits out a round a browser was dropped from, and says why when none counts. `lib/chrome.mjs`: which Chrome, and how (the GPU on a Mac, SwiftShader on Linux). |
 | `lib/upgrade.mjs`, `lib/template-history.json` | `upgrade`: an existing studio takes what a newer template adds, never over its own edits. |
 | `lib/progress.mjs`, `lib/setup.mjs` | The progress feed (`progress …`), a build the chat opened (`progress attach`), a change as a pull request (`progress change`, `progress pr`), and `setup attach`. |
+| `lib/net.mjs`, `lib/repo.mjs` | The toolkit's own web requests: through the environment's proxy, and an honest reason when one fails. The studio's repository (`owner/name`), from its remote, never the engine's. |
 | `template/` (repository root), `scripts/template.mjs` | The public "Deploy to Cloudflare" template, generated from `new --template`. |
 | `lib/port.mjs` | `port plan` (reads a game and grades the port) and `port import`. |
 | `lib/port-check.mjs` | `port check`: held and alternating directions on keys, Android Chrome and iPhone WebKit touch, UI cover, two browsers finishing a round, a killed host, a late joiner, the big screen. |

package/bin/homie-studio.mjs

@@ -37,6 +37,8 @@
  *   homie-studio stats link               (a one-time link to the private stats page, for the owner's browser)
  *   homie-studio stats revoke             (every stats key and page session ends)
  *   homie-studio stats share on|off       (tell the homie.rocks directory "played this week", or stop)
+ *   homie-studio players                  (player accounts and guests with saves: counts, never a passkey or an email)
+ *   homie-studio players owner [--revoke] (a one-time link that marks the owner's own player account as the owner's)
  *
  *   homie-studio progress start [<id>] [--what game|song|video] [--title "<what this build does>"]
  *                                        [--budget <dollars>] [--unit usd|credits] [--share]
@@ -96,19 +98,21 @@ import { look } from '../lib/look.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
 import { portCheck } from '../lib/port-check.mjs';
 import { recordUpload, resolveMedia, typeOf } from '../lib/media.mjs';
-import { ensureStatsMigration, newStudio } from '../lib/scaffold.mjs';
+import { ensureMigrations, newStudio } from '../lib/scaffold.mjs';
 import { lineDiff, upgradeApply, upgradePlan } from '../lib/upgrade.mjs';
 import { listGames, newGame, readStudio, remixGame, requireStudio, siteUrl, starters, workerDir } from '../lib/studio.mjs';
 import { STUDIO_VERSION } from '../lib/version.mjs';
 import { statsKey, statsLink, statsRevoke, statsShare, statsShow } from '../lib/stats.mjs';
+import { playersOwner, playersShow } from '../lib/players.mjs';
 import { Feed, currentFeed, currentId, flushProgress, publicFeed, readFeed, recordChange, startProgress } from '../lib/progress.mjs';
 import { formatStatus, setupStatus } from '../lib/doctor.mjs';
 import { codexTarget, newCodex, writeCodexPage } from '../lib/codex.mjs';
 import { installStatusLine, statusLine } from '../lib/statusline.mjs';
+import { restartWithProxy } from '../lib/net.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open'];
+const BOOL_FLAGS = ['revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -207,8 +211,17 @@ function print(result) {
       for (const e of result.songs) lines.push(`  song ${e.slug}: ${n(e.visits)} page visits, played ${n(e.plays)}`);
       for (const e of result.videos) lines.push(`  video ${e.slug}: ${n(e.visits)} page visits, watched ${n(e.views)}`);
       for (const r of result.referrers.slice(0, 10)) lines.push(`  from ${r.from} (${r.kind}): ${n(r.visits)} visits, ${n(r.plays)} plays`);
+      if (result.players) lines.push(`  players: ${n(result.players.accounts)} accounts (${n(result.players.newAccounts7d)} new this week), ${n(result.players.guests)} guests with saves, ${n(result.players.active7d)} played this week`);
       break;
     }
+    case 'players': {
+      const p = result.players;
+      lines.push(`${p.accounts} player accounts (${p.newAccounts7d} new this week), ${p.guests} guests with saves, ${p.active7d} played this week.`, result.note);
+      break;
+    }
+    case 'players owner':
+      lines.push(result.revoked ? result.message : `One-time link (until ${result.expiresAt}): ${result.link}`, ...(result.revoked ? [] : [result.use]));
+      break;
     case 'stats key':
       lines.push(`Read key (until ${result.expiresAt}): ${result.key}`, result.use);
       break;
@@ -388,6 +401,8 @@ async function main() {
     return { ok: true, command: 'storage', storage: has ? { kind: 'r2', bucket: cf.r2 } : null, why: has ? undefined : 'no storage yet: the studio runs without it; `homie-studio storage add` adds an R2 bucket for large media (Cloudflare asks for a payment method before R2 works)' };
   }
   if (cmd === 'publish') return publish(root, { homie: flags.get('homie'), site: flags.get('site') });
+  if (cmd === 'players' && sub === 'owner') return playersOwner(root, { url: flags.get('url'), revoke: flags.has('revoke') });
+  if (cmd === 'players' && !sub) return playersShow(root, { url: flags.get('url') });
   if (cmd === 'stats' && sub === 'key') return statsKey(root, { url: flags.get('url'), hours: flags.get('hours') });
   if (cmd === 'stats' && sub === 'link') return statsLink(root, { url: flags.get('url') });
   if (cmd === 'stats' && sub === 'revoke') return statsRevoke(root, { url: flags.get('url') });
@@ -562,8 +577,7 @@ async function dev(root) {
   if (!bin) return { ok: false, command: 'dev', why: 'run npm install in the studio first' };
   const studio = readStudio(root);
   const env = { ...process.env, WRANGLER_SEND_METRICS: 'false', CI: '1' };
-  const added = ensureStatsMigration(root);
-  if (added) log(`added ${added} (the studio's own stats)`);
+  for (const added of ensureMigrations(root)) log(`added ${added} (${/players/.test(added) ? 'player accounts and cloud saves' : 'the studio\'s own stats'})`);
   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);
@@ -603,6 +617,13 @@ function mediaPut(root, file, as) {
   });
 }
 
+/*
+ * A machine whose web traffic goes through a proxy (a Claude Code cloud session: HTTPS_PROXY) runs this command once
+ * more with Node's own proxy support on, so the toolkit's requests go the way curl's and npm's do (lib/net.mjs).
+ */
+const proxied = await restartWithProxy();
+if (proxied !== null) process.exit(proxied);
+
 try {
   const result = await main();
   // A shared progress feed sends its last word before the command exits.

package/lib/build.mjs

@@ -220,6 +220,9 @@ export async function build(root, { only = null, log = () => {} } = {}) {
       id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: { min, max },
       roundSeconds: g.roundSeconds ?? net.roundSeconds ?? null, movement: net.movement ?? null, cover: g.cover ?? null,
       ...(g.screen ? { screen: g.screen } : {}),
+      // game.json "saves": true — player accounts and cloud saves (saves/SAVES.md): the play shell answers the game's
+      // saves calls, and the site's nav and the game's landing offer a player account.
+      ...(g.saves === true || (g.saves && typeof g.saves === 'object') ? { saves: true } : {}),
       landing: landingOf(g, join(dist, 'games', g.id), { videos: media.videos, songs: media.songs, log }),
     };
   });

package/lib/cloudflare.mjs

@@ -22,7 +22,8 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { build } from './build.mjs';
-import { ensureLocalIgnored, ensureStatsMigration, wranglerConfig } from './scaffold.mjs';
+import { repoOf } from './repo.mjs';
+import { ensureLocalIgnored, ensureMigrations, wranglerConfig } from './scaffold.mjs';
 import { LOCAL_STATE, configPath, isWorkersDev, layoutOf, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
 
 const ANSI = /\u001b\[[0-9;]*m/g;
@@ -96,7 +97,7 @@ export function deployPlan(root) {
     ok: true, command: 'deploy plan', studio: studio.name, account: cf.accountId ?? null,
     cloudflare: [
       { kind: 'Worker', name: cf.worker, what: 'the studio\'s pages, each game\'s page and play shell, and /.well-known/homie-studio.json for the directory', state: mark(`worker:${cf.worker}`), plan: 'Workers Free' },
-      { kind: 'D1 database', name: cf.d1, what: 'the directory claim, every finished round, and the studio\'s own stats (daily counters of visits, plays, rooms, rounds and songs, for the owner only; nothing about a visitor)', state: mark(`d1:${cf.d1}`), plan: 'Workers Free (500 MB per database, 5 GB per account)' },
+      { kind: 'D1 database', name: cf.d1, what: 'the directory claim, every finished round, the studio\'s own stats (daily counters of visits, plays, rooms, rounds and songs, for the owner only; nothing about a visitor), and, for games that keep saves, player accounts (a passkey\'s public key, never a password) and their saves', state: mark(`d1:${cf.d1}`), plan: 'Workers Free (500 MB per database, 5 GB per account)' },
       { kind: 'Durable Object', name: 'Table', what: 'one per public room: the netplay relay (seats, host, snapshots); runs no game code', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
       { kind: 'Durable Object', name: 'Lobby', what: 'one per game: puts strangers who press Play into the same room', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
       storage
@@ -192,14 +193,13 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   if (!r2) step('no storage (R2): the studio needs none to run; `homie-studio storage add` adds it for large media');
 
   writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root) }));
-  const added = ensureStatsMigration(root);
-  if (added) step(`added ${added} (the studio's own stats: counts, never tracks)`);
+  for (const added of ensureMigrations(root)) step(`added ${added} (${/players/.test(added) ? 'player accounts and cloud saves' : 'the studio\'s own stats: counts, never tracks'})`);
   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);
   step('D1 migrations applied');
 
   const started = Date.now();
-  const dep = w(['deploy']);
+  const dep = w(['deploy', ...repoVar(root)]);
   if (dep.code !== 0) return refuse(`wrangler deploy failed: ${dep.out.trim().split('\n').slice(-6).join(' ')}`, dep.out);
   remember(`worker:${cf.worker}`);
   // The workers.dev address names the Cloudflare account (often after its owner): it stays on this computer, in
@@ -239,6 +239,16 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   };
 }
 
+/*
+ * THE STUDIO'S REPOSITORY, FOR ITS WORKER (lib/repo.mjs). The Claude app's hand-off opens Claude Code on the studio's
+ * own GitHub repository, and only the studio knows which it is: the deploy hands it to the Worker as a variable
+ * (HOMIE_REPO), never into a public file, and the Worker tells its directory alongside its claim.
+ */
+export function repoVar(root) {
+  const repo = repoOf(root);
+  return repo ? ['--var', `HOMIE_REPO:${repo}`] : [];
+}
+
 /**
  * Read the live site's manifest once, which makes a 0.10.0 site claim itself in its directory. Returns the claim it
  * serves, or null (the directory did not answer, the site is not reachable yet, or it is a Preview). A fresh deploy
@@ -283,16 +293,18 @@ export async function ciDeploy(root, { log = () => {} } = {}) {
   const step = (what) => { steps.push({ what }); log(what); };
   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 };
-  if (ensureStatsMigration(root)) step('added the stats migration (the studio\'s own counters)');
+  for (const added of ensureMigrations(root)) step(`added ${added} (${/players/.test(added) ? 'player accounts and cloud saves' : 'the studio\'s own counters'})`);
   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);
   if (migrate.code !== 0 && !first) return refuse(`D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
   if (!first) step('D1 migrations applied');
   const started = Date.now();
-  const dep = w(['deploy']);
+  const dep = w(['deploy', ...repoVar(root)]);
   if (dep.code !== 0) return refuse(`wrangler deploy failed: ${dep.out.trim().split('\n').slice(-6).join(' ')}`, 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');
   if (first) {
     migrate = apply();
     if (migrate.code !== 0) return refuse(`D1 migrations failed after the first deploy: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);

package/lib/codex.mjs

@@ -637,6 +637,7 @@ ${game.blurb ?? ''}
 - **Players in a room:** ${players}
 - **Round:** ${game.roundSeconds ? `${game.roundSeconds} s` : 'how long, and how it ends'}
 - **Bots:** fill empty seats; a person who arrives takes a bot's place
+- **Progress that lasts:** ${game.saves ? 'the player\'s own saves (cloud saves: what is kept, lifetime stats, hardcore or not)' : 'none: a round is all there is (or cloud saves, if the plan says progress persists across sessions or devices)'}
 
 ## Music and sound
 

package/lib/directory.mjs

@@ -4,6 +4,7 @@
  * claim the directory gave it (`homie-studio deploy` stores it in D1), so
  * nobody can list games under someone else's site.
  */
+import { request } from './net.mjs';
 import { readStudio, siteUrl } from './studio.mjs';
 
 export async function publish(root, { homie, site } = {}) {
@@ -11,9 +12,9 @@ export async function publish(root, { homie, site } = {}) {
   const directory = (homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
   const url = site || siteUrl(root, studio);
   if (!url) return { ok: false, command: 'publish', why: 'this studio has no live site yet: run `npm run deploy` first' };
-  const res = await fetch(`${directory}/api/studio/publish`, {
+  const sent = await request(`${directory}/api/studio/publish`, {
     method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ site: url }),
-  }).catch((error) => ({ ok: false, status: 0, json: async () => ({ error: String(error.message) }) }));
-  const body = await res.json().catch(() => ({}));
-  return { ok: Boolean(res.ok && body.ok), command: 'publish', directory, site: url, ...body };
+  }, { timeout: 30_000 });
+  // The directory's own answer (what it listed, or why not), or the connection's error as it is.
+  return { ...(sent.body ?? {}), ok: sent.ok, command: 'publish', directory, site: url, ...(sent.ok ? {} : { why: sent.body?.message ?? sent.why, ...(sent.code ? { code: sent.code } : {}), ...(sent.needs ? { needs: sent.needs } : {}) }) };
 }

package/lib/doctor.mjs

@@ -24,6 +24,7 @@ import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { findChrome } from './chrome.mjs';
+import { whyFailed } from './net.mjs';
 import { isOurs } from './statusline.mjs';
 import { findStudio, readLocal, readStudio } from './studio.mjs';
 import { STUDIO_VERSION } from './version.mjs';
@@ -47,13 +48,17 @@ const MARK = { ok: '✓', act: '→', missing: '✗', optional: '○', later: '
 const RANK = { missing: 0, act: 1, unknown: 2, later: 3, optional: 4, ok: 5 };
 const worst = (states) => states.reduce((a, b) => (RANK[b] < RANK[a] ? b : a), 'ok');
 
+/** Whether the directory answers at all (any status is an answer), and if not, the connection's own error. */
 async function reach(url, fetchFn, ms = 5000) {
   try {
     const res = await fetchFn(url, { method: 'GET', headers: { 'user-agent': `homie-studio/${STUDIO_VERSION}`, accept: 'application/json' }, signal: AbortSignal.timeout(ms) });
     const deny = res.headers?.get?.('x-deny-reason') ?? '';
     if (res.status === 403 && /host_not_allowed/i.test(deny)) return { ok: false, blocked: true };
     return { ok: true, status: res.status };
-  } catch (error) { return { ok: false, why: error?.name === 'TimeoutError' ? 'did not answer in time' : 'did not answer' }; }
+  } catch (error) {
+    const w = whyFailed(error, url);
+    return { ok: false, blocked: w.needs === 'network', why: w.why, code: w.code };
+  }
 }
 
 /**
@@ -133,16 +138,17 @@ export async function setupStatus({
       say: 'Turn the Homie connector on. Claude Code: run /plugin, install or enable "homie" (marketplace homie-rocks/homie), then /mcp shows homie connected. Codex: install the Homie plugin from the same marketplace. The Claude app: Settings, Connectors, Add custom connector, https://homie.rocks/mcp; then its setup card (studio_setup) makes the studio on your own Cloudflare and GitHub in three taps.',
     };
     let state; let detail;
-    if (net.blocked) { state = 'act'; detail = `this environment's network does not reach ${new URL(directory).host}`; }
-    else if (said === 'yes') { state = 'ok'; detail = net.ok ? 'the Homie tools are here, and the directory answers' : `the Homie tools are here; ${new URL(directory).host} ${net.why ?? 'did not answer'} just now`; }
+    if (net.blocked) { state = 'act'; detail = `the network proxy of this machine refused ${new URL(directory).host}`; }
+    else if (said === 'yes') { state = 'ok'; detail = net.ok ? 'the Homie tools are here, and the directory answers' : `the Homie tools are here; this computer's request to the directory failed just now: ${net.why}`; }
     else if (said === 'no') { state = 'act'; detail = 'the Homie tools are not in this session'; }
-    else { state = net.ok ? 'unknown' : 'act'; detail = net.ok ? `${new URL(directory).host} answers; your AI knows whether its Homie tools (studio_scaffold) are here` : `${new URL(directory).host} ${net.why ?? 'did not answer'}`; }
+    // The directory not answering this computer says nothing about the connector: say what failed, as it is.
+    else { state = 'unknown'; detail = net.ok ? `${new URL(directory).host} answers; your AI knows whether its Homie tools (studio_scaffold) are here` : `this computer's request to the directory failed: ${net.why}`; }
     rows.push({
       id: 'connector', label: 'Homie connector', need: 'required', state, detail,
       unlocks: 'making the studio with the right toolkit version, listing games in the homie.rocks directory, and the cards in the Claude app',
       fix: state === 'ok' ? null : net.blocked
         ? { who: 'person', say: `In claude.ai/code, open this environment's settings, set Network access to Custom, add ${new URL(directory).host} (keep the default package managers), and start a new session.` }
-        : fixConnector,
+        : said === 'no' || net.ok ? fixConnector : null,
     });
   }
 

package/lib/net.mjs

@@ -0,0 +1,137 @@
+/**
+ * THE TOOLKIT'S OWN WEB REQUESTS, AND WHAT TO SAY WHEN ONE FAILS.
+ *
+ * A Claude Code cloud session sends ALL of its traffic through an HTTP proxy named in HTTPS_PROXY. curl, npm and
+ * git use that proxy. Node's own fetch() does not, unless the process started with NODE_USE_ENV_PROXY=1 (Node
+ * 22.21 and later): it connects directly, the VM's direct egress fails ("getaddrinfo ENOTFOUND"), and the toolkit
+ * used to report "did not answer". On 2026-09-30 a session with FULL network access read that as a blocked network
+ * and told the person to change their network settings, while curl in the same session reached homie.rocks.
+ *
+ * So:
+ *   - The CLI restarts itself once with NODE_USE_ENV_PROXY=1 when a proxy is set and this Node can use it
+ *     (`restartWithProxy`), so every request it makes goes the way curl's do. Loopback addresses never go
+ *     through the proxy.
+ *   - A failed request is reported as what it is (`request`, `whyFailed`):
+ *       * the status and the server's own message;
+ *       * or the connection error's code (ENOTFOUND, ECONNREFUSED, a timeout, a TLS error) and whether a proxy
+ *         was used.
+ *   - The network setting is named ONLY when the proxy itself refused the host: a 403 with
+ *     `x-deny-reason: host_not_allowed`, or a CONNECT it refused.
+ */
+import { spawn } from 'node:child_process';
+
+const PROXY_VARS = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy', 'ALL_PROXY', 'all_proxy'];
+const LOOPBACK = ['localhost', '127.0.0.1', '::1', '[::1]'];
+
+/** The proxy this machine's web requests go through (the environment's HTTPS_PROXY and friends), or null. */
+export function proxyOf(env = process.env) {
+  for (const k of PROXY_VARS) if (String(env[k] ?? '').trim()) return { variable: k, url: String(env[k]).trim() };
+  return null;
+}
+
+/**
+ * Whether this process's fetch() uses that proxy: Node's NODE_USE_ENV_PROXY / --use-env-proxy is on, and the variable
+ * Node reads for https (https_proxy, then HTTPS_PROXY; an empty one counts, as "none") names one.
+ */
+export function proxyInUse(env = process.env, execArgv = process.execArgv) {
+  const on = env.NODE_USE_ENV_PROXY === '1' || execArgv.includes('--use-env-proxy');
+  return on && Boolean(String(env.https_proxy ?? env.HTTPS_PROXY ?? '').trim());
+}
+
+/** Whether this Node.js can use the environment's proxy at all (22.21 and later have --use-env-proxy). */
+export function canUseProxy() {
+  try { return Boolean(process.allowedNodeEnvironmentFlags?.has('--use-env-proxy')); } catch { return false; }
+}
+
+/** NO_PROXY with this machine's own loopback addresses in it (a dev site or a local directory never goes out). */
+export function noProxyWithLoopback(value) {
+  const have = String(value ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+  return [...new Set([...have, ...LOOPBACK.filter((h) => h !== '[::1]')])].join(',');
+}
+
+/**
+ * Run this CLI once more with Node's proxy support on, when a proxy is set and not yet in use. Resolves to the exit
+ * status of that run, or null when there was nothing to do (no proxy, already on, or a Node without it). A signal
+ * this process gets (Ctrl-C, or a kill by its process id) is passed on, so the run never outlives it.
+ */
+export function restartWithProxy({ argv = process.argv, env = process.env, execArgv = process.execArgv } = {}) {
+  if (!proxyOf(env) || proxyInUse(env, execArgv) || !canUseProxy() || env.HOMIE_STUDIO_NO_PROXY_RESTART === '1') return Promise.resolve(null);
+  // Node reads https_proxy before HTTPS_PROXY, and an EMPTY one counts: it would silently mean "no proxy".
+  const next = Object.fromEntries(Object.entries(env).filter(([k, v]) => !(PROXY_VARS.includes(k) && !String(v ?? '').trim())));
+  const quiet = execArgv.some((a) => a.startsWith('--disable-warning=UNDICI-EHPA')) ? [] : ['--disable-warning=UNDICI-EHPA'];
+  return new Promise((done) => {
+    let child;
+    try {
+      child = spawn(process.execPath, [...quiet, ...execArgv, ...argv.slice(1)], {
+        stdio: 'inherit',
+        env: { ...next, NODE_USE_ENV_PROXY: '1', HOMIE_STUDIO_NO_PROXY_RESTART: '1', NO_PROXY: noProxyWithLoopback(env.NO_PROXY ?? env.no_proxy), no_proxy: noProxyWithLoopback(env.no_proxy ?? env.NO_PROXY) },
+      });
+    } catch { done(null); return; } // could not start it: carry on in this process, and the errors will say why
+    const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+    // Ctrl-C at a terminal reaches the whole process group already: pass SIGINT on only when nothing else will.
+    const pass = (signal) => { if (signal === 'SIGINT' && process.stdin.isTTY) return; try { child.kill(signal); } catch { /* already gone */ } };
+    for (const signal of signals) process.on(signal, pass);
+    child.on('error', () => { for (const signal of signals) process.off(signal, pass); done(null); });
+    child.on('exit', (code, signal) => { for (const signal of signals) process.off(signal, pass); done(code ?? (signal ? 1 : 0)); });
+  });
+}
+
+const hostOf = (url) => { try { return new URL(String(url)).host; } catch { return String(url); } };
+const oneLine = (text, max = 200) => String(text ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
+
+/** The one network setting a Claude Code cloud session can change, said only when its proxy refused the host. */
+export function networkSetting(host) {
+  return `the network proxy of this machine refused ${host}. In a Claude Code cloud session that means the environment's network access leaves it out: 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"; Full works too), and start a new session`;
+}
+
+/**
+ * Why a request that never got an answer failed: the connection error's own code and words, and the proxy's part.
+ * { why, code, needs } where needs is 'network' only for a refusal by the proxy itself.
+ */
+export function whyFailed(error, url, { env = process.env, execArgv = process.execArgv } = {}) {
+  const host = hostOf(url);
+  // fetch() wraps the real error: TypeError "fetch failed" > (a DOMException) > the socket's or the proxy's own.
+  const chain = [];
+  for (let e = error, i = 0; e && i < 6; e = e.cause, i += 1) chain.push(e);
+  const deepest = chain.at(-1) ?? {};
+  const code = chain.map((e) => e?.code).reverse().find((c) => typeof c === 'string' && c.trim())
+    ?? (chain.some((e) => e?.name === 'TimeoutError') ? 'TIMEOUT' : null);
+  const words = oneLine(deepest.message ?? String(error));
+  const proxy = proxyOf(env);
+  const used = Boolean(proxy) && proxyInUse(env, execArgv);
+  const refused = /Proxy response \((\d{3})\)/i.exec(chain.map((e) => e?.message ?? '').join(' '));
+  if (refused && refused[1] === '403') return { why: networkSetting(host), code: 'PROXY_403', needs: 'network' };
+  if (refused) return { why: `the network proxy (${proxy?.variable ?? 'HTTPS_PROXY'}) answered ${refused[1]} when asked to connect to ${host}`, code: `PROXY_${refused[1]}` };
+  const via = proxy ? (used ? ` (through the proxy in ${proxy.variable})` : ` (directly: this machine's proxy in ${proxy.variable} was not used${canUseProxy() ? '' : `, because Node.js ${process.versions.node} cannot use it; Node.js 22.21 or newer can`})`) : '';
+  if (code === 'TIMEOUT' || code === 'UND_ERR_CONNECT_TIMEOUT' || code === 'ETIMEDOUT') return { why: `no answer from ${host} in time${via}`, code: code ?? 'TIMEOUT' };
+  if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') return { why: `could not look up ${host} (${code})${via}`, code };
+  if (code === 'ECONNREFUSED' || code === 'ECONNRESET' || code === 'EHOSTUNREACH' || code === 'ENETUNREACH') return { why: `could not connect to ${host} (${code})${via}`, code };
+  if (/CERT|SELF_SIGNED|UNABLE_TO_VERIFY|UNABLE_TO_GET_ISSUER/i.test(code ?? '') || /certificate/i.test(words)) {
+    return { why: `the TLS certificate ${host} presented is not trusted here (${code ?? words})${via}; when a proxy inspects traffic, its CA belongs in NODE_EXTRA_CA_CERTS`, code: code ?? 'CERT' };
+  }
+  return { why: `the request to ${host} failed (${code ? `${code}: ` : ''}${words})${via}`, code };
+}
+
+/** Why an answer is a refusal: the proxy's (and then the one network setting), or the server's own words. */
+export function whyRefused(res, body, text, url) {
+  const host = hostOf(url);
+  if (res?.status === 403 && /host_not_allowed/i.test(res.headers?.get?.('x-deny-reason') ?? '')) return { why: networkSetting(host), needs: 'network', status: 403 };
+  const said = oneLine(body?.message ?? body?.error ?? (body ? '' : text), 300);
+  return { why: `${host} answered ${res?.status}${said ? `: ${said}` : ''}`, status: res?.status ?? null };
+}
+
+/**
+ * One JSON request with an honest result: { ok: true, status, body } or { ok: false, why, status?, code?, needs? }.
+ * A 2xx answer whose JSON says `ok: false` is a refusal too.
+ */
+export async function request(url, init = {}, { timeout = 10_000, fetchFn = globalThis.fetch } = {}) {
+  let res; let text = '';
+  try {
+    res = await fetchFn(url, { ...init, signal: init.signal ?? AbortSignal.timeout(timeout) });
+    text = await res.text();
+  } catch (error) { return { ok: false, ...whyFailed(error, url) }; }
+  let body = null;
+  try { body = text ? JSON.parse(text) : null; } catch { body = null; }
+  if (!res.ok || body?.ok === false) return { ok: false, body, ...whyRefused(res, body, text, url) };
+  return { ok: true, status: res.status, body, headers: res.headers };
+}

package/lib/players.mjs

@@ -0,0 +1,38 @@
+/**
+ * `homie-studio players` — the studio's players, for its owner (worker/players.mjs, saves/SAVES.md).
+ *
+ *   homie-studio players [--url <site>]          how many have accounts, guests with saves, who played this week
+ *   homie-studio players owner [--url <site>]    a one-time link that marks the owner's OWN player account as the
+ *                                                owner's (open it in the browser where they are signed in on the site)
+ *   homie-studio players owner --revoke          no account is the owner's any more
+ *
+ * The proof of ownership is the studio's own Cloudflare login, as for `stats`: the link's key is minted here and
+ * only its SHA-256 goes into the studio's D1 (through Wrangler). The link works once, for 30 minutes.
+ */
+import { runner } from './cloudflare.mjs';
+import { loopback, mint, siteOf, statsShow } from './stats.mjs';
+
+export async function playersShow(root, { url } = {}) {
+  const s = await statsShow(root, { url, range: '7d' });
+  if (!s.ok) return { ...s, command: 'players' };
+  if (!s.players) return { ok: false, command: 'players', why: 'this studio\'s D1 has no player tables yet: `npm run deploy` applies migration 0004_players.sql (or `npm run dev` for a local site)' };
+  return { ok: true, command: 'players', site: s.site, players: s.players, note: 'Counts only. A player\'s name, passkeys and saves are theirs; the back office lists names, never a passkey or an email.' };
+}
+
+export function playersOwner(root, { url, revoke = false } = {}) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, command: 'players owner', 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);
+  if (revoke) {
+    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', "UPDATE players SET owner = 0; DELETE FROM stats_keys WHERE kind = 'player-owner';"]);
+    return res.code === 0 ? { ok: true, command: 'players owner', site, revoked: true, message: 'No player account is the owner\'s now. `homie-studio players owner` marks one again.' }
+      : { ok: false, command: 'players owner', why: res.out.trim().split('\n').slice(-3).join(' ') };
+  }
+  const k = mint(root, studio, 'player-owner', 30 * 60_000, { local });
+  if (!k.ok) return { ok: false, command: 'players owner', why: k.why };
+  return {
+    ok: true, command: 'players owner', site, link: `${site}/account/?owner=${k.key}`, expiresAt: k.expiresAt,
+    use: 'Give this link to the studio\'s owner to open in the browser where they play: they sign in (or make an account with a passkey) on that page, then press "Yes, this account is mine". It works once, within 30 minutes. It is theirs alone; do not post it anywhere.',
+  };
+}