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

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,40 @@ 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 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
+  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 +62,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 +99,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 +157,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,13 +175,33 @@ 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 === "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");
+        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");
             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();
@@ -151,7 +209,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 +224,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 +310,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 +354,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 +431,17 @@ 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)"}`);
+        {
+            // 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();
@@ -363,7 +523,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,5 +1,5 @@
 #!/usr/bin/env node
-import { mkdirSync, writeFileSync } from "node:fs";
+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";
@@ -21,6 +21,17 @@ 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>] [--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>]]
+                                                 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,9 +49,10 @@ usage:
                    [--zk auto|require|skip] [--crash-after <opKey>] [--crash-before <opKey>]
                                                  run the genesis scenario (idempotent; re-run to resume)
   foga genesis status --world <world.json> [--store <file.sqlite>]    list the operations the store holds
-  foga quickstart [--dir <dir>] [--port <n>] [--listen <host:port> | --no-serve] [--name <cell>] [--no-tenders] [--exit]
-                                                 one command to a live cell: anvil, the local world, a cell born with fresh keys and its two skills, two tenders,
-                                                 the node serving HTTP and MCP, and the MCP client configurations printed with every path filled in (~/.foga/quickstart)
+  foga 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|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
@@ -149,6 +161,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)
@@ -217,6 +244,118 @@ async function main() {
         process.stdout.write(RELAY_SCRIPT);
         return;
     }
+    if (group === "wallet") {
+        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}`);
+            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);
+            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);
+            if (existing) {
+                await printWallet(existing, false);
+                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 }), 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");
@@ -362,7 +501,7 @@ async function main() {
         const { runQuickstart } = await import("./demo/quickstart.js");
         let result;
         try {
-            result = await runQuickstart({ dir: str(flags, "dir"), port: str(flags, "port") ? Number(str(flags, "port")) : undefined, listen: flags["no-serve"] ? null : str(flags, "listen"), name: str(flags, "name"), tenders: !flags["no-tenders"], exit: Boolean(flags.exit) });
+            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);
@@ -371,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

@@ -12,12 +12,18 @@ export async function birthCell(o) {
     const log = o.log ?? (() => { });
     const root = repoRoot();
     const W = k.address("W");
-    const owner = Wallet.createRandom();
-    const operator = Wallet.createRandom();
-    const guardian = Wallet.createRandom();
-    log(`cell ${o.name}: owner ${owner.address}, operator ${operator.address}, guardian ${guardian.address}`);
+    const owner = o.keys ? new Wallet(o.keys.owner) : Wallet.createRandom();
+    const operator = o.keys ? new Wallet(o.keys.operator) : Wallet.createRandom();
+    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;
+}