@finchip.ai/foga 0.6.0 → 0.6.1

package/README.md

@@ -86,6 +86,8 @@ 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
@@ -111,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
 ```

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/docs/loop-d.md

@@ -109,7 +109,7 @@ A refusal can name an operation that exists already (a conflict, an execution re
 
 ## On a public chain: what the Sepolia run taught (0.6.0)
 
-The first Loop D with an outside agent on Sepolia (2026-11-04, world `sepolia-11155111-20261101T043153Z`, cell D agent 11264, the agent a person driving the HTTP entrance with the key) passed every invariant row — every operation under an allowed decision, eleven refusals across every gate with nothing broadcast, the budget books, all operator transactions at the account and allow-listed and none reverted, the recovery drill across the kill and restart, idempotency, conflict, concurrency — and cases a, c, d, d2 and e as expected. Four things about a public chain came out of it, and 0.6.0 carries the answers:
+The first Loop D with an outside agent on Sepolia (2026-11-04, world `sepolia-11155111-20261101T043153Z`, cell D agent 11264, the agent a person driving the HTTP entrance with the key) passed every invariant row — every operation under an allowed decision, eleven refusals across every gate with nothing broadcast, the budget books, all operator transactions at the account and allow-listed and none reverted, the recovery drill across the kill and restart, idempotency, conflict, concurrency — and cases a, c, d, d2 and e as expected. The evidence is committed as `deployments/loop-d.sepolia.example.json` (`foga.loop-d-evidence/1`; the outside agent labelled `external-agent`; `foga doctor --loop-d` over it reads Pass 15, the case-b settlement figure as the one Fail — the accounting artifact fixed below, the chain having paid in full — and f, g and model-agnostic NotTested). Four things about a public chain came out of it, and 0.6.0 carries the answers:
 
 - **A working directory is one run.** `foga loop-d run` in a directory that holds a previous run's files found that run's keyed operations and replayed them against a cell with fresh keys, and the birth failed on the first replayed answer (`the registry assigned …; expected …`). The orchestrator now clears its own files from the working directory first (`cleanLoopDDir`, the run's files and nothing else; the evidence under `--out` is kept) — or pass `--dir` for a fresh one.
 - **Role funding is priced with a floor.** The roles' gas reserve was `units × gasPrice × 2`, and Sepolia quoted a gas price of a few wei: the operator got the flat 0.003 ETH alone, below the cell policy's gas floor (a quarter of `dailyGasWei`), so the budget gate refused every tender; the guardian got next to nothing for its suspend and resume. The reserve is now priced at the chain's gas price floored at 1 gwei (`src/demo/birth.ts`); a local chain, above the floor, is unchanged. A funder on Sepolia should hold about 0.15 ETH for a run.

package/docs/mcp.md

@@ -103,7 +103,7 @@ Each runs `npx -y @finchip.ai/foga mcp --config <cell.config.json>` with, option
 
 ## The package
 
-The npm package is `@finchip.ai/foga` — npm refuses the unscoped name `foga` as too similar to `ora` and `koa`, so it lives under the `finchip.ai` scope; the binary is `foga` and `foga mcp` is the stdio server. `package.json` carries `mcpName: "io.github.garyyang-finchip/foga"`, the name the MCP registry verifies npm ownership by, and `server.json` at the repository root is the registry manifest: the npm package as a stdio server (`npx -y @finchip.ai/foga node mcp --config …`, `FOGA_OPERATOR_KEY_FILE` and `FOGA_RPC_URL` as its environment) and `https://foga.finchip.ai/mcp` as the remote; `foga cell docs build` writes a cell's own copy with its MCP URL as the remote (docs/documents.md). `engines.node` is `>=22.13`, where `node:sqlite` runs without a flag; CI runs Node 22. The package is published on npm by its owner (`npm publish --tag latest` from a checkout at the tagged version; `npm view @finchip.ai/foga version` shows what is live); publication to the registry (`mcp-publisher login github`, then `mcp-publisher publish` with the OG cell's `server.json`) was done in 3d-3, once the manifest's remote answered: the OG cell is listed as `io.github.garyyang-finchip/foga`, and a re-publish follows each change to the manifest (docs/og-deployment.md, "The MCP registry listing").
+The npm package is `@finchip.ai/foga` — npm refuses the unscoped name `foga` as too similar to `ora` and `koa`, so it lives under the `finchip.ai` scope; the binary is `foga` and `foga mcp` is the stdio server. `package.json` carries `mcpName: "io.github.garyyang-finchip/foga"`, the name the MCP registry verifies npm ownership by, and `server.json` at the repository root is the registry manifest: the npm package as a stdio server (`npx -y @finchip.ai/foga node mcp --config …`, `FOGA_OPERATOR_KEY_FILE` and `FOGA_RPC_URL` as its environment) and `https://foga.finchip.ai/mcp` as the remote; `foga cell docs build` writes a cell's own copy with its MCP URL as the remote (docs/documents.md). `engines.node` is `>=22.13`, where `node:sqlite` runs without a flag; CI runs Node 22. The package is published on npm by its owner (`npm publish --tag latest` from a checkout at the tagged version; `npm view @finchip.ai/foga version` shows what is live), and `@finchtech.ai/foga` is republished beside it as an alias (`alias/finchtech.ai`: a launcher and a pinned dependency on `@finchip.ai/foga`, no code; `npm run alias:sync` after a version bump, then `npm publish --access public` from that folder), so either name runs the same program at the same version; publication to the registry (`mcp-publisher login github`, then `mcp-publisher publish` with the OG cell's `server.json`) was done in 3d-3, once the manifest's remote answered: the OG cell is listed as `io.github.garyyang-finchip/foga`, and a re-publish follows each change to the manifest (docs/og-deployment.md, "The MCP registry listing").
 
 What ships: `bin/`, `dist/`, `artifacts/bundle.json` (the ABIs), `worlds/`, `docs/` (the rule texts `spec_read` serves), `scenarios/` (the skill packages and the fixture), the prover bridge and the circuit's verification key, `server.json`. A checkout installed straight from git (`npm install github:garyyang-finchip/foga`, `npx -y github:garyyang-finchip/foga …`) compiles itself on install (`prepare`, `scripts/prepare.mjs`: only when `dist/` is missing and `src/` is there); `.gitattributes` keeps every text file LF on every platform, the launcher's shebang line included. `scripts/pack-smoke.mjs <rpc> <world.json>` is the pre-publication check and a CI step: `npm pack`, a clean `npm install` of the tarball in an empty directory, then the packaged CLI alone — `--help`, the public catalog, a schema, a cell born with `foga cell new` and `foga cell init` on the given world, and `foga node mcp` without a key driven by a raw 2025-era JSON-RPC client over stdio (stdout protocol-only, the keyless tool set, `cell_status`, `resources/list`, `spec_read` of the compatibility matrix from inside the package, no key-shaped value on stderr).
 

