@homie-rocks/studio 0.12.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.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.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
 ```
 
@@ -142,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.12.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)
 ```
 
@@ -231,10 +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") 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 +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

@@ -108,6 +108,7 @@ import { Feed, currentFeed, currentId, flushProgress, publicFeed, readFeed, reco
 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();
@@ -616,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/cloudflare.mjs

@@ -22,6 +22,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { build } from './build.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';
 
@@ -198,7 +199,7 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   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
@@ -289,9 +300,11 @@ export async function ciDeploy(root, { log = () => {} } = {}) {
   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 };
+}

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/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/template-history.json

@@ -223,6 +223,30 @@
      "## 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"
+    }
+   }
   }
  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, optional R2 storage for large media, deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",

package/worker/index.mjs

@@ -115,11 +115,23 @@ const claimMissed = new Map();
 async function storedClaim(env, origin) {
   if (!env.DB) return null;
   try {
-    const rows = (await env.DB.prepare('SELECT key, value FROM meta WHERE key IN (?1, ?2)').bind(`homie_claim:${origin}`, 'homie_claim').all()).results ?? [];
-    return { own: rows.find((r) => r.key === `homie_claim:${origin}`)?.value ?? null, older: rows.find((r) => r.key === 'homie_claim')?.value ?? null };
+    const rows = (await env.DB.prepare('SELECT key, value FROM meta WHERE key IN (?1, ?2, ?3)').bind(`homie_claim:${origin}`, 'homie_claim', `homie_repo:${origin}`).all()).results ?? [];
+    const of = (k) => rows.find((r) => r.key === k)?.value ?? null;
+    return { own: of(`homie_claim:${origin}`), older: of('homie_claim'), repo: of(`homie_repo:${origin}`) };
   } catch { return null; }
 }
 
+/*
+ * THE STUDIO'S GITHUB REPOSITORY (HOMIE_REPO, set by `homie-studio deploy` from the studio's own git remote or
+ * studio.json "github"; lib/repo.mjs). The site tells its directory which repository it is built from, with its
+ * claim, so the Claude app's hand-off opens Claude Code on the studio's own repository. It is never put in a public
+ * page: only the directory hears it, from this Worker (Cloudflare's CF-Worker header names the zone it runs on),
+ * and it is said again only when it changes.
+ */
+const REPO = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9._-]{1,100}$/;
+const repoOf = (env) => { const r = String(env.HOMIE_REPO ?? '').trim(); return REPO.test(r) && r.toLowerCase() !== 'homie-rocks/homie' ? r : null; };
+const repoSaid = new Map();
+
 export function directoryOf(cat) {
   const d = cat?.studio?.directory;
   if (d === null || d === false) return null;
@@ -133,28 +145,34 @@ export function directoryOf(cat) {
 /** This address's claim: kept, else asked of the directory now (and kept), else an older studio's single claim. */
 async function claimOf(env, cat, url) {
   const origin = url.origin;
-  if (claimed.has(origin)) return claimed.get(origin);
+  const repo = repoOf(env);
+  if (claimed.has(origin) && (!repo || repoSaid.get(origin) === repo)) return claimed.get(origin);
   const kept = await storedClaim(env, origin);
-  if (kept?.own) { claimed.set(origin, kept.own); return kept.own; }
+  if (kept?.own && (!repo || kept.repo === repo)) { claimed.set(origin, kept.own); if (repo) repoSaid.set(origin, repo); return kept.own; }
   const directory = directoryOf(cat);
   const local = url.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(url.hostname);
   const may = directory && env.DB && env.HOMIE_PREVIEW !== '1' && (url.protocol === 'https:' || (local && directory.startsWith('http://')))
     && Date.now() - (claimMissed.get(origin) ?? 0) > 60_000;
   if (may) {
     try {
-      const res = await fetch(`${directory}/api/studio/claim?site=${encodeURIComponent(origin)}`, {
+      // Asked when there is no claim yet, or to say a repository the directory has not heard from this site.
+      const res = await fetch(`${directory}/api/studio/claim?site=${encodeURIComponent(origin)}${repo ? `&repo=${encodeURIComponent(repo)}` : ''}`, {
         headers: { accept: 'application/json', 'user-agent': `homie-studio/${STUDIO_VERSION_TAG} (site claim)` }, signal: AbortSignal.timeout(5000),
       });
       const body = await res.json().catch(() => null);
       if (res.ok && CLAIM.test(String(body?.claim ?? ''))) {
-        await env.DB.prepare('INSERT OR REPLACE INTO meta (key, value) VALUES (?1, ?2)').bind(`homie_claim:${origin}`, body.claim).run();
+        await env.DB.batch([
+          env.DB.prepare('INSERT OR REPLACE INTO meta (key, value) VALUES (?1, ?2)').bind(`homie_claim:${origin}`, body.claim),
+          ...(repo ? [env.DB.prepare('INSERT OR REPLACE INTO meta (key, value) VALUES (?1, ?2)').bind(`homie_repo:${origin}`, repo)] : []),
+        ]);
         claimed.set(origin, body.claim);
+        if (repo) repoSaid.set(origin, repo);
         return body.claim;
       }
     } catch { /* the directory is optional for a live site */ }
     claimMissed.set(origin, Date.now());
   }
-  return kept?.older ?? null;
+  return kept?.own ?? kept?.older ?? null;
 }
 
 /** A copy of the public template nobody has named yet shows the name typed into Cloudflare's form (STUDIO_NAME). */

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.12.0';
+export const STUDIO_VERSION_TAG = '0.12.1';