@ogygia/cli 0.11.5 → 0.13.0

package/ai/SKILL.md

@@ -147,12 +147,12 @@ Each island is its own hydration root. Props cross by **value** (devalue), never
 ## Timing and nesting
 
 - `interaction` on an island: zero JS until first pointer/key/focus **inside** the region. The waking click is captured and replayed; typing survives; hover prefetches the chunk. Caveat: the replayed event is not a trusted gesture — `window.open`/clipboard/fullscreen will be blocked; detect with `hydratedBy() === 'interaction'` and render e.g. a real `<a target="_blank">`.
-- `interaction` on a server island = an **on-demand hole**: zero bytes until the visitor shows intent inside it — the first hover (`pointerover`, which bubbles through the boxless `display:contents` wrapper from a child), focus, touch, or key — then ONE fetch, **morphed** in so what the visitor already opened in the static fallback stays open (no click capture/replay — the fallback handles the gesture natively). Hover is the trigger, so the HTML is usually there before the visitor reaches a submenu. To have it there BEFORE the first hover, add `prefetch: 'idle'` (or `load` / `visible` / a media query — deferred-only, never `interaction`): the HTML is warmed into the frame store at that schedule and the hover swaps from it with no request. The shape for a mega menu: fallback = the menu's L1/L2 (today's SSR HTML, byte-identical), hole = the same menu with L3/L4 rendered on the server — no L4 in the initial HTML, no menu JS, no feed download in the browser.
+- `interaction` on a server island = an **on-demand hole**: zero bytes until the visitor shows intent inside it — the first hover (`pointerover`, which bubbles through the boxless `display:contents` wrapper from a child), focus, touch, or key — then ONE fetch, **morphed** in so what the visitor already opened in the static fallback stays open (no click capture/replay — the fallback handles the gesture natively). Hover is the trigger, so the HTML is usually there before the visitor reaches a submenu. To have it there BEFORE the first hover, add `prefetch: 'idle'` (or `load` / `visible` / a media query — deferred-only, never `interaction`): the HTML is warmed into the frame store at that schedule and the hover swaps from it with no request. The shape for a nav menu: fallback = the menu's L1/L2 (today's SSR HTML, byte-identical), hole = the same menu with L3/L4 rendered on the server — no L4 in the initial HTML, no menu JS, no feed download in the browser.
 - Nesting — one rule, **closest marked parent decides**: island-in-island shares the parent's JS (one tree, child's schedule ignored, dev warns); lake-in-island stays static; island-in-lake wakes on its own; server-island-in-island renders inline (`deferred` ignored); an island inside a server island's `ogygiaFallback` is a full region that wakes on its own (the fallback belongs to the page, and a `keepFallback()`-kept fallback stays interactive).
 - **An island hydrates against its own server markup.** The element keeps the HTML it connected with; if another script edited the island while it slept (a design-system runtime stripping whitespace, an A/B tool, a translator) and Svelte's walk mismatches on wake, the runtime puts the server markup back and hydrates that (`data-og-healed`, dev warning) instead of re-rendering client-side; only a second failure falls back to Svelte's recovery (`data-og-recovered`). Foreign scripts should still leave `<ogygia-region>` subtrees alone — whatever they added is gone after a heal.
 - **A lake on a csr=true (Kit-hydrated) page is adopted, not hydrated.** Kit's pass keeps the lake's SSR element as opaque DOM (its component ships no client JS — not even in Kit's bundle), and everything authored INSIDE the lake stays in ogygia's world: islands and server islands there emit real regions and wake on the runtime. This is how a site header (static markup + `render: 'deferred'` personal holes + a `wake: 'interaction'` search) stays zero-JS-for-anonymous on csr=true pages too: mark the header import `with { wake: 'none' }` in the layout. Caveat: a lake first mounted during a Kit client-side navigation has no server HTML and renders empty (dev warns) — keep chrome lakes in a layout that persists, or serve the route csr=false. A hole rendered OUTSIDE a lake on a csr=true page is Kit-hydrated around; if Kit gives up hydrating the document (`Failed to hydrate`: a component threw) and mounts it fresh, the hole is rendered again with no address — the runtime restores it from the document's holes record (by identity, `data-og-hole`), so it still fetches; a hole rendered only in the browser has no record and keeps its fallback.
 - Dedupe: same component + same strategy/options = ONE wrapper module and ONE client chunk, however many instances (each instance still gets its own region + props payload).
-- A hole's timing is `fetch`, never `wake`: `with { render: 'deferred', fetch: 'visible' }`. Any `wake` on a `render: 'deferred'` import fails the build, naming the `fetch` to write; a `fetch` without `render: 'deferred'` fails too.
+- A hole's timing is `fetch`, never `wake`: `with { render: 'deferred', fetch: 'visible' }`. A `wake` on a `render: 'deferred'` import is deprecated: it still times the hole, with a build warning naming the `fetch` to write (both at once fails); a `fetch` without `render: 'deferred'` fails too.
 
 ## csr=false lifecycle rules
 
@@ -317,7 +317,7 @@ CLI (`@ogygia/cli`; `npx ogygia …` runs it): `npx ogygia init` · `site init`
 - **Programmatic routes** take the same `config` in table grammar: `page(C, { config: { postrender: false } })`, `layout(name, C, { config })`, `routes(table, { config })` — merged table → layouts → page. The table registers a matcher at construction; the handle asks it for any request Kit's file router didn't claim (`route.id` null under `sequence(postrender.handle(), ogygia.handle(), app.handle)`, or a catch-all `+server.ts`). Endpoint routes and unclaimed paths follow the vite-config default. The router's default `cache-control: no-store` document stamp yields to the verdict on eligible requests (stored → `public, s-maxage`; refused → `private, no-store`; an explicit page header always wins).
 - Invalidation (any server code, e.g. a CMS webhook endpoint; reaches the store/edges `postrender.handle()` was given): `postrender.invalidate('/fr/fr/solar/')` (exact URL), `postrender.invalidateWhere({ prefix: '/fr/fr/' })` (subtree = locale/section nuke), `postrender.invalidate(fn, [args])` (declared sources).
 - Declared sources (the reverse index): `export const loadDoc = import.meta.og.source(async (…) => …)` — top-level `export const` only (macro laws). Every page whose render calls it files a receipt; `invalidate(loadDoc, [args])` evicts exactly the consuming pages, at origin AND every edge. `{ key: (…args) => string }` canonicalizes exotic args.
-- Stores: `memoryStore` (default) · `valkey(client)` · `upstash({ url, token })` · `cloudflareKv(binding)`. Edges: `akamai(cfg)` · `cloudfront(cfg)` · `cloudflare(cfg)`. Fan-out is allSettled inside ogygia — one edge down never fails a publish or a request.
+- Stores: `new MemoryStore()` (default) · `new ValkeyStore(client)` · `new UpstashStore({ url, token })` · `new CloudflareKvStore(binding)`. Edges: `new AkamaiEdge(cfg)` · `new CloudFrontEdge(cfg)` · `new CloudflareEdge(cfg)`. Fan-out is allSettled inside ogygia — one edge down never fails a publish or a request.
 - The vary law is the cookie-less CDN key, formalized: DEFAULT-valued reads still store (that render IS the canonical), and once minted everyone gets the canonical copy. Truly per-visitor content belongs in a deferred hole; A/B'd pages auto-disqualify on any flag read.
 - Eligible responses are stamped `cache-control: public, s-maxage=<ttl>` plus each edge's tags (Akamai/Cloudflare prefix tags), so CDNs follow proven per-page headers instead of blanket rules. csr=true pages store the same — Kit hydrates the stored copy.
 - **Self-freshening header on a stored page** (SSR'd, no deferred fallback): mark the component `with { render: 'live', wake: 'load' }` INSIDE a small island host — its HTML bakes into the stored bytes, and on served-from-store documents (the handle stamps a doc marker) it revalidates on first mount: a fresh server render with the visitor's cookies, swapped in. Anonymous traffic mints the canonical (default-valued reads store). A live region at page top level OUTSIDE any island bakes once and never revalidates — always give it an island host (dev warns).

package/dist/mcp.js

@@ -1,5 +1,7 @@
+import { line } from "./messages.js";
 import { createInterface } from "node:readline";
 import { createRequire } from "node:module";
+import { STALE, flights, scope } from "@ogygia/machine";
 import { gzipSync } from "node:zlib";
 import { readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
@@ -22,15 +24,18 @@ import { CLIENT_BINDING_STUB, collect_flag_sites, flags_manifest, islandVirtualI
 * @packageDocumentation
 */
 let profiler_reading;
-async function load_profiler_reading() {
-	if (profiler_reading !== void 0) return profiler_reading;
-	try {
+/** The reading's load, kept once it lands; a failed one (the plugin not installed yet) is not kept,
+*  so the next call loads it, with no restart of this long-lived server (#295). */
+const reading_load = flights({
+	name: "profiler report reading",
+	run: async () => {
 		const from_app = createRequire(path.join(process.cwd(), "package.json"));
-		profiler_reading = await import(pathToFileURL(from_app.resolve("@ogygia/devtools/report")).href);
-	} catch {
-		profiler_reading = null;
+		return profiler_reading = await import(pathToFileURL(from_app.resolve("@ogygia/devtools/report")).href);
 	}
-	return profiler_reading;
+});
+async function load_profiler_reading() {
+	const got = await reading_load.get().catch(() => null);
+	return got === STALE ? null : got;
 }
 const TRAILING_SLASH_RE = /\/$/;
 const HTTP_URL_RE = /^https?:\/\//i;
@@ -243,7 +248,7 @@ const TOOLS = [
 	},
 	{
 		name: "ogygia_profile",
-		description: "Profile the SERVER-SIDE render of a route — runs the whole thing itself, nothing to download. ASK THE USER which URL to profile before calling (they prefer to name the host): a full URL like `http://localhost:5173/fr/fr` (local) or `https://app.com/fr/fr` (remote). Pass it as `url`. A bare path is accepted too, but then the tool just asks you for the URL (and lists any local server it can see). Records N renders and returns a digest: verdict (compute- vs io-bound), render p50, CPU findings, time-by-category, hottest functions + components (Svelte names each after its file), network, heap. Self-heals a stuck session (auto /reset + retry). Requires the profiler turned on: `devtools({ profiler: true })` from `@ogygia/devtools/vite` in the app’s vite.config (the tool tells you how if missing). Prod build = real numbers; dev is indicative (the digest says which). For a report you already downloaded, use ogygia_profile_open.",
+		description: "Profile the SERVER-SIDE render of a route — runs the whole thing itself, nothing to download. ASK THE USER which URL to profile before calling (they prefer to name the host): a full URL like `http://localhost:5173/fr/fr` (local) or `https://app.com/fr/fr` (remote). Pass it as `url`. A bare path is accepted too, but then the tool just asks you for the URL (and lists any local server it can see). Records N renders and returns a digest: verdict (compute- vs io-bound), render p50, CPU findings, time-by-category, hottest functions + components (Svelte names each after its file), network, heap. Clears a stale session (auto /reset + retry); leaves a live recording alone and says the profiler is busy. Requires the profiler turned on: `devtools({ profiler: true })` from `@ogygia/devtools/vite` in the app’s vite.config (the tool tells you how if missing). Prod build = real numbers; dev is indicative (the digest says which). For a report you already downloaded, use ogygia_profile_open.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -359,7 +364,7 @@ function tool_compile(args) {
 	try {
 		out = compile(source, filename, true, csr);
 	} catch (e) {
-		return fail(`[ogygia] transform error:\n${e instanceof Error ? e.message : String(e)}`);
+		return fail(line("cli_transform_failed", { error: e instanceof Error ? e.message : String(e) }));
 	}
 	const map = out.islands.length ? out.islands.map((i) => `- ${i.component} (as ${i.local}) — ${i.strategy}${i.id ? ` · id ${i.id.slice(0, 8)}` : ""}`).join("\n") : "(no marked components — the whole file is free server HTML)";
 	const structured = JSON.stringify({
@@ -380,7 +385,7 @@ function tool_islands(args) {
 	try {
 		out = compile(source, "App.svelte", true, false);
 	} catch (e) {
-		return fail(`[ogygia] transform error:\n${e instanceof Error ? e.message : String(e)}`);
+		return fail(line("cli_transform_failed", { error: e instanceof Error ? e.message : String(e) }));
 	}
 	const structured = out.islands.map((i) => ({
 		component: i.component,
@@ -415,7 +420,7 @@ function tool_explain(args) {
 	try {
 		out = compile(source, "App.svelte", true, false);
 	} catch (e) {
-		return fail(`[ogygia] transform error:\n${e instanceof Error ? e.message : String(e)}`);
+		return fail(line("cli_transform_failed", { error: e instanceof Error ? e.message : String(e) }));
 	}
 	if (!out.islands.length) return text("This component marks nothing, so it ships as pure server HTML — zero JavaScript, no islands.");
 	const lines = out.islands.map((i) => {
@@ -815,14 +820,15 @@ const LOCAL_PORTS = [
 /** fetch with a hard deadline — a hung server can't wedge the tool. */
 async function fetch_timeout(url, opts, ms) {
 	const ac = new AbortController();
-	const t = setTimeout(() => ac.abort(), ms);
+	const deadline = scope();
+	deadline.timeout(() => ac.abort(), ms);
 	try {
 		return await fetch(url, {
 			...opts,
 			signal: ac.signal
 		});
 	} finally {
-		clearTimeout(t);
+		deadline.close();
 	}
 }
 /** Probe localhost ports in parallel for a MOUNTED profiler; returns hits in priority order. */
@@ -842,6 +848,17 @@ async function find_local_profiler(base, key) {
 	return (await Promise.all(probes)).filter((o) => !!o);
 }
 const NOT_MOUNTED = (base, where) => `The profiler is not mounted at ${base} on ${where}. Install @ogygia/devtools and turn it on in vite.config.ts:\n\n  import { devtools } from '@ogygia/devtools/vite';\n  plugins: [ogygia(), devtools({ profiler: true /* or { secret, path, … } */ }), sveltekit()]\n\nogygia.handle() mounts it for you — no hooks wiring needed. Restart the server, then retry.`;
+/** The holder a 409 names: null when it names none (an older profiler, or a body that is not its). */
+async function busy_holder(res) {
+	try {
+		return (await res.json()).holder ?? null;
+	} catch {
+		return null;
+	}
+}
+function busy_message(origin, holder) {
+	return `The profiler on ${origin} is busy: ${holder ? `a ${holder.kind === "window" ? "recording window" : holder.kind === "background" ? "background capture" : "page profile"} started ${Math.round(holder.age_ms / 1e3)}s ago` : "another recording"} holds it, and it may be someone else's, so ogygia_profile leaves it alone. Wait for it to end and retry (the dashboard's Reset takes it over, if it is yours and stuck).`;
+}
 async function tool_profile(args) {
 	const raw = String(args.url ?? "").trim();
 	if (!raw) return fail("`url` is required — a route path like `/fr/fr` (profiles your local running server), or a full URL like `https://app.com/fr/fr` (profiles that host).");
@@ -895,19 +912,23 @@ async function tool_profile(args) {
 		const aborted = e instanceof Error && e.name === "AbortError";
 		return fail(aborted ? `Recording ${route} on ${origin} took over 90s and was aborted. Try fewer \`runs\`, or if this host times out (serverless), download the .ogp from ${origin}${profiler_base} and open it with ogygia_profile_open.` : `Recording failed: ${e instanceof Error ? e.message : String(e)}`);
 	}
-	if (res.status === 409) try {
-		await fetch_timeout(new URL(origin + profiler_base + "/reset"), {
-			redirect: "manual",
-			headers: key ? { "x-profiler-key": key } : {}
-		}, 5e3);
-		res = await record_once();
-	} catch {}
+	if (res.status === 409) {
+		const holder = await busy_holder(res);
+		if (holder?.stale !== true) return fail(busy_message(origin, holder));
+		try {
+			await fetch_timeout(new URL(origin + profiler_base + "/reset"), {
+				redirect: "manual",
+				headers: key ? { "x-profiler-key": key } : {}
+			}, 5e3);
+			res = await record_once();
+		} catch {}
+		if (res.status === 409) return fail(busy_message(origin, await busy_holder(res)));
+	}
 	if ((res.headers.get("content-type") ?? "").includes("application/json")) {
 		await load_profiler_reading();
 		return text(render_profile(origin, await res.json()));
 	}
 	const body = (await res.text()).replace(HTML_TAG_G, " ").replace(WS_G, " ").trim().slice(0, 300);
-	if (res.status === 409) return fail(`A profile is already running on ${origin} and /reset didn’t clear it. It auto-heals after ~2 min — wait and retry.`);
 	if (res.status === 401 || res.status === 403) return fail(`The profiler on ${origin} is locked. Pass its secret as \`key\` (ask the user for it).`);
 	return fail(`profiler did not return JSON (HTTP ${res.status}). ${body || "(check the profiler key / route path)"}`);
 }
@@ -1141,6 +1162,7 @@ async function tool_fragment(args) {
 	}
 	return text(`# ogygia fragment probe — ${origin}\n\n- routes endpoint (\`/og/fragment/page\`): ${posture}\n\n## Widgets (\`__catalog\`)\n${widgets_block}`);
 }
+/** Run one tool, as the server does for a `tools/call`. @internal Exported for tests. */
 async function dispatch_tool(name, args) {
 	switch (name) {
 		case "ogygia_compile": return tool_compile(args);
@@ -1242,4 +1264,4 @@ async function runMcp() {
 		}
 	}
 }
-export { render_profile, runMcp };
+export { dispatch_tool, load_profiler_reading, render_profile, runMcp };

package/dist/messages.js

@@ -0,0 +1,75 @@
+import { define_messages, prose } from "@ogygia/core/internal/messages";
+// src/messages.ts
+/**
+* EVERY MESSAGE THE CLI PRINTS AS AN OGYGIA MESSAGE, in one place: its code, its wording, what to do
+* about it (core's `@ogygia/core/internal/messages` says how the system works).
+*
+*   fail(line('cli_transform_failed', { error }));
+*
+* The CLI runs in Node, never in a page, so the wording always prints, then the code's page. (The
+* commands' own usage lines and `✗` failures are terminal output, not messages.)
+*/
+/** The errors: `throw new OgygiaError(code, args)`, or `line(code, args)` where an error is answered
+*  as text (an MCP tool's result). */
+const CLI_ERRORS = {
+	cli_transform_failed: {
+		text: (a) => prose`
+			transform error:
+
+			${a.error}
+		`,
+		details: () => prose`
+			An MCP tool (\`ogygia_compile\`, \`ogygia_islands\`, \`ogygia_explain\`) ran ogygia's
+			transform on the component it was given, and the transform threw. \`error\` is the
+			transform's own message, which usually names the rule the component breaks and links its
+			page.
+		`
+	},
+	cli_server_port_busy: {
+		text: (a) => prose`
+			port ${a.port} (${a.url}) is still held by another process after ${a.ms} ms: the server
+			was not started.
+		`,
+		details: () => prose`
+			\`ogygia bisect\` starts each commit's server (\`--start\`) on the port of \`--url\`, and
+			waits for that port to be free first: a server still on it would answer the readiness
+			check, and bisect would measure that server instead of the commit's. Its own servers are
+			gone before the next one starts, so the process on the port is someone else's (a server
+			left running in another terminal, an earlier run): stop it, or point \`--url\` at a free
+			port.
+		`
+	},
+	cli_server_exited_early: {
+		text: (a) => prose`
+			the server (${a.cmd}) exited before it answered (${a.how}). Its last output:
+
+			${a.output || "(none)"}
+		`,
+		details: () => prose`
+			\`ogygia bisect\` started the commit's server with \`--start\` and it exited before
+			\`--url\` answered: a server that cannot take its port (EADDRINUSE), a build output that
+			is not there, or a crash on boot. Its output says which. The commit is skipped.
+		`
+	},
+	cli_server_not_ready: {
+		text: (a) => prose`
+			the server did not answer at ${a.url} within ${a.ms} ms, and was stopped. Its last output:
+
+			${a.output || "(none)"}
+		`,
+		details: () => prose`
+			\`ogygia bisect\` polls \`--url\` until the commit's server answers (any status under 500),
+			for up to \`--ready\` ms. A server that takes longer to boot needs a larger \`--ready\`; one
+			that listens on another port needs \`--url\` to name that port. The commit is skipped.
+		`
+	}
+};
+/** The warnings: `warn(code, args, ...rest)`. */
+const CLI_WARNINGS = {};
+const own = define_messages(CLI_ERRORS, CLI_WARNINGS);
+/** `throw new OgygiaError(code, args)`; `warn(code, args, ...rest)` logs; `line(code, args)` is the
+*  line as a string. */
+const OgygiaError = own.OgygiaError;
+const warn = own.warn;
+const line = own.line;
+export { CLI_ERRORS, CLI_WARNINGS, OgygiaError, line, warn };

package/dist/perf/cli.js

@@ -1,11 +1,15 @@
+import { OgygiaError } from "../messages.js";
 import { measure } from "./measure.js";
 import { verdict } from "./compare.js";
 import { markdown, summary } from "./report.js";
 import { bisect } from "./bisect.js";
+import { machine } from "@ogygia/machine";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { execSync, spawn } from "node:child_process";
+import { connect } from "node:net";
 import { tmpdir } from "node:os";
+import { setTimeout } from "node:timers/promises";
 // src/perf/cli.ts
 /**
 * `ogygia perf` and `ogygia bisect` — the runners around the pure modules. Loaded by the CLI on
@@ -92,29 +96,145 @@ function sh(cmd, cwd, timeout_ms) {
 		}
 	});
 }
-/** Start a server command, wait until `url` answers (or `ready_ms`), return a stopper. */
-async function serve(cmd, cwd, url, ready_ms) {
+const server_machine = machine()({
+	name: "bisect server",
+	initial: "spawning",
+	steps: {
+		spawning: [
+			"ready",
+			"stopping",
+			"exited_early"
+		],
+		ready: ["stopping", "exited_early"],
+		stopping: ["exited"],
+		exited_early: ["exited"],
+		exited: []
+	}
+});
+/** How long a stopped server has to exit on SIGTERM before its group gets SIGKILL. */
+const STOP_GRACE_MS = 1e4;
+/** `ms` later, or at once when `signal` aborts. Its timer holds the process open, as a wait the
+*  command itself awaits must (a scope's timer does not). */
+const sleep = (ms, signal) => setTimeout(ms, void 0, { signal }).catch((error) => {
+	if (!signal?.aborted) throw error;
+});
+/** Something accepts a connection at `host:port` (an HTTP server or not: either would get in the
+*  way of the readiness check). */
+function port_held(host, port) {
+	return new Promise((resolve) => {
+		const socket = connect({
+			host,
+			port
+		});
+		socket.setTimeout(1e3, () => (socket.destroy(), resolve(false)));
+		socket.once("connect", () => (socket.destroy(), resolve(true)));
+		socket.once("error", () => resolve(false));
+	});
+}
+/** The process group still has a process in it. */
+function group_alive(pid) {
+	try {
+		process.kill(-pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+}
+/**
+* Start a server command and wait until `url` answers (within `ready_ms`, the wait for a free
+* port included). Returns its stop, which resolves once the server's whole process group has
+* exited (SIGTERM, then SIGKILL after `grace_ms`). Throws when the port stays held, when the server
+* exits before it answers (with its output), or when it never answers (stopped first).
+*/
+async function serve(cmd, cwd, url, ready_ms, grace_ms = STOP_GRACE_MS) {
+	const deadline = Date.now() + ready_ms;
+	const at = new URL(url);
+	const host = at.hostname.replace(/^\[(.*)\]$/, "$1");
+	const port = Number(at.port) || (at.protocol === "https:" ? 443 : 80);
+	while (await port_held(host, port)) {
+		if (Date.now() >= deadline) throw new OgygiaError("cli_server_port_busy", {
+			url,
+			port,
+			ms: ready_ms
+		});
+		await sleep(200);
+	}
+	const m = server_machine.create();
+	let output = "";
+	const keep = (chunk) => {
+		output = (output + String(chunk)).slice(-65536);
+	};
+	const tail = () => output.split("\n").slice(-40).join("\n").trim();
 	const child = spawn(cmd, {
 		cwd,
 		shell: true,
-		stdio: "ignore",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
 		detached: true,
 		env: { ...process.env }
 	});
-	const stop = () => {
+	child.stdout?.on("data", keep);
+	child.stderr?.on("data", keep);
+	const closed = new Promise((r) => child.once("close", () => r()));
+	const pid = child.pid;
+	const signal_group = (sig) => {
 		try {
-			if (child.pid) process.kill(-child.pid, "SIGTERM");
+			if (pid !== void 0) process.kill(-pid, sig);
 		} catch {}
 	};
-	const until = Date.now() + ready_ms;
-	while (Date.now() < until) {
-		try {
-			if ((await fetch(url, { redirect: "manual" })).status < 500) return stop;
-		} catch {}
-		await new Promise((r) => setTimeout(r, 500));
+	let exit_seen = false;
+	const on_exit = async (how) => {
+		if (exit_seen) return;
+		exit_seen = true;
+		if (m.move("spawning", "exited_early", { how }) || m.move("ready", "exited_early", { how })) signal_group("SIGKILL");
+		while (pid !== void 0 && group_alive(pid)) await sleep(25);
+		await Promise.race([closed, sleep(1e3)]);
+		if (!m.move("stopping", "exited")) m.move("exited_early", "exited");
+	};
+	child.once("exit", (code, sig) => void on_exit(sig ? `signal ${sig}` : `code ${code}`));
+	child.once("error", (error) => {
+		keep(error.message);
+		on_exit(error.message);
+	});
+	const stop = async () => {
+		if (m.move("spawning", "stopping") || m.move("ready", "stopping")) {
+			signal_group("SIGTERM");
+			m.scope.timeout(() => signal_group("SIGKILL"), grace_ms);
+		}
+		await m.wait("exited");
+	};
+	if (await m.scope.task(async (signal) => {
+		while (Date.now() < deadline && !signal.aborted) {
+			try {
+				const res = await fetch(url, {
+					redirect: "manual",
+					signal: AbortSignal.any([signal, AbortSignal.timeout(2e3)])
+				});
+				await res.body?.cancel();
+				if (res.status < 500) return true;
+			} catch {}
+			await sleep(200, signal);
+		}
+		return false;
+	}) === true && m.move("spawning", "ready")) return stop;
+	const now = m.now;
+	if (now.kind === "exited_early") {
+		await m.wait("exited");
+		throw new OgygiaError("cli_server_exited_early", {
+			cmd,
+			how: now.how,
+			output: tail()
+		});
 	}
-	stop();
-	throw new Error(`server did not answer at ${url} within ${ready_ms} ms`);
+	await stop();
+	throw new OgygiaError("cli_server_not_ready", {
+		url,
+		ms: ready_ms,
+		output: tail()
+	});
 }
 async function runBisect(argv) {
 	const good = arg(argv, "--good");
@@ -143,7 +263,6 @@ async function runBisect(argv) {
 	}
 	process.stdout.write(`ogygia bisect · ${commits.length} commits between ${good.slice(0, 7)} and ${bad.slice(0, 7)} · page ${page}\n`);
 	const worktree = mkdtempSync(path.join(tmpdir(), "ogygia-bisect-"));
-	const running = { stop: null };
 	const measure_sha = async (sha) => {
 		try {
 			const dir = path.join(worktree, sha.slice(0, 12));
@@ -154,7 +273,7 @@ async function runBisect(argv) {
 				process.stdout.write(`  ${sha.slice(0, 7)}: build failed — skipped\n`);
 				return null;
 			}
-			running.stop = await serve(start, dir, url, ready_ms);
+			const stop = await serve(start, dir, url, ready_ms);
 			try {
 				return (await measure({
 					url,
@@ -163,8 +282,7 @@ async function runBisect(argv) {
 					key
 				})).pages[0].render_p50;
 			} finally {
-				running.stop();
-				running.stop = null;
+				await stop();
 			}
 		} catch (e) {
 			process.stdout.write(`  ${sha.slice(0, 7)}: ${e instanceof Error ? e.message : String(e)} — skipped\n`);
@@ -211,11 +329,10 @@ async function runBisect(argv) {
 		process.stdout.write(`\nfirst bad commit: ${result.culprit.slice(0, 7)} — ${subject}\n${result.last_good ? `last good: ${result.last_good.slice(0, 7)}\n` : ""}bar: ${result.bar.toFixed(1)} ms · ${result.steps.length} steps${result.skipped.length ? ` · skipped ${result.skipped.length}` : ""}\n`);
 		return 0;
 	} finally {
-		running.stop?.();
 		rmSync(worktree, {
 			recursive: true,
 			force: true
 		});
 	}
 }
-export { number_arg, runBisect, runPerf };
+export { number_arg, runBisect, runPerf, serve };

package/dist/perf/measure.js

@@ -1,4 +1,12 @@
+import { scope } from "@ogygia/machine";
 // src/perf/measure.ts
+/**
+* MEASURE — a page list rendered under the profiler on a running server (a local preview, a
+* deployed one), folded into a small snapshot a CI step can keep and diff. Nothing new is
+* instrumented: this is the `/__profiler/page?format=json` report the UI reads, reduced to the
+* numbers a budget can be set on. Pure apart from the fetch it is handed, so a test drives it with
+* a fake and a runner with the real one.
+*/
 const r1 = (n) => Math.round(n * 10) / 10;
 const median = (xs) => xs.length ? [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)] : 0;
 /** One report → one page's snapshot. */
@@ -62,7 +70,8 @@ async function measure(opts) {
 		if (!page.startsWith("/")) throw new Error(`page must be a path on the site: ${page}`);
 		const url = `${origin}${base}/page?p=${encodeURIComponent(page)}&runs=${runs}&format=json`;
 		const ctrl = new AbortController();
-		const timer = setTimeout(() => ctrl.abort(), opts.timeout_ms ?? 12e4);
+		const deadline = scope();
+		deadline.timeout(() => ctrl.abort(), opts.timeout_ms ?? 12e4);
 		let res;
 		try {
 			res = await f(url, {
@@ -76,7 +85,7 @@ async function measure(opts) {
 		} catch (e) {
 			throw new Error(`${page}: the profiler did not answer (${e instanceof Error ? e.message : String(e)})`);
 		} finally {
-			clearTimeout(timer);
+			deadline.close();
 		}
 		if (res.status === 409) throw new Error(`${page}: the profiler is busy on that server (another recording is running)`);
 		if (!res.ok) throw new Error(`${page}: the profiler answered ${res.status}${res.status === 401 || res.status === 302 || res.status === 303 ? " — is the key right (x-profiler-key)?" : ""}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogygia/cli",
-  "version": "0.11.5",
+  "version": "0.13.0",
   "description": "The ogygia command line: init and site scaffolds, the AI skill, the MCP server, perf budgets and bisect, federation keys and catalogs",
   "keywords": [
     "cli",
@@ -27,15 +27,22 @@
   "type": "module",
   "exports": {
     "./bin": "./dist/cli.mjs",
+    "./internal/messages": {
+      "types": "./src/messages.ts",
+      "default": "./dist/messages.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@ogygia/machine": "^0.13.0"
+  },
   "devDependencies": {
-    "@ogygia/core": "0.11.5",
-    "@ogygia/devtools": "0.11.4",
-    "@ogygia/tooling": "0.0.0",
+    "@ogygia/config": "0.0.0",
+    "@ogygia/core": "0.13.0",
+    "@ogygia/devtools": "0.13.0",
     "@sveltejs/sv-utils": "^0.3.3",
     "@types/node": "^26.1.2",
     "@typescript/native": "npm:typescript@^7.0.2",
@@ -45,7 +52,7 @@
     "vitest": "^4.1.12"
   },
   "peerDependencies": {
-    "@ogygia/core": "^0.11.5",
+    "@ogygia/core": "^0.13.0",
     "playwright": "^1.62.0",
     "svelte": "^5.56.8"
   },