@homie-rocks/studio 0.12.0 → 0.13.0

package/README.md

@@ -19,6 +19,7 @@ npx homie-studio deploy --plan                         # what deploy will create
 npx homie-studio deploy                                # the studio's own Cloudflare
 npx homie-studio publish                               # the homie.rocks directory
 npx homie-studio stats                                 # the studio's own numbers, for its owner
+npx homie-studio office                                 # who is playing now, in every live room (the back office)
 npx homie-studio upgrade                               # what a newer template adds to this studio (--apply to take it)
 ```
 
@@ -72,8 +73,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.12.0 upgrade          # the plan; changes nothing
-npx -y @homie-rocks/studio@0.12.0 upgrade --apply  # after the person agrees
+npx -y @homie-rocks/studio@0.13.0 upgrade          # the plan; changes nothing
+npx -y @homie-rocks/studio@0.13.0 upgrade --apply  # after the person agrees
 npm install && npm run build
 ```
 
@@ -139,10 +140,70 @@ npx homie-studio stats share on                         # tell the directory "pl
 Each key is minted on the owner's computer; only its SHA-256 goes into D1, through the
 studio's own Cloudflare login. `worker/stats.mjs` says exactly what is counted.
 
+## The back office: run your live games
+
+The owner sees and runs the studio's live games from `/_studio/office`, a private page
+that refreshes itself: every live room of every game (players, bots, the round, how long
+it has been up) and who is in it (each seat's handle, its device, whether it hosts, the
+browser it came from; signed-in players once a studio has player accounts). From there,
+and from a small Owner button in the owner's own play page (nobody else's page carries
+it):
+
+- **Kick** a player: they get a polite notice and cannot come back to that room for the
+  minutes the owner chose (their seat, their browser, their account; their network only
+  when asked, since a household shares one).
+- **Mute** a player: their chat and emotes reach nobody (the `say`, `chat` and `emote`
+  events; a game hides the rest with `net.isMuted(seat)`).
+- **Announce** one line to a room, a game or the whole studio: every player sees it as a
+  banner, and a game can show it its own way (`net.on('announce')`).
+- **Close** a room: everyone is sent out with a thank-you; nobody gets in until it opens.
+- Per game: **players per room**, the **launch state** (`private`: only the owner;
+  `invite`: an invite-only beta, where each invite link or code lets a browser in;
+  `public`: anyone, listed), and **remixable** (publish or withdraw the game's source).
+  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 is private from its
+  first deploy with `"launch": "private"` in its game.json.
+
+```sh
+npx homie-studio office link                            # a one-time link that signs the owner's browser in
+npx homie-studio office link --to /crown-thief/play     # ... onto a private game, on the owner's phone
+npx homie-studio office                                 # every live room and who is in it, now
+npx homie-studio office announce "Double gems this round!" --game crown-thief
+npx homie-studio office invite crown-thief --label "Sam" --uses 1
+npx homie-studio office launch crown-thief invite       # asks: the owner confirms with one tap
+npx homie-studio office kick crown-thief pub-3 2        # asks: seat 2 of Room 3
+npx homie-studio office key                             # a key for the Homie MCP's owner tools
+```
+
+Going private or invite-only never cuts a round short: each live room finishes its current round with a notice to
+the players, then everyone the new state leaves out is sent out with a thank-you (the owner, and in a beta the
+invited, play on). Mute drops a player's `say…`, `chat…` and `emote…` events, so a game that sends its chat and
+emotes under those kinds needs nothing more (`netplay/NETPLAY.md` section 15). Kicking a whole network address is in
+the studio's API (`address: true`) and deliberately not in the office. A Preview (a branch's own unlisted address, with
+no D1) enforces no launch state and has no office.
+
+**Privacy.** The site still sets no cookie on a visitor to count or follow them. Two things are kept for the back
+office, both functional: a random room key in the play page's own storage (what a kick holds; it says nothing about
+who the player is), and, for an invited player of an invite-only beta only, their pass to that game: an HttpOnly
+cookie for that game's pages alone, for 90 days. D1 keeps only a hash of each pass.
+
+**Only the owner.** The owner's browser is signed in with the same one-time link as the
+stats (an HttpOnly session no page or game can read; games run in a sandboxed, opaque
+frame). An office key (minted with the studio's own Cloudflare login) lets the owner's AI
+look, announce and invite at once; a kick, a mute, a closed room or a launch change is only
+**asked** for, and the owner confirms it with one tap in their own browser. No key can
+confirm. The Worker signs each control with the studio's own secret and the room verifies
+it before it acts (`netplay/NETPLAY.md` section 15). Everything is in the studio's own
+Worker and D1 (migration `0003_studio_office.sql`); homie.rocks stores none of it.
+
+With player accounts (0.12.0), a signed-in player's play page names their account in its room ticket (an invited
+player's names the invite and the account), so the office shows them by name and a kick holds the account on every
+device; the owner's own passkey account (`homie-studio players owner`) counts as the owner.
+
 ## Setup status
 
 ```sh
-npx -y @homie-rocks/studio@0.12.0 setup status --connector yes   # before a studio exists
+npx -y @homie-rocks/studio@0.13.0 setup status --connector yes   # before a studio exists
 npx homie-studio setup status                                    # in a studio (also: homie-studio doctor)
 ```
 
@@ -231,10 +292,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") reaches homie.rocks. If a session's network blocks it
-(its proxy answers 403 `host_not_allowed`, and the progress card stops updating), 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
@@ -297,6 +375,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

@@ -40,6 +40,19 @@
  *   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 office [--url <site>]    the back office: 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 own phone)
