run402 4.93.2 → 4.95.0

package/lib/cold-start.mjs

@@ -1,11 +1,11 @@
 /**
  * `cold-start.mjs` — the minimal x402/Base-Sepolia cold-start chain
- * (kygit-handoff design D5): allowance → faucet → one x402 prototype
+ * (kygit-handoff design D5): wallet → faucet → one x402 prototype
  * payment. `repos create` (and so `kygit create`) folds this in when it is
  * refused `NO_ACTIVE_TIER`, so `kygit create` on a genuinely fresh machine
  * ends with a vault, no human signup, no cloud dashboard.
  *
- * This is the SAME shape `run402 init` already walks (allowance create →
+ * This is the SAME shape `run402 init` already walks (create the wallet →
  * balance check → faucet → tier), factored down to the x402/Base-Sepolia
  * default rail only (MPP/Tempo is `init`'s own separate concern — an agent
  * hitting NO_ACTIVE_TIER mid-`repos create` gets the default rail, not a
@@ -15,7 +15,7 @@
  * create` needs when it discovers there is no tier and nothing else has
  * set one up yet.
  *
- * add-room-invite design D9 splits the funded-wallet half (allowance →
+ * add-room-invite design D9 splits the funded-wallet half (wallet →
  * faucet-if-empty → brief settlement poll) out as {@link ensureFundedWallet}
  * — `rooms join <key>` needs exactly that half, with NO tier purchase and NO
  * project creation (the claim itself is the one x402 payment that funds the
@@ -23,42 +23,42 @@
  * `ensureFundedWallet` followed by the tier step — so every EXISTING caller
  * (`repos create`/`resume`/`join`) is unchanged.
  */