package/docs/quickstart.md

@@ -6,6 +6,8 @@ One command from nothing to a cell an MCP client can connect to. It needs Node 2
 npx -y @finchip.ai/foga quickstart
 ```
 
+`npx -y @finchtech.ai/foga quickstart` is the same command: `@finchtech.ai/foga` is an alias package (`alias/finchtech.ai`) whose only content is a launcher for `@finchip.ai/foga` at the same version.
+
 Run it from any directory except a checkout of this repository itself: inside one, `npx` takes the checkout for the package already present (same name, same version) and looks for the `foga` command among its installed binaries, where a project's own binaries never are — `'foga' is not recognized` on Windows, `foga: not found` elsewhere. From a checkout the command is `node bin/foga.js quickstart` after `npm run build`.
 
 What it does, in order (about twenty-five seconds on a laptop): makes the default wallet — one key, the agent's identity, under `~/.foga/wallet` — when there is none, and reuses it when there is (docs/wallet.md: the wallet is the first step, and never a reason to stop; a disk that refuses the write gets keys made in memory for the run); starts `anvil` on port 8545; deploys the local world — the ten reference implementations and the FOGA contracts, 47 contracts (`worlds/local.json`); births a cell (`quick`) with the wallet's keys, funded by anvil's first account, which also registers the attested standing scheme and attests the cell's level-2 standing; mints the cell's two skills (`foga-probe`, `finch-extract-verify`) and offers them; builds the cell's documents and commits them on chain (the registration, the AID document, the ARD descriptor, the AUF unit; docs/documents.md); mints two tenders for the cell to find (a probe of the cell itself, an extraction over the fixture); serves the node — the watchers, the HTTP API, MCP over Streamable HTTP, A2A and the documents on `127.0.0.1:8787` — on the operator key alone, read from the wallet's file; checks that the entrances answer (health, a public read, the agent key's pre-check of the first tender, the MCP handshake and the 37-tool list over HTTP, the agent card naming `/a2a` and an A2A quote; the stdio server's handshake and its 44 tools with the operator key); and prints the summary below, with every path filled in. Then it waits: the chain lives as long as the process, and Ctrl-C ends both.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finchip.ai/foga",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/garyyang-finchip/foga.git"
@@ -70,7 +70,8 @@
     "test": "node --test --import tsx test/*.test.ts",
     "test:contracts": "cd contracts && forge test -vv",
     "zk:install": "npm --prefix prover ci",
-    "zk:predicate": "node prover/build-predicate.mjs"
+    "zk:predicate": "node prover/build-predicate.mjs",
+    "alias:sync": "node scripts/alias-sync.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.4.0",

package/server.json

@@ -8,13 +8,13 @@
     "source": "github"
   },
   "websiteUrl": "https://foga.finchip.ai",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@finchip.ai/foga",
-      "version": "0.6.0",
+      "version": "0.6.1",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"