@homie-rocks/studio 0.9.0 → 0.10.0

package/lib/cloudflare.mjs

@@ -19,11 +19,11 @@
  * before anything happens and calls nothing.
  */
 import { spawnSync } from 'node:child_process';
-import { existsSync, writeFileSync } from 'node:fs';
+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 { LOCAL_STATE, isWorkersDev, readLocal, readStudio, siteUrl, writeLocal, writeStudio } from './studio.mjs';
+import { LOCAL_STATE, configPath, isWorkersDev, layoutOf, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
 
 const ANSI = /\u001b\[[0-9;]*m/g;
 
@@ -36,7 +36,7 @@ export function wranglerBin(root) {
 export function runner(root, env) {
   const bin = wranglerBin(root);
   if (!bin) throw new Error('Wrangler is not installed in this studio yet: run `npm install` in the studio folder first');
-  return (args, { cwd = join(root, 'site'), input } = {}) => {
+  return (args, { cwd = workerDir(root), input } = {}) => {
     const res = spawnSync(bin, args, {
       cwd, env: { ...process.env, ...env, WRANGLER_SEND_METRICS: 'false', CI: '1' }, encoding: 'utf8',
       input, maxBuffer: 64 * 1024 * 1024, timeout: 10 * 60_000,
@@ -186,7 +186,7 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   const r2 = cf.r2 && created.has(`r2:${cf.r2}`) ? cf.r2 : null;
   if (!r2) step('no storage (R2): the studio needs none to run; `homie-studio storage add` adds it for large media');
 
-  writeFileSync(join(root, 'site', 'wrangler.jsonc'), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2 }));
+  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)`);
   const migrate = w(['d1', 'migrations', 'apply', cf.d1, '--remote']);
@@ -211,20 +211,14 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   const url = siteUrl(root);
   step(`deployed ${cf.worker} in ${Math.round((Date.now() - started) / 1000)} s`, { url, ...(workersDev && workersDev !== url ? { workersDev } : {}) });
 
-  // The homie.rocks directory claim, for the site's public address (its own domain when it has one): the site
-  // serves it, which proves this studio controls the site.
+  // The homie.rocks directory claim: the live site claims itself the first time its manifest is read (0.10.0), so
+  // reading it once now is all it takes; nothing is stored by hand.
   const directory = homie || studio.homie?.directory || 'https://homie.rocks';
   let claim = null;
   if (url) {
-    try {
-      const res = await fetch(`${directory.replace(/\/+$/, '')}/api/studio/claim?site=${encodeURIComponent(url)}`);
-      const body = await res.json();
-      if (res.ok && /^[a-f0-9]{16,128}$/.test(body.claim ?? '')) claim = body.claim;
-    } catch { /* the directory is optional for a live site */ }
-    if (claim) {
-      const put = w(['d1', 'execute', cf.d1, '--remote', '--command', `INSERT OR REPLACE INTO meta (key, value) VALUES ('homie_claim', '${claim}')`]);
-      step(put.code === 0 ? 'directory claim stored' : 'could not store the directory claim (publish will say so)');
-    }
+    claim = await warmClaim(url);
+    if (claim) step('the site claimed itself in the directory');
+    else step('the directory claim is not there yet (the site claims itself when the directory first reads it)');
   }
 
   // studio.json keeps what is safe to commit: names, ids, the custom domain; never the workers.dev address.
@@ -240,6 +234,81 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   };
 }
 
+/**
+ * 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
+ * can take a few seconds to answer everywhere, so it asks three times.
+ */
+export async function warmClaim(site, { tries = 3, wait = 2500 } = {}) {
+  if (process.env.HOMIE_STUDIO_WARM === '0') return null; // the toolkit's own tests: their live site is made up
+  for (let i = 0; i < tries; i++) {
+    try {
+      const res = await fetch(`${String(site).replace(/\/+$/, '')}/.well-known/homie-studio.json`, { headers: { accept: 'application/json', 'user-agent': 'homie-studio-deploy' }, signal: AbortSignal.timeout(15_000) });
+      if (res.ok) {
+        const body = await res.json();
+        if (/^[a-f0-9]{16,128}$/.test(body?.claim ?? '')) return body.claim;
+      }
+    } catch { /* not answering yet */ }
+    if (i < tries - 1) await new Promise((r) => setTimeout(r, wait));
+  }
+  return null;
+}
+
+/** The Worker's name and D1 database, as the studio's wrangler.jsonc says (Cloudflare's forms may have renamed them). */
+export function configNames(root) {
+  try {
+    const text = readFileSync(configPath(root), 'utf8');
+    const json = JSON.parse(text.replace(/^\s*\/\/.*$/gm, ''));
+    return { worker: json.name ?? null, d1: json.d1_databases?.[0]?.database_name ?? null, binding: json.d1_databases?.[0]?.binding ?? 'DB' };
+  } catch { return { worker: null, d1: null, binding: 'DB' }; }
+}
+
+/*
+ * `npm run deploy` IN WORKERS BUILDS (WORKERS_CI=1, or `deploy --ci`). Cloudflare's own CI has already run
+ * `npm run build`, and holds its own API token for this one account; the Worker and its database were made by the
+ * "Deploy to Cloudflare" flow or by an earlier deploy. So this only applies the D1 migrations (by binding name: the
+ * form may have renamed the database) and deploys. It creates nothing by hand and refuses nothing, and writes
+ * nothing back (a CI checkout is thrown away). On the very first deploy the database may not exist yet: Wrangler
+ * creates the one the binding names while it deploys, and the migrations run right after.
+ */
+export async function ciDeploy(root, { log = () => {} } = {}) {
+  const w = runner(root, {});
+  const names = configNames(root);
+  const steps = [];
+  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)');
+  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']);
+  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`);
+  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);
+    step('D1 migrations applied (the database was created with this first deploy)');
+  }
+  // The live address, from what Wrangler printed (a custom domain in studio.json wins).
+  const workersDev = /https:\/\/[a-z0-9.-]+\.workers\.dev/i.exec(dep.out)?.[0] ?? null;
+  let url = null;
+  try { url = siteUrl(root) ?? workersDev; } catch { url = workersDev; }
+  const claim = url ? await warmClaim(url) : null;
+  step(claim ? 'the site claimed itself in the directory' : 'no directory claim yet (the site claims itself when the directory first reads it)');
+  let games = [];
+  try { games = JSON.parse(readFileSync(join(root, 'site', 'dist', 'games.json'), 'utf8')).games.map((g) => g.id); } catch { games = []; }
+  return {
+    ok: true, command: 'deploy', ci: true, url, worker: names.worker, d1: names.d1, r2: null, steps, announced: [],
+    commit: process.env.WORKERS_CI_COMMIT_SHA ?? null, branch: process.env.WORKERS_CI_BRANCH ?? null,
+    games: games.map((id) => ({ id, page: url ? `${url}/${id}/` : null, play: url ? `${url}/${id}/play` : null })), songs: [], videos: [],
+    claim: Boolean(claim),
+  };
+}
+
 /*
  * `homie-studio storage add` — the studio's own storage for large media (songs,
  * videos, big art), as an R2 bucket on its account, bound as MEDIA and served at
@@ -283,7 +352,7 @@ export async function storageAdd(root, { log = () => {} } = {}) {
   const next = { ...readStudio(root), cloudflare: { ...readStudio(root).cloudflare, accountId, r2: bucket, created: [...created].sort() } };
   writeStudio(root, next);
   if (next.cloudflare.d1Id) {
-    writeFileSync(join(root, 'site', 'wrangler.jsonc'), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: next.cloudflare.d1Id, r2: bucket }));
+    writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: next.cloudflare.d1Id, r2: bucket, layout: layoutOf(root) }));
   }
   log(`created R2 ${bucket}`);
   return { ok: true, command: 'storage add', bucket, account: accountId, next: ['npm run deploy   (binds the bucket as MEDIA; the site serves it at /media/<key>)', 'npx --no-install homie-studio media put <file>'] };

package/lib/look.mjs

@@ -7,16 +7,11 @@
  * `--shots` (default .studio/look/), which git ignores. One Chrome, closed at the end; its visits are house QA
  * (the studio's stats leave them out).
  */
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { chromeArgs, findChrome, noChrome } from './chrome.mjs';
 
-const CHROMES = [
-  process.env.CHROME_PATH,
-  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-  '/Applications/Chromium.app/Contents/MacOS/Chromium',
-  '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
-].filter(Boolean);
 
 export const LOOK_DEVICES = {
   computer: { width: 1440, height: 900, deviceScaleFactor: 1 },
@@ -29,8 +24,8 @@ const nameOf = (path) => path.replace(/^\/+|\/+$/g, '').replace(/[^a-z0-9]+/gi,
 
 export async function look({ url, paths, shots, devices = Object.keys(LOOK_DEVICES), log = () => {} }) {
   if (!url) return { ok: false, command: 'look', why: 'give --url (the local dev address or the live site)' };
-  const chrome = CHROMES.find((p) => existsSync(p));
-  if (!chrome) return { ok: false, command: 'look', why: 'no Chrome found (set CHROME_PATH)' };
+  const chrome = findChrome();
+  if (!chrome) return { ok: false, command: 'look', why: noChrome() };
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'look', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
   const base = String(url).replace(/\/+$/, '');
@@ -39,7 +34,7 @@ export async function look({ url, paths, shots, devices = Object.keys(LOOK_DEVIC
   // 150 s for Chrome to start: on a loaded computer a cold start has taken over a minute.
   const browser = await puppeteer.launch({
     executablePath: chrome, headless: true, userDataDir: profile, timeout: 150_000, protocolTimeout: 180_000,
-    args: ['--use-angle=metal', '--enable-gpu-rasterization', '--ignore-gpu-blocklist', '--autoplay-policy=no-user-gesture-required', '--no-first-run', '--no-default-browser-check'],
+    args: [...chromeArgs(), '--autoplay-policy=no-user-gesture-required', '--no-first-run', '--no-default-browser-check'],
   });
   const rows = [];
   try {

package/lib/port-check.mjs

@@ -29,20 +29,14 @@
  * Exit 0 only when every row passed.
  */
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { chromeArgs, findChrome, noChrome } from './chrome.mjs';
 
-const CHROMES = [
-  process.env.CHROME_PATH,
-  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-  '/Applications/Chromium.app/Contents/MacOS/Chromium',
-  '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
-].filter(Boolean);
 const GPU = [
-  ...(process.platform === 'darwin' ? ['--use-angle=metal'] : []),
-  '--enable-gpu-rasterization', '--ignore-gpu-blocklist', '--autoplay-policy=no-user-gesture-required',
+  ...chromeArgs(), '--autoplay-policy=no-user-gesture-required',
   '--disable-background-timer-throttling', '--disable-backgrounding-occluded-windows', '--disable-renderer-backgrounding',
   '--no-first-run', '--no-default-browser-check',
 ];
@@ -396,8 +390,8 @@ export async function portCheck({ url, game, root, only = null, shots = null, lo
   if (!url || !game) throw new Error('usage: homie-studio port check <game> --url <site>');
   const base = String(url).replace(/\/+$/, '');
   const want = new Set((only ? String(only).split(',') : ALL).map((s) => s.trim()).filter(Boolean));
-  const exe = CHROMES.find((p) => existsSync(p));
-  if (!exe) return { ok: false, command: 'port check', why: 'no Chrome found (set CHROME_PATH)' };
+  const exe = findChrome();
+  if (!exe) return { ok: false, command: 'port check', why: noChrome() };
   const req = createRequire(join(root ?? process.cwd(), 'package.json'));
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { try { puppeteer = req('puppeteer-core'); } catch { return { ok: false, command: 'port check', why: 'puppeteer-core is missing (it comes with @homie-rocks/studio: npm install)' }; } }

package/lib/progress.mjs

@@ -34,12 +34,24 @@
  *     stop: { requested, at, by },
  *     song?: { peaks: [0..1], lyrics: [{ line, sung: true|false|null }] },
  *     video?: { shots: [{ id, label, state, image }] },
+ *     change?: { url, number, title, repo, branch, state: open|merged|closed, files, additions, deletions, preview, mark, at },
+ *     site?: the studio's live address (for the Claude app's card to tell when a merged change is live),
  *     log: [{ at, text }], error, shared?: { build, directory } }
+ *
+ * A BUILD OPENED IN THE CHAT (`build_open`, the Claude app's "Build it" card): the chat gets the build id first
+ * and shows its card; the Claude Code session that does the work attaches to it ONCE with
+ * `progress attach <hb_…>`, and the directory hands the write key to that first attach only. No key ever travels
+ * in a prompt; a second attach is refused.
+ *
+ * A CHANGE THAT GOES OUT AS A PULL REQUEST: `progress change "<what it does>"` writes changes/<date>-<mark>.json
+ * (committed with the change; the site lists the newest marks in its manifest), and `progress pr --url <pr>` puts
+ * the pull request on the card, whose Publish button opens it in GitHub for the person's one-tap merge. When the
+ * live site lists the change's mark, Workers Builds has deployed it: the card says Live by itself.
  */
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { extname, join } from 'node:path';
-import { readStudio } from './studio.mjs';
+import { readStudio, siteUrl } from './studio.mjs';
 
 export const PROGRESS_KIND = 'homie-studio-progress';
 export const PROGRESS_DIR = join('.studio', 'progress');
@@ -72,6 +84,28 @@ 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 ON THE DEFAULT NETWORK. Its "Trusted" network reaches package registries and GitHub,
+ * not homie.rocks: the session's proxy answers 403 with `x-deny-reason: host_not_allowed`. Say which setting lets
+ * the card follow the build, instead of "did not answer"; the build itself goes on with its local feed.
+ */
+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;
+}
+
+/** The studio's live address for the card: an https origin (or this computer's own dev site), else null. */
+export function liveSite(url) {
+  try { const u = new URL(String(url ?? '')); return u.protocol === 'https:' || (u.protocol === 'http:' && loopback(u.href)) ? u.origin : null; } catch { return null; }
+}
+
+/** A change's mark: what the site lists once the change is live. It names the build without being able to read it. */
+export const changeMark = (build) => createHash('sha256').update(`homie-change\n${build}`).digest('hex').slice(0, 16);
+
 function writeAtomic(file, text) {
   const tmp = `${file}.${process.pid}.${randomBytes(3).toString('hex')}.tmp`;
   writeFileSync(tmp, text);
@@ -120,6 +154,11 @@ async function pushDoc(root, id) {
     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 }; });
@@ -309,6 +348,33 @@ export class Feed {
     });
   }
 
+  /** The pull request this build's change went out as: the card's Publish button opens it for the person's merge. */
+  pr({ url, number, title, repo, branch, state = 'open', files, additions, deletions, preview, site } = {}) {
+    let u;
+    try { u = new URL(String(url ?? '')); } catch { throw new Error('--url is the pull request\'s https://github.com/<owner>/<repo>/pull/<n> address'); }
+    const m = /^\/([A-Za-z0-9-]{1,39})\/([A-Za-z0-9._-]{1,100})\/pull\/(\d{1,7})\/?$/.exec(u.pathname);
+    if (u.protocol !== 'https:' || u.hostname !== 'github.com' || !m) throw new Error('--url is the pull request\'s https://github.com/<owner>/<repo>/pull/<n> address');
+    if (!['open', 'merged', 'closed'].includes(state)) throw new Error('a pull request is open, merged or closed');
+    const count = (n) => (n === undefined || n === null || n === true ? null : Number.isFinite(Number(n)) && Number(n) >= 0 ? Math.round(Number(n)) : null);
+    return this.change((doc) => {
+      const before = doc.change ?? {};
+      doc.change = {
+        url: `https://github.com/${m[1]}/${m[2]}/pull/${m[3]}`, number: Number(m[3]), repo: `${m[1]}/${m[2]}`,
+        title: plain(title ?? before.title ?? doc.title, LIMITS.title), branch: branch ? plain(branch, 100) : before.branch ?? null, state,
+        files: count(files) ?? before.files ?? null, additions: count(additions) ?? before.additions ?? null, deletions: count(deletions) ?? before.deletions ?? null,
+        preview: preview ? String(preview).slice(0, 300) : before.preview ?? null, mark: before.mark ?? null, at: now(),
+      };
+      // The live address may have been learned after the build was opened (`setup attach`): the card reads it.
+      if (liveSite(site)) doc.site = liveSite(site);
+      const deploy = doc.stages.find((s) => s.id === 'deploy' || s.id === 'publish');
+      if (deploy && state === 'open' && deploy.state === 'pending') { deploy.state = 'running'; deploy.startedAt = now(); deploy.note = 'Waiting for the merge: Publish on the card opens the pull request'; doc.stage = deploy.id; }
+      pushLog(doc, `Pull request #${m[3]} ${state}`);
+    }, { soon: true });
+  }
+
+  /** The studio's live address, so the card can read the site's own manifest for the change once it is merged. */
+  site(url) { return this.change((doc) => { doc.site = url ? String(url).slice(0, 200) : null; }); }
+
   stopRequested() { return Boolean(this.doc?.stop?.requested); }
 
   /**
@@ -362,7 +428,9 @@ export function publicFeed(doc) {
  * Open a feed for one build. `share` asks the studio's directory (studio.json `homie.directory`, or `directory`)
  * to keep a copy for the Claude app's widget; if it cannot, the build goes on with the local feed only.
  */
-export async function startProgress(root, { what = 'game', id, title, budget, unit, share = false, directory } = {}) {
+export async function startProgress(root, { what = 'game', id, title, budget, unit, share = false, directory, attach = null } = {}) {
+  if (attach !== null && !REMOTE_ID.test(String(attach))) return { ok: false, command: 'progress attach', why: 'attach to the build id the Claude app showed: hb_ and 32 hex digits' };
+  if (attach) share = true;
   if (!STAGES[what]) return { ok: false, command: 'progress start', why: `what is being made: ${Object.keys(STAGES).join(', ')}` };
   if (id !== undefined && id !== null && !SLUG.test(String(id))) return { ok: false, command: 'progress start', why: 'the id is the game, song or video id (lowercase letters, digits and hyphens)' };
   const studio = readStudio(root);
@@ -384,6 +452,9 @@ export async function startProgress(root, { what = 'game', id, title, budget, un
     log: [{ at: now(), text: `Started: ${plain(title || id || what, 100)}` }],
     error: null,
   };
+  let live = null;
+  try { live = siteUrl(root, studio); } catch { live = null; }
+  if (liveSite(live)) doc.site = liveSite(live);
   mkdirSync(dir(root), { recursive: true });
   writeAtomic(docPath(root, build), `${JSON.stringify(doc, null, 1)}\n`);
   writeAtomic(currentPath(root), `${build}\n`);
@@ -394,12 +465,16 @@ export async function startProgress(root, { what = 'game', id, title, budget, un
     if (!/^https:\/\//.test(at) && !(/^http:\/\//.test(at) && loopback(at))) why = `the directory ${at} is not https`;
     else {
       try {
-        const res = await fetch(`${at}/api/studio/progress`, {
+        // 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 && body?.ok && REMOTE_ID.test(String(body.build)) && /^hbk_[a-f0-9]{48}$/.test(String(body.key))) {
+        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 };
@@ -410,11 +485,45 @@ export async function startProgress(root, { what = 'game', id, title, budget, un
       } catch (error) { why = `${at} did not answer (${error?.message ?? error})`; }
     }
   }
+  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: true, command: 'progress start', build, file: join(PROGRESS_DIR, `${build}.json`), what, id: id ?? null, title: doc.title,
+    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,
     stages: doc.stages.map((s) => s.id), budget: doc.spend.budget, unit: doc.spend.unit,
     shared: shared ? { build: shared.build, directory: shared.directory, expiresAt: shared.expiresAt } : null,
     ...(share && !shared ? { sharedWhy: `not shared: ${why}; the feed is local only` } : {}),
     widget: shared ? `In the Claude app: call the Homie MCP tool build_progress with { "build": "${shared.build}" }` : null,
   };
 }
+
+/**
+ * `progress change "<what it does>"`: the change's mark, as a small file the change commits (changes/<date>-<mark>.json).
+ * `homie-studio build` lists the newest marks in the site's manifest; when the live site lists this one, the change
+ * is deployed, and the Claude app's card says so. Returns the file, relative to the studio.
+ */
+export function recordChange(root, id, title) {
+  const doc = readFeed(root, id);
+  if (!doc) throw new Error('no build is open: start or attach one first');
+  const mark = changeMark(doc.shared?.build ?? doc.build);
+  const folder = join(root, 'changes');
+  mkdirSync(folder, { recursive: true });
+  if (!existsSync(join(folder, 'README.md'))) writeFileSync(join(folder, 'README.md'), CHANGES_README);
+  const rel = join('changes', `${now().slice(0, 10)}-${mark.slice(0, 8)}.json`);
+  const text = `${JSON.stringify({ v: 1, change: mark, title: plain(title || doc.title, LIMITS.title), at: now() }, null, 2)}\n`;
+  writeFileSync(join(root, rel), text);
+  mutateDoc(root, id, (d) => { d.change = { ...(d.change ?? {}), mark }; pushLog(d, `Change recorded: ${plain(title || doc.title, 100)}`); });
+  schedule(root, id, { soon: true });
+  return { file: rel, mark };
+}
+
+export const CHANGES_README = `# changes/
+
+One small file per change this studio made through a pull request, written by \`homie-studio progress change\`:
+what it does, when, and its mark. \`npm run build\` lists the newest marks in the site's
+\`/.well-known/homie-studio.json\`, so the Claude app's card can tell when a merged change is live. Nothing in
+here is secret; old files may be deleted.
+`;