@finchip.ai/foga 0.6.0-alpha.5 → 0.6.0-alpha.6

package/README.md

@@ -19,7 +19,9 @@ ERC-8004 (Trustless Agents) is a required dependency: ERC-8419, ERC-8434 and ERC
 
 The project delivers three things from one kernel: the **Finch OG Agent** (the first running instance), the **FOGA node software** anyone can run with their own identity, model and wallet, and a **public access layer** (MCP, A2A, HTTP/CLI). It is built in phases; this repository has completed **Phase 2c: the genesis on a public chain**, on top of the Phase 2 genesis (T0–T9) and the Phase 1 world layer.
 
-## Status: Phase 3c done — Loop D, the unscripted run (3c); Phase 3b done — the node served over MCP and HTTP; Phase 3a done — the kernel hardened and turned into a node with a capability catalog; Phase 2c done
+## Status: Phase 3d in progress — 3d-1 done (quickstart, an outside agent's Loop D); Phase 3c done — Loop D, the unscripted run; Phase 3b done — the node served over MCP and HTTP; Phase 3a done — the kernel hardened and turned into a node with a capability catalog; Phase 2c done
+
+**3d-1 (0.6.0-alpha.6, 2026-11-02).** The package is on npm as `@finchip.ai/foga` (0.6.0-alpha.4 and alpha.5, the latter with the launcher fixed for Windows), so the first slice of 3d is the two things that make it usable from nothing. `foga quickstart` (`src/demo/quickstart.ts`, docs/quickstart.md) is one command to a live cell: anvil, the local world, a cell born with keys nobody held and its two skills, two tenders minted for it, the node served (watchers, HTTP API, MCP over Streamable HTTP), both entrances checked (the handshake and tool list over HTTP with an act-level key, and over stdio with the operator key), and the MCP client configurations — Claude Desktop, Claude Code, Cursor, and the HTTP form with URL and Bearer key — printed and written with every path filled in, under `~/.foga/quickstart`. Loop D gains `--model external` (docs/loop-d.md): the node is served instead of run, an act-level key is minted for whoever proposes, the orchestrator prints a brief (the entrance, the five steps of a tender, what the run does around the agent — nothing about the cases) and waits for the agent — any model, any runtime, a person with `curl` — with the same recovery drill, the same entrance checks and the same acceptance; the evidence names the agent and carries no runner ticks, the doctor marks a case the agent left alone `NotTested` rather than `Fail`, and `--compare` skips what one run did not reach. `test/loop-d-external.test.ts` drives it with a scripted agent through the MCP entrance and every verdict passes, the model-agnostic row included against the kept stub run. Smaller: `.gitattributes` keeps every text file LF (the launcher's shebang included), a `prepare` script compiles a checkout installed straight from git, the shared cell birth (`src/demo/birth.ts`) and anvil helpers (`src/demo/anvil.ts`) serve the demos, and the docs carry the PowerShell and Windows notes. Next in 3d: `foga node preflight`, `docs build/publish` with `setAgentURI`, the A2A card and inbound mapping, Sourcify, then the OG deployment runbook, the documentation site and the registry listing.
 
 **3c (0.6.0-alpha.4, 2026-11-02).** A model in the loop, and the acceptance that looks at records rather than words. `src/node/runner.ts` is the node's loop with a model: each tick perceives through the read capabilities, hands the situation and the catalog as tools to the model, carries out what it proposes — reads at once, acts through `Catalog.invoke` where the three checks decide and a refusal goes back so the model can revise once — and records the tick by hash (the decision records carry the model and the hashes of its request and answer; the journal the hash of the whole transcript; the text never). Limits bound a tick (12 tool calls, 2 acts) and a day (the model's calls, counted in the store). Two adapters on one interface: `anthropic` (the Messages API over `fetch`, the key in the environment, the model name in the configuration) and `stub` (a deterministic decision table that also proposes, once, a tender above the budget so the evidence shows the gate closing). `foga node run` is the embedded node — server, watchers, runner — on the operator key alone. `foga demo --loop-d` (`src/demo/loop-d.ts`) is the unscripted run: a new cell with fresh keys, an independent demander process minting cases a–f in a seeded order (two tenders to take, four to refuse at `skill`, `policy`, `verifier`, and one met during the guardian's suspension), the node killed after its first submission and restarted, the HTTP entrance used beside the runner (the same request answered once, the same job under another request a conflict, three mints at once of which the third is refused at `budget` before anything is sent), and an evidence file with every record, the cases' outcomes and a scan of every transaction the operator key signed. `foga doctor --loop-d` judges it beside layer 5: every operation under an allowed decision, refusals that broadcast nothing, the four budget books, the operator's transactions all at the account and allow-listed, the cases as expected, the recovery, the entrances, and — given two runs — the same outcomes from the stub and a real model. The slice also closed a race the run exposed: the catalog's decision section now runs one act at a time per node and a job reserves the value it will move from its decision. `test/loop-d.test.ts` (anvil, under a minute) and `test/model.test.ts` are the gate; CI runs Loop D on the world the genesis ran on. docs/loop-d.md.
 
@@ -70,11 +72,17 @@ From Phase 1, unchanged in substance:
 - **The doctor.** `foga doctor` reports five layers per contract — chain and code, interfaces, version match, configuration and permissions, semantic validation — with the verdicts Pass / Fail / Unknown / Not tested / Not applicable. Layers 1–4 probe the chain; layer 5 reads the genesis evidence. A doctor run can be exported as a JSON-RPC probe plan and replayed from results collected elsewhere, so a report never depends on which machine can reach which RPC.
 - **Sepolia address book.** `worlds/sepolia.json` records every upstream reference deployment at its deployed revision, including the three seams the inventory found (docs/version-lock.md); the completed world and the doctor's report on it are the 2c files above.
 
-What is next: 3d closes Phase 3 — A2A, the documents, `foga quickstart`, the npm and registry publication, the OG instance's move to a revision-2 account with public endpoints and a real model's Loop D run on Sepolia; Phase 4 the hosted node and payments. The design is in docs/design-memo.md.
+What is next: the rest of 3d closes Phase 3 — the readiness check, the documents on chain, A2A, Sourcify, the OG instance's move to a revision-2 account with public endpoints, the registry listing and an outside agent's Loop D run on Sepolia; Phase 4 the hosted node and payments. The design is in docs/design-memo.md.
 
 ## Quick start
 
-Three ways in, from most to least demanding:
+With Node 22.13+ and Foundry's `anvil` installed, one command births a cell on a local chain and prints the MCP client configuration to connect to it (docs/quickstart.md; in PowerShell quote the name: `npx -y '@finchip.ai/foga' quickstart`):
+
+```bash
+npx -y @finchip.ai/foga quickstart
+```
+
+From a checkout, three ways in, from most to least demanding:
 
 ```bash
 # 1. Full reproduction (needs git, Node >= 22 and Foundry):
@@ -197,9 +205,10 @@ foga node serve --config <cell.config.json> [--listen <host:port>] [--no-watch]
 foga node key new --config <cell.config.json> --id <id> [--level read|build|act] [--visibility public|caller|operator] [--note <text>]
 foga node run --config <cell.config.json> [--model stub|anthropic] [--listen <host:port> | --no-http] [--interval <s>] [--once | --ticks <n>] [--transcripts <dir>]
                                                                           the embedded node: server, watchers and the runner (operator key alone)
-foga demo --loop-d [--model stub|anthropic] [--model-name <name>] [--seed <n>] [--no-recovery]   anvil, the world, then Loop D judged by the doctor
-foga loop-d run --world <world.json> --rpc <url> [--dir <dir>] [--out <evidence.json>] [--model] [--model-name] [--seed] [--no-recovery]
+foga demo --loop-d [--model stub|anthropic|external] [--model-name <name>] [--seed <n>] [--no-recovery]   anvil, the world, then Loop D judged by the doctor
+foga loop-d run --world <world.json> --rpc <url> [--dir <dir>] [--out <evidence.json>] [--model] [--model-name] [--seed] [--no-recovery] [--listen] [--wait <s>] [--idle <s>]
 foga doctor [--world <world.json>] --loop-d <evidence.json> [--compare <evidence2.json>] [--out <report.json>]
+foga quickstart [--dir <dir>] [--port <n>] [--listen <host:port> | --no-serve] [--name <cell>] [--no-tenders] [--exit]   one command to a live cell and its client configuration
 ```
 
 During development the CLI runs from source with `npm run foga -- <args>`; `npm run build` compiles it to `dist/` for the `foga` binary.

package/dist/cli.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-import { spawn } from "node:child_process";
-import { closeSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
-import { createConnection } from "node:net";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { cpus, homedir, loadavg } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { buildBundle } from "./build/bundle.js";
 import { syncVendor, verifyVendor } from "./build/vendor.js";
+import { anvilBinary, launchAnvil, portProblem } from "./demo/anvil.js";
+import { LOOP_D_MODELS } from "./demo/loop-d.js";
 import { runDoctor } from "./doctor/doctor.js";
-import { ensureDir, exists, readJson, repoRoot, writeJson } from "./util/fs.js";
+import { exists, readJson, repoRoot, writeJson } from "./util/fs.js";
 import { fail, log } from "./util/log.js";
 import { attachWorld, deployWorld, loadWorldConfig, missingPlanSteps } from "./world/deploy.js";
 import { loadBundle } from "./bundle/load.js";
@@ -38,12 +38,17 @@ usage:
                    [--zk auto|require|skip] [--crash-after <opKey>] [--crash-before <opKey>]
                                                  run the genesis scenario (idempotent; re-run to resume)
   foga genesis status --world <world.json> [--store <file.sqlite>]    list the operations the store holds
+  foga quickstart [--dir <dir>] [--port <n>] [--listen <host:port> | --no-serve] [--name <cell>] [--no-tenders] [--exit]
+                                                 one command to a live cell: anvil, the local world, a cell born with fresh keys and its two skills, two tenders,
+                                                 the node serving HTTP and MCP, and the MCP client configurations printed with every path filled in (~/.foga/quickstart)
   foga demo [--port <n>] [--keep] [--genesis <T0..T9>]   start anvil, deploy the local world, run the doctor (and the genesis)
-  foga demo --loop-d [--model stub|anthropic] [--model-name <name>] [--seed <n>] [--no-recovery] [--port <n>] [--keep]
-                                                 the above, then Loop D: a new cell born, a demander minting cases a-g, the embedded node with a model,
-                                                 the recovery drill, the guardian's suspension; evidence to deployments/loop-d.local.json, judged by the doctor
-  foga loop-d run --world <world.json> --rpc <url> [--dir <dir>] [--out <evidence.json>] [--model stub|anthropic] [--model-name <name>] [--seed <n>] [--no-recovery]
-                                                 Loop D on a world that exists (FOGA_FUNDER_KEY funds the cell's roles on a non-local chain)
+  foga demo --loop-d [--model stub|anthropic|external] [--model-name <name>] [--seed <n>] [--no-recovery] [--port <n>] [--keep]
+                                                 the above, then Loop D: a new cell born, a demander minting cases a-g, the node with a model (or served for an
+                                                 outside agent), the recovery drill, the guardian's suspension; evidence to deployments/loop-d.local.json, judged by the doctor
+  foga loop-d run --world <world.json> --rpc <url> [--dir <dir>] [--out <evidence.json>] [--model stub|anthropic|external] [--model-name <name>] [--seed <n>] [--no-recovery]
+                  [--listen <host:port>] [--wait <s>] [--idle <s>]
+                                                 Loop D on a world that exists (FOGA_FUNDER_KEY funds the cell's roles on a non-local chain); with --model external the
+                                                 node is served and an outside agent — any model, any runtime — works the tenders through /mcp or /api with the key printed
   foga demo demander --world <w> --rpc <url> --store <sqlite> --cell <addr> --scheme <id> --issuer <addr> --probe-hash <h> --extract-hash <h> --cases a,b,c --seed <n> --out <json>
                                                  the independent demander of Loop D (FOGA_DEMANDER_KEY; anvil's first account by default)
   foga bundle info                               summarize the committed bundle
@@ -350,33 +355,54 @@ async function main() {
         const { runLoopD, defaultLoopDDir } = await import("./demo/loop-d.js");
         const worldPath = str(flags, "world") ?? fail("--world <world.json> is required");
         const rpc = str(flags, "rpc") ?? process.env.FOGA_RPC_URL ?? fail("--rpc <url> is required");
-        const model = (str(flags, "model") ?? "stub");
-        if (model !== "stub" && model !== "anthropic")
-            fail("--model must be stub or anthropic");
-        await runLoopD({ rpc, worldPath: resolve(worldPath), dir: str(flags, "dir") ? resolve(str(flags, "dir")) : defaultLoopDDir(), evidencePath: resolve(str(flags, "out") ?? join(root, "deployments", "loop-d.local.json")), model, modelName: str(flags, "model-name") ?? process.env.FOGA_MODEL, seed: str(flags, "seed") ? Number(str(flags, "seed")) : undefined, recovery: !flags["no-recovery"], funderKey: process.env.FOGA_FUNDER_KEY });
+        await runLoopD({ rpc, worldPath: resolve(worldPath), dir: str(flags, "dir") ? resolve(str(flags, "dir")) : defaultLoopDDir(), evidencePath: resolve(str(flags, "out") ?? join(root, "deployments", "loop-d.local.json")), funderKey: process.env.FOGA_FUNDER_KEY, ...loopDFlags(flags) });
         return;
     }
+    if (group === "quickstart") {
+        const { runQuickstart } = await import("./demo/quickstart.js");
+        let result;
+        try {
+            result = await runQuickstart({ dir: str(flags, "dir"), port: str(flags, "port") ? Number(str(flags, "port")) : undefined, listen: flags["no-serve"] ? null : str(flags, "listen"), name: str(flags, "name"), tenders: !flags["no-tenders"], exit: Boolean(flags.exit) });
+        }
+        catch (e) {
+            fail(e.message);
+        }
+        if (flags.exit) {
+            await result.stop();
+            return;
+        }
+        const stopping = () => {
+            console.error("quickstart: stopping the node and the chain");
+            result.stop().finally(() => process.exit(0));
+        };
+        process.on("SIGINT", stopping);
+        process.on("SIGTERM", stopping);
+        const why = await result.ended;
+        fail(`${why}; the quickstart is over`);
+    }
     if (group === "demo") {
-        const model = (str(flags, "model") ?? "stub");
-        if (model !== "stub" && model !== "anthropic")
-            fail("--model must be stub or anthropic");
-        await demo({ port: Number(str(flags, "port") ?? 8545), keep: Boolean(flags.keep), genesis: str(flags, "genesis"), loopD: flags["loop-d"] ? { model, modelName: str(flags, "model-name") ?? process.env.FOGA_MODEL, seed: str(flags, "seed") ? Number(str(flags, "seed")) : undefined, recovery: !flags["no-recovery"] } : undefined });
+        await demo({ port: Number(str(flags, "port") ?? 8545), keep: Boolean(flags.keep), genesis: str(flags, "genesis"), loopD: flags["loop-d"] ? loopDFlags(flags) : undefined });
         return;
     }
     console.log(USAGE);
     fail(`unknown command: ${positional.join(" ")}`);
 }
+/** The Loop D options the flags name (shared by `foga demo --loop-d` and `foga loop-d run`). */
+function loopDFlags(flags) {
+    const model = (str(flags, "model") ?? "stub");
+    if (!LOOP_D_MODELS.includes(model))
+        fail(`--model must be one of ${LOOP_D_MODELS.join(", ")}`);
+    const seconds = (key) => (str(flags, key) ? Number(str(flags, key)) * 1000 : undefined);
+    return { model, modelName: str(flags, "model-name") ?? process.env.FOGA_MODEL, seed: str(flags, "seed") ? Number(str(flags, "seed")) : undefined, recovery: !flags["no-recovery"], listen: str(flags, "listen"), waitMs: seconds("wait"), idleMs: seconds("idle") };
+}
 async function demo(opts) {
     const root = repoRoot();
     const rpc = `http://127.0.0.1:${opts.port}`;
     // Say what is wrong before starting anything: a port that is already taken makes anvil exit at once, and a
     // silent exit would otherwise surface only as "the RPC did not come up".
-    if (await portInUse(opts.port)) {
-        const answers = await rpcAnswers(rpc);
-        fail(answers
-            ? `${rpc} already answers JSON-RPC (another anvil or node is running). Stop it, or pass --port <n> to use another port.`
-            : `port ${opts.port} is in use by something that does not speak JSON-RPC. Free it, or pass --port <n>.`);
-    }
+    const problem = await portProblem(opts.port);
+    if (problem)
+        fail(problem);
     // A machine that is already saturated (a proving-key build, for instance) starves anvil: blocks come late and the
     // kernel gives up on a receipt after its timeout. Say so before starting rather than after a failure.
     const cores = cpus().length || 1;
@@ -385,51 +411,27 @@ async function demo(opts) {
         log.warn(`this machine is busy (load ${load.toFixed(1)} on ${cores} core${cores === 1 ? "" : "s"}): another heavy process slows anvil down and can make the genesis time out waiting for receipts. If a proving-key build (npm run zk:predicate) is running, let it finish or stop it first.`);
     }
     // FOGA_FOUNDRY_DIR points at a Foundry install of its own (scripts/install-foundry.sh puts the static build there).
-    const foundryDir = process.env.FOGA_FOUNDRY_DIR;
-    const anvilBin = foundryDir ? join(foundryDir, "anvil") : "anvil";
     // anvil's output goes to a log file rather than a pipe: with --keep the node survives this process, and a
     // Rust program whose stderr pipe has gone away dies on its next write.
+    const { path: anvilBin, fromDir } = anvilBinary();
     const logPath = join(root, ".foga-build", "anvil.log");
-    ensureDir(join(root, ".foga-build"));
-    const logFd = openSync(logPath, "w");
-    log.info(`starting anvil on ${rpc}${foundryDir ? ` (${anvilBin})` : ""}; log ${relative(root, logPath)}`);
-    const anvil = spawn(anvilBin, ["--port", String(opts.port), "--silent"], { stdio: ["ignore", logFd, logFd], detached: opts.keep });
-    closeSync(logFd);
-    let exited = null;
-    anvil.on("exit", (code, signal) => {
-        exited = code !== null ? `exit code ${code}` : `signal ${signal}`;
-    });
+    log.info(`starting anvil on ${rpc}${fromDir ? ` (${anvilBin})` : ""}; log ${relative(root, logPath)}`);
+    let anvil;
+    try {
+        anvil = await launchAnvil({ port: opts.port, logPath, detached: opts.keep });
+    }
+    catch (e) {
+        fail(e.message);
+    }
     const stop = () => {
         if (!opts.keep && !anvil.killed)
             anvil.kill("SIGTERM");
     };
-    anvil.on("error", (e) => fail(e.code === "ENOENT"
-        ? foundryDir
-            ? `${anvilBin} not found (FOGA_FOUNDRY_DIR=${foundryDir}). Run scripts/install-foundry.sh ${foundryDir} first.`
-            : "anvil not found on PATH. Install Foundry (https://getfoundry.sh: `curl -L https://foundry.sh | bash && foundryup`), or run scripts/install-foundry.sh and export FOGA_FOUNDRY_DIR, or use docker compose."
-        : `could not start anvil: ${e.message}`));
     process.on("exit", stop);
     process.on("SIGINT", () => {
         stop();
         process.exit(130);
     });
-    try {
-        await waitForRpc(rpc, 20000, () => exited !== null);
-    }
-    catch (e) {
-        let output = "";
-        try {
-            output = readFileSync(logPath, "utf8").slice(-8000);
-        }
-        catch {
-            /* no log */
-        }
-        const why = exited ? `anvil stopped (${exited}) before serving ${rpc}` : `anvil did not serve ${rpc} within 20 s`;
-        const glibc = /GLIBC_[0-9.]+' not found/.test(output)
-            ? "\nThis anvil is the glibc build and this machine's glibc is older than it needs (GLIBC >= 2.35: Ubuntu 22.04 or newer). Install the static build next to it: `scripts/install-foundry.sh` then `export FOGA_FOUNDRY_DIR=~/.foga/foundry` (or put that directory first on PATH)."
-            : "";
-        fail(`${why}.${output.trim() ? `\n--- anvil output ---\n${output.trim()}\n--------------------` : ""}${glibc}\nRun \`${anvilBin} --port ${opts.port}\` by hand to see its output; \`${anvilBin} --version\` shows the installed version (CI uses Foundry v1.7.1).`);
-    }
     const worldConfig = join(root, "worlds", "local.json");
     const out = join(root, "deployments", "local.json");
     await deployWorld({ worldConfigPath: worldConfig, rpc, outPath: out });
@@ -454,7 +456,7 @@ async function demo(opts) {
     if (opts.loopD) {
         const { runLoopD, defaultLoopDDir } = await import("./demo/loop-d.js");
         const evidencePath = join(root, "deployments", "loop-d.local.json");
-        await runLoopD({ rpc, worldPath: out, dir: defaultLoopDDir(), evidencePath, model: opts.loopD.model, modelName: opts.loopD.modelName, seed: opts.loopD.seed, recovery: opts.loopD.recovery });
+        await runLoopD({ rpc, worldPath: out, dir: defaultLoopDDir(), evidencePath, ...opts.loopD });
         const judged = await runDoctor({ worldPath: out, rpc, outPath: join(root, "deployments", "local.doctor.json"), genesisPath: opts.genesis ? join(root, "deployments", "local.genesis.json") : undefined, loopDPath: evidencePath, quiet: true });
         if (judged.report && judged.report.summary.Fail > 0)
             process.exitCode = 3;
@@ -467,39 +469,6 @@ async function demo(opts) {
     else
         stop();
 }
-/** True when something accepts TCP connections on 127.0.0.1:port. */
-function portInUse(port) {
-    return new Promise((resolve) => {
-        const socket = createConnection({ host: "127.0.0.1", port });
-        const done = (v) => {
-            socket.destroy();
-            resolve(v);
-        };
-        socket.setTimeout(1000, () => done(false));
-        socket.once("connect", () => done(true));
-        socket.once("error", () => done(false));
-    });
-}
-async function rpcAnswers(rpc) {
-    try {
-        const res = await fetch(rpc, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_chainId", params: [] }), signal: AbortSignal.timeout(2000) });
-        return res.ok;
-    }
-    catch {
-        return false;
-    }
-}
-async function waitForRpc(rpc, timeoutMs, giveUp) {
-    const start = Date.now();
-    while (Date.now() - start < timeoutMs) {
-        if (await rpcAnswers(rpc))
-            return;
-        if (giveUp?.())
-            break;
-        await new Promise((r) => setTimeout(r, 250));
-    }
-    throw new Error(`RPC at ${rpc} did not come up within ${timeoutMs} ms`);
-}
 main().catch((e) => {
     fail(e?.stack ?? String(e));
 });

package/dist/demo/anvil.js

@@ -0,0 +1,129 @@
+import { execFileSync, spawn } from "node:child_process";
+import { closeSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { createConnection } from "node:net";
+import { dirname, join } from "node:path";
+/**
+ * A local chain for the demos (`foga demo`, `foga quickstart`): finding anvil, starting it with its output in a log
+ * file, waiting for its RPC, and saying what is wrong in the words a first run needs — the binary missing (with the
+ * install path per platform), the port taken, the glibc too old for the dynamic build.
+ */
+/** The anvil binary this machine offers: FOGA_FOUNDRY_DIR/anvil (scripts/install-foundry.sh) or anvil on PATH. */
+export function anvilBinary() {
+    const dir = process.env.FOGA_FOUNDRY_DIR;
+    return { path: dir ? join(dir, "anvil") : "anvil", fromDir: dir ?? null };
+}
+/** anvil's version line, or null when the binary cannot be run from here. */
+export function anvilVersion(path) {
+    try {
+        return execFileSync(path, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim().split("\n")[0];
+    }
+    catch {
+        return null;
+    }
+}
+export const ANVIL_INSTALL_HINT = [
+    "anvil (Foundry) is not installed, or not where FOGA_FOUNDRY_DIR says.",
+    "  Linux, macOS:  curl -L https://foundry.sh | bash && foundryup   (an older glibc: scripts/install-foundry.sh, then export FOGA_FOUNDRY_DIR=~/.foga/foundry)",
+    "  Windows:       download the win32_amd64 zip of a release from https://github.com/foundry-rs/foundry/releases, unzip it, and put the folder",
+    "                 holding anvil.exe on PATH (or set FOGA_FOUNDRY_DIR to that folder); then open a new terminal",
+    "  any platform:  docker compose (docker/) runs the toolchain with anvil inside",
+].join("\n");
+/** True when something accepts TCP connections on 127.0.0.1:port. */
+export function portInUse(port) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ host: "127.0.0.1", port });
+        const done = (v) => {
+            socket.destroy();
+            resolve(v);
+        };
+        socket.setTimeout(1000, () => done(false));
+        socket.once("connect", () => done(true));
+        socket.once("error", () => done(false));
+    });
+}
+export async function rpcAnswers(rpc) {
+    try {
+        const res = await fetch(rpc, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_chainId", params: [] }), signal: AbortSignal.timeout(2000) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function waitForRpc(rpc, timeoutMs, giveUp) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        if (await rpcAnswers(rpc))
+            return;
+        if (giveUp?.())
+            break;
+        await new Promise((r) => setTimeout(r, 250));
+    }
+    throw new Error(`RPC at ${rpc} did not come up within ${timeoutMs} ms`);
+}
+/** Why a port cannot be used for a new anvil: another RPC already answers there, or something else holds it. */
+export async function portProblem(port) {
+    if (!(await portInUse(port)))
+        return null;
+    const rpc = `http://127.0.0.1:${port}`;
+    return (await rpcAnswers(rpc))
+        ? `${rpc} already answers JSON-RPC (another anvil or node is running). Stop it, or pass --port <n> to use another port.`
+        : `port ${port} is in use by something that does not speak JSON-RPC. Free it, or pass --port <n>.`;
+}
+/**
+ * Start anvil and wait until its RPC answers. Rejects with a message fit to print when the binary is missing, when
+ * anvil stops before serving (its output quoted, the glibc case named) or when it does not come up in time.
+ */
+export async function launchAnvil(o) {
+    const { path: bin, fromDir } = anvilBinary();
+    const rpc = `http://127.0.0.1:${o.port}`;
+    mkdirSync(dirname(o.logPath), { recursive: true });
+    const logFd = openSync(o.logPath, "w");
+    const child = spawn(bin, ["--port", String(o.port), "--silent", ...(o.args ?? [])], { stdio: ["ignore", logFd, logFd], detached: Boolean(o.detached) });
+    closeSync(logFd);
+    let exited = null;
+    child.on("exit", (code, signal) => {
+        exited = code !== null ? `exit code ${code}` : `signal ${signal}`;
+    });
+    const spawnError = new Promise((_, reject) => {
+        child.once("error", (e) => {
+            reject(new Error(e.code === "ENOENT" ? (fromDir ? `${bin} not found (FOGA_FOUNDRY_DIR=${fromDir}). Run scripts/install-foundry.sh ${fromDir} first, or unset FOGA_FOUNDRY_DIR to use anvil on PATH.\n${ANVIL_INSTALL_HINT}` : `anvil not found on PATH.\n${ANVIL_INSTALL_HINT}`) : `could not start anvil: ${e.message}`));
+        });
+    });
+    const timeoutMs = o.timeoutMs ?? 20_000;
+    try {
+        await Promise.race([waitForRpc(rpc, timeoutMs, () => exited !== null), spawnError]);
+    }
+    catch (e) {
+        if (!child.killed && child.exitCode === null)
+            child.kill("SIGTERM");
+        if (e.message?.startsWith("RPC at ")) {
+            let output = "";
+            try {
+                output = readFileSync(o.logPath, "utf8").slice(-8000);
+            }
+            catch {
+                /* no log */
+            }
+            const why = exited ? `anvil stopped (${exited}) before serving ${rpc}` : `anvil did not serve ${rpc} within ${timeoutMs / 1000} s`;
+            const glibc = /GLIBC_[0-9.]+' not found/.test(output)
+                ? "\nThis anvil is the glibc build and this machine's glibc is older than it needs (GLIBC >= 2.35: Ubuntu 22.04 or newer). Install the static build next to it: `scripts/install-foundry.sh` then `export FOGA_FOUNDRY_DIR=~/.foga/foundry` (or put that directory first on PATH)."
+                : "";
+            throw new Error(`${why}.${output.trim() ? `\n--- anvil output ---\n${output.trim()}\n--------------------` : ""}${glibc}\nRun \`${bin} --port ${o.port}\` by hand to see its output; \`${bin} --version\` shows the installed version (CI uses Foundry v1.7.1).`);
+        }
+        throw e;
+    }
+    return child;
+}
+/** Stop a child and wait for it to be gone (SIGTERM, then SIGKILL after a grace period). */
+export async function stopChild(child, graceMs = 5000) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    const gone = new Promise((r) => child.once("exit", () => r()));
+    child.kill("SIGTERM");
+    await Promise.race([gone, new Promise((r) => setTimeout(r, graceMs))]);
+    if (child.exitCode === null && child.signalCode === null) {
+        child.kill("SIGKILL");
+        await Promise.race([gone, new Promise((r) => setTimeout(r, 2000))]);
+    }
+}

package/dist/demo/birth.js

@@ -0,0 +1,71 @@
+import { join } from "node:path";
+import { Wallet, getAddress, parseEther } from "ethers";
+import { dataUriJcs, keccakJcs } from "../core/canonical.js";
+import { accountSubject, fogaAttestedSchemeDescriptor } from "../core/kya.js";
+import { loadCellConfig, newCellConfig, saveCellConfig } from "../node/config.js";
+import { cellInit } from "../node/init.js";
+import { Node } from "../node/node.js";
+import { defaultCatalog, OPERATOR_CALLER } from "../tools/index.js";
+import { repoRoot } from "../util/fs.js";
+export async function birthCell(o) {
+    const k = o.kernel;
+    const log = o.log ?? (() => { });
+    const root = repoRoot();
+    const W = k.address("W");
+    const owner = Wallet.createRandom();
+    const operator = Wallet.createRandom();
+    const guardian = Wallet.createRandom();
+    log(`cell ${o.name}: owner ${owner.address}, operator ${operator.address}, guardian ${guardian.address}`);
+    // --- funding by W, the standing scheme registered by W
+    const price = (await k.world.provider.getFeeData()).gasPrice ?? 1000000000n;
+    const gas = (units) => units * price * 2n;
+    await k.transfer("fund.owner", "W", owner.address, parseEther("0.05") + gas(12000000n));
+    await k.transfer("fund.operator", "W", operator.address, gas(20000000n) + parseEther("0.003"));
+    await k.transfer("fund.guardian", "W", guardian.address, gas(1000000n));
+    const att = await k.call("scheme", "W", k.kya.schemeRegistryAddress, k.kya.schemes().interface, "registerScheme", [k.kya.attestedSchemeInput(fogaAttestedSchemeDescriptor())]);
+    const schemeId = k.kya.schemeIdFromReceipt(att.receipt);
+    const bornAtBlock = await k.blockNumber();
+    // --- the configuration and the birth (the owner's act, in this process, as `foga cell init` would)
+    const cfg = newCellConfig({ name: o.name, world: o.worldPath, store: o.storePath, owner: owner.address, operator: operator.address, guardian: guardian.address, rpc: o.rpc, skillsDir: join(root, "scenarios", "skills"), inputDir: join(root, "scenarios", "fixtures"), description: o.description });
+    cfg.identity.standing = { schemeId, issuers: [W] };
+    o.configure?.(cfg);
+    saveCellConfig(o.configPath, cfg);
+    const birthNode = await Node.open({ configPath: o.configPath, rpc: o.rpc, keys: { owner: owner.privateKey }, allowUnborn: true, log: () => { } });
+    const born = await cellInit(birthNode, { log: () => { } });
+    birthNode.close();
+    const account = getAddress(born.account);
+    log(`cell ${o.name}: born as ${account} (agent ${born.agentId}) in ${born.operations.length} operations`);
+    // --- standing from the world operator, the two skills minted by the operator
+    const claim = { scheme: "S_att", level: 2, subject: `eip155:${k.chainId}:${account.toLowerCase()}` };
+    const expiresAt = (await k.blockTimestamp()) + 365 * 86400;
+    await k.call("attest", "W", k.kya.registryAddress, k.kya.registry().interface, "attest", [accountSubject(k.chainId, account), schemeId, 2, keccakJcs(claim), expiresAt, dataUriJcs(claim), keccakJcs(claim)]);
+    const catalog = defaultCatalog();
+    const skillNode = await Node.open({ configPath: o.configPath, rpc: o.rpc, keys: { operator: operator.privateKey }, log: () => { } });
+    try {
+        for (const skill of ["foga-probe", "finch-extract-verify"]) {
+            const r = await catalog.invoke(skillNode, "skill_mint", { skill }, OPERATOR_CALLER, { mode: "act" });
+            if (!r.ok)
+                throw new Error(`skill_mint ${skill}: ${r.gate}: ${r.reason}`);
+        }
+    }
+    finally {
+        skillNode.close();
+    }
+    const held = loadCellConfig(o.configPath).config.skills.held;
+    log(`cell ${o.name}: standing level 2 attested by ${W}; skills minted (${Object.keys(held).join(", ")})`);
+    return {
+        owner,
+        operator,
+        guardian,
+        account,
+        agentId: born.agentId,
+        specId: born.specId ?? null,
+        schemeId,
+        bornAtBlock,
+        birthOperations: born.operations.length,
+        held,
+        packages: { "foga-probe": held["foga-probe"].packageHash, "finch-extract-verify": held["finch-extract-verify"].packageHash },
+        configPath: o.configPath,
+        storePath: o.storePath,
+    };
+}