run402 4.93.2 → 4.95.0

package/lib/up.mjs

@@ -7,27 +7,27 @@ import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs } from "./argparse.mjs";
 import { createUpdateCheckScheduler, emitUpdateNotice } from "./update-check.mjs";
-import { allowanceAuthHeaders, isCoreApiTarget, updateProject } from "./config.mjs";
+import { walletAuthHeaders, isCoreApiTarget, updateProject } from "./config.mjs";
 import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
 
 const HELP = `run402 up — Provision/link/deploy the current app
 
 Usage:
-  run402 up [repo-or-path] [--name <name>] [--project <id>] [--manifest <path>] [--dir <path>] [--tier <tier>] [-y|--yes] [--check|--print-spec|--print-manifest|--plan|--require-plan <id>|--repo-only] [--nested] [--verify] [--human|--json-stream] [--quiet]
-  run402 up verify [repo-or-path] [--project <id>] [--manifest <path>] [--dir <path>] [--human|--json-stream]
+  run402 up [repo-or-path] [--name <name>] [--project <project_id>] [--manifest <path>] [--dir <path>] [--tier <tier>] [-y|--yes] [--check|--print-spec|--print-manifest|--plan|--require-plan <plan_id>|--repo-only] [--nested] [--verify] [--human|--json-stream] [--quiet]
+  run402 up verify [repo-or-path] [--project <project_id>] [--manifest <path>] [--dir <path>] [--human|--json-stream]
 
 Options:
   repo-or-path        Local app directory or public Git repository URL. Defaults
                       to the current directory.
   --name <name>       Project display name when up needs to create a project.
                       Not a deploy manifest field and never renames a project.
-  --project <id>      Explicit project id. All supplied selectors must agree.
+  --project <project_id>      Explicit project id. All supplied selectors must agree.
   --manifest <path>   Manifest path. Defaults to run402.json, then
                       run402.deploy.json, then app.json in --dir/current directory.
   --dir <path>        Workspace directory to inspect (default: current dir).
   --tier <tier>       Bootstrap tier if no active Cloud tier exists
                       (prototype, hobby, team; default prototype).
-  -y, --yes           Approve recursive prerequisites/local writes (allowance,
+  -y, --yes           Approve recursive prerequisites/local writes (wallet,
                       tier, project creation, workspace link) for non-interactive runs.
   --check             Validate the manifest/config locally and print the
                       preflight, including the site inventory by content type
@@ -39,7 +39,7 @@ Options:
                       uploads, or local writes.
   --plan              Ask the gateway for a reviewed deploy plan. No upload,
                       commit, project provisioning, or workspace link write.
-  --require-plan <id> Apply only if this reviewed plan still matches.
+  --require-plan <plan_id> Apply only if this reviewed plan still matches.
   --plan-fingerprint <fingerprint>
                       Optional fingerprint returned by --plan. Only valid
                       with --require-plan.
@@ -53,7 +53,7 @@ Options:
   --propagation-budget-s <n>
                       Maximum wall-clock seconds to wait for fresh edge
                       propagation during app HTTP verification (default 120).
-  --verify            After a deploy apply, wait for gateway/edge release
+  --verify            After the deploy, wait for gateway/edge release
                       coherence and attach the report to the final result.
   --no-propagation-wait
                       Return propagation_pending immediately when the edge is
@@ -104,7 +104,7 @@ coordination only. RUN402_AGENT_NAME=<name> sets the name, overriding an
 existing one; RUN402_CLIENT=<name> declares the client when it is not
 auto-detected. A detected client that was not applied (the principal is
 already named) is still reported. Change the name any time with
-'run402 org whoami --set-name <name>'. Reported under result.identity
+'run402 whoami --set-name <name>'. Reported under result.identity
 (source, detected, detection).
   --json              Emit one final JSON object on stdout (default; compatibility no-op).
   --human             Emit the legacy human success/blocking summary on stdout.
@@ -138,12 +138,12 @@ Works for both app manifests (run402.json) and deploy manifests
 (run402.deploy.json / app.json) that declare a top-level verify block.
 
 Usage:
-  run402 up verify [repo-or-path] [--project <id>] [--manifest <path>] [--dir <path>] [--name <name>] [--human|--json-stream]
+  run402 up verify [repo-or-path] [--project <project_id>] [--manifest <path>] [--dir <path>] [--name <name>] [--human|--json-stream]
 
 Options:
   repo-or-path        Local app directory or public Git repository URL. Defaults
                       to the current directory.
-  --project <id>      Existing project id. Defaults to .run402/project.json,
+  --project <project_id>      Existing project id. Defaults to .run402/project.json,
                       manifest project id, then active project.
   --manifest <path>   Manifest path. Defaults to run402.json, then
                       run402.deploy.json, then app.json.
@@ -373,7 +373,7 @@ export async function run(args = []) {
             ? undefined
             : undefined,
       });
-      // Cache the activated deployment id so `run402 subdomains claim` can
+      // Cache the activated deployment id so `run402 subdomains add` can
       // pass it as an optimization (the gateway binds the live release
       // without it). Best-effort: a keystore hiccup never fails `up`.
       {
@@ -773,12 +773,12 @@ async function readLocalGitState(workDir) {
  * inside `up`'s mental model" entry point to the same outcome.
  */
 async function runRepoOnly({ sdk, workDir, createdRepository, nested = false, opts, tier, idempotencyKey }) {
-  // `sdk.up()`'s action graph auto-approves prerequisites (allowance, tier)
+  // `sdk.up()`'s action graph auto-approves prerequisites (wallet, tier)
   // for a cold start; calling projects.provision directly bypasses that, so
   // this mirrors the SAME gate `run402 projects provision` itself uses —
-  // fail with the actionable NO_ALLOWANCE guidance rather than an opaque
+  // fail with the actionable NO_WALLET guidance rather than an opaque
   // auth error from the gateway.
-  if (!isCoreApiTarget() && !loadLiveControlPlaneSession()) allowanceAuthHeaders("/projects/v1");
+  if (!isCoreApiTarget() && !loadLiveControlPlaneSession()) walletAuthHeaders("/projects/v1");
   const name = flagValue(opts, "--name") ?? undefined;
   const provisioned = await sdk.projects.provision({ tier, name, idempotencyKey });
   createdRepository = await gitInitIfNeeded(workDir);

package/lib/wallet-context.mjs

@@ -25,7 +25,7 @@ import { join } from "node:path";
 import { fail } from "./sdk-errors.mjs";
 import { isValidProfileName } from "../core-dist/config.js";
 import { getDefaultWallet, profileExists, readMeta, profileDir } from "../core-dist/profiles.js";
-import { readAllowance } from "../core-dist/allowance.js";
+import { readWallet } from "../core-dist/wallet.js";
 import { describeRejectedValue } from "../core-dist/redact.js";
 // The binding file is a CHECKOUT-LEVEL CONTRACT read by more than one surface,
 // so its reader lives in core — `run402-mcp` ships core/dist but not cli/, and
@@ -104,7 +104,7 @@ export function splitWalletFlag(rawArgv = []) {
  * a file left with no keys is deleted rather than committed empty.
  *
  * The file is shared by tiers (`wallet` from `wallets bind`, `org`/`room` from
- * `org bind`) and unknown keys are preserved, so one tier can never clobber
+ * `orgs bind`) and unknown keys are preserved, so one tier can never clobber
  * another's binding — which a whole-file write did until this existed.
  */
 export function updateBindingFile(dir, patch) {
@@ -301,12 +301,12 @@ function shortAddr(a) {
   return typeof a === "string" && a.length >= 12 ? `${a.slice(0, 6)}…${a.slice(-4)}` : a;
 }
 
-/** Best-effort address for display: meta.json (no key) first, allowance second. */
+/** Best-effort address for display: meta.json (no key) first, wallet second. */
 function walletAddress(name) {
   const meta = readMeta(name);
   if (meta?.address) return meta.address;
   try {
-    return readAllowance(join(profileDir(name), "allowance.json"))?.address ?? null;
+    return readWallet(join(profileDir(name), "wallet.json"))?.address ?? null;
   } catch {
     return null;
   }

package/lib/wallet-context.test.mjs

@@ -67,8 +67,8 @@ describe("splitWalletFlag", () => {
     assert.deepEqual(r.walletFlag, { flag: "--wallet", value: "kychon" });
   });
   it("strips --wallet=<value> mid-args", () => {
-    const r = splitWalletFlag(["deploy", "apply", "--wallet=foo", "--manifest", "x"]);
-    assert.deepEqual(r.argv, ["deploy", "apply", "--manifest", "x"]);
+    const r = splitWalletFlag(["deploy", "--wallet=foo", "--manifest", "x"]);
+    assert.deepEqual(r.argv, ["deploy", "--manifest", "x"]);
     assert.equal(r.walletFlag.value, "foo");
   });
   it("leaves --profile to `repos`, which owns it as the AWS credential profile", () => {
@@ -238,7 +238,7 @@ describe("enforceWalletExists — fail closed", () => {
   });
   it("no-op for an existing wallet", () => {
     ensureProfileDir("client-a");
-    writeFileSync(join(tmp, "profiles", "client-a", "allowance.json"), "{}");
+    writeFileSync(join(tmp, "profiles", "client-a", "wallet.json"), "{}");
     assert.doesNotThrow(() => enforceWalletExists({ name: "client-a", source: "binding" }, "deploy"));
   });
   it("fails closed for a missing wallet on a normal command", () => {

package/lib/wallets.mjs

@@ -17,6 +17,7 @@ import { writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
 import { failUnknownSubcommand } from "./argparse.mjs";
 import { join } from "node:path";
 import { fail, reportSdkError } from "./sdk-errors.mjs";
+import { walletFile, readWallet as readActiveWallet, saveWallet as saveActiveWallet } from "./config.mjs";
 import { isValidProfileName, getActiveProfile } from "../core-dist/config.js";
 import {
   listProfileNames,
@@ -30,10 +31,11 @@ import {
   getDefaultWallet,
   setDefaultWallet,
 } from "../core-dist/profiles.js";
-import { readAllowance, saveAllowance } from "../core-dist/allowance.js";
+import { readWallet, saveWallet } from "../core-dist/wallet.js";
 import { describeRejectedValue } from "../core-dist/redact.js";
 import { getSdk } from "./sdk.mjs";
 import { readBindingFile, updateBindingFile } from "./wallet-context.mjs";
+import { initializeWalletAction } from "./next-actions.mjs";
 
 const DEFAULT = "default";
 const PRIVATE_KEY_RE = /^0x[0-9a-fA-F]{64}$/;
@@ -42,16 +44,18 @@ const HELP = `run402 wallets — manage named wallets (profiles)
 
 Usage:
   run402 wallets list                 List all wallets (local_label, server_label, address, rail, active)
