@finchip.ai/foga 0.6.0-alpha.7 → 0.6.1

package/README.md

@@ -19,9 +19,11 @@ 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 3d in progress — 3d-2 done (the wallet, signed callers, the documents on chain, preflight, A2A, Sourcify), 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
+## Status: Phase 3 done (0.6.0, 2026-11-05) — the OG live at foga.finchip.ai, the MCP registry listing, the Sepolia Loop D with an outside agent; 3d-2 (the wallet, signed callers, the documents on chain, preflight, A2A, Sourcify), 3d-1 (quickstart, an outside agent's Loop D), 3c (Loop D with a model), 3b (MCP and HTTP), 3a (the kernel as a node) all done
 
-**3d-2 (0.6.0-alpha.7, 2026-11-03).** The second slice of 3d is what a cell needs to stand on its own among other agents, under one principle (docs/design-memo.md, section 10): the wallet is the first step, made by default and never a reason to stop; identity is one's own; only the genome replicates. `foga wallet new` (`src/node/wallet.ts`, docs/wallet.md) makes an agent's keys on its own machine — owner, operator, guardian in 0600 files under `~/.foga/wallet`, never overwritten, no network — and `foga quickstart` makes the default wallet on its first run and births every later cell with the same keys; `--wallet <dir>` on every `foga cell` and `foga node` command takes a role's key from there. A wallet is also a credential: `Authorization: FOGA-EIP712 <envelope>` (`src/http/signed.ts`, `src/http/access.ts`) is an EIP-712 signature in the cell's own domain — bound to one request and good once, or a session for a client with static headers — and the caller is the signing address at the level `access.signers` grants it (the cell's own operator or owner, an allow-list by address or ERC-8004 agent id, a KYA standing threshold, a default); `/api`, `/mcp` and `/a2a` take it, `foga wallet sign` prints it, and every cell's MCP server carries the prompt `become-a-cell` and the resource `foga://docs/quickstart` for an agent that meets it. `foga cell docs build | publish | status` (`src/node/documents.ts`, docs/documents.md) generates the cell's documents from one configuration — the ERC-8004 registration, the ERC-8434 AID document, the ERC-8444 descriptor, the ERC-8454 unit, the A2A agent card, `server.json`, a manifest with content hashes — serves them at `/documents/*` and `/.well-known/*`, and commits them on chain as the operator's keyed job (`setAgentURI`, `setDocumentURI`, `updateDescriptor`, `publishVersion`; only what differs is sent), read back and cross-checked; `docs_status` and `docs_publish` are the catalog's 30th and 31st capabilities. `foga node preflight` (`src/node/preflight.ts`) is the readiness reconciliation — the world, the account and its allow-list, the budget, the keys, the standing, the skills run in the worker, the documents against the chain, the public URL, the model — advisory, `--strict` for CI. `POST /a2a` (`src/a2a/`, docs/a2a.md) is the A2A 1.0 JSON-RPC binding with the card at `/.well-known/agent-card.json`: a quote for anyone, a tender taken for an act-level caller as one task over the catalog's jobs, `GetTask`, `ListTasks`, `CancelTask`, errors by the specification. `foga world verify --sourcify` (`src/world/sourcify.ts`, docs/world.md) submits every FOGA-deployed contract of a world with the standard JSON input of its own compiler run (`forge build` now leaves the build-info beside the artifacts), matched by runtime code; a local chain is a dry run, which CI runs over all 47. The OG instance's default is host mode (`foga node serve`: every entrance, the watchers, no model) with embedded mode (`foga node run`, the runner with a model) on demand. Seven new tests on anvil and offline (`wallet`, `signed`, `documents`, `a2a`, `preflight`, `sourcify`, and `quickstart` extended) are the gate; `foga quickstart` now ends with a cell whose documents are on chain, whose card answers, and whose A2A entrance quotes. Next, 3d-3: the OG deployment runbook, `foga.finchip.ai`, the registry listing, the Sepolia Sourcify run, the OG cell's migration to revision 2 and an outside agent's Loop D on Sepolia.
+**3d-3 (0.6.0, 2026-11-05).** Phase 3 closes with the reference cell served and the last acceptance run on the public chain. The OG was born fresh on Sepolia by the path any cell takes (`wallet new`, `cell new`, `cell init`, `docs publish`, `node serve` — one key, no migration; docs/og-deployment.md): agent 11261, its skill offered, its documents on chain, its fifteen contracts Sourcify-verified; it is served in host mode under systemd behind Caddy at `foga.finchip.ai` and listed in the MCP registry as `io.github.garyyang-finchip/foga`. Loop D with an outside agent ran on Sepolia and every invariant row passed (docs/loop-d.md, "On a public chain"); what the public chain taught is fixed in this release — a working directory is one run, role funding is priced with a floor, the settlement figure is the tender's own, a log scan is windowed. `foga cell advise` (`src/node/advise.ts`) tells a running cell what to do next — separate the one key into owner, operator and guardian first — and the recommended items print after a quickstart, a birth and at serve; the first run stays minimal on purpose. The covenant list is read off the world (an eleventh covenant appears with no code change) and the manifest carries a `services` slot — the maintainer's catalog, declinable, served by the reference cell at `/services.json` — docs/extending.md. 107 tests.
+
+**3d-2 (0.6.0-alpha.7, 2026-11-03).** The second slice of 3d is what a cell needs to stand on its own among other agents, under one principle (docs/design-memo.md, section 10): the wallet is the first step, made by default and never a reason to stop; identity is one's own; only the genome replicates. `foga wallet new` (`src/node/wallet.ts`, docs/wallet.md) makes an agent's keys on its own machine — by default one key in a 0600 file under `~/.foga/wallet` — the identity that fills every role a cell needs; `--cell` for the separated owner/operator/guardian set — never overwritten, no network — and `foga quickstart` makes the default wallet on its first run and births every later cell with the same keys; `--wallet <dir>` on every `foga cell` and `foga node` command takes a role's key from there. A wallet is also a credential: `Authorization: FOGA-EIP712 <envelope>` (`src/http/signed.ts`, `src/http/access.ts`) is an EIP-712 signature in the cell's own domain — bound to one request and good once, or a session for a client with static headers — and the caller is the signing address at the level `access.signers` grants it (the cell's own operator or owner, an allow-list by address or ERC-8004 agent id, a KYA standing threshold, a default); `/api`, `/mcp` and `/a2a` take it, `foga wallet sign` prints it, and every cell's MCP server carries the prompt `become-a-cell` and the resource `foga://docs/quickstart` for an agent that meets it. `foga cell docs build | publish | status` (`src/node/documents.ts`, docs/documents.md) generates the cell's documents from one configuration — the ERC-8004 registration, the ERC-8434 AID document, the ERC-8444 descriptor, the ERC-8454 unit, the A2A agent card, `server.json`, a manifest with content hashes — serves them at `/documents/*` and `/.well-known/*`, and commits them on chain as the operator's keyed job (`setAgentURI`, `setDocumentURI`, `updateDescriptor`, `publishVersion`; only what differs is sent), read back and cross-checked; `docs_status` and `docs_publish` are the catalog's 30th and 31st capabilities. `foga node preflight` (`src/node/preflight.ts`) is the readiness reconciliation — the world, the account and its allow-list, the budget, the keys, the standing, the skills run in the worker, the documents against the chain, the public URL, the model — advisory, `--strict` for CI. `POST /a2a` (`src/a2a/`, docs/a2a.md) is the A2A 1.0 JSON-RPC binding with the card at `/.well-known/agent-card.json`: a quote for anyone, a tender taken for an act-level caller as one task over the catalog's jobs, `GetTask`, `ListTasks`, `CancelTask`, errors by the specification. `foga world verify --sourcify` (`src/world/sourcify.ts`, docs/world.md) submits every FOGA-deployed contract of a world with the standard JSON input of its own compiler run (`forge build` now leaves the build-info beside the artifacts), matched by runtime code; a local chain is a dry run, which CI runs over all 47. The OG instance's default is host mode (`foga node serve`: every entrance, the watchers, no model) with embedded mode (`foga node run`, the runner with a model) on demand. Seven new tests on anvil and offline (`wallet`, `signed`, `documents`, `a2a`, `preflight`, `sourcify`, and `quickstart` extended) are the gate; `foga quickstart` now ends with a cell whose documents are on chain, whose card answers, and whose A2A entrance quotes. Next, 3d-3: the OG deployment runbook, `foga.finchip.ai`, the registry listing, the Sepolia Sourcify run, the OG cell's migration to revision 2 and an outside agent's Loop D on Sepolia.
 
 **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.
 
@@ -84,10 +86,12 @@ With Node 22.13+ and Foundry's `anvil` installed, one command makes your wallet
 npx -y @finchip.ai/foga quickstart
 ```
 
+`@finchtech.ai/foga` is the same package under a second scope (`alias/finchtech.ai`: a launcher that runs `@finchip.ai/foga` at the same version), so `npx -y @finchtech.ai/foga quickstart` is the same command.
+
 The wallet alone, for an agent that will only call cells (docs/wallet.md), and a cell on a public chain born with it:
 
 ```bash
-npx -y @finchip.ai/foga wallet new                       # ~/.foga/wallet: owner, operator, guardian keys; prints the addresses to fund
+npx -y @finchip.ai/foga wallet new                       # ~/.foga/wallet: one key (your identity, every role); prints the address to fund. --cell for the separated owner/operator/guardian set
 foga cell new --wallet ~/.foga/wallet --name mine --world deployments/sepolia.json --store mine.sqlite --out mine.json
 foga cell init --config mine.json --wallet ~/.foga/wallet
 foga node preflight --config mine.json --wallet ~/.foga/wallet
@@ -109,6 +113,10 @@ npm run demo:genesis         # anvil + world deploy + doctor + genesis T0-T9 + d
 # 2. World and genesis only (Node >= 22 and Foundry's anvil, no Solidity build; the ZK paths are left out without their material):
 npm ci && npm run demo:genesis
 
+# 2b. The same show without a checkout, from the published package (Node >= 22.13 and anvil): a fresh chain, the 47 contracts,
+#     the genesis T0-T9 operation by operation, then the doctor's per-standard verdicts — about half a minute
+npx -y @finchip.ai/foga demo --genesis T9        # add --keep to leave the chain running afterwards
+
 # 3. Containers (Docker with Compose):
 docker compose up --build     # anvil + world + doctor + genesis; outputs land in ./deployments
 ```
@@ -176,7 +184,9 @@ deployments/         world files, doctor reports, genesis evidence (local output
 prover/              the ZK proving sub-package: run.cjs bridge (credential and predicate proofs), build-predicate.mjs (the development ceremony), its own dependencies
 zk/                  circuits/ (kya_predicate_count_v1.circom) and build/ (verification_key.json committed; the proving key is rebuilt locally)
 docker/, docker-compose.yml
-docs/                design memo, compatibility matrix, version lock, build, world, doctor, cell account, kernel, genesis, zk, node, mcp, loop-d, quickstart, wallet, documents, a2a; examples/ (client configurations)
+deploy/              the OG host assets: foga-og.service (systemd, host mode), Caddyfile, og.env.example (docs/og-deployment.md)
+site/                 the documentation site for GitHub Pages (docs.foga.finchip.ai): index.html, llms.txt, CNAME
+docs/                design memo, compatibility matrix, version lock, build, world, doctor, cell account, kernel, genesis, zk, node, mcp, loop-d, quickstart, wallet, documents, a2a, og-deployment; examples/ (client configurations)
 scenarios/skills/    the two ERC-8338 skill packages of the genesis: foga-probe, finch-extract-verify
 scenarios/fixtures/  the pinned document finch-extract-verify works on in T5 and T7
 scripts/             install-solc.sh, install-foundry.sh, relay.mjs, pack-smoke.mjs (the npm tarball run from a clean install)
@@ -206,8 +216,8 @@ foga probe relay-script
 foga genesis run --world <world> [--rpc <url>] [--until T0..T9] [--store <file>] [--out <evidence>] [--zk auto|require|skip] [--crash-after <key>] [--crash-before <key>]
 foga genesis status --world <world> [--store <file>]
 foga keys new [--out <file>] | show | export --role <role> [--out <file>] | check
-foga wallet new [--name <n> | --dir <dir>] [--single] | show [--rpc <url>] | sign --config <cell.config.json> [--role] [--ttl <s>] [--agent-id <id>] [--method --path [--body]]
-                                                                          an agent's own keys (the first step), and a signed Authorization header for a cell
+foga wallet new [--name <n> | --dir <dir>] [--cell] | show [--rpc <url>] | sign (--config <cfg> | --url <node> | --cell <acct> --chain-id <n>) [--role] [--ttl <s>] [--agent-id <id>] [--method --path [--body]]
+                                                                          an agent's own key (the first step; --cell for the separated owner/operator/guardian set), and a signed Authorization header for a cell
 foga demo [--port <n>] [--keep] [--genesis <T0..T9>]
 foga cell list [--public] | schema <capability>
 foga cell new --name <cell> --world <world.json> --store <ops.sqlite> --out <cell.config.json> (--wallet <dir> | --owner <addr> --operator <addr> --guardian <addr>)

package/dist/cli-cell.js

@@ -27,6 +27,9 @@ export const CELL_USAGE = `
   foga cell migrate --config <cell.config.json> --to <new.config.json> [--store <new ops.sqlite>] [--operator <addr>] [--capital-wei <n>] [--no-sweep]
                                                  move the cell to a new revision-2 account (the owner's key); the new config and store are written beside
   foga cell status --config <cell.config.json>   cell_status as the operator
+  foga cell advise --config <cell.config.json> [--brief] [--as-json]
+                                                 what a running cell should do next — separate the roles, tune the policy, standing, a public face, a supervisor,
+                                                 backups, a dedicated RPC — only what applies to this cell; advice, never required; no chain read, no key
   foga cell docs build --config <cell.config.json> [--rpc <url>] [--out <dir>]
                                                  the cell's documents from its configuration and the chain (registration, AID document, ARD descriptor, AUF unit,
                                                  agent card, server.json, manifest) under runtime.http.documentsDir — what the node serves at /documents and /.well-known
@@ -173,6 +176,20 @@ export async function cellCommand(cmd, rest, flags) {
     const rpc = str(flags, "rpc");
     const log = (line) => console.error(line);
     const wallet = walletFromFlags(flags);
+    if (cmd === "advise") {
+        const { adviseCell, formatAdvice } = await import("./node/advise.js");
+        const node = await Node.open({ configPath, rpc, keys: {}, allowUnborn: true, log: () => { } });
+        try {
+            const advice = adviseCell(node);
+            if (flags["as-json"])
+                return print(advice);
+            console.log(formatAdvice(advice, { brief: Boolean(flags.brief), config: configPath }));
+        }
+        finally {
+            node.close();
+        }
+        return;
+    }
     if (cmd === "init") {
         const owner = keysFor("owner", false, wallet);
         const node = await Node.open({ configPath, rpc, keys: { owner }, allowUnborn: true, log });
@@ -180,6 +197,11 @@ export async function cellCommand(cmd, rest, flags) {
             const capital = str(flags, "capital-wei");
             const result = await cellInit(node, { capitalWei: capital ? BigInt(capital) : undefined, log });
             print(result);
+            // Born: say what a cell should do next, once, briefly — the first run stays minimal, the hardening is advice.
+            const { adviseCell, formatAdvice } = await import("./node/advise.js");
+            const next = formatAdvice(adviseCell(node), { brief: true, config: configPath });
+            if (next)
+                console.error(`\n${next}`);
         }
         finally {
             node.close();
@@ -413,6 +435,13 @@ export async function nodeCommand(cmd, rest, flags) {
         const built = readBuilt(documentsDir(node));
         const signers = node.config.access.signers;
         log(`foga ${version}: serving cell ${node.config.name}${node.cell ? ` (${node.cell.address})` : ""} at ${running.url} — /mcp, /api/<capability>, /a2a, /.well-known/agent-card.json, /documents/*, /healthz; ${keys.operator ? "acting with the operator key" : "no operator key: reads and builds only"}; ${node.config.access.keys.length} API key(s) configured; signatures: ${signers.default} by default, ${signers.allow.length} allowed${signers.standing ? `, standing level ${signers.standing.minLevel}+ granted ${signers.standing.level}` : ""}; documents ${built ? `v${built.manifest.version}` : "not built (foga cell docs build)"}`);
+        {
+            // One line of advice at start-up (the full list is `foga cell advise`); nothing here is a condition of serving.
+            const { adviseCell } = await import("./node/advise.js");
+            const recommended = adviseCell(node).filter((a) => a.level === "recommended");
+            if (recommended.length)
+                log(`advice: ${recommended.map((a) => a.id).join(", ")} — foga cell advise --config ${configPath} explains; nothing required`);
+        }
         const stopWatch = !flags["no-watch"] && keys.operator && node.cell ? startWatchLoop(new Watchers(node, catalog), node.config.runtime.pollSeconds * 1000, log) : () => { };
         const stop = () => {
             stopWatch();

package/dist/cli.js

@@ -24,8 +24,9 @@ usage:
   foga world verify --world <world.json> --sourcify [--dry-run] [--only <id,id>] [--server <url>] [--out <dir>] [--build-info <dir>]
                                                  submit every contract the world deployed from the bundle to Sourcify, with the standard JSON input of its
                                                  compiler run (.foga-build/out/<repo>/build-info, written by npm run bundle:verify); a local chain is a dry run
-  foga wallet new [--name <n> | --dir <dir>] [--single]   the first step: a wallet of your own — owner, operator and guardian keys in 0600 files
-                                                 (default ~/.foga/wallet; --name under ~/.foga/wallets/<n>; --single: one signer key). Never overwrites; prints the addresses
+  foga wallet new [--name <n> | --dir <dir>] [--cell]   the first step: a key of your own — one signer in a 0600 file, your identity, which fills
+                                                 every role a cell needs (default ~/.foga/wallet; --name under ~/.foga/wallets/<n>; --cell: the
+                                                 separated owner/operator/guardian set for a guarded cell account). Never overwrites; prints the addresses
   foga wallet show [--name <n> | --dir <dir>] [--rpc <url>]   the wallet's addresses (and balances with an RPC)
   foga wallet sign (--config <cell.config.json> | --url <node url> | --cell <account> --chain-id <n>) [--name <n> | --dir <dir>]
                    [--role signer|operator|owner|guardian] [--ttl <s>] [--agent-id <id>] [--method <METHOD> --path <path> [--body '<json>' | --body-file <f>]]
@@ -244,7 +245,7 @@ async function main() {
         return;
     }
     if (group === "wallet") {
-        const { createWallet, loadWallet, walletDir, walletFileProblems } = await import("./node/wallet.js");
+        const { CELL_ROLES, createWallet, loadWallet, walletDir, walletFileProblems } = await import("./node/wallet.js");
         const dir = resolve(str(flags, "dir") ?? walletDir(str(flags, "name")));
         const printWallet = async (w, made) => {
             console.log(`${made ? "wallet made at" : "wallet"} ${w.dir}${w.name !== "default" ? ` (${w.name})` : ""}, ${w.createdAt}`);
@@ -265,8 +266,11 @@ async function main() {
             provider?.destroy();
             for (const p of walletFileProblems(w))
                 log.warn(p);
-            if (w.roles.includes("owner"))
-                console.log(`fund the owner for a cell's birth (capital and gas) and the operator for its gas; then: foga cell new --wallet ${dir} … and foga cell init --config <cfg> --wallet ${dir}`);
+            const single = w.roles.length === 1 && w.roles[0] === "signer";
+            if (single)
+                console.log(`one key, your identity; it fills every role a cell needs. For a cell's birth, fund this address (capital and gas), then: foga cell new --wallet ${dir} … and foga cell init --config <cfg> --wallet ${dir}`);
+            else if (w.roles.includes("owner"))
+                console.log(`a separated cell wallet; fund the owner for a cell's birth (capital and gas) and the operator for its gas, then: foga cell new --wallet ${dir} … and foga cell init --config <cfg> --wallet ${dir}`);
         };
         if (cmd === "new") {
             const existing = loadWallet(dir);
@@ -275,8 +279,10 @@ async function main() {
                 console.log("(already there; a wallet is never overwritten — foga wallet new --name <n> makes another)");
                 return;
             }
+            // the base is one key (--single, now the default); --cell makes the separated owner/operator/guardian set (the guarded FogaCellAccount profile)
+            const roles = flags.cell ? [...CELL_ROLES] : undefined;
             try {
-                await printWallet(createWallet(dir, { name: str(flags, "name") ?? "default", roles: flags.single ? ["signer"] : undefined }), true);
+                await printWallet(createWallet(dir, { name: str(flags, "name") ?? "default", roles }), true);
             }
             catch (e) {
                 fail(e.message);
@@ -504,13 +510,19 @@ async function main() {
             await result.stop();
             return;
         }
+        let asked = false;
         const stopping = () => {
+            if (asked)
+                return;
+            asked = true;
             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;
+        if (why === "stopped")
+            return; // a stop that was asked for: both children are gone
         fail(`${why}; the quickstart is over`);
     }
     if (group === "demo") {

package/dist/core/world.js

@@ -39,6 +39,23 @@ export class World {
     get chainId() {
         return this.file.chainId;
     }
+    get network() {
+        return this.file.network;
+    }
+    /**
+     * The covenants this world has contracts for, as ERC ids ("ERC-8414"), read off the contract keys ("8414/TaskToken";
+     * "identity8004/…" is the ERC-8004 registry). Data, not a constant: a world that attaches an eleventh covenant under
+     * a new key advertises it here with no code change (docs/extending.md), and a world that lacks one does not claim it.
+     */
+    covenants() {
+        const ids = new Set();
+        for (const key of [...Object.keys(this.file.contracts), ...this.dynamic.keys()]) {
+            const m = /^(?:identity)?(\d{4,5})$/.exec(key.split("/")[0]);
+            if (m)
+                ids.add(`ERC-${m[1]}`);
+        }
+        return [...ids].sort((a, b) => Number(a.slice(4)) - Number(b.slice(4)));
+    }
     has(id) {
         return Boolean(this.file.contracts[id] || this.dynamic.get(id));
     }

package/dist/demo/birth.js

@@ -17,7 +17,13 @@ export async function birthCell(o) {
     const guardian = o.keys ? new Wallet(o.keys.guardian) : Wallet.createRandom();
     log(`cell ${o.name}: owner ${owner.address}, operator ${operator.address}, guardian ${guardian.address}${o.keys ? " (the wallet's keys)" : " (fresh keys)"}`);
     // --- funding by W, the standing scheme registered by W
-    const price = (await k.world.provider.getFeeData()).gasPrice ?? 1000000000n;
+    // The reserve is priced at the chain's gas price, floored at 1 gwei. A public testnet can quote a price near zero
+    // (Sepolia has sat at a few wei), which would fund the roles with the flat amounts alone: the operator below the
+    // cell policy's gas floor (a quarter of the daily gas budget — the budget gate then refuses every tender) and the
+    // guardian with next to nothing for its suspend and resume. The floor keeps the funding meaningful on any chain;
+    // on a local chain, whose price is above it, nothing changes.
+    const quoted = (await k.world.provider.getFeeData()).gasPrice ?? 1000000000n;
+    const price = quoted > 1000000000n ? quoted : 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"));

package/dist/demo/loop-d.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:net";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -106,6 +106,14 @@ export async function runLoopD(opts) {
     const root = repoRoot();
     const dir = resolve(opts.dir);
     mkdirSync(dir, { recursive: true });
+    // One working directory holds one run: the cell's configuration and store, the orchestrator's and the demander's
+    // stores, the cases, the brief, the transcripts. A second run in the same directory would find the first run's
+    // keyed operations and replay them (a resumable kernel resumes) against a cell with fresh keys — the birth then
+    // fails on the first replayed answer. So a previous run's files are cleared first; the evidence (`--out`) lives
+    // elsewhere and is kept.
+    const cleared = cleanLoopDDir(dir);
+    if (cleared.length)
+        log(`loop D: cleared the previous run's files in ${dir} (${cleared.join(", ")})`);
     const worldPath = resolve(opts.worldPath);
     const seed = opts.seed ?? 7;
     const cases = opts.cases ?? ALL_CASES;
@@ -563,3 +571,33 @@ export function defaultLoopDDir() {
         mkdirSync(dir, { recursive: true });
     return dir;
 }
+/** The files a Loop D run leaves in its working directory — its own and nothing else. */
+const LOOP_D_FILES = ["D.json", "D.ops.sqlite", "D.ops.sqlite-wal", "D.ops.sqlite-shm", "orchestrator.sqlite", "orchestrator.sqlite-wal", "orchestrator.sqlite-shm", "demander.sqlite", "demander.sqlite-wal", "demander.sqlite-shm", "agent-brief.md"];
+const LOOP_D_DIRS = ["transcripts", "documents"];
+/** Remove what a previous Loop D run left in `dir` (only the run's own files); returns the names removed. */
+export function cleanLoopDDir(dir) {
+    if (!existsSync(dir))
+        return [];
+    const removed = [];
+    for (const name of LOOP_D_FILES) {
+        const p = join(dir, name);
+        if (existsSync(p)) {
+            rmSync(p, { force: true });
+            removed.push(name);
+        }
+    }
+    for (const name of readdirSync(dir)) {
+        if (/^cases-.*\.json$/.test(name)) {
+            rmSync(join(dir, name), { force: true });
+            removed.push(name);
+        }
+    }
+    for (const name of LOOP_D_DIRS) {
+        const p = join(dir, name);
+        if (existsSync(p)) {
+            rmSync(p, { recursive: true, force: true });
+            removed.push(`${name}/`);
+        }
+    }
+    return removed;
+}

package/dist/demo/quickstart.js

@@ -17,7 +17,8 @@ import { birthCell } from "./birth.js";
 import { mintCases } from "./demander.js";
 import { cleanEnv, ownCli, waitForHttp } from "./loop-d.js";
 export const MARKER = "quickstart.json";
-export const PACKAGE_NAME = "@finchip.ai/foga";
+export { PACKAGE_NAME } from "../util/version.js";
+import { PACKAGE_NAME } from "../util/version.js";
 /** How a client should start this very CLI: the published package through npx, or this checkout's compiled launcher. */
 export function clientLauncher() {
     const root = repoRoot();
@@ -87,22 +88,32 @@ export async function runQuickstart(o = {}) {
     mkdirSync(keysDir, { recursive: true, mode: 0o700 });
     // --- the wallet: the first step; made now when there is none, reused when there is; never a reason to stop
     const wallet = ensureWallet(walletPath, { name: "default" });
+    const singleKey = wallet.wallet.roles.length === 1 && wallet.wallet.roles[0] === "signer";
+    const walletAddrs = singleKey ? `identity ${wallet.wallet.addresses.signer}` : `owner ${wallet.wallet.addresses.owner}, operator ${wallet.wallet.addresses.operator}, guardian ${wallet.wallet.addresses.guardian}`;
     if (wallet.ephemeral)
         log(`quickstart: wallet: could not write ${walletPath} (${wallet.reason}); using keys made in memory for this run — they are not kept`);
     else
-        log(`quickstart: wallet: ${wallet.created ? "made" : "using"} ${wallet.wallet.dir} — owner ${wallet.wallet.addresses.owner}, operator ${wallet.wallet.addresses.operator}, guardian ${wallet.wallet.addresses.guardian}`);
+        log(`quickstart: wallet: ${wallet.created ? "made" : "using"} ${wallet.wallet.dir} — ${walletAddrs}`);
     // --- the chain and the world
     log(`quickstart: starting ${version} on ${rpc} (log ${join(dir, "anvil.log")})`);
     const anvil = await launchAnvil({ port, logPath: join(dir, "anvil.log") });
     let node = null;
     let endedWith = null;
     const ended = new Promise((r) => (endedWith = r));
-    anvil.on("exit", (code, signal) => endedWith?.(`anvil stopped (${code !== null ? `exit code ${code}` : `signal ${signal}`})`));
+    // a stop asked for (Ctrl-C, --exit, SIGTERM) ends the children in order; their exits are then expected and do not end the run
+    // early — otherwise the node's exit would resolve `ended` while anvil is still being stopped and leave the chain running
+    let stopping = false;
+    anvil.on("exit", (code, signal) => {
+        if (!stopping)
+            endedWith?.(`anvil stopped (${code !== null ? `exit code ${code}` : `signal ${signal}`})`);
+    });
     const stop = async () => {
+        stopping = true;
         if (node)
             await stopChild(node);
         node = null;
         await stopChild(anvil);
+        endedWith?.("stopped");
     };
     try {
         const worldPath = join(dir, "world.json");
@@ -189,12 +200,17 @@ export async function runQuickstart(o = {}) {
             const host = listen.slice(0, i) || "127.0.0.1";
             nodeUrl = `http://${host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host}:${listen.slice(i + 1)}`;
             node = spawn(cli.command, [...cli.args, "node", "serve", "--config", configPath, "--rpc", rpc, "--listen", listen], { env: cleanEnv({ FOGA_OPERATOR_KEY_FILE: keyPaths.operator }), stdio: ["ignore", "ignore", "pipe"] });
+            // the node's lines are relayed, except a watcher tick in which nothing happened (every two seconds, forever)
+            const idleTick = /: anchor ACTIVE, heartbeat not sent \([^)]*\); 0 new tender\(s\); 0 settled, 0 withdrawn; safety Satisfied$/;
             node.stderr.on("data", (d) => {
                 for (const line of String(d).split("\n"))
-                    if (line.trim())
+                    if (line.trim() && !idleTick.test(line.trim()))
                         log(`  node| ${line}`);
             });
-            node.on("exit", (code, signal) => endedWith?.(`the node stopped (${code !== null ? `exit code ${code}` : `signal ${signal}`})`));
+            node.on("exit", (code, signal) => {
+                if (!stopping)
+                    endedWith?.(`the node stopped (${code !== null ? `exit code ${code}` : `signal ${signal}`})`);
+            });
             await waitForHttp(`${nodeUrl}/healthz`);
             // --- the entrance answers: health, a public read, the agent key's pre-check of the first tender, the MCP handshake and tool list
             const health = (await (await fetch(`${nodeUrl}/healthz`)).json());
@@ -246,7 +262,8 @@ export async function runQuickstart(o = {}) {
         lines.push("");
         lines.push(`  chain     anvil on ${rpc} (chain ${world.chainId}), world ${world.worldId} — the chain lives as long as this process`);
         lines.push(`  cell      ${name} = ${cell.account}${cell.agentId ? ` (ERC-8004 agent ${cell.agentId})` : ""}`);
-        lines.push(`  wallet    ${wallet.ephemeral ? `keys made in memory for this run, written to ${keysDir} (${walletPath} was not writable)` : `${wallet.wallet.dir} (${wallet.created ? "made now" : "reused"}) — owner ${cell.owner.address}, operator ${cell.operator.address}, guardian ${cell.guardian.address}; the same wallet on every run`}`);
+        const walletRoles = singleKey ? `identity ${cell.owner.address} (one key, every role)` : `owner ${cell.owner.address}, operator ${cell.operator.address}, guardian ${cell.guardian.address}`;
+        lines.push(`  wallet    ${wallet.ephemeral ? `keys made in memory for this run, written to ${keysDir} (${walletPath} was not writable)` : `${wallet.wallet.dir} (${wallet.created ? "made now" : "reused"}) — ${walletRoles}; the same wallet on every run`}`);
         lines.push(`  skills    ${Object.keys(cell.held).join(", ")} (held and offered)`);
         if (minted.length)
             lines.push(`  tenders   ${minted.map((c) => `#${c.tokenId} ${c.skill} (${formatEther(c.rewardWei)} ETH)`).join(", ")} — open, waiting for the cell to take them`);
@@ -279,6 +296,22 @@ export async function runQuickstart(o = {}) {
         lines.push(`  FOGA_DEMANDER_KEY=<a funded key, anvil's first account by default> ${demanderCmd}`);
         if (launcher.fromCheckout)
             lines.push(`(This is a checkout: the configurations start ${launcher.command} ${launcher.args.join(" ")}; a published install would start npx -y ${PACKAGE_NAME}.)`);
+        // Next: what a cell should do once it runs — advice, kept out of the first run on purpose (docs/node.md, "Advice").
+        try {
+            const { adviseCell, formatAdvice } = await import("../node/advise.js");
+            const reader = await Node.open({ configPath, rpc, keys: {}, allowUnborn: true, log: () => { } });
+            try {
+                const next = formatAdvice(adviseCell(reader), { brief: true, config: configPath });
+                if (next)
+                    lines.push("", next);
+            }
+            finally {
+                reader.close();
+            }
+        }
+        catch {
+            // advice is never a reason for a quickstart to fail
+        }
         lines.push("");
         lines.push(o.exit ? "Started with --exit: stopping the node and the chain." : "Ctrl-C stops the node and the chain; the next quickstart starts over in the same directory.");
         const summary = lines.join("\n");

package/dist/genesis/probe.js

@@ -18,6 +18,22 @@ export async function runProbe(world, input) {
         throw new Error(`block ${input.block} not found`);
     const at = { blockTag: tag };
     const fromBlock = input.lookback === undefined ? 0 : Math.max(0, input.block - input.lookback);
+    // A bounded scan is asked in windows of 2000 blocks, the windows in parallel and their logs concatenated in block
+    // order — the same logs a single query returns, in the same order (the answer hash is over them, so this must not
+    // change), but each request small enough for a public endpoint, which caps the range of `eth_getLogs` and answers
+    // a 9000-block scan slowly or not at all: a skill run on Sepolia overran its worker's budget on exactly this. An
+    // unbounded scan (no lookback: a local chain) stays one query.
+    const WINDOW = 2000;
+    const logsOf = async (c, filter) => {
+        const to = input.block;
+        if (input.lookback === undefined || to - fromBlock < WINDOW)
+            return c.queryFilter(filter, fromBlock, to);
+        const windows = [];
+        for (let a = fromBlock; a <= to; a += WINDOW)
+            windows.push([a, Math.min(a + WINDOW - 1, to)]);
+        const parts = await Promise.all(windows.map(([a, b]) => c.queryFilter(filter, a, b)));
+        return parts.flat();
+    };
     const section = async (fn) => {
         try {
             return await fn();
@@ -95,13 +111,13 @@ export async function runProbe(world, input) {
     });
     checks.erc8454 = await section(async () => {
         const units = world.contract("8454/AUFUnitRegistry");
-        const logs = await units.queryFilter(units.filters.UnitRegistered(null, subject), fromBlock, input.block);
+        const logs = await logsOf(units, units.filters.UnitRegistered(null, subject));
         return { unitsControlled: logs.map((l) => String(l.args.unitId)) };
     });
     checks.erc8338 = await section(async () => {
         const skills = world.contract("8338/SkillToken");
         const held = String(await skills.balanceOf(subject, at));
-        const received = await skills.queryFilter(skills.filters.Transfer(null, subject), fromBlock, input.block);
+        const received = await logsOf(skills, skills.filters.Transfer(null, subject));
         const ids = new Set();
         for (const l of received)
             ids.add(String(l.args.tokenId));
@@ -122,13 +138,13 @@ export async function runProbe(world, input) {
     checks.erc8414 = await section(async () => {
         const tasks = world.contract("8414/TaskToken");
         const held = String(await tasks.balanceOf(subject, at));
-        const submitted = await tasks.queryFilter(tasks.filters.FulfillmentSubmitted(null, null, subject), fromBlock, input.block);
-        const accepted = await tasks.queryFilter(tasks.filters.FulfillmentAccepted(null, null, subject), fromBlock, input.block);
+        const submitted = await logsOf(tasks, tasks.filters.FulfillmentSubmitted(null, null, subject));
+        const accepted = await logsOf(tasks, tasks.filters.FulfillmentAccepted(null, null, subject));
         return { held, submissions: String(submitted.length), accepted: String(accepted.length) };
     });
     checks.erc8447 = await section(async () => {
         const swarms = world.contract("8447/SwarmRegistry");
-        const activated = await swarms.queryFilter(swarms.filters.MemberActivated(null, subject), fromBlock, input.block);
+        const activated = await logsOf(swarms, swarms.filters.MemberActivated(null, subject));
         const ids = [...new Set(activated.map((l) => String(l.args.swarmId)))].sort();
         const memberships = [];
         for (const swarmId of ids)
@@ -137,12 +153,12 @@ export async function runProbe(world, input) {
     });
     checks.erc8436 = await section(async () => {
         const acdf = world.contract("8436/ACDFRegistry");
-        const filed = await acdf.queryFilter(acdf.filters.IssueFiled(null, null, null, subject), fromBlock, input.block);
+        const filed = await logsOf(acdf, acdf.filters.IssueFiled(null, null, null, subject));
         return { issuesFiled: String(filed.length) };
     });
     checks.erc8471 = await section(async () => {
         const adrf = world.contract("8471/ADRFDisputeRegistry");
-        const filed = await adrf.queryFilter(adrf.filters.CaseFiled(), fromBlock, input.block);
+        const filed = await logsOf(adrf, adrf.filters.CaseFiled());
         let asParty = 0;
         for (const l of filed) {
             if (String(l.args.claimant).toLowerCase() === low || String(l.args.respondent).toLowerCase() === low)

package/dist/genesis/skill-runner.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
-import { dirname, resolve } from "node:path";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { repoRoot } from "../util/fs.js";
 import { buildSkillPackage, readSkillDir } from "../core/pack/skillpack.js";
 /**
@@ -26,6 +27,34 @@ function workerPath() {
     const ext = here.endsWith(".ts") ? ".ts" : ".js";
     return new URL(`./skill-worker${ext}`, here).pathname;
 }
+/**
+ * The `node_modules` directories the worker's imports resolve through. In a checkout they are under the package root;
+ * in an npm or npx install the dependencies are hoisted beside the package (`<prefix>/node_modules/ethers` next to
+ * `<prefix>/node_modules/@finchip.ai/foga`), outside it, and a worker allowed to read the package root alone died on
+ * its first import (`ERR_ACCESS_DENIED` on `ethers/package.json`). Every ancestor's `node_modules` is granted, by its
+ * real path as well when a link is involved; the grant is read-only and the worker still never sees a key.
+ */
+export function dependencyDirs(root = repoRoot()) {
+    const out = new Set();
+    let dir = resolve(root);
+    for (;;) {
+        const nm = join(dir, "node_modules");
+        if (existsSync(nm)) {
+            out.add(nm);
+            try {
+                out.add(realpathSync(nm));
+            }
+            catch {
+                /* a dangling link: the literal path is enough */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return [...out];
+}
 /** True under the development loader (tsx): Node's permission model cannot be combined with a custom loader. */
 function underLoader() {
     return process.execArgv.some((a) => /--import|--loader|--require|tsx/.test(a)) || /\.ts$/.test(workerPath());
@@ -43,7 +72,7 @@ export async function runIsolated(job, opts = {}) {
     const args = [...process.execArgv, "--max-old-space-size=512"];
     if (!underLoader() && opts.readDirs?.length) {
         args.push("--permission");
-        for (const d of new Set([...opts.readDirs, dirname(workerPath())]))
+        for (const d of new Set([...opts.readDirs, dirname(workerPath()), ...dependencyDirs()]))
             args.push(`--allow-fs-read=${resolve(d)}`);
     }
     args.push(workerPath());

package/dist/http/server.js

@@ -6,6 +6,7 @@ import { A2AServer } from "../a2a/server.js";
 import { A2A_ERRORS, A2A_WELL_KNOWN } from "../a2a/types.js";
 import { buildMcpServer } from "../mcp/server.js";
 import { DOCUMENT_FILES, documentsDir, readManifest } from "../node/documents.js";
+import { buildPropagationManifest, servicesCatalogOf } from "../node/propagation.js";
 import { PUBLIC_CALLER } from "../tools/index.js";
 import { resolveCaller } from "./access.js";
 import { NonceCache } from "./signed.js";
@@ -162,7 +163,7 @@ export function createHttpServer(o) {
         if (method === "GET" && url.pathname === "/") {
             const r = await catalog.invoke(node, "cell_status", {}, caller);
             const decisions = node.store.summary().decisions;
-            return json(res, 200, { foga: o.version, cell: cfg.name, status: r.ok ? r.output : null, decisions, endpoints: { mcp: "/mcp", api: "/api/<capability>", a2a: "/a2a", agentCard: A2A_WELL_KNOWN, documents: "/documents/<file>", health: "/healthz" } });
+            return json(res, 200, { foga: o.version, cell: cfg.name, status: r.ok ? r.output : null, decisions, endpoints: { mcp: "/mcp", api: "/api/<capability>", a2a: "/a2a", agentCard: A2A_WELL_KNOWN, manifest: "/.well-known/foga-cell.json", documents: "/documents/<file>", health: "/healthz" } });
         }
         if (method === "GET" && url.pathname === "/api/capabilities")
             return json(res, 200, { caller: { id: caller.id, level: caller.level, visibility: caller.visibility, via: resolved.via }, capabilities: catalog.list(caller) });
@@ -200,6 +201,24 @@ export function createHttpServer(o) {
                 return json(res, 400, { ok: false, gate: "input", reason: "mode must be simulate, build or act" });
             return answer(res, await catalog.invoke(node, name, input, caller, { mode }));
         }
+        // the propagation manifest: free, built live from the configuration, answered even before any document is published
+        if (method === "GET" && url.pathname === "/.well-known/foga-cell.json") {
+            const text = Buffer.from(JSON.stringify(buildPropagationManifest(node, { version: o.version }), null, 2) + "\n");
+            res.writeHead(200, { "content-type": "application/json; charset=utf-8", "cache-control": "public, max-age=300", "content-length": text.length });
+            res.end(text);
+            return;
+        }
+        // the services catalog, when the one this cell's manifest points at is its own (the reference cell: the maintainer's list);
+        // a static file at this path on the host, answered by the proxy before the node, is how the list changes without a release
+        if (method === "GET" && url.pathname === "/services.json") {
+            const doc = servicesCatalogOf(node, { version: o.version });
+            if (!doc)
+                return json(res, 404, { ok: false, reason: "this cell's services pointer names another catalog; read it from the manifest at /.well-known/foga-cell.json" });
+            const text = Buffer.from(JSON.stringify(doc, null, 2) + "\n");
+            res.writeHead(200, { "content-type": "application/json; charset=utf-8", "cache-control": "public, max-age=300", "content-length": text.length });
+            res.end(text);
+            return;
+        }
         // the published documents (foga cell docs build): served as built, by their file names, and at the well-known paths
         if (method === "GET" && (url.pathname.startsWith("/.well-known/") || url.pathname.startsWith("/documents/"))) {
             const dir = documentsDir(node);