run402 4.93.2 → 4.95.0

package/lib/sign-in.mjs

@@ -0,0 +1,296 @@
+/**
+ * Shared machinery for a person's command-line sign-in: `run402 login`,
+ * `run402 logout`, `run402 whoami`, and `run402 approve`.
+ *
+ * One sign-in session (wire token class `control_plane_session`), bound to the
+ * principal and graded by how it was minted:
+ *   - `run402 login` — loopback PKCE (RFC 8252): the browser runs the passkey
+ *     ceremony and redirects to a 127.0.0.1 listener. Grade `loopback`: full and
+ *     step-up-able.
+ *   - `run402 login --device` — RFC 8628 device authorization for a terminal
+ *     with no browser. Grade `device`: read-only (every mutation answers
+ *     `SESSION_READ_ONLY`).
+ *
+ * Provisioning, deploying, and writing secrets without a wallet additionally
+ * need a **write approval** — passkey-signed, scoped to one (action, target),
+ * minted by `run402 approve` and sent as `X-Run402-Write-Approval`. A write
+ * approval never satisfies step-up.
+ *
+ * The session and approvals are cached at the BASE config dir (principal-
+ * scoped, shared across named wallets), mode 0600. Agent-first: JSON to stdout;
+ * the URL and code a person must open go to stderr.
+ */
+
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { randomBytes, createHash } from "node:crypto";
+import { fail, reportSdkError } from "./sdk-errors.mjs";
+import { getSdk } from "./sdk.mjs";
+import { isWriteApprovalRequired } from "#sdk/node";
+import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
+import {
+  saveApproval,
+  hashControlPlaneSession,
+  approvalFromTokenResponse,
+} from "../core-dist/write-approvals.js";
+import { getApiBase } from "../core-dist/config.js";
+
+/** Gateway write-approval capabilities → required target scope. */
+export const APPROVAL_ACTIONS = {
+  "org.project.create": "org",
+  "project.deploy": "project",
+  "project.secret.write": "project",
+};
+
+/** True when `url` is same-origin as the API base (confirm_url validation). */
+function sameApiOrigin(url) {
+  try {
+    return new URL(url).origin === new URL(getApiBase()).origin;
+  } catch {
+    return false;
+  }
+}
+
+/** Best-effort, cross-platform browser open. Never throws. */
+export function openBrowser(url) {
+  try {
+    let cmd;
+    let cmdArgs;
+    if (process.platform === "darwin") {
+      cmd = "open";
+      cmdArgs = [url];
+    } else if (process.platform === "win32") {
+      cmd = "cmd";
+      cmdArgs = ["/c", "start", "", url];
+    } else {
+      cmd = "xdg-open";
+      cmdArgs = [url];
+    }
+    const child = spawn(cmd, cmdArgs, { stdio: "ignore", detached: true });
+    child.on("error", () => {}); // ignore: the URL is also printed to stderr
+    child.unref();
+  } catch {
+    // Best-effort only — the person can always copy the printed URL.
+  }
+}
+
+/** Output shape for a cached sign-in session. NEVER includes the token. */
+export function sessionView(session, nowMs = Date.now()) {
+  return {
+    logged_in: true,
+    grade: session.grade,
+    read_only: session.grade === "device",
+    principal_id: session.principal_id || null,
+    amr: session.amr,
+    expires_at: new Date(session.expires_at).toISOString(),
+    expires_in_seconds: Math.max(0, Math.round((session.expires_at - nowMs) / 1000)),
+  };
+}
+
+const base64url = (buf) => buf.toString("base64url");
+
+/** Generate PKCE (S256) + CSRF state + replay nonce for the loopback flow. */
+export function pkce() {
+  const codeVerifier = base64url(randomBytes(32));
+  const codeChallenge = base64url(createHash("sha256").update(codeVerifier).digest());
+  return { codeVerifier, codeChallenge, state: base64url(randomBytes(16)), nonce: base64url(randomBytes(16)) };
+}
+
+/**
+ * Start a 127.0.0.1 loopback server (RFC 8252) that captures exactly one
+ * redirect. Returns the bound port (via `ready`), a promise for the auth code,
+ * and a `close()`. State is validated here to reject CSRF before exchange.
+ */
+export function startLoopbackServer({ expectedState, timeoutMs }) {
+  let resolveCode;
+  let rejectCode;
+  const codePromise = new Promise((res, rej) => {
+    resolveCode = res;
+    rejectCode = rej;
+  });
+  let timer;
+  // Track live sockets: server.close() alone stops NEW connections but leaves
+  // the browser's keep-alive socket open, which keeps Node's event loop alive
+  // and hangs the CLI after a successful login. close() must destroy them.
+  const sockets = new Set();
+  const server = createServer((req, res) => {
+    let u;
+    try {
+      u = new URL(req.url, "http://127.0.0.1");
+    } catch {
+      res.writeHead(400).end("bad request");
+      return;
+    }
+    if (u.pathname !== "/callback") {
+      res.writeHead(404).end("not found");
+      return;
+    }
+    const code = u.searchParams.get("code");
+    const gotState = u.searchParams.get("state");
+    const errParam = u.searchParams.get("error");
+    // `connection: close` so the browser does not keep the socket alive.
+    res.writeHead(200, { "content-type": "text/html", connection: "close" });
+    res.end(
+      "<!doctype html><html><body style=\"font-family:system-ui;padding:3rem\">" +
+        "<h2>run402 - you're signed in.</h2><p>You can close this window and return to your terminal.</p></body></html>",
+    );
+    // Do NOT tear down here — let the response flush. The caller calls close()
+    // once it has the code (or on any failure path).
+    if (errParam) rejectCode(new Error(`authorization error: ${errParam}`));
+    else if (!code) rejectCode(new Error("no authorization code on the loopback redirect"));
+    else if (gotState !== expectedState) rejectCode(new Error("state mismatch on the loopback redirect (possible CSRF) - aborted"));
+    else resolveCode(code);
+  });
+  server.on("connection", (s) => {
+    sockets.add(s);
+    s.once("close", () => sockets.delete(s));
+  });
+  function close() {
+    clearTimeout(timer);
+    for (const s of sockets) {
+      try {
+        s.destroy();
+      } catch {
+        // already gone
+      }
+    }
+    try {
+      server.close();
+    } catch {
+      // already closing
+    }
+  }
+  timer = setTimeout(() => {
+    close();
+    rejectCode(new Error("timed out waiting for browser approval"));
+  }, timeoutMs);
+  server.on("error", (e) => {
+    close();
+    rejectCode(e);
+  });
+  const ready = new Promise((res, rej) => {
+    server.once("error", rej);
+    server.listen(0, "127.0.0.1", () => res(server.address().port));
+  });
+  return { ready, codePromise, close };
+}
+
+/**
+ * Run the write-approval ceremony (loopback + passkey) and cache the minted
+ * approval. Requires a live, write-capable sign-in session. Returns the cached
+ * approval (or exits non-zero via fail/reportSdkError). Reused by
+ * `run402 approve` AND the TTY auto-approve path in provision/deploy.
+ */
+export async function mintApproval({ action, orgId, projectId, noOpen = false }) {
+  const cp = loadLiveControlPlaneSession();
+  if (!cp) {
+    return fail({
+      code: "LOGIN_REQUIRED",
+      message: "No sign-in session. Run 'run402 login' first, then approve.",
+      hint: "A write approval is minted on top of your sign-in session.",
+      next_actions: [{ type: "authenticate", command: "run402 login" }],
+    });
+  }
+  if (cp.grade === "device") {
+    return fail({
+      code: "SESSION_READ_ONLY",
+      message: "This sign-in session came from 'run402 login --device' and can only read; it cannot mint a write approval.",
+      hint: "Run 'run402 login' (the browser passkey sign-in), then approve.",
+      next_actions: [{ type: "authenticate", command: "run402 login" }],
+    });
+  }
+  const sdk = getSdk();
+  const { codeVerifier, codeChallenge, state } = pkce();
+  const { ready, codePromise, close } = startLoopbackServer({ expectedState: state, timeoutMs: 300_000 });
+
+  let port;
+  try {
+    port = await ready;
+  } catch (err) {
+    close();
+    return fail({ code: "APPROVE_FAILED", message: `Could not start the loopback server: ${err.message}` });
+  }
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+  let challenge;
+  try {
+    challenge = await sdk.writeApproval.requestChallenge({
+      action,
+      orgId: orgId ?? undefined,
+      projectId: projectId ?? undefined,
+      cliRedirectUri: redirectUri,
+      codeChallenge,
+      state,
+      token: cp.control_plane_session_token,
+    });
+  } catch (err) {
+    close();
+    return reportSdkError(err);
+  }
+
+  const confirmUrl = challenge?.confirm_url;
+  if (!confirmUrl || !sameApiOrigin(confirmUrl)) {
+    close();
+    return fail({
+      code: "APPROVE_BAD_CONFIRM_URL",
+      message: "The gateway returned a confirm_url that is not same-origin as the API base; aborting.",
+    });
+  }
+  const targetLabel = orgId ? `org ${orgId}` : projectId ? `project ${projectId}` : "(no target)";
+  process.stderr.write(
+    `\nTo approve '${action}' for ${targetLabel}, open and approve with your passkey:\n  ${confirmUrl}\n\n`,
+  );
+  if (!noOpen && process.stderr.isTTY) {
+    openBrowser(confirmUrl);
+    process.stderr.write("(opening your browser…)\n\n");
+  }
+  process.stderr.write("Waiting for passkey approval…\n");
+
+  let code;
+  try {
+    code = await codePromise;
+  } catch (err) {
+    close();
+    return fail({ code: "APPROVE_FAILED", message: err.message, hint: "Run 'run402 approve' to try again." });
+  }
+
+  let token;
+  try {
+    token = await sdk.writeApproval.exchangeClaimCode({ code, codeVerifier, state });
+  } catch (err) {
+    close();
+    return reportSdkError(err);
+  }
+  close();
+
+  const approval = approvalFromTokenResponse(token, {
+    action,
+    target: { org_id: orgId ?? undefined, project_id: projectId ?? undefined },
+    apiOrigin: new URL(getApiBase()).origin,
+    controlPlaneSessionHash: hashControlPlaneSession(cp.control_plane_session_token),
+    controlPlanePrincipalId: cp.principal_id || "",
+  });
+  saveApproval(approval);
+  process.stderr.write(`\nApproved '${action}' for ${targetLabel}.\n`);
+  return approval;
+}
+
+/**
+ * Run a write action; on `WriteApprovalRequiredError` AND an interactive TTY
+ * (CLI), run the scoped approval ceremony and retry once. In MCP / CI /
+ * non-TTY the typed error is rethrown unchanged — the agent relays the resolved
+ * `run402 approve …` command rather than a browser opening unexpectedly.
+ */
+export async function withAutoApprove(fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (!isWriteApprovalRequired(err) || !process.stderr.isTTY) throw err;
+    const action = err.capability;
+    const target = err.target || {};
+    if (!action) throw err;
+    process.stderr.write(`\nThis '${action}' needs a one-time write approval. Opening the browser to approve…\n`);
+    await mintApproval({ action, orgId: target.org_id ?? undefined, projectId: target.project_id ?? undefined });
+    return await fn(); // retry once with the now-cached approval
+  }
+}

