@homie-rocks/studio 0.58.20 → 0.58.23

package/CHANGELOG.md

@@ -17,6 +17,54 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.58.23] - 2026-10-29
+
+**Plugin 0.58.15**
+
+A booking agent books, finds its hold, pays and cancels with one hold id and a private token, and every refusal comes with a stable error code.
+
+### Changed
+
+- `studio_book` needs no `id`. The returned `data.id` (now `hold_` and 48 hex) is the hold: pass it as `hold` to the Venue desk tools, `studio_holds` and `studio_checkout`. An `id` you still send is an optional idempotency key, scoped to your account or private token, so two guests using the same slot name never collide (that was the `Booking owner required` error). Holds made by earlier versions keep their 64-hex ids and keep working.
+- Every studio MCP tool refusal is an MCP error (`isError`) with `structuredContent` `{kind:'studio-error', error:{code, message, status}}` and a stable `code`, e.g. `hold_not_found`, `slot_full`, `hold_ended`, `invalid_input`, or a closed shop's `closed` with `details.missing`. `studio_checkout` no longer returns a closed shop as success.
+- `studio_checkout` takes top-level `app`, `hold` and `token`, the same as the Venue desk tools, and fills in the booking's line (its service item × quantity). `venue_booking_confirm` (Venue desk 1.0.1), for a venue that takes payment in advance, returns `checkout: {tool:'studio_checkout', arguments, lines}` naming exactly what to call.
+
+### Added
+
+- `studio_holds { token }` lists a guest's own active holds; `release` (a hold id, or `"all"`) releases them. Only that token's holds are ever shown or changed.
+
+### Fixed
+
+- A hold past its expiry no longer takes a place: availability stops counting it, and the next booking on that slot releases it.
+
+## [0.58.22] - 2026-10-29
+
+**Plugin 0.58.15**
+
+The parts that come with the toolkit, like the Venue desk, add to a studio with no download.
+
+### Fixed
+
+- `part_add` and `parts_find` find the parts that come with the toolkit (`parts/catalogue.json`: Venue desk, Owner action checklist, Terrain route map) in the installed toolkit, with no download: `part_add { "part": "venue-desk" }` (or `"homie.rocks/venue-desk"`) copies it in, every file checked against the catalogue's SHA-256, and `parts_find` lists them even when the shared catalogue cannot be reached.
+
+## [0.58.21] - 2026-10-29
+
+**Plugin 0.58.15**
+
+Also released: `@homie-rocks/physics` 0.1.3 (README matches the code; the studio's optional peer pin follows) and `@homie-rocks/nav` 0.1.2 (package metadata), so every published version is exactly what this release packs.
+
+A check, a playtest, a deploy or the site on your computer keeps going when the app or the AI's connection that started it goes away.
+
+### Added
+
+- A shared **Venue desk** part (`parts/venue-desk`) for any venue: public `venue_info` (schema.org hours with time zone, holiday exceptions, policies, FAQ, contact), booking contact and confirmation on top of `studio_book` holds (`venue_booking_details`, `venue_booking_confirm`, `venue_booking_status`, `venue_booking_cancel`), a waitlist (`venue_waitlist_join`, `venue_waitlist_status`), and owner tools to edit the info, see the desk and offer a freed slot (`venue_info_set`, `venue_desk`, `venue_waitlist_offer`). Offers go to an outbox; Homie never sends them. Opt in by copying its one-line `tools/` files.
+
+### Fixed
+
+- Long jobs (a check, a playtest, a deploy, an npm install, `preview_run`'s site, a sign-in or a Stripe webhook) run under a small supervisor of their own, with their state in `.studio/mcp/<job>.json`. They outlive the MCP server that started them, so a host that runs the server once per tool call, or quitting Claude Desktop, no longer stops them; `studio_job` reads a job an earlier server started, and a job whose process is gone is reported as failed, never as still running. The site keeps running until `preview_stop`. A finished job's files are removed a day later, when the next job starts in that studio.
+- A studio made from 0.58.20 is recognised again by `homie-studio upgrade`: the template history now knows the five AGENTS.md sections (Apps, Commands, Making games, Servers and AI seats, Selling things) as 0.58.20 shipped them, so their untouched text is upgraded instead of being kept as the studio's own. Packing the toolkit now fails if the template history is behind its template (`scripts/studio-template-history.mjs --check`).
+- The toolkit's own `npm test`, run from `packages/studio` on a fresh install, builds the workspace first and no longer depends on the working directory, so the collision, round-idle and selling-bundle tests run there as they do from the repo root.
+
 ## [0.58.20] - 2026-10-26
 
 **Plugin 0.58.14**

package/bin/homie-studio.mjs

@@ -891,7 +891,7 @@ function unknownFlags(words, given) {
 async function main() {
   const [cmd, sub] = positional;
   if (!cmd || cmd === 'help' || flags.has('help')) {
-    const text = readFileSync(new URL(import.meta.url), 'utf8').split('*/')[0].split('\n').slice(1).map((l) => l.replace(/^ \* ?/, '')).join('\n');
+    const text = readFileSync(new URL(import.meta.url), 'utf8').split('*/')[0].split('\n').slice(1).filter((l) => l.trim() !== '/**').map((l) => l.replace(/^ \* ?/, '')).join('\n');
     process.stdout.write(`homie-studio ${STUDIO_VERSION}\n${text}\n`);
     return { ok: true, command: 'help' };
   }

package/guides/playtest/SKILL.md

@@ -19,7 +19,7 @@ A local review is labelled local, not independent. If a fresh reviewer was reque
 
 The question is never "does it run". It is: **would a stranger who pressed Play stay for a whole
 round, and come back?** Instruments measure what can be measured; a fresh reviewer who never saw
-the code answers the rest. A builder never grades its own work.
+the code answers the rest when the person asks for one.
 
 One script: `scripts/playtest.mjs` in this skill's folder (Claude Code:
 `node "${CLAUDE_PLUGIN_ROOT}/skills/playtest/scripts/playtest.mjs" <command>`), run from inside the
@@ -196,7 +196,7 @@ test, and the traps that make an instrument lie.
 
 ## Never
 
-- Never call a game good, fixed or finished from the code, a build that passed, or your own look at it.
+- Never call a game good, fixed or finished from the code or a build that passed: play it first, and label your own look as local.
 - Never report a local review as a blind one, and never read a BLOCKED or N/A row, or a missing review, as a pass.
 - Never turn one scripted round into a rule ("people cannot win", "input does not matter"): say what was measured, and run it again.
 - Never call the builder's local verdict an independent review: an independent reviewer is fresh every time.

package/guides/servers/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: servers
 description: Give a Homie studio game lasting servers - named communities with their own rooms and rules - humans-only, hybrid (seats reserved for AI companions), beginner (new players, AI guides, kids-safe) - plus agent passes, the AI skill dial, the party's level vote, and AI guides that talk (a game vocabulary; Cloudflare's Clef decision model on the studio's Workers AI by default, Llama or the owner's key instead, Clef on the person's own computer under dev, or the owner's own Claude in a seat). Use when someone asks for servers, realms or shards, human-only play, AI party members or companions, guides or helpers for new players or kids, guides that answer "help me with this quest", "fill empty spots with AI", letting Claude play as a guide, which model the guides think with, testing an agents.json, free local AI guides, or how strong the bots should be.
-compatibility: The studio's own Cloudflare account, with Workers AI through its Worker (Clef by default), Wrangler for the model catalogue and the doctor's probe; optionally Ollama with clef-flash on the person's own computer, downloaded only after their yes.
+compatibility: The studio's own Cloudflare account, with Workers AI through its Worker (Clef by default), Wrangler for the model catalogue and the doctor's probe; optionally Ollama with clef-flash on the person's own computer, downloaded when they want it.
 metadata:
   providers: cloudflare ollama
 ---
@@ -36,7 +36,7 @@ Rooms currently hold at most 32 seats; a named server is a pool of rooms, not a
 | "Close that server" | `servers close <game> <server>` (`server_close`) | ASKED; its rooms finish their round, then everyone leaves with a thank-you. `--reopen` opens it again at once. Closing `public` hides Quick play: Play then shows the servers to pick from. |
 | "Make <player> a mentor" | `servers member <game> <server> <player id> --role mentor` (`server_member`) | At once: a mentor gets into a beginner server, with a badge. `--remove` is an ASK. |
 | "Can we sell things on this server?" / "a shop for the kids server" | nothing to run: the shop skill (`shop.json`) | A kids server (`--kids`) never shows a shop, takes no purchase and shows no supporter badges; a beginner server never offers, or counts as owned, an item with `"advantage": true`. Every other server shows the studio's shop sheet from the room button and the game's `shop.open()`. These are the protective shop preset defaults; the studio can edit policy in shop.json. |
-| "Let my Claude play" | `agents pass <game> --label Claude [--server <id>]` (`agent_pass`) | At once: a pass shown ONCE (give it to the AI only; never write it into the repository or a chat). The AI sits with `POST /<game>/api/agent` (`Authorization: Bearer <pass>`), only in a room with people in it, as "Claude · AI", on an open, hybrid or beginner server. `agents revoke <id>` ends it (the AI leaves at once). |
+| "Let my Claude play" | the local MCP's `agent_sit { game, server }`, or the studio's `/mcp` `agent_sit` for a signed-in person's AI (no pass); for an AI with no MCP, `agents pass <game> --label Claude [--server <id>]` (`agent_pass`) | At once: a pass shown ONCE (give it to the AI only; never write it into the repository or a chat). The AI sits with `POST /<game>/api/agent` (`Authorization: Bearer <pass>`), only in a room with people in it, as "Claude · AI", on an open, hybrid or beginner server. `agents revoke <id>` ends it (the AI leaves at once). |
 
 ## Guides that talk (0.17.0)
 
@@ -66,9 +66,9 @@ signed in). Pick one that is not marked Workers Paid; the doctor's Workers AI ro
 **Under `homie-studio dev`** guides, chat review and game decisions think with Clef on this computer when Ollama (0.35.1 or
 later) has `clef-flash` (free, nothing sent to Cloudflare; `dev --no-local-ai` turns it off), else from the script;
 `dev --remote-ai` uses the real Workers AI (billed). The doctor's "Clef on this computer" row says what is there.
-**Ask first.** Nothing downloads a model by itself: before `ollama pull clef-flash`, tell the person it downloads about
-11 GB (`clef`, the 27B, about 18 GB) and wait for their yes. Never pull it to make a test pass; the Homie mod (Claude Code) and
-Homie's hooks (Codex) hold the pull until they say Proceed.
+**Pull it when they want it.** `ollama pull clef-flash` downloads about 11 GB (`clef`, the 27B, about 18 GB): pull it
+when the person wants Clef on this computer, saying the size in the same line, not to make a test pass. Homie's hooks
+show the size as a one-line note; they do not hold the pull.
 **Adopting guides in an existing RPG** (zones, quests, a party): `node_modules/@homie-rocks/studio/agents/GUIDES.md`
 is the short path, in the game's own repository and with its owner's say.
 

package/guides/studio-setup/SKILL.md

@@ -67,16 +67,16 @@ few seconds, and never prints a key:
    wanted; the skill that needs it (`music`, `art`, `video`) offers it then. A "do this now" row you can
    do (`fix.run`, like `npx wrangler login` or `brew install ffmpeg`): run it yourself as part of setup. A row the person does on their own (`fix.open`) can be done any time, even while they wait
    for something else: give them the link. The optional "Clef on this computer" row is a large download:
-   say its size first (`ollama pull clef-flash`, about 11 GB) and run it only after their yes.
+   run it when they want Clef, saying its size in the same line (`ollama pull clef-flash`, about 11 GB).
 5. Run it again whenever they say they did something, and tick the row.
 6. **Homie's holds (Codex, Grok Build).** With `--client` the status has a `holds` row: whether Homie's
    hooks ran just now in this app (`"on": true`). When it is off, say so in one sentence in this first reply,
    with the row's fix. In Codex: "Homie's holds are off in this session: open `/hooks` and trust Homie's
-   three hooks. Until then I'll ask you before a deploy, a Cloudflare change, a paid call or a model
-   download." In Grok Build: "Homie's holds are off in this session: install the Homie plugin again with
-   `--trust` and start a new session. Until then I'll ask you before a deploy, a Cloudflare change, a paid
-   call or a model download." Then
-   do ask, every time, also when the app approves commands for you. When it is on, say nothing about it and
+   three hooks. Until then I'll ask you before a deploy you didn't ask for, a Cloudflare change or a paid
+   call." In Grok Build: "Homie's holds are off in this session: install the Homie plugin again with
+   `--trust` and start a new session. Until then I'll ask you before a deploy you didn't ask for, a Cloudflare
+   change or a paid call." Then
+   do ask, also when the app approves commands for you; a deploy the person asked for is already approved. When it is on, say nothing about it and
    change nothing: the hooks hold what they hold. A status with no `holds` row in Codex or Grok (a toolkit
    before 0.30.2) cannot tell: say the sentence anyway.
 
@@ -118,8 +118,8 @@ the status line only to someone who wants the line under the prompt as well.
 
 **Homie's holds in Codex.** In Codex, Homie's hooks hold what the mod holds in Claude Code: an edit to a
 file `studio.json` `"protect"` lists, a production deploy, a change to the studio's Cloudflare account
-outside its deploy, a paid call past the budget or whose cost cannot be read first, and a Clef model
-download; they refuse what the mod refuses, and take secrets out of what you read. Codex runs a plugin's
+outside its deploy, and a paid call past the budget or whose cost cannot be read first (a big file
+into git and a Clef model download only get a one-line warning); they refuse what the mod refuses, and take secrets out of what you read. Codex runs a plugin's
 hooks only after the person trusts them once: after installing Homie, tell them to open `/hooks` and
 trust Homie's three (until then nothing is held, so ask before each of those yourself). Never assume they
 are on: the setup status says which it is (item 6 above). A held call comes
@@ -134,7 +134,7 @@ and the Codex hooks ask, `hooks/lib/holds.mjs`) hold and refuse the same calls a
 of what you read. Grok runs a plugin's hooks only once the person has trusted the plugin (`grok plugin install
 homie-rocks/homie#plugins/homie --trust`, then a new session; `/hooks` lists them). Never assume they are on:
 the setup status with `--client grok` says which it is (item 6 above), and while it says off, before a
