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

package/dist/cli-cell.js

@@ -6,6 +6,7 @@ import { cellInit } from "./node/init.js";
 import { KeyIsolationError, forbiddenVariables, loadOperatorKey, loadRoleKey } from "./node/keys.js";
 import { cellMigrate } from "./node/migrate.js";
 import { Node } from "./node/node.js";
+import { loadWallet, walletKey } from "./node/wallet.js";
 import { Watchers } from "./node/watchers.js";
 import { defaultCatalog, OPERATOR_CALLER, PUBLIC_CALLER } from "./tools/index.js";
 import { exists, repoRoot } from "./util/fs.js";
@@ -20,23 +21,37 @@ import { fail } from "./util/log.js";
 export const CELL_USAGE = `
   foga cell list [--public] [--as-json]          the capabilities (action, visibility, principal, modes) as the operator or as the public sees them
   foga cell schema <capability>                  the input and output JSON Schema of a capability
-  foga cell new --name <cell> --world <world.json> --store <ops.sqlite> --owner <addr> --operator <addr> --guardian <addr> --out <cell.config.json> [--rpc <url>] [--skills <dir>] [--input-dir <dir>]
-  foga cell init --config <cell.config.json> [--rpc <url>] [--capital-wei <n>]
-                                                 the cell's birth (the owner's key: FOGA_OWNER_KEY[_FILE]); writes the account, agent id, binding, record and unit into the config
+  foga cell new --name <cell> --world <world.json> --store <ops.sqlite> --out <cell.config.json> (--wallet <dir> | --owner <addr> --operator <addr> --guardian <addr>) [--rpc <url>] [--skills <dir>] [--input-dir <dir>]
+  foga cell init --config <cell.config.json> [--wallet <dir>] [--rpc <url>] [--capital-wei <n>]
+                                                 the cell's birth (the owner's key: the wallet's, or FOGA_OWNER_KEY[_FILE]); writes the account, agent id, binding, record and unit into the config
   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 <capability> --config <cell.config.json> [--mode simulate|build|act] [--json '<input json>' | --json-file <f>] [--<field> <value> ...]
-                                                 any capability; an act loads FOGA_OPERATOR_KEY[_FILE], an admin capability FOGA_OWNER_KEY[_FILE] or FOGA_GUARDIAN_KEY[_FILE]
+  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
+  foga cell docs publish --config <cell.config.json> [--wallet <dir>] [--rpc <url>]
+                                                 build, then commit on chain what differs (setAgentURI, setDocumentURI, updateDescriptor, publishVersion; the operator
+                                                 key, one keyed job), then read every commitment back
+  foga cell docs status --config <cell.config.json> [--rpc <url>]   what is built, what the chain holds, what a publish would commit
+  foga cell <capability> --config <cell.config.json> [--wallet <dir>] [--mode simulate|build|act] [--json '<input json>' | --json-file <f>] [--<field> <value> ...]
+                                                 any capability; an act loads the operator key, an admin capability the owner's or the guardian's — from --wallet, or from
+                                                 FOGA_OPERATOR_KEY[_FILE], FOGA_OWNER_KEY[_FILE], FOGA_GUARDIAN_KEY[_FILE]
                                                  [--caller <id> --level read|build|act] call as another caller (what the public or an API-key holder would get)
   foga cell owner <capability> … | foga cell guardian <capability> …   the same, said explicitly
+  foga node <command> … [--wallet <dir>]         every node command takes the operator key from the wallet's operator.key (= FOGA_OPERATOR_KEY_FILE)
+  foga node preflight --config <cell.config.json> [--wallet <dir>] [--rpc <url>] [--no-executors] [--no-network] [--out <report.json>] [--strict]
+                                                 the readiness reconciliation before the public is served: the account and its allow-list, the operator key and its
+                                                 gas, the standing, the skills' packages and executors, the documents against the chain, the public URL, the model;
+                                                 advisory (exit 5 on a Fail only with --strict)
   foga node tick --config <cell.config.json>     run the watchers once (heartbeat, discovery, settlement, safety) in a node environment (operator key alone)
   foga node watch --config <cell.config.json> [--interval <s>]   run the watchers on the poll interval until stopped
   foga node mcp --config <cell.config.json>      MCP over stdio for a local client (Claude Desktop, Claude Code, Cursor): the operator's full level with
                                                  FOGA_OPERATOR_KEY[_FILE] in the environment, read and build without it; logs go to stderr
   foga node serve --config <cell.config.json> [--listen <host:port>] [--no-watch]
-                                                 the HTTP server: POST /api/<capability>, /mcp (Streamable HTTP), /healthz, / — the public reads and builds,
-                                                 a Bearer key acts as its grant says; the watchers run beside it
+                                                 host mode: POST /api/<capability>, /mcp (Streamable HTTP), /a2a (A2A 1.0), /.well-known/agent-card.json, /documents/*,
+                                                 /healthz, / — the public reads and builds, a Bearer key or a wallet signature (FOGA-EIP712) acts as its grant says;
+                                                 the watchers run beside it; no model
   foga node key new --config <cell.config.json> --id <id> [--level read|build|act] [--visibility public|caller|operator] [--note <text>]
                                                  mint an API key for the HTTP entrance: printed once, kept only as its hash in the config
   foga node run --config <cell.config.json> [--model stub|anthropic] [--listen <host:port> | --no-http] [--interval <s>] [--once | --ticks <n>] [--transcripts <dir>]
@@ -44,7 +59,7 @@ export const CELL_USAGE = `
                                                  judges) on the poll interval; the operator key alone; anthropic needs ANTHROPIC_API_KEY and runtime.model.model
 `;
 const str = (flags, key) => (typeof flags[key] === "string" ? flags[key] : undefined);
-const RESERVED = new Set(["config", "mode", "json", "json-file", "caller", "level", "rpc", "public", "help"]);
+const RESERVED = new Set(["config", "mode", "json", "json-file", "caller", "level", "rpc", "public", "help", "wallet"]);
 function inputFromFlags(flags) {
     let input = {};
     const inline = str(flags, "json");
@@ -81,7 +96,26 @@ function callerFromFlags(flags) {
         fail(`--level must be read, build, act or admin`);
     return { id: id ?? "caller", entrance: "cli", level: lvl, visibility: lvl === "admin" ? "operator" : id ? "caller" : "public" };
 }
-function keysFor(role, strict = false) {
+/** The wallet `--wallet <dir>` names, or null without the flag. */
+function walletFromFlags(flags) {
+    const dir = str(flags, "wallet");
+    if (!dir)
+        return null;
+    const w = loadWallet(resolve(dir));
+    if (!w)
+        fail(`${resolve(dir)} holds no wallet (no wallet.json); foga wallet new --dir ${resolve(dir)} makes one`);
+    return w;
+}
+/** A role's key: from the wallet when --wallet is given, from the environment otherwise. */
+function keysFor(role, strict = false, wallet = null) {
+    if (wallet) {
+        try {
+            return walletKey(wallet, role);
+        }
+        catch (e) {
+            fail(e.message);
+        }
+    }
     try {
         return (role === "operator" && strict ? loadOperatorKey() : loadRoleKey(role)).privateKey;
     }
@@ -120,7 +154,8 @@ export async function cellCommand(cmd, rest, flags) {
         return print({ name: cap.name, title: cap.title, description: cap.description, action: cap.action, visibility: cap.visibility, principal: cap.principal, ercs: cap.ercs, input: z.toJSONSchema(cap.input, { target: "draft-2020-12", io: "input" }), output: z.toJSONSchema(cap.output, { target: "draft-2020-12", io: "output" }) });
     }
     if (cmd === "new") {
-        const need = (k) => str(flags, k) ?? fail(`--${k} is required`);
+        const wallet = walletFromFlags(flags);
+        const need = (k) => str(flags, k) ?? (wallet && wallet.addresses[k] ? wallet.addresses[k] : fail(`--${k} is required (or --wallet <dir> with a ${k} key)`));
         const out = resolve(need("out"));
         if (exists(out))
             fail(`${out} exists; choose another --out (a config is never overwritten)`);
@@ -137,8 +172,9 @@ export async function cellCommand(cmd, rest, flags) {
     const configPath = str(flags, "config") ?? fail("--config <cell.config.json> is required");
     const rpc = str(flags, "rpc");
     const log = (line) => console.error(line);
+    const wallet = walletFromFlags(flags);
     if (cmd === "init") {
-        const owner = keysFor("owner");
+        const owner = keysFor("owner", false, wallet);
         const node = await Node.open({ configPath, rpc, keys: { owner }, allowUnborn: true, log });
         try {
             const capital = str(flags, "capital-wei");
@@ -151,7 +187,7 @@ export async function cellCommand(cmd, rest, flags) {
         return;
     }
     if (cmd === "migrate") {
-        const owner = keysFor("owner");
+        const owner = keysFor("owner", false, wallet);
         const to = resolve(str(flags, "to") ?? fail("--to <new.config.json> is required"));
         if (exists(to))
             fail(`${to} exists; choose another --to`);
@@ -166,6 +202,72 @@ export async function cellCommand(cmd, rest, flags) {
         }
         return;
     }
+    if (cmd === "docs") {
+        const sub = rest[0];
+        const { buildDocuments, readBack, documentsDir, onChainState, readBuilt, publishSteps } = await import("./node/documents.js");
+        const { version } = await import("./util/version.js");
+        if (sub === "build") {
+            const node = await Node.open({ configPath, rpc, keys: {}, log });
+            try {
+                const built = await buildDocuments(node, { version, dir: str(flags, "out") });
+                console.error(`documents v${built.manifest.version} written to ${built.dir}:`);
+                for (const [file, d] of Object.entries(built.manifest.documents))
+                    console.error(`  ${file.padEnd(20)} ${d.standard.padEnd(40)} ${d.contentHash}`);
+                const { steps, unchanged } = await publishSteps(node, built);
+                console.error(steps.length ? `a publish would commit: ${steps.map((x) => x.label).join("; ")}` : "every commitment on chain matches what was built");
+                if (unchanged.length)
+                    console.error(`already as built: ${unchanged.join(", ")}`);
+                print(built.manifest);
+            }
+            finally {
+                node.close();
+            }
+            return;
+        }
+        if (sub === "status") {
+            const node = await Node.open({ configPath, rpc, keys: {}, log });
+            try {
+                const dir = documentsDir(node);
+                const built = readBuilt(dir);
+                const rows = built ? await readBack(node, built) : [];
+                print({ dir, manifest: built?.manifest ?? null, onChain: await onChainState(node), readBack: rows, pending: built ? (await publishSteps(node, built)).steps.map((x) => x.label) : [] });
+                if (rows.some((r) => r.ok === false))
+                    process.exitCode = 2;
+            }
+            finally {
+                node.close();
+            }
+            return;
+        }
+        if (sub === "publish") {
+            const node = await Node.open({ configPath, rpc, keys: { operator: keysFor("operator", false, wallet) }, log });
+            try {
+                const result = await catalog.invoke(node, "docs_publish", {}, OPERATOR_CALLER, { mode: "act" });
+                if (!result.ok) {
+                    print(result);
+                    process.exitCode = 2;
+                    return;
+                }
+                const out = result.output;
+                console.error(`documents v${out.version} in ${out.dir}: ${out.committed.length ? `committed ${out.committed.join(", ")}` : "nothing to commit"}${out.unchanged.length ? `; already as built: ${out.unchanged.join(", ")}` : ""} (job ${out.jobId}, ${out.operations.length} operation(s))`);
+                // the read-back from here fetches the URLs too, when the node serves them
+                const built = readBuilt(out.dir);
+                const rows = await readBack(node, built, { fetchUrls: true });
+                for (const r of rows)
+                    console.error(`  ${r.ok === true ? "ok     " : r.ok === false ? "FAIL   " : "unread "} ${r.commitment.padEnd(26)} ${r.detail}`);
+                print({ ...out, readBack: rows });
+                if (rows.some((r) => r.ok === false)) {
+                    console.error("a commitment read back from the chain does not match what was built: the publish is not complete");
+                    process.exitCode = 2;
+                }
+            }
+            finally {
+                node.close();
+            }
+            return;
+        }
+        fail("foga cell docs build | publish | status");
+    }
     // a capability, possibly said as "owner <capability>" / "guardian <capability>"
     let name = cmd;
     let explicitRole = null;
@@ -186,10 +288,10 @@ export async function cellCommand(cmd, rest, flags) {
     if (cap.action !== "read" && mode === "act") {
         if (cap.action === "admin") {
             const role = cap.signer ?? explicitRole ?? "owner";
-            keys[role] = keysFor(role);
+            keys[role] = keysFor(role, false, wallet);
         }
         else
-            keys.operator = keysFor("operator");
+            keys.operator = keysFor("operator", false, wallet);
     }
     const node = await Node.open({ configPath, rpc, keys, log });
     try {
@@ -230,6 +332,32 @@ export async function nodeCommand(cmd, rest, flags) {
     }
     const configPath = str(flags, "config") ?? fail("--config <cell.config.json> is required");
     const log = (line) => console.error(line);
+    // --wallet <dir>: the operator key file of the wallet, as FOGA_OPERATOR_KEY_FILE would name it; never beside another key source
+    const wallet = walletFromFlags(flags);
+    if (wallet) {
+        if (process.env.FOGA_OPERATOR_KEY || process.env.FOGA_OPERATOR_KEY_FILE)
+            fail("--wallet and FOGA_OPERATOR_KEY[_FILE] are both set; a node takes its operator key from one place");
+        if (!wallet.files.operator)
+            fail(`wallet ${wallet.dir} has no operator key`);
+        process.env.FOGA_OPERATOR_KEY_FILE = wallet.files.operator;
+    }
+    if (cmd === "preflight") {
+        const { preflight, printPreflight } = await import("./node/preflight.js");
+        const { writeJson } = await import("./util/fs.js");
+        const node = await Node.open({ configPath, rpc: str(flags, "rpc"), keys: {}, log });
+        try {
+            const report = await preflight(node, { executors: !flags["no-executors"], network: !flags["no-network"] });
+            printPreflight(report, (line) => console.log(line));
+            if (str(flags, "out"))
+                writeJson(resolve(str(flags, "out")), report);
+            if (flags.strict && report.summary.Fail > 0)
+                process.exitCode = 5;
+        }
+        finally {
+            node.close();
+        }
+        return;
+    }
     if (cmd === "key") {
         if (rest[0] !== "new")
             fail("foga node key new --config <cfg> --id <id> [--level act] [--visibility caller]");
@@ -281,7 +409,10 @@ export async function nodeCommand(cmd, rest, flags) {
         const { version } = await import("./util/version.js");
         const listen = str(flags, "listen") ?? node.config.runtime.http.listen;
         const running = await createHttpServer({ node, catalog, version, log }).listen(listen);
-        log(`foga ${version}: serving cell ${node.config.name}${node.cell ? ` (${node.cell.address})` : ""} at ${running.url} — /mcp, /api/<capability>, /healthz; ${keys.operator ? "acting with the operator key" : "no operator key: reads and builds only"}; ${node.config.access.keys.length} API key(s) configured`);
+        const { documentsDir, readBuilt } = await import("./node/documents.js");
+        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)"}`);
         const stopWatch = !flags["no-watch"] && keys.operator && node.cell ? startWatchLoop(new Watchers(node, catalog), node.config.runtime.pollSeconds * 1000, log) : () => { };
         const stop = () => {
             stopWatch();
@@ -363,7 +494,7 @@ export async function nodeCommand(cmd, rest, flags) {
         return;
     }
     if (cmd !== "tick" && cmd !== "watch")
-        fail(`unknown node command ${cmd}; tick, watch, mcp, serve, run or key`);
+        fail(`unknown node command ${cmd}; tick, watch, mcp, serve, run, preflight or key`);
     // a node environment: the operator key alone, nothing that derives another role
     const operator = keysFor("operator", true);
     const node = await Node.open({ configPath, rpc: str(flags, "rpc"), keys: { operator }, log });

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, readFileSync, 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";
@@ -21,6 +21,16 @@ usage:
                                                  deploy-mode config: the whole stack; attach-mode config: attach what it
                                                  lists and deploy the reference contracts it does not (deployer = W)
   foga world attach --world <config.json> [--out <file>]   address book only, no transactions (every contract listed)
+  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 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>]]
+                                                 an Authorization header (FOGA-EIP712) proving the wallet to that cell — named by its configuration, by its node's
+                                                 URL (/healthz says which account and chain) or by hand: a session envelope, or one bound to a request
   foga keys new [--out <file>]                   write a fresh 12-word phrase (default ~/.foga/genesis.mnemonic) and print the role addresses
   foga keys show                                 print the role addresses the environment derives (FOGA_MNEMONIC[_FILE], FOGA_KEY_*)
   foga keys export --role <role> [--out <file>]  write one role's key to a 0600 file for a node that holds that key alone
