feat(status): redesign account-status output shape

Rename wallet identity fields name/label -> local_label/server_label across run402 status, r.whoami() (WhoAmI type), the MCP status tool, and wallets list/current. Group balances under a single `balances` object (on_chain_usd_micros + rail-aware on_chain_token, prepaid_credit_usd_micros, held_usd_micros), drop the redundant `allowance` block and the stale `funded` boolean, and move the no-allowance empty-state to { wallet: null, hint }. Align run402 init to the same wallet/balances shape; add held_usd_micros? to the BillingBalance SDK type.

BREAKING: run402 status / init JSON and the WhoAmI SDK type field names change. Pre-launch; no external consumers. Implements OpenSpec change redesign-status-output.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: MajorTal

README.md

@@ -310,7 +310,7 @@ Every subcommand prints JSON to stdout, JSON errors to stderr, exits 0 on succes
 
 ```bash
 run402 init                              # one-shot allowance + faucet + tier check
-run402 status                            # account snapshot (allowance, balance, tier, projects)
+run402 status                            # account snapshot (wallet, rail, balances, tier, projects)
 run402 projects provision --name my-app
 run402 projects sql <id> "CREATE TABLE …"
 run402 projects validate-expose <id> --file manifest.json

cli-argv.test.mjs

@@ -1576,7 +1576,7 @@ describe("CLI JSON-only output contract (v3.x cleanup)", () => {
     if (out.length > 0) {
       const parsed = JSON.parse(out);
       assert.equal(typeof parsed.config_dir, "string", "stdout JSON should include config_dir");
-      assert.equal(typeof parsed.allowance, "object", "stdout JSON should include allowance object");
+      assert.equal(typeof parsed.wallet, "object", "stdout JSON should include wallet object");
     }
     const err = stderr.join("\n");
     assert.match(err, /\bConfig\b/, `human banner should be on stderr, got: ${err.slice(0, 300)}`);

cli-e2e.test.mjs

@@ -3888,10 +3888,16 @@ describe("CLI e2e happy path", () => {
     }
     assert.ok(typeof parsed === "object" && parsed !== null, "stdout must be a JSON object");
     assert.ok(typeof parsed.config_dir === "string", "should include config_dir");
-    assert.ok(typeof parsed.allowance === "object" && parsed.allowance?.address, "should include allowance.address");
+    assert.ok(typeof parsed.wallet === "object" && parsed.wallet?.address, "should include wallet.address");
+    assert.ok(typeof parsed.wallet.local_label === "string", "wallet should include local_label");
+    assert.ok(Object.prototype.hasOwnProperty.call(parsed.wallet, "server_label"), "wallet should include server_label");
+    assert.ok(!Object.prototype.hasOwnProperty.call(parsed.wallet, "funded"), "wallet should not include stale funded");
     assert.ok(parsed.rail === "x402" || parsed.rail === "mpp", `should include rail, got: ${parsed.rail}`);
     assert.ok(typeof parsed.network === "string", "should include network");
-    assert.ok(Object.prototype.hasOwnProperty.call(parsed, "balance"), "should include balance field");
+    assert.ok(typeof parsed.balances === "object" && parsed.balances !== null, "should include balances object");
+    assert.equal(parsed.balances.on_chain_token, parsed.rail === "mpp" ? "pathUSD" : "USDC", "on_chain_token should track rail");
+    assert.ok(!Object.prototype.hasOwnProperty.call(parsed, "balance"), "should not expose ambiguous balance field");
+    assert.ok(!Object.prototype.hasOwnProperty.call(parsed, "allowance"), "should not expose allowance block");
     assert.ok(Object.prototype.hasOwnProperty.call(parsed, "tier"), "should include tier field");
     assert.equal(typeof parsed.projects_saved, "number", "should include projects_saved (number)");
     assert.ok(typeof parsed.next_step === "string", "should include next_step");
@@ -3900,27 +3906,44 @@ describe("CLI e2e happy path", () => {
     assert.ok(stderr.includes("Config"), `stderr should contain human lines, got: ${stderr}`);
   });
 
-  it("status has billing, wallet_balance_usd_micros, and project_id fields (GH-32)", async () => {
+  it("status exposes wallet identity, grouped balances, and project_id fields", async () => {
     const { run } = await import("./cli/lib/status.mjs");
     captureStart();
     await run();
     captureStop();
     const out = captured();
     const data = JSON.parse(out);
-    assert.ok(data.allowance, "should include allowance");
-    assert.ok(data.allowance.address, "should include allowance address");
+    // Wallet identity uses local_label / server_label (not name / label).
+    assert.ok(data.wallet, "should include wallet");
+    assert.ok(data.wallet.address, "should include wallet.address");
+    assert.ok(typeof data.wallet.local_label === "string", "wallet should include local_label");
+    assert.ok(Object.prototype.hasOwnProperty.call(data.wallet, "server_label"), "wallet should include server_label");
+    assert.ok(!Object.prototype.hasOwnProperty.call(data.wallet, "name"), "wallet should not use legacy name field");
+    assert.ok(!Object.prototype.hasOwnProperty.call(data.wallet, "label"), "wallet should not use legacy label field");
     assert.ok(Array.isArray(data.projects), "should include projects array");
-    // GH-32 sub-issue 2: rename balance → billing, add wallet_balance_usd_micros
+    // The duplicate allowance block and the stale funded boolean are gone.
+    assert.ok(!Object.prototype.hasOwnProperty.call(data, "allowance"),
+      `status should not expose duplicate "allowance" block; got: ${JSON.stringify(data)}`);
+    assert.ok(!Object.prototype.hasOwnProperty.call(data, "funded"),
+      `status should not expose stale "funded" boolean; got: ${JSON.stringify(data)}`);
+    // Balances are grouped; no ambiguous top-level balance / wallet_balance_usd_micros / billing.
     assert.ok(!Object.prototype.hasOwnProperty.call(data, "balance"),
       `status should not expose ambiguous "balance" field; got: ${JSON.stringify(data)}`);
-    assert.ok(Object.prototype.hasOwnProperty.call(data, "billing"),
-      `status should expose "billing" field; got: ${JSON.stringify(data)}`);
-    assert.ok(Object.prototype.hasOwnProperty.call(data, "wallet_balance_usd_micros"),
-      `status should expose "wallet_balance_usd_micros"; got: ${JSON.stringify(data)}`);
-    const wb = data.wallet_balance_usd_micros;
+    assert.ok(!Object.prototype.hasOwnProperty.call(data, "wallet_balance_usd_micros"),
+      `status should fold on-chain balance into balances; got: ${JSON.stringify(data)}`);
+    assert.ok(!Object.prototype.hasOwnProperty.call(data, "billing"),
+      `status should fold prepaid credit into balances; got: ${JSON.stringify(data)}`);
+    assert.ok(typeof data.balances === "object" && data.balances !== null, "should include balances object");
+    const wb = data.balances.on_chain_usd_micros;
     assert.ok(wb === null || typeof wb === "number",
-      `wallet_balance_usd_micros must be number or null; got: ${JSON.stringify(wb)}`);
-    // GH-32 sub-issue 4: projects entries must use project_id
+      `balances.on_chain_usd_micros must be number or null; got: ${JSON.stringify(wb)}`);
+    assert.equal(data.balances.on_chain_token, data.rail === "mpp" ? "pathUSD" : "USDC",
+      `on_chain_token should track rail; got: ${JSON.stringify(data.balances)}`);
+    assert.ok(Object.prototype.hasOwnProperty.call(data.balances, "prepaid_credit_usd_micros"),
+      "balances should include prepaid_credit_usd_micros");
+    assert.ok(Object.prototype.hasOwnProperty.call(data.balances, "held_usd_micros"),
+      "balances should include held_usd_micros");
+    // projects entries must use project_id
     for (const p of data.projects) {
       assert.ok(typeof p.project_id === "string" && p.project_id.length > 0,
         `each project should have a project_id; got: ${JSON.stringify(p)}`);
@@ -4049,11 +4072,12 @@ describe("CLI e2e happy path", () => {
     assert.equal(allowance.rail, "mpp", "rail should be mpp");
   });
 
-  // GH-81: after MPP faucet succeeds, the JSON summary must reflect funded=true
-  // and the polled balance. Previously `summary.allowance` was captured before
-  // the faucet branch ran, so the JSON reported `funded: false` and
-  // `usd_micros: 0` even when the human-readable lines said "funded".
-  it("init mpp reports funded=true after faucet settles (GH-81)", async () => {
+  // GH-81: after MPP faucet succeeds, the JSON summary must reflect the polled
+  // on-chain balance. Previously the balance was captured before the faucet
+  // branch ran, so the JSON reported `usd_micros: 0` even when the
+  // human-readable lines said "funded". On-chain balance now lives under
+  // `balances.on_chain_usd_micros` (the old `funded` boolean was removed).
+  it("init mpp reflects polled on-chain balance after faucet settles (GH-81)", async () => {
     tempoRpcCallCount = 0; // first eth_call returns 0 → triggers faucet path
     const { run } = await import("./cli/lib/init.mjs");
     captureStart();
@@ -4062,11 +4086,9 @@ describe("CLI e2e happy path", () => {
     const stdout = capturedStdout();
     const parsed = JSON.parse(stdout);
     assert.equal(parsed.rail, "mpp", `rail must be mpp; got: ${parsed.rail}`);
-    assert.equal(parsed.allowance.funded, true,
-      `summary.allowance.funded must be true after successful faucet; got: ${JSON.stringify(parsed.allowance)}`);
-    assert.equal(parsed.balance.symbol, "pathUSD");
-    assert.ok(parsed.balance.usd_micros > 0,
-      `summary.balance.usd_micros must reflect polled balance (>0); got: ${parsed.balance.usd_micros}`);
+    assert.equal(parsed.balances.on_chain_token, "pathUSD");
+    assert.ok(parsed.balances.on_chain_usd_micros > 0,
+      `balances.on_chain_usd_micros must reflect polled balance (>0) after faucet; got: ${parsed.balances.on_chain_usd_micros}`);
   });
 
   it("allowance status (MPP rail)", async () => {
@@ -5020,11 +5042,11 @@ describe("CLI canonical error envelope (GH-215, GH-174)", () => {
 
 describe("CLI status local-state inspection (cli-output-shape)", () => {
   // Per cli-output-shape spec: absence of local state is an informational
-  // read, not an error. status exits 0 with `{ allowance: null, hint: "..." }`;
+  // read, not an error. status exits 0 with `{ wallet: null, hint: "..." }`;
   // allowance status exits 0 with `{ wallet: null, hint: "..." }`. The
   // previous GH-191 contract (exit 1 + `status: "no_allowance"`) was retired
   // in v3.0 as part of the CLI envelope normalization.
-  it("status with no allowance emits typed null allowance and exits 0", async () => {
+  it("status with no allowance emits typed null wallet and exits 0", async () => {
     const { ALLOWANCE_FILE } = await import("./cli/lib/config.mjs");
     try { rmSync(ALLOWANCE_FILE, { force: true }); } catch {}
     const { run } = await import("./cli/lib/status.mjs");
@@ -5041,7 +5063,7 @@ describe("CLI status local-state inspection (cli-output-shape)", () => {
     assert.ok(line, `should emit payload on stdout, got: ${stdout}`);
     const parsed = JSON.parse(line);
     assert.equal(parsed.status, undefined, "must not emit a top-level status field");
-    assert.equal(parsed.allowance, null, "allowance must be typed null when absent");
+    assert.equal(parsed.wallet, null, "wallet must be typed null when absent");
     assert.ok(parsed.hint && /run402 init/.test(parsed.hint), `hint must guide to next step, got: ${parsed.hint}`);
   });
 
@@ -5161,7 +5183,7 @@ describe("CLI malformed allowance.json (GH-194)", () => {
       `message should mention privateKey; got: ${parsed.message}`);
   });
 
-  it("status with unparseable allowance.json still surfaces as typed null allowance (existing UX preserved)", async () => {
+  it("status with unparseable allowance.json still surfaces as typed null wallet (existing UX preserved)", async () => {
     const { ALLOWANCE_FILE } = await import("./cli/lib/config.mjs");
     const fs = await import("node:fs");
     fs.writeFileSync(ALLOWANCE_FILE, "not json");
@@ -5180,8 +5202,8 @@ describe("CLI malformed allowance.json (GH-194)", () => {
     assert.ok(line, `should emit payload on stdout, got: ${stdout}`);
     const parsed = JSON.parse(line);
     assert.equal(parsed.status, undefined, "must not emit a top-level status field");
-    assert.equal(parsed.allowance, null,
-      `unparseable JSON should surface as typed null allowance (no BAD_ALLOWANCE_FILE error envelope); got: ${JSON.stringify(parsed)}`);
+    assert.equal(parsed.wallet, null,
+      `unparseable JSON should surface as typed null wallet (no BAD_ALLOWANCE_FILE error envelope); got: ${JSON.stringify(parsed)}`);
   });
 });
 

cli-integration.test.ts

@@ -510,7 +510,9 @@ describe("CLI integration (live API, no mocks)", { timeout: 180_000 }, () => {
     await run();
     captureStop();
     const data = capturedJson();
-    assert.ok(data.allowance, "should include allowance");
+    assert.ok(data.wallet, "should include wallet");
+    assert.ok(data.wallet.address, "should include wallet.address");
+    assert.ok(data.balances, "should include balances");
     assert.ok(Array.isArray(data.projects), "should include projects");
   });
 

cli-wallets.test.mjs

@@ -60,8 +60,8 @@ describe("wallets — lifecycle", () => {
   it("new → list → rm", () => {
     assert.equal(run(["wallets", "new", "kychon"]).status, 0);
     const list = jsonOut(run(["wallets", "list"]));
-    assert.deepEqual(list.map((w) => w.name).sort(), ["kychon"]);
-    assert.equal(list[0].label, "kychon");
+    assert.deepEqual(list.map((w) => w.local_label).sort(), ["kychon"]);
+    assert.equal(list[0].server_label, "kychon");
     // rm requires --yes
     const noConfirm = run(["wallets", "rm", "kychon"]);
     assert.notEqual(noConfirm.status, 0);
@@ -76,7 +76,7 @@ describe("wallets — lifecycle", () => {
     assert.equal(run(["wallets", "rename", "default", "kychon"]).status, 0);
     assert.ok(!existsSync(join(configDir, "allowance.json")), "root allowance.json migrated away");
     assert.ok(existsSync(join(configDir, "profiles", "kychon", "allowance.json")));
-    assert.deepEqual(jsonOut(run(["wallets", "list"])).map((w) => w.name), ["kychon"]);
+    assert.deepEqual(jsonOut(run(["wallets", "list"])).map((w) => w.local_label), ["kychon"]);
   });
 });
 
@@ -88,20 +88,20 @@ describe("wallets — selection precedence", () => {
 
   it("flag wins and reports source=flag", () => {
     const cur = jsonOut(run(["--wallet", "kychon", "wallets", "current"]));
-    assert.equal(cur.name, "kychon");
+    assert.equal(cur.local_label, "kychon");
     assert.equal(cur.source, "flag");
   });
 
   it("env selects when no flag", () => {
     const cur = jsonOut(run(["wallets", "current"], { env: { RUN402_WALLET: "client-a" } }));
-    assert.equal(cur.name, "client-a");
+    assert.equal(cur.local_label, "client-a");
     assert.equal(cur.source, "env");
   });
 
   it("directory binding selects when no flag/env", () => {
     writeFileSync(join(workDir, ".run402.json"), JSON.stringify({ wallet: "client-a" }));
     const cur = jsonOut(run(["wallets", "current"]));
-    assert.equal(cur.name, "client-a");
+    assert.equal(cur.local_label, "client-a");
     assert.equal(cur.source, "binding");
   });
 
@@ -111,19 +111,19 @@ describe("wallets — selection precedence", () => {
     const sub = join(workDir, "api");
     mkdirSync(sub);
     const cur = jsonOut(run(["wallets", "current"], { cwd: sub }));
-    assert.equal(cur.name, "kychon");
+    assert.equal(cur.local_label, "kychon");
   });
 
   it("global `wallets use` applies when no flag/env/binding", () => {
     assert.equal(run(["wallets", "use", "kychon"]).status, 0);
     const cur = jsonOut(run(["wallets", "current"]));
-    assert.equal(cur.name, "kychon");
+    assert.equal(cur.local_label, "kychon");
     assert.equal(cur.source, "config");
   });
 
   it("falls back to default when nothing selects", () => {
     const cur = jsonOut(run(["wallets", "current"]));
-    assert.equal(cur.name, "default");
+    assert.equal(cur.local_label, "default");
     assert.equal(cur.source, "default");
   });
 });

cli/lib/init.mjs

@@ -1,6 +1,8 @@
 import { readAllowance, saveAllowance, loadKeyStore, configDir } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { fail } from "./sdk-errors.mjs";
+import { getActiveProfile } from "../core-dist/config.js";
+import { readMeta } from "../core-dist/profiles.js";
 import { mkdirSync } from "fs";
 
 const USDC_ABI = [{ name: "balanceOf", type: "function", stateMutability: "view", inputs: [{ name: "account", type: "address" }], outputs: [{ name: "", type: "uint256" }] }];
@@ -25,7 +27,7 @@ Options:
                   idempotent and does not need this flag.
 
 Output:
-  Stdout is a JSON summary { config_dir, allowance, rail, network, balance,
+  Stdout is a JSON summary { config_dir, wallet, rail, network, balances,
   tier, projects_saved, next_step }. Progress lines (Config / Allowance /
   Balance / Tier / Next) go to stderr so a human re-running interactively
   sees what's happening while a script piping stdout to jq stays clean.
@@ -87,10 +89,10 @@ export async function run(args = []) {
   const line = (label, value) => write(`  ${label.padEnd(10)} ${value}`);
   const summary = {
     config_dir: CONFIG_DIR,
-    allowance: null,
+    wallet: null,
     rail: null,
     network: null,
-    balance: null,
+    balances: null,
     tier: null,
     projects_saved: 0,
     next_step: null,
@@ -124,7 +126,9 @@ export async function run(args = []) {
     line("Allowance", short(allowance.address));
   }
 
-  summary.allowance = { address: allowance.address, funded: allowance.funded || false };
+  const walletName = getActiveProfile();
+  const walletMeta = readMeta(walletName);
+  summary.wallet = { local_label: walletName, server_label: walletMeta?.label ?? null, address: allowance.address };
   summary.network = isMpp ? "tempo-moderato" : "base-sepolia";
   summary.rail = isMpp ? "mpp" : "x402";
 
@@ -172,7 +176,6 @@ export async function run(args = []) {
             } catch {}
           }
           saveAllowance({ ...allowance, funded: true, lastFaucet: new Date().toISOString() });
-          summary.allowance.funded = true;
           if (balance > 0) {
             line("Balance", `${(balance / 1e6).toFixed(2)} pathUSD (funded)`);
           } else {
@@ -186,9 +189,7 @@ export async function run(args = []) {
       }
     } else {
       line("Balance", `${(balance / 1e6).toFixed(2)} pathUSD`);
-      summary.allowance.funded = balance > 0;
     }
-    summary.balance = { symbol: "pathUSD", usd_micros: balance };
   } else {
     // Base Sepolia: read USDC balance (existing behavior)
     const { createPublicClient, http } = await import("viem");
@@ -214,7 +215,6 @@ export async function run(args = []) {
           } catch {}
         }
         saveAllowance({ ...allowance, funded: true, lastFaucet: new Date().toISOString() });
-        summary.allowance.funded = true;
         if (balance > 0) {
           line("Balance", `${(balance / 1e6).toFixed(2)} USDC (funded)`);
         } else {
@@ -225,11 +225,21 @@ export async function run(args = []) {
       }
     } else {
       line("Balance", `${(balance / 1e6).toFixed(2)} USDC`);
-      summary.allowance.funded = balance > 0;
     }
-    summary.balance = { symbol: "USDC", usd_micros: balance };
   }
 
+  // Balances mirror `run402 status`: the on-chain figure above plus the
+  // Run402-held prepaid credit (rail-independent). Prepaid credit is fetched
+  // best-effort so a billing read failure never blocks setup.
+  const billing = await getSdk().billing.checkBalance(allowance.address).catch(() => null);
+  const hasBilling = billing && billing.exists !== false;
+  summary.balances = {
+    on_chain_usd_micros: balance,
+    on_chain_token: isMpp ? "pathUSD" : "USDC",
+    prepaid_credit_usd_micros: hasBilling ? billing.available_usd_micros : null,
+    held_usd_micros: hasBilling ? (billing.held_usd_micros ?? 0) : null,
+  };
+
   // Show note if switching rails
   if (previousRail && previousRail !== (isMpp ? "mpp" : "x402")) {
     const prev = previousRail === "mpp" ? "Tempo pathUSD" : "Base Sepolia USDC";