-import { readAllowance, saveAllowance } from "./config.mjs";
+import { readWallet, saveWallet } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 
 const USDC_ABI = [{ name: "balanceOf", type: "function", stateMutability: "view", inputs: [{ name: "account", type: "address" }], outputs: [{ name: "", type: "uint256" }] }];
 const USDC_SEPOLIA = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
 
 /**
- * Allowance → faucet-if-empty → brief settlement poll. NO tier purchase, no
+ * Wallet → faucet-if-empty → brief settlement poll. NO tier purchase, no
  * project creation — the caller decides what (if anything) to pay for next.
  *
  * @param {(line: string) => void} announce Called once per step, so the
  *   caller can print each one it took (client-surface spec: "announcing
  *   each step").
- * @returns {Promise<{allowance_created: boolean, faucet_requested: boolean, address: string}>}
+ * @returns {Promise<{wallet_created: boolean, faucet_requested: boolean, address: string}>}
  */
 export async function ensureFundedWallet(announce = () => {}) {
-  const out = { allowance_created: false, faucet_requested: false, address: "" };
+  const out = { wallet_created: false, faucet_requested: false, address: "" };
 
-  let allowance = readAllowance();
-  if (!allowance) {
+  let localWallet = readWallet();
+  if (!localWallet) {
     const { generatePrivateKey, privateKeyToAccount } = await import("viem/accounts");
     const privateKey = generatePrivateKey();
     const account = privateKeyToAccount(privateKey);
-    allowance = { address: account.address, privateKey, created: new Date().toISOString(), funded: false, rail: "x402" };
-    saveAllowance(allowance);
-    out.allowance_created = true;
-    announce(`allowance created: ${allowance.address}`);
+    localWallet = { address: account.address, privateKey, created: new Date().toISOString(), funded: false, rail: "x402" };
+    saveWallet(localWallet);
+    out.wallet_created = true;
+    announce(`wallet created: ${localWallet.address}`);
   }
-  out.address = allowance.address;
+  out.address = localWallet.address;
 
   const { createPublicClient, http } = await import("viem");
   const { baseSepolia } = await import("viem/chains");
   const client = createPublicClient({ chain: baseSepolia, transport: http() });
   let balance = 0;
   try {
-    balance = Number(await client.readContract({ address: USDC_SEPOLIA, abi: USDC_ABI, functionName: "balanceOf", args: [allowance.address] }));
+    balance = Number(await client.readContract({ address: USDC_SEPOLIA, abi: USDC_ABI, functionName: "balanceOf", args: [localWallet.address] }));
   } catch {
     /* an RPC hiccup here is not fatal — the payment below will surface a real failure if the balance really is zero */
   }
@@ -67,19 +67,19 @@ export async function ensureFundedWallet(announce = () => {}) {
     // The faucet is throttled (0.25 USDC / 24h): a throttle refusal is
     // surfaced with its wait and NEVER retried silently (client-surface
     // spec) — this call is not wrapped in a swallowing catch.
-    await getSdk().allowance.faucet(allowance.address);
+    await getSdk().wallets.faucet(localWallet.address);
     out.faucet_requested = true;
     announce("faucet requested — waiting briefly for on-chain confirmation");
     for (let i = 0; i < 30; i++) {
       await new Promise((r) => setTimeout(r, 1000));
       try {
-        balance = Number(await client.readContract({ address: USDC_SEPOLIA, abi: USDC_ABI, functionName: "balanceOf", args: [allowance.address] }));
+        balance = Number(await client.readContract({ address: USDC_SEPOLIA, abi: USDC_ABI, functionName: "balanceOf", args: [localWallet.address] }));
         if (balance > 0) break;
       } catch {
         /* keep polling */
       }
     }
-    saveAllowance({ ...allowance, funded: true, lastFaucet: new Date().toISOString() });
+    saveWallet({ ...localWallet, funded: true, lastFaucet: new Date().toISOString() });
   }
 
   return out;
@@ -91,13 +91,13 @@ export async function ensureFundedWallet(announce = () => {}) {
  * no edits.
  *
  * @param {(line: string) => void} announce Called once per step.
- * @returns {Promise<{allowance_created: boolean, faucet_requested: boolean, tier: object|null}>}
+ * @returns {Promise<{wallet_created: boolean, faucet_requested: boolean, tier: object|null}>}
  */
 export async function foldColdStartChain(announce = () => {}) {
   const funded = await ensureFundedWallet(announce);
 
-  announce("subscribing to the prototype tier (one x402 testnet payment, perpetual)");
+  announce("setting the prototype tier (one x402 testnet payment; the free tier, no lease)");
   const tier = await getSdk().tier.set("prototype");
   announce(`prototype tier active${tier?.status === "already_active" ? " (already active)" : ""}`);
-  return { allowance_created: funded.allowance_created, faucet_requested: funded.faucet_requested, tier };
+  return { wallet_created: funded.wallet_created, faucet_requested: funded.faucet_requested, tier };
 }

package/lib/command-manifest.mjs

@@ -13,13 +13,13 @@
  *   positionals            canonical positional ATTRIBUTES (post-conventions).
  *                          A variadic list of the SAME kind counts as one.
  *   projectScoped          command operates on a project and accepts
- *                          `--project <id>` (precedence: --project > legacy
+ *                          `--project <project_id>` (precedence: --project > legacy
  *                          leading prj_ positional > active project)
  *   orgScoped              command acts ON an organization and resolves it
  *                          through the ONE shared chain (cli-org-context):
  *                          an optional leading <org_id> positional, else
  *                          --org, else RUN402_ORG, else the .run402.json
- *                          binding, else `org use`. The gate drives every
+ *                          binding, else `orgs use`. The gate drives every
  *                          such entry through --org AND RUN402_ORG with no
  *                          positional and fails on any "Missing <org_id>".
  *                          Any entry with an `org_id` positional MUST be
@@ -107,6 +107,8 @@ export const COMMAND_MANIFEST = [
   { path: ["wallets", "unbind"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["wallets", "import"], positionals: [p("name")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["gate-import-wallet", "--key", "__FIXTURE_FILE__"] },
   { path: ["wallets", "rm"], positionals: [p("name")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["no-such-wallet", "--yes"] },
+  { path: ["wallets", "fund"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], skipBehavioral: "polls on-chain funding with sleeps" },
+  { path: ["wallets", "balance"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["wallets", "lightning"], positionals: [p("action", { required: false })], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["status"] },
 
   // ── credentials (gateway project credentials) ────────────────────────────
@@ -124,14 +126,6 @@ export const COMMAND_MANIFEST = [
   { path: ["credentials", "project-keys", "export"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--reveal"] },
   { path: ["credentials", "project-keys", "remove"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [] },
 
-  // ── allowance ────────────────────────────────────────────────────────────
-  { path: ["allowance", "status"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["allowance", "create"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], skipBehavioral: "creates a real local wallet key outside the gate's scratch profile" },
-  { path: ["allowance", "fund"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], skipBehavioral: "polls on-chain funding with sleeps" },
-  { path: ["allowance", "balance"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["allowance", "export"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["allowance", "checkout"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--amount", "5000000"] },
-  { path: ["allowance", "history"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
 
   // ── tier ─────────────────────────────────────────────────────────────────
   { path: ["tier", "status"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
@@ -157,7 +151,6 @@ export const COMMAND_MANIFEST = [
   { path: ["projects", "delete"], positionals: [], projectScoped: true, legacyPositionalProject: true, minimalArgs: [] },
   { path: ["projects", "promote-user"], positionals: [p("email")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["user@example.com"] },
   { path: ["projects", "demote-user"], positionals: [p("email")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["user@example.com"] },
-  { path: ["projects", "export"], positionals: [], projectScoped: true, legacyPositionalProject: true, minimalArgs: [] },
 
   // ── snapshots ────────────────────────────────────────────────────────────
   { path: ["snapshots", "create"], positionals: [], projectScoped: true, legacyPositionalProject: true, minimalArgs: [] },
@@ -177,27 +170,30 @@ export const COMMAND_MANIFEST = [
   { path: ["admin", "archive"], positionals: [], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["--reason", "gate"] },
   { path: ["admin", "reactivate"], positionals: [], projectScoped: true, legacyPositionalProject: true, minimalArgs: [] },
 
-  // ── cloud / archives / core ──────────────────────────────────────────────
-  { path: ["cloud", "archives", "create"], positionals: [], projectScoped: true, legacyPositionalProject: true, minimalArgs: [] },
-  { path: ["cloud", "archives", "download"], positionals: [p("archive_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["arc_gate1", "--output", "__OUT_FILE__"] },
-  { path: ["cloud", "archives", "status"], positionals: [p("archive_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["arc_gate1"] },
+  // ── archives ─────────────────────────────────────────────────────────────
+  { path: ["archives", "create"], positionals: [], projectScoped: true, legacyPositionalProject: true, minimalArgs: [] },
+  { path: ["archives", "download"], positionals: [p("archive_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["arc_gate1", "--output", "__OUT_FILE__"] },
+  { path: ["archives", "status"], positionals: [p("archive_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["arc_gate1"] },
   { path: ["archives", "inspect"], positionals: [p("archive_path")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["__FIXTURE_FILE__"] },
   { path: ["archives", "verify"], positionals: [p("archive_path")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["__FIXTURE_FILE__"] },
-  { path: ["core", "projects", "import"], positionals: [p("archive_path")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["__FIXTURE_FILE__", "--name", "gate-import"] },
+  { path: ["archives", "import"], positionals: [p("archive_path")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["__FIXTURE_FILE__", "--name", "gate-import"] },
 
   // ── deploy (unified deploy v2) ───────────────────────────────────────────
-  { path: ["deploy", "apply"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--spec", "{}", "--check"], runStyle: "deployV2" },
+  // Bare `run402 deploy` IS the deploy (a verb); the family's subcommands
+  // follow. Dispatched flat through deploy.mjs so the gate exercises the
+  // same argv decision a person's shell does.
+  { path: ["deploy"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--spec", "{}", "--check"], runStyle: "flat" },
   { path: ["deploy", "rehearse"], positionals: [p("plan_id", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["plan_gate1"], runStyle: "deployV2" },
   { path: ["deploy", "promote"], positionals: [p("release_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["rel_gate1"], runStyle: "deployV2" },
   { path: ["deploy", "resume"], positionals: [p("operation_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["op_gate1"], runStyle: "deployV2" },
+  { path: ["deploy", "status"], positionals: [p("operation_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["op_gate1"], runStyle: "deployV2" },
   { path: ["deploy", "list"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "deployV2" },
   { path: ["deploy", "events"], positionals: [p("operation_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["op_gate1"], runStyle: "deployV2" },
   { path: ["deploy", "verify"], positionals: [p("operation_id", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["op_gate1"], runStyle: "deployV2" },
-  { path: ["deploy", "release", "get"], positionals: [p("release_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["rel_gate1"], runStyle: "deployV2" },
-  { path: ["deploy", "release", "active"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "deployV2" },
-  { path: ["deploy", "release", "diff"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--from", "empty", "--to", "active"], runStyle: "deployV2" },
-  { path: ["deploy", "diagnose"], positionals: [p("url")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["https://example.com/"], runStyle: "deployV2" },
-  { path: ["deploy", "resolve"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--url", "https://example.com/"], runStyle: "deployV2" },
+  { path: ["deploy", "releases", "get"], positionals: [p("release_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["rel_gate1"], runStyle: "deployV2" },
+  { path: ["deploy", "releases", "active"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "deployV2" },
+  { path: ["deploy", "releases", "diff"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--from", "empty", "--to", "active"], runStyle: "deployV2" },
+  { path: ["deploy", "resolve"], positionals: [p("url", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["https://example.com/"], runStyle: "deployV2" },
 
   // ── ci ───────────────────────────────────────────────────────────────────
   { path: ["ci", "link"], positionals: [p("provider")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["github"] },
@@ -210,34 +206,32 @@ export const COMMAND_MANIFEST = [
   { path: ["transfer", "preview"], positionals: [p("transfer_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["tr_gate1"] },
   { path: ["transfer", "list"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["transfer", "accept"], positionals: [p("transfer_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["tr_gate1"] },
-  { path: ["transfer", "claim"], positionals: [p("transfer_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["tr_gate1"] },
   { path: ["transfer", "cancel"], positionals: [p("transfer_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["tr_gate1"] },
 
-  // ── org ──────────────────────────────────────────────────────────────────
-  { path: ["org", "create"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["org", "list"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["org", "get"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG] },
-  { path: ["org", "rename"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--name", "Gate"] },
-  { path: ["org", "payout-wallet"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "0x1111111111111111111111111111111111111111"] },
+  // ── orgs ──────────────────────────────────────────────────────────────────
+  { path: ["orgs", "create"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
+  { path: ["orgs", "list"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
+  { path: ["orgs", "get"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG] },
+  { path: ["orgs", "rename"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--name", "Gate"] },
+  { path: ["orgs", "payout-wallet"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "0x1111111111111111111111111111111111111111"] },
   // `--org` (not a positional org_id
   // like rename/payout-wallet above) goes through resolveOrg's SHAPE
   // validation (a real UUID) — "org_gate1" fails that locally, so this needs
-  // the same UUID-shaped fixture `org use` below already established.
-  { path: ["org", "slug"], positionals: [p("slug")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["acme", "--org", "11111111-2222-3333-4444-555555555555"] },
-  { path: ["org", "whoami"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["org", "audit"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG] },
-  { path: ["org", "use"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["11111111-2222-3333-4444-555555555555"] },
-  { path: ["org", "current"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["org", "clear"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["org", "bind"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--org", "11111111-2222-3333-4444-555555555555"] },
-  { path: ["org", "unbind"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["org", "member", "list"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG] },
-  { path: ["org", "member", "add"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "0x1111111111111111111111111111111111111111"] },
-  { path: ["org", "member", "role"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--principal", "prn_gate1", "--role", "viewer"] },
-  { path: ["org", "member", "rm"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--principal", "prn_gate1"] },
-  { path: ["org", "invite", "list"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG] },
-  { path: ["org", "invite", "create"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--email", "gate@example.com"] },
-  { path: ["org", "invite", "rm"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--principal", "prn_gate1"] },
+  // the same UUID-shaped fixture `orgs use` below already established.
+  { path: ["orgs", "slug"], positionals: [p("slug")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["acme", "--org", "11111111-2222-3333-4444-555555555555"] },
+  { path: ["orgs", "audit"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG] },
+  { path: ["orgs", "use"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["11111111-2222-3333-4444-555555555555"] },
+  { path: ["orgs", "current"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
+  { path: ["orgs", "clear"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
+  { path: ["orgs", "bind"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--org", "11111111-2222-3333-4444-555555555555"] },
+  { path: ["orgs", "unbind"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
+  { path: ["orgs", "members", "list"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG] },
+  { path: ["orgs", "members", "add"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "0x1111111111111111111111111111111111111111"] },
+  { path: ["orgs", "members", "role"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--principal", "prn_gate1", "--role", "viewer"] },
+  { path: ["orgs", "members", "rm"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--principal", "prn_gate1"] },
+  { path: ["orgs", "invite", "list"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG] },
+  { path: ["orgs", "invite", "create"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--email", "gate@example.com"] },
+  { path: ["orgs", "invite", "rm"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--principal", "prn_gate1"] },
 
   // ── grants ───────────────────────────────────────────────────────────────
   { path: ["grants", "create"], positionals: [p("wallet")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["0x1111111111111111111111111111111111111111", "--capability", "deploy"] },
@@ -249,8 +243,8 @@ export const COMMAND_MANIFEST = [
   { path: ["delegates", "revoke"], legacyPositionalProject: false, positionals: [p("delegate_id")], projectScoped: true, minimalArgs: ["dlg_gate1"] },
   { path: ["delegates", "rotate"], legacyPositionalProject: false, positionals: [p("delegate_id")], projectScoped: true, minimalArgs: ["dlg_gate1"] },
 
-  // ── events / errors (flat, merged runners) ───────────────────────────────
-  { path: ["events"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "merged" },
+  // ── events / live ────────────────────────────────────────────────────────
+  { path: ["events", "list"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
   { path: ["live"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--tables", "cells", "--once"], runStyle: "merged" },
   { path: ["deliveries", "list"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
   { path: ["deliveries", "get"], positionals: [p("notification_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["n_1"], runStyle: "sub" },
@@ -266,9 +260,11 @@ export const COMMAND_MANIFEST = [
   // add-room-invite design D9: `rooms join` is one verb, two forms — no
   // positional registers a presence (the behaviorally-tested path, unchanged
   // by the optional positional below since minimalArgs stays empty); a
-  // `kri1_…` positional claims a room seat first (a real x402 payment + an
+  // `kri1_…` positional redeems the key first (a real x402 payment + an
   // org-membership mutation), so that form is never behaviorally exercised
   // here — the same reasoning `repos join`'s own row states.
+  { path: ["rooms", "list"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
+  { path: ["rooms", "get"], positionals: [p("room_key")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["run402-dev"], runStyle: "sub" },
   { path: ["rooms", "join"], positionals: [p("key", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
   { path: ["rooms", "invite"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "mints a single-use bearer key from a live room, registering the inviter's presence and posting a real room message — never run against the gate's own checkout" },
   { path: ["rooms", "leave"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
@@ -329,7 +325,8 @@ export const COMMAND_MANIFEST = [
   // Principal-scoped (one bundle covers every vault you can read), so no
   // --project — deliberately unlike its eleven vault-scoped siblings.
   { path: ["repos", "recovery-bundle"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--out", "-"], runStyle: "sub", skipBehavioral: "exports the caller's live member recovery bundle (stamps recovery-posture export evidence server-side)" },
-  { path: ["errors"], positionals: [p("fingerprint_id", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "merged" },
+  { path: ["errors", "list"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
+  { path: ["errors", "get"], positionals: [p("fingerprint_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["fp_gate1"], runStyle: "sub" },
 
   // ── jobs ─────────────────────────────────────────────────────────────────
   { path: ["jobs", "submit"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--file", "__FIXTURE_FILE__"] },
@@ -375,7 +372,7 @@ export const COMMAND_MANIFEST = [
   { path: ["sites", "deploy-dir"], positionals: [p("dir")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["__SCRATCH_DIR__"] },
 
   // ── subdomains ───────────────────────────────────────────────────────────
-  { path: ["subdomains", "claim"], positionals: [p("name")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["gate-sub"] },
+  { path: ["subdomains", "add"], positionals: [p("name")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["gate-sub"] },
   { path: ["subdomains", "list"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["subdomains", "delete"], positionals: [p("name")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["gate-sub", "--confirm"] },
 
@@ -427,18 +424,16 @@ export const COMMAND_MANIFEST = [
   { path: ["email", "webhooks", "deliveries"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["email", "webhooks", "redrive"], positionals: [p("delivery_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["dlv_gate1"] },
 
-  // ── message / agent / operator ───────────────────────────────────────────
+  // ── message / agent / sign-in ────────────────────────────────────────────
   { path: ["feedback", "send"], positionals: [p("words", { variadic: true })], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["hello", "from", "the", "gate"] },
   { path: ["agent", "contact"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--name", "gate-agent"] },
   { path: ["agent", "status"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["agent", "verify-email"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["agent", "passkey"], positionals: [p("action")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["enroll"] },
-  { path: ["operator", "login"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], skipBehavioral: "opens a browser / loopback listener" },
-  { path: ["operator", "logout"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["operator", "overview"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["operator", "whoami"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["operator", "claim-wallet-org"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["operator", "approve"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--action", "org.project.create", "--org", "org_gate1", "--no-open"] },
+  { path: ["login"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], runStyle: "flat", skipBehavioral: "opens a browser / loopback listener" },
+  { path: ["logout"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], runStyle: "flat" },
+  { path: ["whoami"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], runStyle: "flat", skipBehavioral: "requires live principal authentication" },
+  { path: ["approve"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--action", "org.project.create", "--org", "org_gate1", "--no-open"], runStyle: "flat" },
 
   // ── auth ─────────────────────────────────────────────────────────────────
   { path: ["auth", "magic-link"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--email", "gate@example.com", "--redirect", "https://example.com/cb"] },
@@ -488,8 +483,8 @@ export const COMMAND_MANIFEST = [
   // without rejecting it," which this satisfies.
   { path: ["doctor"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--no-scan"], runStyle: "merged" },
   { path: ["webhook-secret", "rotate"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  // `run402 logs [<function>] --request-id <id>`: the optional positional is
-  // the function name (`run402 errors` samples print it that way); it is
+  // `run402 logs [<function>] --request-id <request_id>`: the optional positional is
+  // the function name (`run402 errors list` samples print it that way); it is
   // never a project id.
   { path: ["logs"], positionals: [p("function", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--request-id", "req_gate123"], runStyle: "merged" },
 ];
@@ -497,7 +492,6 @@ export const COMMAND_MANIFEST = [
 // Families deliberately absent from the manifest, consumed by the gate's
 // completeness check against cli.mjs's dispatch switch.
 export const SKIPPED_FAMILIES = {
-  "apply": "pure alias for `deploy apply` (covered by the deploy family)",
   "dev": "interactive wrapper that spawns `astro dev`",
   // RESERVED, not dispatched: every `run402 message …` fails with
   // COMMAND_REMOVED pointing at `feedback send` / `messages send` /
@@ -538,22 +532,13 @@ export const SKIPPED_FAMILIES = {
 export const RESERVED_SUBCOMMANDS = {
   "source-access:export": "moved to `repos recovery-bundle` — the artifact `repos recover --bundle` consumes belongs to the repos family",
   "source-access:status": "moved to `repos access` — your own wrapper custody rides its member_custody block; the org advisory is `doctor --only recovery_posture`",
-  "rooms:who": "renamed to `rooms join` — an interrogative must not name a write",
-  "rooms:send": "moved to `messages send` — the verb acts on a message",
-  // The routes and SDK methods for room list/get exist (agent-room-lifecycle);
-  // only these two SPELLINGS are held back, because they were freed from
-  // meaning "list/get MESSAGES" and a reused spelling changes meaning without
-  // ever failing. One major, then they may name the room.
-  "rooms:list": "moved to `messages list` — the verb acts on a message",
-  "rooms:get": "moved to `messages get` — the verb acts on a message",
-  "rooms:ack": "moved to `messages ack` — the verb acts on a message",
   "escalations:contacts": "merged into `contacts` — the ladder and Telegram channels are one question",
   // Every `gitvault <verb>` spelling. Nine
   // answer COMMAND_MOVED naming their `repos` successor; `push` and
   // `reconcile` answer COMMAND_REMOVED (no equivalent successor for either —
   // `push`'s one-release alias window is over, `reconcile` was a workaround
   // with no permanent replacement, only a read at `repos access`).
-  "gitvault:init": "moved to `repos create --project <id>`",
+  "gitvault:init": "moved to `repos create --project <project_id>`",
   "gitvault:status": "moved to `repos view`",
   "gitvault:snapshot": "moved to `repos snapshot`",
   "gitvault:policy": "moved to `repos policy`",

package/lib/config.mjs

@@ -12,22 +12,22 @@ import {
   getLegacyProjectsPath,
   getProfileStatePath,
   getProjectCredentialsPath,
-  getAllowancePath,
+  getWalletPath,
   configureApiBase,
   isCoreApiTarget,
   readApiTargetConfig,
 } from "../core-dist/config.js";
-import { readAllowance as coreReadAllowance, saveAllowance as coreSaveAllowance } from "../core-dist/allowance.js";
+import { readWallet as coreReadWallet, saveWallet as coreSaveWallet } from "../core-dist/wallet.js";
 import { loadKeyStore, getProject, saveProject, updateProject, removeProject, saveKeyStore, getActiveProjectId, setActiveProjectId } from "../core-dist/keystore.js";
-import { getAllowanceAuthHeaders as coreGetAllowanceAuthHeaders } from "../core-dist/allowance-auth.js";
+import { getWalletAuthHeaders as coreGetWalletAuthHeaders } from "../core-dist/wallet-auth.js";
 import { fail } from "./sdk-errors.mjs";
 import { initializeWalletAction, selectProjectAction } from "./next-actions.mjs";
 
 // Wallet-dependent paths are exposed as getters (preferred — they always
 // reflect the active profile, even if some future code path imports this module
-// before wallet resolution). Production code (init/doctor/allowance) uses these.
+// before wallet resolution). Production code (init/doctor/wallet) uses these.
 export function configDir() { return getConfigDir(); }
-export function allowanceFile() { return getAllowancePath(); }
+export function walletFile() { return getWalletPath(); }
 export function projectCredentialsFile() { return getProjectCredentialsPath(); }
 export function profileStateFile() { return getProfileStatePath(); }
 export function legacyProjectsFile() { return getLegacyProjectsPath(); }
@@ -45,7 +45,7 @@ export function activeProfile() { return getActiveProfile(); }
 // module, and tests set RUN402_CONFIG_DIR before importing. New code should
 // prefer the getters above.
 export const CONFIG_DIR = getConfigDir();
-export const ALLOWANCE_FILE = getAllowancePath();
+export const WALLET_FILE = getWalletPath();
 export const PROJECTS_FILE = getProjectCredentialsPath();
 export const PROJECT_CREDENTIALS_FILE = getProjectCredentialsPath();
 export const PROFILE_STATE_FILE = getProfileStatePath();
@@ -54,40 +54,40 @@ export const PROFILE_STATE_FILE = getProfileStatePath();
 export const API = getApiBase();
 
 /**
- * Wraps core's `readAllowance()` and converts the malformed-shape throw
+ * Wraps core's `readWallet()` and converts the malformed-shape throw
  * into the canonical CLI failure envelope. Without this guard, every
- * CLI subcommand that touches the allowance leaks a Node stack trace and
- * source paths the moment a user has a malformed `allowance.json`.
+ * CLI subcommand that touches the wallet leaks a Node stack trace and
+ * source paths the moment a user has a malformed `wallet.json`.
  *
  * The unparseable-JSON case still returns `null` (matching the historical
- * "no_allowance" UX); only valid-JSON-but-wrong-shape becomes a structured
- * error with `code: BAD_ALLOWANCE_FILE`.
+ * "no_wallet" UX); only valid-JSON-but-wrong-shape becomes a structured
+ * error with `code: BAD_WALLET_FILE`.
  */
-export function readAllowance() {
+export function readWallet() {
   try {
-    return coreReadAllowance();
+    return coreReadWallet();
   } catch (err) {
     fail({
-      code: "BAD_ALLOWANCE_FILE",
-      message: err?.message ?? "allowance.json is malformed",
-      hint: "Back up ~/.config/run402/allowance.json and run 'run402 init' to recreate it.",
-      details: { path: allowanceFile() },
+      code: "BAD_WALLET_FILE",
+      message: err?.message ?? "wallet.json is malformed",
+      hint: "Back up ~/.config/run402/wallet.json and run 'run402 init' to recreate it.",
+      details: { path: walletFile() },
       next_actions: [initializeWalletAction()],
     });
   }
 }
 
-export function saveAllowance(data) {
-  coreSaveAllowance(data);
+export function saveWallet(data) {
+  coreSaveWallet(data);
 }
 
-export function allowanceAuthHeaders(path) {
-  const headers = coreGetAllowanceAuthHeaders(path);
+export function walletAuthHeaders(path) {
+  const headers = coreGetWalletAuthHeaders(path);
   if (!headers) {
     fail({
-      code: "NO_ALLOWANCE",
-      message: "No agent allowance found.",
-      hint: "Run: run402 allowance create",
+      code: "NO_WALLET",
+      message: "No local wallet found.",
+      hint: "Run: run402 init",
       next_actions: [initializeWalletAction()],
     });
   }
@@ -101,11 +101,11 @@ export function findProject(id) {
     fail({
       code: "PROJECT_CREDENTIAL_NOT_FOUND",
       message: `No local project credentials cached for ${idStr}.`,
-      hint: "Use a principal-auth command, or import project keys with `run402 credentials project-keys import --project <id> --service-key-stdin`.",
+      hint: "Use a principal-auth command, or import project keys with `run402 credentials project-keys import --project <project_id> --service-key-stdin`.",
       details: { project_id: idStr, source: "local_cache", cache_path: projectCredentialsFile(), wallet: activeProfile(), profile: activeProfile() },
       next_actions: [{
         type: "run_command",
-        command: `run402 credentials project-keys status --project ${idStr || "<id>"}`,
+        command: `run402 credentials project-keys status --project ${idStr || "<project_id>"}`,
         why: "Inspect the local project-key cache without revealing secrets.",
       }],
     });
@@ -119,7 +119,7 @@ export function resolveProject(id) {
     fail({
       code: "PROJECT_REQUIRED",
       message: "no project specified and no active project set.",
-      hint: "Pass --project <id>, set RUN402_PROJECT_ID, or run: run402 projects use <id>",
+      hint: "Pass --project <project_id>, set RUN402_PROJECT_ID, or run: run402 projects use <project_id>",
       next_actions: [selectProjectAction()],
     });
   }
@@ -132,7 +132,7 @@ export function resolveProjectId(id) {
     fail({
       code: "PROJECT_REQUIRED",
       message: "no project specified and no active project set.",
-      hint: "Pass --project <id>, set RUN402_PROJECT_ID, or run: run402 projects use <id>",
+      hint: "Pass --project <project_id>, set RUN402_PROJECT_ID, or run: run402 projects use <project_id>",
       next_actions: [selectProjectAction()],
     });
   }