@@ -38,12 +48,18 @@ 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>] [--wallet <dir>] [--port <n>] [--listen <host:port> | --no-serve] [--name <cell>] [--no-tenders] [--exit]
+                                                 one command to a live cell: the wallet (made on the first run, reused after), anvil, the local world, a cell born with
+                                                 the wallet's 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
@@ -144,6 +160,21 @@ async function main() {
         }
         return;
     }
+    if (group === "world" && cmd === "verify") {
+        if (!flags.sourcify)
+            fail("foga world verify --sourcify --world <world.json> (Sourcify is the one verifier wired so far)");
+        const worldPath = str(flags, "world") ?? fail("--world <world.json> is required (a deployed world)");
+        const { verifyWorld } = await import("./world/sourcify.js");
+        const { report, outDir } = await verifyWorld({ worldPath: resolve(worldPath), server: str(flags, "server"), dryRun: flags["dry-run"] ? true : undefined, only: str(flags, "only")?.split(","), outDir: str(flags, "out") ? resolve(str(flags, "out")) : undefined, buildInfoRoot: str(flags, "build-info") ? resolve(str(flags, "build-info")) : undefined, log: (line) => console.error(line) });
+        for (const r of report.results)
+            console.log(`  ${r.outcome.padEnd(12)} ${r.id.padEnd(32)} ${r.address}  ${r.contractIdentifier} (${r.compilerVersion})${r.outcome === "dry-run" ? "" : `  ${r.detail}`}`);
+        for (const m of report.missing)
+            console.log(`  missing      ${m.id.padEnd(32)} ${m.reason}`);
+        console.log(`sourcify: ${Object.entries(report.summary).map(([k, v]) => `${v} ${k}`).join(", ") || "nothing to do"}${report.missing.length ? `, ${report.missing.length} missing` : ""}; report ${relative(root, join(outDir, "report.json"))}`);
+        if (report.missing.length || report.results.some((r) => r.outcome === "failed" || r.outcome === "error"))
+            process.exitCode = 3;
+        return;
+    }
     if (group === "world" && (cmd === "deploy" || cmd === "attach")) {
         const worldConfigPath = str(flags, "world");
         if (!worldConfigPath)
@@ -212,6 +243,113 @@ async function main() {
         process.stdout.write(RELAY_SCRIPT);
         return;
     }
+    if (group === "wallet") {
+        const { 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}`);
+            const rpc = str(flags, "rpc") ?? process.env.FOGA_RPC_URL;
+            const provider = rpc ? new (await import("ethers")).JsonRpcProvider(rpc) : null;
+            for (const role of w.roles) {
+                let balance = "";
+                if (provider) {
+                    try {
+                        balance = `   ${(await import("ethers")).formatEther(await provider.getBalance(w.addresses[role]))} ETH`;
+                    }
+                    catch {
+                        balance = "   (balance: RPC did not answer)";
+                    }
+                }
+                console.log(`  ${role.padEnd(9)} ${w.addresses[role]}${balance}   ${w.files[role]}`);
+            }
+            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}`);
+        };
+        if (cmd === "new") {
+            const existing = loadWallet(dir);
+            if (existing) {
+                await printWallet(existing, false);
+                console.log("(already there; a wallet is never overwritten — foga wallet new --name <n> makes another)");
+                return;
+            }
+            try {
+                await printWallet(createWallet(dir, { name: str(flags, "name") ?? "default", roles: flags.single ? ["signer"] : undefined }), true);
+            }
+            catch (e) {
+                fail(e.message);
+            }
+            return;
+        }
+        if (cmd === "show") {
+            const w = loadWallet(dir);
+            if (!w)
+                fail(`no wallet at ${dir}; foga wallet new makes one`);
+            await printWallet(w, false);
+            return;
+        }
+        if (cmd === "sign") {
+            const w = loadWallet(dir);
+            if (!w)
+                fail(`no wallet at ${dir}; foga wallet new makes one`);
+            const { walletKey } = await import("./node/wallet.js");
+            const { loadCellConfig, configPath } = await import("./node/config.js");
+            const { signAuthorization } = await import("./http/signed.js");
+            const { Wallet } = await import("ethers");
+            // the cell the signature is for: its own configuration (the operator's shell), its node's URL (anyone's: /healthz names the account and the chain), or both values by hand
+            let cellAddress;
+            let chainId;
+            let cellName;
+            if (str(flags, "config")) {
+                const loaded = loadCellConfig(str(flags, "config"));
+                cellAddress = loaded.config.identity.account ?? fail("the config names no account yet (the cell is not born)");
+                chainId = readJson(configPath(loaded, loaded.config.world)).chainId;
+                cellName = loaded.config.name;
+            }
+            else if (str(flags, "url")) {
+                const base = str(flags, "url").replace(/\/+$/, "");
+                let health;
+                try {
+                    health = (await (await fetch(`${base}/healthz`, { signal: AbortSignal.timeout(10_000) })).json());
+                }
+                catch (e) {
+                    fail(`${base}/healthz did not answer: ${e.message}`);
+                }
+                if (!health.account || !health.chainId)
+                    fail(`${base}/healthz names no account or chain (${JSON.stringify(health).slice(0, 200)}); the cell is not born or this is not a FOGA node`);
+                cellAddress = health.account;
+                chainId = health.chainId;
+                cellName = health.cell ?? base;
+            }
+            else if (str(flags, "cell") && str(flags, "chain-id")) {
+                cellAddress = str(flags, "cell");
+                chainId = Number(str(flags, "chain-id"));
+                cellName = cellAddress;
+            }
+            else
+                fail("the signature is made for one cell: --config <cell.config.json>, or --url <its node's URL>, or --cell <account> --chain-id <n>");
+            const role = (str(flags, "role") ?? (w.roles.includes("signer") ? "signer" : "operator"));
+            let key;
+            try {
+                key = walletKey(w, role);
+            }
+            catch (e) {
+                fail(e.message);
+            }
+            const method = str(flags, "method");
+            const path = str(flags, "path");
+            if ((method && !path) || (!method && path))
+                fail("--method and --path go together");
+            const bodyText = str(flags, "body") ?? (str(flags, "body-file") ? readFileSync(resolve(str(flags, "body-file")), "utf8") : undefined);
+            const header = await signAuthorization(new Wallet(key), { chainId, cell: cellAddress, ttlSeconds: str(flags, "ttl") ? Number(str(flags, "ttl")) : undefined, agentId: str(flags, "agent-id"), request: method ? { method, path: path, body: bodyText ?? null } : undefined });
+            console.error(`${role} ${new Wallet(key).address} signed ${method ? `a ${method} ${path} envelope` : "a session envelope"} for cell ${cellName} (${cellAddress}, chain ${chainId}); the header value follows (one line):`);
+            console.log(header);
+            return;
+        }
+        fail("foga wallet new | show | sign");
+    }
     if (group === "keys" && cmd === "export") {
         const { ROLE_ORDER, envKeys, roleAddresses } = await import("./genesis/roles.js");
         const role = str(flags, "role");
@@ -350,33 +488,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"), wallet: str(flags, "wallet"), 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 +544,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 +589,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 +602,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));
 });