package/lib/sites.mjs

@@ -2,7 +2,7 @@ import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs"
 import { tmpdir } from "os";
 import { dirname, join, resolve } from "path";
 import { fileSetFromDir, delegateTokenFromEnv } from "#sdk/node";
-import { allowanceAuthHeaders, resolveProjectId, updateProject } from "./config.mjs";
+import { walletAuthHeaders, resolveProjectId, updateProject } from "./config.mjs";
 import { resolveFilePathsInManifest } from "./manifest.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
@@ -13,8 +13,8 @@ const SMALL_DIR_THRESHOLD = 5;
 const HELP = `run402 sites - Deploy and manage static sites
 
 Usage:
-  run402 sites deploy --manifest <file> [--project <id>]
-  run402 sites deploy-dir <path> --project <id>
+  run402 sites deploy --manifest <file> [--project <project_id>]
+  run402 sites deploy-dir <path> --project <project_id>
   cat manifest.json | run402 sites deploy
 
 Subcommands:
@@ -23,12 +23,12 @@ Subcommands:
 
 Options (deploy):
   --manifest <file>     Path to manifest JSON file (or read from stdin)
-  --project <id>        Project ID (defaults to active project)
+  --project <project_id>        Project ID (defaults to active project)
   --help, -h            Show this help message
 
 Options (deploy-dir):
   <path>                Positional: local directory to deploy
-  --project <id>        Project ID (defaults to active project)
+  --project <project_id>        Project ID (defaults to active project)
   --quiet               Suppress progress events on stderr
   --dry-run             Plan-only: print the diff envelope and exit
   --confirm-prune       Required when <path> has fewer files than the
@@ -58,25 +58,25 @@ Notes:
     (CAS-backed): only bytes the gateway doesn't already have are uploaded.
     Re-deploys of an unchanged tree make no S3 PUTs.
   - To check status of an in-flight deploy, use 'run402 deploy events <op>'
-    or 'run402 deploy list --project <id>'.
+    or 'run402 deploy list --project <project_id>'.
   - deploy-dir walks the directory, skips .git / node_modules / .DS_Store,
     and auto-detects binary files. Symlinks are rejected.
   - Progress events are emitted as JSON-line objects on stderr by default
     (one object per line). Final result envelope goes to stdout. Pass --quiet
     to silence stderr.
-  - Free with active tier - requires allowance auth
+  - Free with active tier - requires SIWX auth
 `;
 
 const SUB_HELP = {
   deploy: `run402 sites deploy - Deploy a static site from a manifest
 
 Usage:
-  run402 sites deploy --manifest <file> [--project <id>]
-  cat manifest.json | run402 sites deploy [--project <id>]
+  run402 sites deploy --manifest <file> [--project <project_id>]
+  cat manifest.json | run402 sites deploy [--project <project_id>]
 
 Options:
   --manifest <file>   Path to manifest JSON file (or read from stdin)
-  --project <id>      Project ID (defaults to the active project)
+  --project <project_id>      Project ID (defaults to the active project)
 
 Manifest format (JSON):
   {
@@ -90,7 +90,7 @@ Manifest format (JSON):
 
 Notes:
   - Must include at least index.html in the files array
-  - Free with active tier - requires allowance auth
+  - Free with active tier - requires SIWX auth
 
 Examples:
   run402 sites deploy --manifest site.json
@@ -99,14 +99,14 @@ Examples:
   "deploy-dir": `run402 sites deploy-dir - Deploy a static site from a local directory
 
 Usage:
-  run402 sites deploy-dir <path> [--project <id>] [--quiet]
+  run402 sites deploy-dir <path> [--project <project_id>] [--quiet]
                                   [--dry-run] [--confirm-prune]
 
 Arguments:
   <path>              Local directory to deploy (positional, required)
 
 Options:
-  --project <id>      Project ID (defaults to the active project)
+  --project <project_id>      Project ID (defaults to the active project)
   --quiet             Suppress progress events on stderr (events are on by
                       default — see Progress events below)
   --dry-run           Plan the deploy and print a JSON envelope describing
@@ -139,7 +139,7 @@ Progress events:
 Notes:
   - Re-deploying an unchanged tree makes no S3 PUTs (returns immediately
     with bytes_uploaded: 0)
-  - Free with active tier - requires allowance auth
+  - Free with active tier - requires SIWX auth
 
 Examples:
   run402 sites deploy-dir ./dist --project prj_abc
@@ -196,7 +196,7 @@ async function deploy(args) {
     fail({
       code: "BAD_USAGE",
       message: `Unexpected argument for sites deploy: ${extra[0]}`,
-      hint: "Use `run402 sites deploy --manifest <file> [--project <id>]`.",
+      hint: "Use `run402 sites deploy --manifest <file> [--project <project_id>]`.",
     });
   }
   const opts = { manifest: null, project: undefined, target: undefined, quiet: false };
@@ -219,10 +219,10 @@ async function deploy(args) {
   const manifest = JSON.parse(raw);
   if (opts.manifest) resolveFilePathsInManifest(manifest, dirname(resolve(opts.manifest)));
 
-  // Preserve the aggressive early exit when no allowance is configured.
+  // Preserve the aggressive early exit when no local wallet is configured.
   // A delegate holds `deploy` and /apply/v1/plans accepts it; refusing locally
   // would tell a wallet-less holder to run `run402 init` (see 4.11.2).
-  if (!delegateTokenFromEnv()) allowanceAuthHeaders("/apply/v1/plans");
+  if (!delegateTokenFromEnv()) walletAuthHeaders("/apply/v1/plans");
 
   const stage = stageFilesToTempDir(manifest.files || []);
   try {
@@ -252,7 +252,7 @@ async function deployDir(args) {
     fail({
       code: "BAD_USAGE",
       message: `Unexpected argument for sites deploy-dir: ${positionals[1]}`,
-      hint: "Use `run402 sites deploy-dir <path> --project <id>`.",
+      hint: "Use `run402 sites deploy-dir <path> --project <project_id>`.",
     });
   }
   const opts = {
@@ -282,16 +282,16 @@ async function deployDir(args) {
     fail({
       code: "BAD_USAGE",
       message: "Missing <path>.",
-      hint: "run402 sites deploy-dir <path> --project <id>",
+      hint: "run402 sites deploy-dir <path> --project <project_id>",
     });
   }
   const projectId = resolveProjectId(opts.project);
   if (opts.target !== undefined) failUnsupportedTarget();
 
-  // Preserve the aggressive early exit when no allowance is configured.
+  // Preserve the aggressive early exit when no local wallet is configured.
   // A delegate holds `deploy` and /apply/v1/plans accepts it; refusing locally
   // would tell a wallet-less holder to run `run402 init` (see 4.11.2).
-  if (!delegateTokenFromEnv()) allowanceAuthHeaders("/apply/v1/plans");
+  if (!delegateTokenFromEnv()) walletAuthHeaders("/apply/v1/plans");
 
   let fileSet;
   try {
@@ -325,7 +325,7 @@ async function deployDir(args) {
   if (opts.dryRun) {
     try {
       const { plan } = await getSdk()._applyEngine.plan({
-        project: projectId,
+        project_id: projectId,
         site: { replace: fileSet },
       }, { dryRun: true });
       console.log(JSON.stringify({

package/lib/snapshots.mjs

@@ -15,14 +15,14 @@ import {
 const HELP = `run402 snapshots — Project database restore points
 
 Usage:
-  run402 snapshots create [--project <id>] [--json]
-  run402 snapshots list [--project <id>] [--kind <kind>] [--limit <n>] [--after <cursor>] [--json]
-  run402 snapshots get <snapshot-id> [--project <id>] [--json]
-  run402 snapshots restore <snapshot-id> [--project <id>] [--include-auth] [--confirm <token>] [--json]
-  run402 snapshots delete <snapshot-id> [--project <id>] [--json]
+  run402 snapshots create [--project <project_id>] [--json]
+  run402 snapshots list [--project <project_id>] [--kind <kind>] [--limit <n>] [--after <cursor>] [--json]
+  run402 snapshots get <snapshot_id> [--project <project_id>] [--json]
+  run402 snapshots restore <snapshot_id> [--project <project_id>] [--include-auth] [--confirm <token>] [--json]
+  run402 snapshots delete <snapshot_id> [--project <project_id>] [--json]
 
 Legacy (still supported): a leading prj_... positional selects the project,
-e.g. run402 snapshots restore prj_abc123 <snapshot-id>. --project defaults to
+e.g. run402 snapshots restore prj_abc123 <snapshot_id>. --project defaults to
 the active project.
 
 Restore is a two-step handshake. First call without --confirm to get a
@@ -82,7 +82,7 @@ async function list(args) {
 }
 
 async function get(args) {
-  const { projectId, snapshotId } = resolveProjectAndSnapshot(args, "run402 snapshots get [project-id] <snapshot-id>");
+  const { projectId, snapshotId } = resolveProjectAndSnapshot(args, "run402 snapshots get [project_id] <snapshot_id>");
   try {
     const snapshot = await getSdk().snapshots.get(projectId, snapshotId);
     console.log(JSON.stringify({ snapshot }, null, 2));
@@ -92,7 +92,7 @@ async function get(args) {
 }
 
 async function restore(args) {
-  const { projectId, snapshotId } = resolveProjectAndSnapshot(args, "run402 snapshots restore [project-id] <snapshot-id> [--confirm <token>]");
+  const { projectId, snapshotId } = resolveProjectAndSnapshot(args, "run402 snapshots restore [project_id] <snapshot_id> [--confirm <token>]");
   const includeAuth = args.includes("--include-auth");
   const confirm = flagValue(args, "--confirm");
   try {
@@ -115,7 +115,7 @@ async function restore(args) {
 }
 
 async function deleteSnapshot(args) {
-  const { projectId, snapshotId } = resolveProjectAndSnapshot(args, "run402 snapshots delete [project-id] <snapshot-id>");
+  const { projectId, snapshotId } = resolveProjectAndSnapshot(args, "run402 snapshots delete [project_id] <snapshot_id>");
   try {
     await getSdk().snapshots.delete(projectId, snapshotId);
     console.log(JSON.stringify({ ok: true, project_id: projectId, snapshot_id: snapshotId, deleted: true }, null, 2));
@@ -125,7 +125,7 @@ async function deleteSnapshot(args) {
 }
 
 function resolveProjectAndSnapshot(args, usage) {
-  // Canonical: `<snapshot-id> [--project <id>]`; legacy `<prj_id> <snapshot-id>`
+  // Canonical: `<snapshot_id> [--project <project_id>]`; legacy `<prj_id> <snapshot_id>`
   // still works (requireRestPositional keeps a lone snapshot id that happens to
   // start with prj_ from being eaten as the project selector).
   const { projectId, rest } = resolveProjectSelector(args, { valueFlags: FLAG_VALUES, requireRestPositional: true });

package/lib/stats.mjs

@@ -8,7 +8,7 @@
  * line per request to stderr, automatically, for every SDK caller (CLI, MCP,
  * `git-remote-run402`). This module is the thin CLI-edge reader of that
  * per-instance accumulator: it turns `sdk.stats()` into the `stats` envelope
- * field every `repos` verb's result and `deploy apply`'s final result carry
+ * field every `repos` verb's result and `deploy`'s final result carry
  * (always on), plus the `-v`/`--verbose` stderr summary line.
  *
  * `sdk.stats()` reflects only calls made through the ONE `Run402` instance
@@ -47,7 +47,7 @@ function writeVerboseStatsLine(sdk) {
 /**
  * One stderr summary line, only when verbose was requested. Coexists with
  * `--human`. `verbose` is either normalized argv (checked for `-v`/
- * `--verbose`) or a plain boolean, for callers (e.g. `deploy apply`) that
+ * `--verbose`) or a plain boolean, for callers (e.g. `deploy`) that
  * already parsed their own flags into an options object.
  */
 export function printVerboseStats(verbose, sdk) {

package/lib/status.mjs

@@ -1,6 +1,6 @@
 import { readRemoteStatus } from "#sdk/node";
 import {
-  readAllowance,
+  readWallet,
   loadKeyStore,
   getActiveProjectId,
   apiBase,
@@ -21,8 +21,8 @@ Usage:
 Displays:
   - Wallet identity (local_label, server_label, address)
   - Payment rail (x402 | mpp)
-  - Balances (on_chain_usd_micros + on_chain_token, prepaid_credit_usd_micros, held_usd_micros)
-  - Tier subscription (name, status, expiry)
+  - Balances (on_chain_usd_micros + on_chain_token, allowance_usd_micros, held_usd_micros)
+  - Tier and lease (name, status, expiry)
   - Projects (from server, with fallback to local keystore)
   - Active project ID
   - Active API target
@@ -31,11 +31,11 @@ Output is JSON by default. --json is accepted as a compatibility no-op.
 --human renders a compact human summary instead (wallet, API target, tier,
 active project, balance, and the next action); it cannot be combined with
 --json.
-Run402 Cloud status requires an allowance; Core target status can still report
+Run402 Cloud status requires a wallet; Core target status can still report
 local project state without one.
 `;
 
-// USDC / pathUSD constants (match allowance.mjs)
+// USDC / pathUSD constants (match wallet.mjs)
 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";
@@ -105,13 +105,13 @@ export async function run(args = []) {
       hint: "JSON is the default; drop --json to keep it, or keep --human alone for the rendered view.",
     });
   }
-  const allowance = readAllowance();
+  const localWallet = readWallet();
   const target = {
     api_base: apiBase(),
     api_base_source: apiBaseSource(),
     kind: apiTargetKind(),
   };
-  if (!allowance) {
+  if (!localWallet) {
     const store = loadKeyStore();
     const bare = {
       wallet: null,
@@ -128,16 +128,16 @@ export async function run(args = []) {
     return;
   }
 
-  const wallet = allowance.address.toLowerCase();
-  const rail = allowance.rail || "x402";
+  const wallet = localWallet.address.toLowerCase();
+  const rail = localWallet.rail || "x402";
 
-  // Parallel API calls: tier + billing balance + server-side projects + on-chain wallet balance.
+  // Parallel API calls: tier + allowance + server-side projects + on-chain wallet balance.
   // projects.list() is the membership-scoped named inventory (project-findability);
-  // SIWX wallet auth is signed from the allowance. Best-effort — a missing
-  // allowance yields null and we fall back to the local keystore below.
+  // SIWX wallet auth is signed from the wallet. Best-effort — a missing
+  // wallet yields null and we fall back to the local keystore below.
   const [status, walletBalance] = await Promise.all([
     readRemoteStatus(getSdk(), wallet),
-    readWalletBalanceUsdMicros(rail, allowance.address),
+    readWalletBalanceUsdMicros(rail, localWallet.address),
   ]);
   const { tier, billing, remote } = status;
 
@@ -155,18 +155,18 @@ export async function run(args = []) {
   const walletName = getActiveProfile();
   const walletMeta = readMeta(walletName);
 
-  // Balances are grouped under one object so the on-chain and
-  // prepaid-credit numbers are unambiguous and rail-legible.
+  // Balances are grouped under one object so the on-chain (wallet) and
+  // allowance numbers are unambiguous and rail-legible.
   //   - on_chain_usd_micros / on_chain_token: on-chain USDC (x402) or pathUSD
-  //     (mpp), null if the RPC read failed
-  //   - prepaid_credit_usd_micros / held_usd_micros: Run402-held credits,
-  //     rail-independent, null when no organization exists
+  //     (mpp) in the wallet, null if the RPC read failed
+  //   - allowance_usd_micros / held_usd_micros: the organization's Run402-held
+  //     allowance, rail-independent, null when no organization exists
   const hasBilling = billing && billing.exists !== false;
   const result = {
     wallet: {
       local_label: walletName,
       server_label: walletMeta?.label ?? null,
-      address: allowance.address,
+      address: localWallet.address,
     },
     rail,
     remote_status: status.availability,
@@ -175,7 +175,7 @@ export async function run(args = []) {
     balances: {
       on_chain_usd_micros: walletBalance,
       on_chain_token: rail === "mpp" ? "pathUSD" : "USDC",
-      prepaid_credit_usd_micros: hasBilling ? billing.available_usd_micros : null,
+      allowance_usd_micros: hasBilling ? billing.allowance_usd_micros : null,
       held_usd_micros: hasBilling ? (billing.held_usd_micros ?? 0) : null,
     },
     tier: tier && tier.tier
@@ -205,7 +205,7 @@ function usdFromMicros(micros) {
 
 /**
  * The one next action for the human view, derived from the same state the
- * JSON carries. Mirrors `init`: `run402 up -y` subscribes the prototype tier
+ * JSON carries. Mirrors `init`: `run402 up -y` sets the prototype tier
  * itself as part of the first deploy, so a tier-less account gets ONE command.
  */
 function statusNextAction(result) {
@@ -214,7 +214,7 @@ function statusNextAction(result) {
   }
   if (result.remote_status?.tier?.state === "unavailable") return "Check connectivity/authentication and retry run402 status; tier state is unavailable.";
   if (!result.tier) {
-    return "run402 up -y  (subscribes the prototype tier, free on testnet, as part of the first deploy; or: run402 tier set prototype)";
+    return "run402 up -y  (sets the prototype tier, free on testnet, as part of the first deploy; or: run402 tier set prototype)";
   }
   if (!result.active_project) {
     return "run402 up --name <name> -y  (or select an existing project: run402 projects use <project_id>)";
@@ -230,7 +230,7 @@ function statusNextAction(result) {
 export function formatStatusHuman(result) {
   const lines = [];
   if (!result.wallet) {
-    lines.push("Wallet:   none (no allowance on this machine)");
+    lines.push("Wallet:   none (no local wallet on this machine)");
   } else {
     const label = result.wallet.server_label
       ? `${result.wallet.local_label} (${result.wallet.server_label})`
@@ -262,8 +262,8 @@ export function formatStatusHuman(result) {
     const parts = [];
     const onChain = usdFromMicros(result.balances.on_chain_usd_micros);
     if (onChain) parts.push(`${onChain} ${result.balances.on_chain_token} on-chain`);
-    const credit = usdFromMicros(result.balances.prepaid_credit_usd_micros);
-    if (credit) parts.push(`${credit} prepaid credit`);
+    const allowance = usdFromMicros(result.balances.allowance_usd_micros);
+    if (allowance) parts.push(`${allowance} allowance`);
     if (parts.length) lines.push(`Balance:  ${parts.join(", ")}`);
   }
   lines.push(`Next:     ${statusNextAction(result)}`);