-production deploy, a Cloudflare change outside that deploy, a paid call, a model download or an edit to a file
+production deploy, a Cloudflare change outside that deploy, a paid call or an edit to a file
 `studio.json` `"protect"` lists, say what it would do in one sentence and wait for the person's yes, also when
 Grok approves commands by itself; and never repeat a key or a token you read. A held call comes back denied
 with a code, and the person answers `proceed <code>` or `cancel <code>` in their own message, as in Codex; then
@@ -280,7 +280,7 @@ Music, Videos, Rooms and Posts, each once the studio has something in it, in the
 1. `npx wrangler whoami` in the studio folder. Not signed in: run `npx wrangler login` and tell the
    person in one line that Cloudflare opened in their browser and they should approve it (their own account). That is their only step. Never ask for or write an API key.
 2. Before the first deploy, `npx --no-install homie-studio deploy --plan`, and tell them its gist in two
-   or three lines: the resources (one Worker, one D1 database, two Durable Objects; no R2), the cost
+   or three lines: the resources (one Worker with its Durable Objects and two Queues, one D1 database; no R2), the cost
    (on your account), and what the directory stores. Then go on.
 3. `npm run deploy`. It creates the Worker and the D1 database named in `studio.json`, applies
    migrations, deploys, and reads the live site once, which makes the site claim itself in the