-  run402 wallets current              Show the resolved active wallet + how it was selected
-  run402 wallets new <name>           Create a new named wallet (key stays local)
+  run402 wallets current              Show the active wallet: how it was selected, address, rail, file path, faucet use
+  run402 wallets fund                 Request testnet funds from the faucet into the active wallet (Base Sepolia or Tempo)
+  run402 wallets balance              The active wallet's on-chain balances, plus its organization's allowance
+  run402 wallets new <name>           Create a new wallet (key stays local); 'default' creates the root wallet
   run402 wallets use <name>           Set the global default wallet
   run402 wallets rename <old> --to <new>   Rename a wallet (legacy: rename <old> <new>)
   run402 wallets bind [<name>]        Write ./.run402.json binding this directory to a wallet
   run402 wallets unbind               Remove ./.run402.json
   run402 wallets import <name> --key <path|->   Adopt an existing private key as a named wallet
   run402 wallets rm <name> --yes      Delete a wallet and its keys (requires --yes)
-  run402 wallets lightning status     The active wallet's Lightning allowance (balance, budget, custody)
-  run402 wallets lightning mint       Mint the Lightning allowance for the active wallet (same as init lightning)
+  run402 wallets lightning status     The active wallet's Lightning wallet (balance, budget, custody)
+  run402 wallets lightning mint       Mint the Lightning wallet for the active wallet (same as init lightning)
   run402 wallets lightning revoke     Revoke it: the sub-wallet is deleted on Run402's Hub; the rail returns to x402
 
 Selection precedence for normal commands:
@@ -102,7 +106,7 @@ function walletInfo(name, active) {
   const label = meta?.label ?? null;
   if (!address) {
     try {
-      const a = readAllowance(join(profileDir(name), "allowance.json"));
+      const a = readWallet(join(profileDir(name), "wallet.json"));
       address = a?.address ?? null;
       rail = rail ?? a?.rail ?? null;
     } catch {
@@ -127,7 +131,7 @@ function cmdList() {
   out(listProfileNames().map((n) => walletInfo(n, active)));
 }
 
-function cmdCurrent() {
+async function cmdCurrent() {
   const ctx = activeContext();
   const name = ctx?.name ?? getActiveProfile();
   const info = walletInfo(name, name);
@@ -146,21 +150,33 @@ function cmdCurrent() {
       hint: "Run 'run402 wallets rename' to reconcile.",
     });
   }
+  // The active wallet's own file: when it was created, its persisted rail, and
+  // whether the faucet has been used on it. `faucet_used` tracks faucet
+  // invocation, not pay-readiness — `run402 wallets balance` reads real funds.
+  let local = null;
+  try {
+    local = await getSdk().wallets.status();
+  } catch (err) {
+    reportSdkError(err);
+  }
   out({
     local_label: name,
     source: ctx?.source ?? "unknown",
     source_detail: ctx?.sourceDetail ?? null,
-    address: info.address,
+    address: local?.configured ? local.address : info.address,
     server_label: info.server_label,
+    configured: !!local?.configured,
+    created: local?.created ?? null,
+    rail: local?.configured ? local.rail ?? "x402" : info.rail,
+    faucet_used: !!local?.faucet_used,
+    path: local?.path ?? walletFile(),
+    ...(local?.configured ? {} : { next_actions: [initializeWalletAction()] }),
     warnings,
   });
 }
 
 async function cmdNew(args) {
   const name = requireName(args.find((a) => a && !a.startsWith("-")));
-  if (name === DEFAULT) {
-    fail({ code: "BAD_WALLET_NAME", message: "'default' is reserved. Use 'run402 init' for the default wallet.", details: { name } });
-  }
   if (profileExists(name)) {
     fail({ code: "WALLET_EXISTS", message: `A wallet named '${name}' already exists.`, hint: "run402 wallets list", details: { name } });
   }
@@ -175,12 +191,23 @@ async function cmdNew(args) {
   const address = privateKeyToAccount(privateKey).address;
   const created = new Date().toISOString();
   ensureProfileDir(name);
-  saveAllowance({ address, privateKey, created, funded: false, rail }, join(profileDir(name), "allowance.json"));
-  writeMeta(name, { name, address, label: name, rail, created });
-  await maybePushLabel(name, name, address);
+  saveWallet({ address, privateKey, created, funded: false, rail }, join(profileDir(name), "wallet.json"));
+  // The reserved `default` wallet lives at the config-dir root and carries no
+  // server label; a named wallet mirrors its name as the label.
+  if (name === DEFAULT) {
+    writeMeta(name, { name, address, rail, created });
+  } else {
+    writeMeta(name, { name, address, label: name, rail, created });
+    await maybePushLabel(name, name, address);
+  }
   // requireName constrains aliases to shell-safe lowercase identifiers.
-  const command = rail === "lightning" ? `run402 --wallet ${name} init lightning` : `run402 wallets use ${name}`;
-  out({ local_label: name, address, rail, created: true, next: command, next_actions: [{ type: "run_command", command, why: rail === "lightning" ? "Initialize this Lightning wallet." : "Select the wallet you just created." }] });
+  const command = rail === "lightning"
+    ? `run402 --wallet ${name} init lightning`
+    : name === DEFAULT ? "run402 wallets fund" : `run402 wallets use ${name}`;
+  const why = rail === "lightning"
+    ? "Initialize this Lightning wallet."
+    : name === DEFAULT ? "Fund the wallet you just created from the testnet faucet." : "Select the wallet you just created.";
+  out({ local_label: name, address, rail, created: true, next: command, next_actions: [{ type: "run_command", command, why }] });
 }
 
 function cmdUse(args) {
@@ -216,7 +243,7 @@ async function cmdRename(args) {
   let address = meta.address ?? null;
   if (!address) {
     try {
-      address = readAllowance(join(profileDir(newName), "allowance.json"))?.address ?? null;
+      address = readWallet(join(profileDir(newName), "wallet.json"))?.address ?? null;
     } catch {
       /* best-effort */
     }
@@ -229,7 +256,7 @@ async function cmdRename(args) {
 function cmdBind(args) {
   let name = args.find((a) => a && !a.startsWith("-"));
   name = name ? requireName(name) : getActiveProfile();
-  // MERGE, never clobber: the same file carries `org`/`room` from `org bind`.
+  // MERGE, never clobber: the same file carries `org`/`room` from `orgs bind`.
   const { contents } = updateBindingFile(process.cwd(), { wallet: name });
   const result = {
     wallet: name,
@@ -285,7 +312,7 @@ async function cmdImport(args) {
   }
   const created = new Date().toISOString();
   ensureProfileDir(name);
-  saveAllowance({ address, privateKey, created, funded: false, rail: "x402" }, join(profileDir(name), "allowance.json"));
+  saveWallet({ address, privateKey, created, funded: false, rail: "x402" }, join(profileDir(name), "wallet.json"));
   writeMeta(name, { name, address, label: name, rail: "x402", created });
   await maybePushLabel(name, name, address);
   out({ local_label: name, address, imported: true });
@@ -323,11 +350,11 @@ function flagVal(args, flag) {
 }
 
 /**
- * Best-effort server-side label push. Signs with the TARGET wallet's allowance
+ * Best-effort server-side label push. Signs with the TARGET wallet's key
  * (not the active one) so a just-created/renamed wallet can set its own label.
  *
  * ON by default — the gateway label endpoint is live, and the display label is
- * what makes the wallet name show up cross-machine and in the operator console
+ * what makes the wallet name show up cross-machine and in the console
  * (WEB). Set `RUN402_WALLET_LABEL_SYNC=0` to disable (fully-offline wallet ops,
  * or hermetic tests). The local folder name is always the source of truth; this
  * only mirrors the display label to the server. Always best-effort — `setLabel`
@@ -339,7 +366,7 @@ async function maybePushLabel(name, label, address) {
   if (!address) return;
   try {
     const sdk = getSdk({
-      allowancePath: join(profileDir(name), "allowance.json"),
+      walletPath: join(profileDir(name), "wallet.json"),
       keystorePath: join(profileDir(name), "projects.json"),
     });
     await sdk.wallet(address).setLabel(label);
@@ -364,6 +391,8 @@ export async function run(sub, args = []) {
     case "unbind": return cmdUnbind();
     case "import": return cmdImport(rest);
     case "rm": return cmdRm(rest);
+    case "fund": return cmdFund();
+    case "balance": return cmdBalance();
     case "lightning": return cmdLightning(rest);
     default:
       failUnknownSubcommand("wallets", sub);
@@ -371,30 +400,30 @@ export async function run(sub, args = []) {
 }
 
 // ── lightning ────────────────────────────────────────────────────────────────
-// The Lightning allowance of the ACTIVE wallet (mpp-lightning-over-nwc).
-// The pairing secret stays in allowance.json and is never printed.
+// The Lightning wallet of the ACTIVE wallet (mpp-lightning-over-nwc).
+// The pairing secret stays in wallet.json and is never printed.
 async function cmdLightning(args) {
   const action = args.find((a) => a && !a.startsWith("-")) ?? "status";
   const { ensureLightningWallet, revokeLightningWallet, describeLightning, readLightningBalance } = await import("./lightning-wallet.mjs");
-  const { readAllowance } = await import("../core-dist/allowance.js");
+  const { readWallet } = await import("../core-dist/wallet.js");
   try {
     if (action === "status") {
-      const allowance = readAllowance();
-      if (!allowance) fail({ code: "NO_ALLOWANCE", message: "No allowance configured for this wallet.", hint: "run402 init lightning" });
+      const localWallet = readWallet();
+      if (!localWallet) fail({ code: "NO_WALLET", message: "No local wallet configured for this wallet.", hint: "run402 init lightning" });
       let wallet = null;
       try { wallet = await getSdk().agent.lightningWallet.get(); } catch (err) {
         const code = err?.body?.code ?? err?.code;
         if (code !== "LIGHTNING_WALLET_NOT_FOUND") throw err;
       }
-      const balance = await readLightningBalance(allowance);
-      const lightning = describeLightning(allowance, wallet, balance);
-      out({ rail: allowance.rail ?? "x402", lightning, ...(lightning ? {} : { hint: "run402 init lightning" }) });
+      const balance = await readLightningBalance(localWallet);
+      const lightning = describeLightning(localWallet, wallet, balance);
+      out({ rail: localWallet.rail ?? "x402", lightning, ...(lightning ? {} : { hint: "run402 init lightning" }) });
       return;
     }
     if (action === "mint") {
       const result = await ensureLightningWallet();
-      const balance = result.outcome === "stored" || result.outcome === "present" ? await readLightningBalance(result.allowance) : null;
-      out({ outcome: result.outcome, rail: result.allowance.rail ?? "x402", lightning: describeLightning(result.allowance, result.wallet, balance) });
+      const balance = result.outcome === "stored" || result.outcome === "present" ? await readLightningBalance(result.localWallet) : null;
+      out({ outcome: result.outcome, rail: result.localWallet.rail ?? "x402", lightning: describeLightning(result.localWallet, result.wallet, balance) });
       return;
     }
     if (action === "revoke") {
@@ -407,3 +436,139 @@ async function cmdLightning(args) {
     reportSdkError(err);
   }
 }
+
+// ── fund / balance (the ACTIVE wallet) ─────────────────────────────────────
+
+const USDC_ABI = [{ name: "balanceOf", type: "function", stateMutability: "view", inputs: [{ name: "account", type: "address" }], outputs: [{ name: "", type: "uint256" }] }];
+const USDC_MAINNET = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+const USDC_SEPOLIA = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+const PATH_USD = "0x20c0000000000000000000000000000000000000";
+const TEMPO_RPC = "https://rpc.moderato.tempo.xyz/";
+
+async function loadDeps() {
+  const { generatePrivateKey, privateKeyToAccount } = await import("viem/accounts");
+  const { createPublicClient, http, defineChain } = await import("viem");
+  const { base, baseSepolia } = await import("viem/chains");
+  const tempoModerato = defineChain({
+    id: 42431,
+    name: "Tempo Moderato",
+    nativeCurrency: { name: "pathUSD", symbol: "pathUSD", decimals: 6 },
+    rpcUrls: { default: { http: [TEMPO_RPC] } },
+  });
+  return { generatePrivateKey, privateKeyToAccount, createPublicClient, http, base, baseSepolia, tempoModerato };
+}
+
+async function cmdFund() {
+  const w = readActiveWallet();
+  if (!w) {
+    fail({
+      code: "NO_WALLET",
+      message: "No local wallet.",
+      hint: "Run: run402 init",
+    });
+  }
+
+  if (w.rail === "mpp") {
+    // Tempo Moderato faucet — instant, no polling needed
+    const { createPublicClient, http, tempoModerato } = await loadDeps();
+    const client = createPublicClient({ chain: tempoModerato, transport: http() });
+    const before = await readUsdcBalance(client, PATH_USD, w.address).catch(() => 0);
+
+    const res = await fetch(TEMPO_RPC, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", method: "tempo_fundAddress", params: [w.address], id: 1 }),
+    });
+    const data = await res.json();
+    if (data.error) {
+      fail({
+        code: "FAUCET_FAILED",
+        message: data.error.message || "Tempo faucet failed",
+        details: { rail: "mpp" },
+      });
+    }
+
+    // Re-read balance once (instant confirmation)
+    const now = await readUsdcBalance(client, PATH_USD, w.address).catch(() => before);
+    saveActiveWallet({ ...w, funded: true, lastFaucet: new Date().toISOString() });
+    console.log(JSON.stringify({
+      address: w.address,
+      rail: "mpp",
+      onchain: {
+        "tempo-moderato_pathusd_micros": now,
+      },
+    }, null, 2));
+    return;
+  }
+
+  // Default: Base Sepolia faucet (existing behavior)
+  const { createPublicClient, http, baseSepolia } = await loadDeps();
+  const client = createPublicClient({ chain: baseSepolia, transport: http() });
+  const before = await readUsdcBalance(client, USDC_SEPOLIA, w.address).catch(() => 0);
+
+  let data;
+  try {
+    data = await getSdk().wallets.faucet(w.address);
+  } catch (err) {
+    reportSdkError(err);
+  }
+
+  const MAX_WAIT = 30;
+  for (let i = 0; i < MAX_WAIT; i++) {
+    await new Promise(r => setTimeout(r, 1000));
+    const now = await readUsdcBalance(client, USDC_SEPOLIA, w.address).catch(() => before);
+    if (now > before) {
+      saveActiveWallet({ ...w, funded: true, lastFaucet: new Date().toISOString() });
+      console.log(JSON.stringify({
+        address: w.address,
+        rail: w.rail || "x402",
+        onchain: {
+          "base-sepolia_usd_micros": now,
+        },
+      }, null, 2));
+      return;
+    }
+  }
+
+  saveActiveWallet({ ...w, funded: true, lastFaucet: new Date().toISOString() });
+  console.log(JSON.stringify({ ...data, balance_confirmed: false, hint: "Faucet request sent but on-chain balance not yet confirmed" }));
+}
+
+async function readUsdcBalance(client, usdc, address) {
+  const raw = await client.readContract({ address: usdc, abi: USDC_ABI, functionName: "balanceOf", args: [address] });
+  return Number(raw);
+}
+
+async function cmdBalance() {
+  const w = readActiveWallet();
+  if (!w) {
+    fail({
+      code: "NO_WALLET",
+      message: "No local wallet.",
+      hint: "Run: run402 init",
+    });
+  }
+
+  const { createPublicClient, http, base, baseSepolia, tempoModerato } = await loadDeps();
+  const mainnetClient = createPublicClient({ chain: base, transport: http() });
+  const sepoliaClient = createPublicClient({ chain: baseSepolia, transport: http() });
+  const tempoClient = createPublicClient({ chain: tempoModerato, transport: http() });
+
+  const [mainnetUsdc, sepoliaUsdc, tempoPathUsd, billingRes] = await Promise.all([
+    readUsdcBalance(mainnetClient, USDC_MAINNET, w.address).catch(() => null),
+    readUsdcBalance(sepoliaClient, USDC_SEPOLIA, w.address).catch(() => null),
+    readUsdcBalance(tempoClient, PATH_USD, w.address).catch(() => null),
+    getSdk().billing.checkBalance(w.address).catch(() => null),
+  ]);
+
+  console.log(JSON.stringify({
+    address: w.address,
+    rail: w.rail || "x402",
+    onchain: {
+      "base-mainnet_usd_micros": mainnetUsdc,
+      "base-sepolia_usd_micros": sepoliaUsdc,
+      "tempo-moderato_pathusd_micros": tempoPathUsd,
+    },
+    allowance_usd_micros: billingRes ? billingRes.allowance_usd_micros : null,
+  }, null, 2));
+}

package/lib/webhook-secret.mjs

@@ -1,18 +1,18 @@
 /**
- * run402 webhook-secret — Manage the operator webhook signing secret.
+ * run402 webhook-secret — Manage your webhook signing secret.
  *
  * Split out from notifications.mjs so the SURFACE inventory parser sees
  * `webhook-secret:rotate` as its own command, separate from the
  * `notifications:*` group.
  */
 
-import { allowanceAuthHeaders } from "./config.mjs";
-import { operatorProofs } from "./operator-proofs.mjs";
+import { walletAuthHeaders } from "./config.mjs";
+import { sessionProofs } from "./session-proofs.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError } from "./sdk-errors.mjs";
 import { assertKnownFlags, normalizeArgv, failUnknownSubcommand } from "./argparse.mjs";
 
-const HELP = `run402 webhook-secret — Manage the operator webhook signing secret
+const HELP = `run402 webhook-secret — Manage your webhook signing secret
 
 Usage:
   run402 webhook-secret rotate
@@ -20,7 +20,7 @@ Usage:
 Notes:
   - Returns the new plaintext secret EXACTLY once. Store it immediately.
   - Previous secret remains valid for 24 hours after rotation.
-  - Requires operator_passkey assurance level.
+  - Requires passkey assurance ('run402 login', or 'run402 agent passkey enroll').
 `;
 
 export async function run(sub, args = []) {
@@ -39,7 +39,7 @@ export async function run(sub, args = []) {
   }
   const parsedArgs = normalizeArgv(args);
   assertKnownFlags(parsedArgs, ["--help", "-h"]);
-  const proofs = operatorProofs("/agent/v1/webhook-secret/rotate");
+  const proofs = sessionProofs("/agent/v1/webhook-secret/rotate");
   try {
     const data = await getSdk().admin.rotateWebhookSecret(proofs);
     console.log(JSON.stringify(data, null, 2));

package/lib/webhooks.mjs

@@ -9,13 +9,13 @@ Usage:
   run402 email webhooks <action> [args...]
 
 Actions:
-  list       [--mailbox <slug|id>] [--project <id>]            List webhooks
-  get        <webhook_id> [--mailbox <slug|id>] [--project <id>]   Get a webhook
-  delete     <webhook_id> [--mailbox <slug|id>] [--project <id>]   Delete a webhook
+  list       [--mailbox <slug|id>] [--project <project_id>]            List webhooks
+  get        <webhook_id> [--mailbox <slug|id>] [--project <project_id>]   Get a webhook
+  delete     <webhook_id> [--mailbox <slug|id>] [--project <project_id>]   Delete a webhook
   update     <webhook_id> [--url <url>] [--events <e1,e2>] [--mailbox <slug|id>]  Update a webhook
-  register   --url <url> --events <e1,e2> [--mailbox <slug|id>] [--project <id>]  Register a new webhook
-  deliveries [--status <s>] [--mailbox <slug|id>] [--project <id>]  List durable delivery rows (DLQ visibility)
-  redrive    <delivery_id> [--mailbox <slug|id>] [--project <id>]   Re-queue a dead-lettered delivery
+  register   --url <url> --events <e1,e2> [--mailbox <slug|id>] [--project <project_id>]  Register a new webhook
+  deliveries [--status <s>] [--mailbox <slug|id>] [--project <project_id>]  List durable delivery rows (DLQ visibility)
+  redrive    <delivery_id> [--mailbox <slug|id>] [--project <project_id>]   Re-queue a dead-lettered delivery
 
 Valid events: delivery, bounced, complained, reply_received, mailbox_suspended
 Delivery statuses: pending, in_flight, delivered, failed_permanent (the DLQ)
@@ -41,12 +41,12 @@ const SUB_HELP = {
   update: `run402 email webhooks update — Update an existing webhook
 
 Usage:
-  run402 email webhooks update <webhook_id> [--url <url>] [--events <e1,e2>] [--mailbox <slug|id>] [--project <id>]
+  run402 email webhooks update <webhook_id> [--url <url>] [--events <e1,e2>] [--mailbox <slug|id>] [--project <project_id>]
 `,
   register: `run402 email webhooks register — Register a new webhook
 
 Usage:
-  run402 email webhooks register --url <url> --events <e1,e2> [--mailbox <slug|id>] [--project <id>]
+  run402 email webhooks register --url <url> --events <e1,e2> [--mailbox <slug|id>] [--project <project_id>]
 `,
 };