+ *   homie-studio office key [--hours 1]   a key for the Homie MCP's owner tools (studio_office, room_kick, ...)
+ *   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]
+ *                                         (kick, close and launch are ASKED for: the owner confirms each with one
+ *                                          tap in their own browser, from the link this prints)
+ *   homie-studio office revoke            (every office key, play ticket and pending ask ends)
+ *
  *   homie-studio progress start [<id>] [--what game|song|video] [--title "<what this build does>"]
  *                                        [--budget <dollars>] [--unit usd|credits] [--share]
  *                                         (a progress feed for one build; --share shows it in the Claude app
@@ -98,20 +111,22 @@ 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 { ensureMigrations, newStudio } from '../lib/scaffold.mjs';
+import { ensureMigrations, migrationWord, 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 { officeAnnounce, officeClose, officeInvite, officeKey, officeKick, officeLaunch, officeLines, officeLink, officeRevoke, officeShow } from '../lib/office.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 = ['revoke', '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', 'reopen'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -231,6 +246,28 @@ function print(result) {
     case 'stats share':
       lines.push(result.message);
       break;
+    case 'office':
+      lines.push(...officeLines(result));
+      break;
+    case 'office link':
+      lines.push(`One-time link (until ${result.expiresAt}): ${result.link}`, result.use);
+      break;
+    case 'office key':
+      lines.push(`Office key (until ${result.expiresAt}): ${result.key}`, result.use);
+      break;
+    case 'office announce':
+    case 'office revoke':
+      lines.push(result.message);
+      break;
+    case 'office invite':
+      for (const i of result.invites) lines.push(`Invite ${i.code}${i.label ? ` (${i.label})` : ''}, ${i.maxUses ? `${i.maxUses} use${i.maxUses === 1 ? '' : 's'}` : 'any number of uses'}: ${i.link}`);
+      if (result.note) lines.push(result.note);
+      break;
+    case 'office launch':
+    case 'office kick':
+    case 'office close':
+      lines.push(result.asked ? `Asked: ${result.what}` : result.message, ...(result.asked ? [`Owner's one-tap link (until the ask ends, 15 min): ${result.link}`, result.use] : []));
+      break;
     case 'setup status':
       lines.push(formatStatus(result));
       break;
@@ -407,6 +444,18 @@ async function main() {
   if (cmd === 'stats' && sub === 'revoke') return statsRevoke(root, { url: flags.get('url') });
   if (cmd === 'stats' && sub === 'share') return statsShare(root, positional[2]);
   if (cmd === 'stats' && !sub) return statsShow(root, { url: flags.get('url'), range: flags.get('range'), game: flags.get('game'), song: flags.get('song'), video: flags.get('video') });
+  if (cmd === 'office') {
+    const url = flags.get('url');
+    if (!sub) return officeShow(root, { url });
+    if (sub === 'link') return officeLink(root, { url, to: flags.get('to') });
+    if (sub === 'key') return officeKey(root, { url, hours: flags.get('hours') });
+    if (sub === 'announce') return officeAnnounce(root, positional.slice(2).join(' '), { url, game: flags.get('game'), room: flags.get('room'), seconds: flags.get('seconds') });
+    if (sub === 'invite') return officeInvite(root, positional[2], { url, label: flags.get('label'), uses: flags.get('uses'), count: flags.get('count'), days: flags.get('days') });
+    if (sub === 'launch') return officeLaunch(root, positional[2], positional[3], { url, remixable: flags.get('remixable'), max: flags.get('max') });
+    if (sub === 'kick') return officeKick(root, positional[2], positional[3], positional.slice(4).join(' ') || undefined, { url, minutes: flags.get('minutes') });
+    if (sub === 'close') return officeClose(root, positional[2], positional[3], { url, minutes: flags.get('minutes'), reopen: flags.has('reopen') });
+    if (sub === 'revoke') return officeRevoke(root, { url });
+  }
   if (cmd === 'media' && sub === 'put') return mediaPut(root, positional[2], flags.get('as'));
   if (cmd === 'media' && sub === 'list') {
     const studio = readStudio(root);
@@ -576,7 +625,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' };
-  for (const added of ensureMigrations(root)) log(`added ${added} (${/players/.test(added) ? 'player accounts and cloud saves' : 'the studio\'s own stats'})`);
+  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);
@@ -616,6 +665,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

@@ -223,6 +223,8 @@ export async function build(root, { only = null, log = () => {} } = {}) {
       // 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 } : {}),
+      // game.json `"launch": "private" | "invite"`: the game's launch state until its owner sets one live (the office).
+      ...(g.launch === 'private' || g.launch === 'invite' ? { launch: g.launch } : {}),
       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, ensureMigrations, wranglerConfig } from './scaffold.mjs';
+import { repoOf } from './repo.mjs';
+import { ensureLocalIgnored, ensureMigrations, migrationWord, 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;
@@ -192,13 +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) }));
-  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'})`);
+  for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
   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
@@ -238,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
@@ -282,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 };
-  for (const added of ensureMigrations(root)) step(`added ${added} (${/players/.test(added) ? 'player accounts and cloud saves' : 'the studio\'s own counters'})`);
+  for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
   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/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 };
+}