@@ -381,7 +381,7 @@ there (checked by SHA-256, at the same addresses); `homie-studio media move --dr
 
 ## Never
 
-- Never jump ahead of the checklist, and never copy a starter or another studio's game into the studio
+- Never copy a starter or another studio's game into the studio
   unless the person asked for it.
 - Never read or copy from another studio in the same folder unless the person asks: it is somebody else's
   work.

package/lib/doctor.mjs

@@ -264,7 +264,7 @@ export async function setupStatus({
         : seen ? `off: Homie's hooks last ran in ${name} ${ago(seen.ageMs)} ago, and not for this session's calls`
           : `off: Homie's hooks have not run in ${name} on this computer`,
       ...(seen ? { seen: { at: new Date(seen.at).toISOString(), event: seen.event } } : {}),
-      unlocks: 'a wait for your own "proceed <code>" before a production deploy, an edit to a file the studio protects, a Cloudflare change outside the deploy, a paid call past the budget and a model download; and secrets taken out of what your AI reads',
+      unlocks: 'a wait for your own "proceed <code>" before a production deploy, an edit to a file the studio protects, a Cloudflare change outside the deploy, and a paid call past the budget; and secrets taken out of what your AI reads',
       fix: on ? null : {
         who: 'person',
         say: app === 'codex'

package/lib/job-runner.mjs

@@ -0,0 +1,133 @@
+/**
+ * THE PROCESS A JOB RUNS IN (lib/jobs.mjs starts it): a small supervisor, detached from the MCP server that started
+ * it (its own process group on macOS and Linux), so a job outlives that server. A host may run the server once per
+ * tool call, and the desktop app's server ends when the app quits; a check, a deploy, an npm install or the site
+ * here goes on either way, and the next server reads how it went.
+ *
+ * Its whole state is one file, .studio/mcp/<job>.json: what it runs, the supervisor's pid, each step's start, end,
+ * exit code and JSON result, and the job's own end. Each step's output goes to files beside it (<job>[.<n>].out and
+ * .err) and to <job>.log. The file is replaced whole (written aside, then renamed), so a reader never sees half.
+ *
+ * Steps run in order; a step that fails ends the job unless it is soft. With `feed`, the build's progress feed is
+ * ended when the job ends (what the MCP server would do), so a build card never stays "running" after its job.
+ *
+ * Usage: node job-runner.mjs <state file>. Nothing here ever runs a shell (a Windows .cmd shim aside).
+ */
+import { spawn } from 'node:child_process';
+import { appendFileSync, closeSync, existsSync, openSync, readFileSync, readSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const WIN = process.platform === 'win32';
+export const MAX_OUT = 4 * 1024 * 1024;
+
+/** The last JSON document a command printed (homie-studio --json prints one, pretty). */
+export function lastJson(text) {
+  const s = String(text ?? '').trim();
+  if (!s) return null;
+  try { return JSON.parse(s); } catch { /* look for the last top-level object */ }
+  for (let i = s.lastIndexOf('\n{'); i >= 0; i = s.lastIndexOf('\n{', i - 1)) {
+    try { return JSON.parse(s.slice(i + 1)); } catch { /* earlier */ }
+    if (i === 0) break;
+  }
+  return null;
+}
+
+export function readState(file) {
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+export function writeState(file, state) {
+  const aside = `${file}.${process.pid}.tmp`;
+  writeFileSync(aside, JSON.stringify(state));
+  renameSync(aside, file);
+}
+
+/** The last `bytes` of a file ('' when it is not there). */
+export function tailOf(file, bytes = 64 * 1024) {
+  if (!file) return '';
+  let fd;
+  try {
+    const size = statSync(file).size;
+    const n = Math.min(size, bytes);
+    if (!n) return '';
+    const buf = Buffer.alloc(n);
+    fd = openSync(file, 'r');
+    readSync(fd, buf, 0, n, size - n);
+    return buf.toString('utf8');
+  } catch { return ''; } finally { if (fd !== undefined) try { closeSync(fd); } catch { /* closed */ } }
+}
+
+/** A step's own words when it failed: its `why`, else its last lines, else its exit code. */
+export function stepWhy(step, { lines = 6 } = {}) {
+  if (step?.result?.why) return step.result.why;
+  const text = `${tailOf(step?.err, 16 * 1024)}\n${step?.json ? '' : tailOf(step?.out, 16 * 1024)}`.split('\n').map((l) => l.trimEnd()).filter(Boolean);
+  return text.slice(-lines).join('\n') || `exited with ${step?.code}`;
+}
+
+/** End a build's progress feed the way the MCP server does: pending stages skipped, then its end (once). */
+export function endFeed(Feed, root, build, state, note) {
+  try {
+    const feed = new Feed(root, build);
+    const doc = feed.doc;
+    if (!doc || doc.state !== 'running') return;
+    feed.change((d) => { for (const s of d.stages) if (s.state === 'pending') s.state = 'skipped'; });
+    feed.end(state, note);
+  } catch { /* the feed stays as it was */ }
+}
+
+async function supervise(file) {
+  const state = readState(file);
+  if (!state) process.exit(2);
+  state.pid = process.pid;
+  writeState(file, state);
+  let child = null;
+  let stopped = false;
+  const log = (d) => { try { appendFileSync(state.log, d); } catch { /* full disk: keep going */ } };
+  const stop = (signal) => {
+    if (stopped) return;
+    stopped = true;
+    try { child?.kill(signal); } catch { /* gone */ }
+  };
+  for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => stop(signal));
+  if (!WIN) process.on('SIGHUP', () => { /* the terminal or server that started it went away: carry on */ });
+  let failed = null;
+  for (const step of state.steps) {
+    if (stopped) break;
+    step.startedAt = new Date().toISOString();
+    writeState(file, state);
+    const code = await new Promise((done) => {
+      let outBytes = 0;
+      try {
+        child = spawn(step.cmd, step.args, { cwd: state.root, env: process.env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, shell: WIN && /\.cmd$/i.test(step.cmd) });
+      } catch (error) { appendFileSync(step.err, `\n${error.message}`); done(127); return; }
+      child.stdout.on('data', (d) => { if (outBytes < MAX_OUT) { outBytes += d.length; try { appendFileSync(step.out, d); } catch { /* keep going */ } } log(d); });
+      child.stderr.on('data', (d) => { try { appendFileSync(step.err, d); } catch { /* keep going */ } log(d); });
+      let ended = false;
+      const end = (c) => { if (!ended) { ended = true; done(c); } };
+      child.on('error', (error) => { try { appendFileSync(step.err, `\n${error.message}`); } catch { /* keep going */ } end(127); });
+      child.on('close', (c, signal) => end(c ?? (signal ? 128 + 15 : 1)));
+    });
+    child = null;
+    step.code = code;
+    step.endedAt = new Date().toISOString();
+    if (step.json) step.result = lastJson(existsSync(step.out) ? readFileSync(step.out, 'utf8') : '');
+    writeState(file, state);
+    if (code !== 0 && !step.soft) { failed = step; break; }
+  }
+  const ran = state.steps.filter((s) => s.endedAt);
+  const last = failed ?? ran.at(-1) ?? null;
+  state.code = stopped ? 143 : failed ? failed.code : 0;
+  state.result = last?.result ?? null;
+  state.stopped = stopped || undefined;
+  state.why = stopped ? 'it was stopped' : failed ? `${state.steps.length > 1 ? `${failed.label}: ` : ''}${stepWhy(failed)}` : null;
+  state.endedAt = new Date().toISOString();
+  writeState(file, state);
+  if (state.feed?.build) {
+    const { Feed } = await import('./progress.mjs');
+    endFeed(Feed, state.root, state.feed.build, stopped ? 'stopped' : failed ? 'failed' : 'passed', stopped ? `${state.feed.title ?? state.label}: stopped.` : failed ? state.why : `${state.feed.title ?? state.label}: done.`);
+  }
+  process.exit(0);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await supervise(process.argv[2]);

package/lib/jobs.mjs

@@ -10,13 +10,17 @@
  * install, Wrangler, esbuild), so commands always run with the first Node 22 or newer on the PATH. A GUI app's PATH
  * is short, so the usual places Node lives are added (Homebrew, nvm, Volta, asdf, fnm, the Node installer).
  *
- * Logs go to .studio/mcp/<job>.log in the studio (git-ignored). Nothing here ever runs a shell.
+ * A job outlives the server that started it (lib/job-runner.mjs supervises it, detached): its state is
+ * .studio/mcp/<job>.json and its logs .studio/mcp/<job>.log in the studio (git-ignored), which a later server reads.
+ * Nothing here ever runs a shell.
  */
 import { spawn, spawnSync } from 'node:child_process';
-import { appendFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { delimiter, dirname, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
+import { lastJson, readState, tailOf, writeState } from './job-runner.mjs';
 import { nodeHome } from './prepare.mjs';
 import { PACKAGE_ROOT } from './studio.mjs';
 
@@ -93,61 +97,215 @@ export function cliOf(root) {
 export const installed = (root) => existsSync(join(root, 'node_modules', '@homie-rocks', 'studio', 'package.json')) && existsSync(join(root, 'node_modules', 'wrangler'));
 
 const jobs = new Map();
-const MAX_OUT = 4 * 1024 * 1024;
+const RUNNER = fileURLToPath(new URL('./job-runner.mjs', import.meta.url));
+const JOB_ID = /^j_[a-f0-9]{12}$/;
+/** A finished job's files are kept this long, then removed when a later job starts in the same studio (pruneJobs). */
+export const JOB_KEPT_MS = 24 * 60 * 60_000;
+/** A job whose supervisor never wrote its pid this long after it was started never ran. */
+const NEVER_STARTED_MS = 60_000;
+export { lastJson };
+
+/** Is that process still there? (EPERM: it is, under another user.) */
+export function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return e?.code === 'EPERM'; }
+}
+
+/**
+ * Is `pid` still this job's own supervisor, not another process the system gave its number to later? Its command line
+ * names the job's state file (node job-runner.mjs <dir>/<job>.json): read from /proc on Linux, from ps elsewhere (once
+ * every few seconds per job). Where neither can say (Windows, no ps), a live pid is taken as the job's.
+ */
+export function jobAlive(pid, id, job = null) {
+  if (!alive(pid)) return false;
+  if (WIN || !JOB_ID.test(String(id ?? ''))) return true;
+  const now = Date.now();
+  if (job?.seen && job.seen.pid === pid && now - job.seen.at < 5000) return job.seen.ok;
+  let ok = true;
+  try {
+    if (process.platform === 'linux') ok = readFileSync(`/proc/${pid}/cmdline`, 'utf8').includes(`${id}.json`);
+    else {
+      const r = spawnSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000, windowsHide: true });
+      if (!r.error) ok = r.status === 0 && r.stdout.includes(`${id}.json`);
+    }
+  } catch { ok = alive(pid); }
+  if (job) job.seen = { pid, at: now, ok };
+  return ok;
+}
+
+/**
+ * Remove the files of this studio's jobs that ended more than JOB_KEPT_MS ago (state, log, output), and of ones whose
+ * process went without an end that long ago; also a left-over file with no state beside it (an older toolkit's log, a
+ * write cut short) that old. Called when a job starts: no process of its own. A running job's files are never touched.
+ */
+export function pruneJobs(dir, now = Date.now()) {
+  let names = [];
+  try { names = readdirSync(dir); } catch { return 0; }
+  const byJob = new Map();
+  for (const n of names) {
+    const m = /^(j_[a-f0-9]{12})(?:\.|$)/.exec(n);
+    if (m) byJob.set(m[1], [...(byJob.get(m[1]) ?? []), n]);
+  }
+  let removed = 0;
+  for (const [id, files] of byJob) {
+    if (jobs.get(id) && !jobs.get(id).endedAt) continue;
+    let old;
+    if (files.includes(`${id}.json`)) {
+      const s = readState(join(dir, `${id}.json`));
+      if (!s) continue;
+      const ended = Date.parse(s.endedAt ?? '');
+      const started = Date.parse(s.startedAt ?? '');
+      old = Number.isFinite(ended) ? now - ended > JOB_KEPT_MS : Number.isFinite(started) && now - started > JOB_KEPT_MS && !jobAlive(s.pid, id);
+    } else {
+      old = files.every((n) => { try { return now - statSync(join(dir, n)).mtimeMs > JOB_KEPT_MS; } catch { return false; } });
+    }
+    if (!old) continue;
+    for (const n of files) try { rmSync(join(dir, n), { force: true }); removed++; } catch { /* next time */ }
+  }
+  return removed;
+}
+
+/** A Node that can run the supervisor: the system's, else this one (the Claude app's own, as plain Node). */
+function runnerNode(env) {
+  const node = findNode();
+  if (node) return { bin: node.bin, env };
+  return { bin: process.execPath, env: process.versions.electron ? { ...env, ELECTRON_RUN_AS_NODE: '1' } : env };
+}
+
+/** A job as this process sees it: its state file read again; its output read from its files when asked. */
+function jobFrom(file, extra = {}) {
+  const job = { stateFile: file, child: null, done: null, onEnd: null, steps: [], ...extra };
+  Object.defineProperty(job, 'out', { enumerable: true, get: () => (job.json ? '' : job.steps.map((s) => tailOf(s.out)).join('')) });
+  Object.defineProperty(job, 'err', { enumerable: true, get: () => job.steps.map((s) => tailOf(s.err)).join('').slice(-64 * 1024) });
+  return refreshJob(job);
+}
 
 /**
- * Start one process for a studio. `json`: the command prints a JSON result on stdout (homie-studio --json), kept
- * as job.result. `onEnd(job)` runs once when it exits.
+ * Read a job's state file again. A job whose supervisor is gone without having written its end (killed, or the
+ * computer restarted) is ended here as failed, and its file says so: no one is handed the id of a dead job as running.
  */
-export function startJob({ root, label, cmd, args, env = toolEnv(), json = false, onEnd = null, keep = false }) {
+const now = () => Date.now();
+export function refreshJob(job) {
+  if (job.endedAt && job.final) return job;
+  const s = readState(job.stateFile);
+  if (!s) return job;
+  Object.assign(job, { id: s.id, label: s.label, root: s.root, args: s.args, json: s.json, startedAt: s.startedAt, log: s.log, steps: s.steps, feed: s.feed ?? null, endsWithServer: Boolean(s.endsWithServer) });
+  job.pid = s.pid ?? job.pid ?? null;
+  if (s.endedAt) {
+    Object.assign(job, { endedAt: s.endedAt, code: s.code, result: s.result ?? null, why: s.why ?? null, final: true });
+    return job;
+  }
+  const neverStarted = !job.child && !job.pid && now() - Date.parse(s.startedAt ?? '') > NEVER_STARTED_MS;
+  if (neverStarted || (!job.child && job.pid && !jobAlive(job.pid, s.id, job))) {
+    s.code = 1;
+    s.why = neverStarted ? 'the job\'s process never started' : 'the job\'s process ended without finishing (it was stopped, or the computer restarted)';
+    s.endedAt = new Date().toISOString();
+    for (const st of s.steps) if (st.startedAt && !st.endedAt) { st.endedAt = s.endedAt; st.code = 1; try { appendFileSync(st.err, `\n${s.why}\n`); } catch { /* read-only */ } }
+    try { writeState(job.stateFile, s); } catch { /* the view below still says it */ }
+    Object.assign(job, { endedAt: s.endedAt, code: s.code, result: null, why: s.why, steps: s.steps, final: true });
+  }
+  return job;
+}
+
+/**
+ * Start one job for a studio: one command, or `steps` run in order ([{ label, cmd, args, json, soft }]; a step that
+ * fails ends the job unless it is soft). It runs under lib/job-runner.mjs, detached, so it outlives this MCP server;
+ * its state is .studio/mcp/<job>.json, which any later server reads (getJob). `json`: the command prints a JSON result
+ * on stdout (homie-studio --json), kept as job.result. `onEnd(job)` runs once when it ends, if this process is still
+ * here then. `feed`: { build, title }, the progress feed the supervisor ends with the job. `endsWithServer`: stopped
+ * when this server ends (stopAllJobs) instead.
+ */
+export function startJob({ root, label, cmd, args, env = toolEnv(), json = false, onEnd = null, endsWithServer = false, steps = null, feed = null }) {
   const id = `j_${randomBytes(6).toString('hex')}`;
   const dir = join(root, '.studio', 'mcp');
   mkdirSync(dir, { recursive: true });
-  const log = join(dir, `${id}.log`);
-  appendFileSync(log, `$ ${[cmd, ...args].map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ')}\n`);
-  const child = spawn(cmd, args, { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, shell: WIN && /\.cmd$/i.test(cmd) });
-  const job = { id, label, root, args, pid: child.pid ?? null, startedAt: new Date().toISOString(), endedAt: null, code: null, out: '', err: '', log, result: null, json, keep, child };
+  pruneJobs(dir);
+  const base = join(dir, id);
+  const log = `${base}.log`;
+  const list = (steps ?? [{ label, cmd, args, json }]).map((st, n, all) => {
+    const name = all.length > 1 ? `${base}.${n}` : base;
+    return { label: st.label ?? label, cmd: st.cmd ?? cmd, args: st.args, json: Boolean(st.json), soft: Boolean(st.soft), out: `${name}.out`, err: `${name}.err`, startedAt: null, endedAt: null, code: null, result: null };
+  });
+  appendFileSync(log, list.map((st) => `$ ${[st.cmd, ...st.args].map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ')}\n`).join(''));
+  const stateFile = `${base}.json`;
+  const startedAt = new Date().toISOString();
+  writeState(stateFile, { v: 1, id, label, root, args: list[0].args, json: Boolean(list.at(-1).json), startedAt, endedAt: null, code: null, result: null, pid: null, log, steps: list, feed, endsWithServer });
+  const node = runnerNode(env);
+  const child = spawn(node.bin, [RUNNER, stateFile], { cwd: root, env: node.env, stdio: 'ignore', detached: true, windowsHide: true });
+  child.unref();
+  const job = jobFrom(stateFile, { child, onEnd, pid: child.pid ?? null });
+  jobs.set(id, job);
   let finish;
   job.done = new Promise((r) => { finish = r; });
-  child.stdout.on('data', (d) => { if (job.out.length < MAX_OUT) job.out += d; try { appendFileSync(log, d); } catch { /* full disk: keep going */ } });
-  child.stderr.on('data', (d) => { job.err = (job.err + d).slice(-64 * 1024); try { appendFileSync(log, d); } catch { /* keep going */ } });
   const end = (code) => {
-    if (job.endedAt) return;
-    job.code = code;
-    job.endedAt = new Date().toISOString();
-    if (json) job.result = lastJson(job.out);
+    if (job.final) { finishOnce(); return; }
+    job.child = null;
+    refreshJob(job);
+    if (!job.endedAt) Object.assign(job, { endedAt: new Date().toISOString(), code: code === 0 ? 1 : code ?? 1, result: null, final: true });
+    finishOnce();
+  };
+  let finished = false;
+  const finishOnce = () => {
+    if (finished) return;
+    finished = true;
     job.child = null;
     try { onEnd?.(job); } catch { /* the job's own result stands */ }
     finish(job);
   };
-  child.on('error', (error) => { job.err += `\n${error.message}`; end(127); });
-  child.on('close', (code) => end(code ?? 1));
-  jobs.set(id, job);
+  child.on('error', (error) => { for (const st of job.steps) try { appendFileSync(st.err, `\n${error.message}`); } catch { /* keep going */ } end(127); });
+  child.on('close', (code) => end(code));
   return job;
 }
 
-/** The last JSON document a command printed (homie-studio --json prints one, pretty). */
-export function lastJson(text) {
-  const s = String(text ?? '').trim();
-  if (!s) return null;
-  try { return JSON.parse(s); } catch { /* look for the last top-level object */ }
-  for (let i = s.lastIndexOf('\n{'); i >= 0; i = s.lastIndexOf('\n{', i - 1)) {
-    try { return JSON.parse(s.slice(i + 1)); } catch { /* earlier */ }
-    if (i === 0) break;
+/** Each step of a job that has started, as a job of its own (what a build card lists); its `done` is the job's. */
+export function stepJobs(job) {
+  refreshJob(job);
+  return (job.steps ?? []).filter((s) => s.startedAt).map((s) => {
+    const step = { id: job.id, label: s.label, root: job.root, args: s.args, startedAt: s.startedAt, endedAt: s.endedAt ?? (job.endedAt && !s.endedAt ? job.endedAt : null), code: s.code ?? (job.endedAt ? job.code : null), result: s.result ?? null, json: s.json, log: job.log, steps: [s], done: job.done };
+    Object.defineProperty(step, 'out', { enumerable: true, get: () => (s.json ? '' : tailOf(s.out)) });
+    Object.defineProperty(step, 'err', { enumerable: true, get: () => tailOf(s.err) });
+    return step;
+  });
+}
+
+/** A job by its id: this server's, else one an earlier server started in one of `roots` (its .studio/mcp). */
+export function getJob(id, { roots = [] } = {}) {
+  const key = String(id ?? '');
+  const known = jobs.get(key);
+  if (known) return refreshJob(known);
+  if (!JOB_ID.test(key)) return null;
+  for (const root of new Set(roots.filter(Boolean))) {
+    const file = join(root, '.studio', 'mcp', `${key}.json`);
+    if (!existsSync(file)) continue;
+    const job = jobFrom(file);
+    if (!job.id) continue;
+    jobs.set(key, job);
+    return job;
   }
   return null;
 }
 
-export const getJob = (id) => jobs.get(String(id ?? '')) ?? null;
-export const runningJobs = (root) => [...jobs.values()].filter((j) => !j.endedAt && (!root || j.root === root));
+/** The jobs still running: this server's, and (for a studio) any an earlier server started there. */
+export function runningJobs(root) {
+  if (root) {
+    let names = [];
+    try { names = readdirSync(join(root, '.studio', 'mcp')).filter((n) => /^j_[a-f0-9]{12}\.json$/.test(n)); } catch { /* none yet */ }
+    for (const n of names) getJob(n.slice(0, -5), { roots: [root] });
+  }
+  return [...jobs.values()].map(refreshJob).filter((j) => !j.endedAt && (!root || j.root === root));
+}
 
 /** Wait for a job at most `ms`; true when it ended. */
 export async function waitJob(job, ms) {
-  if (job.endedAt) return true;
-  let t;
-  const ended = await Promise.race([job.done.then(() => true), new Promise((r) => { t = setTimeout(() => r(false), ms); })]);
-  clearTimeout(t);
-  return ended;
+  const until = Date.now() + ms;
+  refreshJob(job);
+  while (!job.endedAt && Date.now() < until) {
+    let t;
+    await Promise.race([...(job.done ? [job.done] : []), new Promise((r) => { t = setTimeout(r, Math.max(1, Math.min(500, until - Date.now()))); })]);
+    clearTimeout(t);
+    refreshJob(job);
+  }
+  return Boolean(job.endedAt);
 }
 
 /** What a person (and the model) is told about a job. */
@@ -184,10 +342,15 @@ export function installJob(root, opts = {}) {
   return startJob({ root, label: 'npm install (the studio\'s pinned toolkit and Wrangler)', ...npmInvocation(node), ...opts });
 }
 
-/** When the server ends (the app quit), nothing it started keeps running, except what asked to (none today). */
+/**
+ * When the server ends (the app quit, or a host's one-call server is done): the jobs it started go on (each under its
+ * own supervisor, lib/job-runner.mjs) and the next server reads them; only one that asked (endsWithServer) is stopped,
+ * with everything it started (its process group).
+ */
 export function stopAllJobs() {
   for (const job of jobs.values()) {
-    if (job.endedAt || !job.child || job.keep) continue;
-    try { job.child.kill('SIGTERM'); } catch { /* gone */ }
+    // Only its own supervisor's process group: never a process that has the number since.
+    if (job.endedAt || !job.endsWithServer || !jobAlive(job.pid, job.id, job)) continue;
+    try { process.kill(WIN ? job.pid : -job.pid, 'SIGTERM'); } catch { try { process.kill(job.pid, 'SIGTERM'); } catch { /* gone */ } }
   }
 }

package/lib/local-ai.mjs

@@ -8,8 +8,8 @@
  *                           a guide's seat that thinks on this computer every few seconds, with no AI turn per decision
  *   homie-studio doctor     says what is there, and what one sentence gets the rest
  *
- * It never downloads a model. `ollama pull clef-flash` is about 11 GB (clef, the 27B, about 18 GB): the person says yes
- * first, every time (the studio skill asks and names the size). It needs Ollama 0.35.1 or later (the first with Clef).
+ * It never downloads a model. `ollama pull clef-flash` is about 11 GB (clef, the 27B, about 18 GB): pulled when the
+ * person wants Clef here, with the size said in the same line. It needs Ollama 0.35.1 or later (the first with Clef).
  */
 
 export const OLLAMA_BASE = 'http://127.0.0.1:11434';