run402 4.93.1 → 4.94.0

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 */
     }
@@ -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/whoami.mjs

@@ -0,0 +1,75 @@
+/**
+ * `run402 whoami` — who this CLI acts as: the principal, its org memberships,
+ * and the sign-in session (`session.grade`: `browser` | `loopback` | `device`,
+ * or `null` for a wallet caller) from `GET /agent/v1/whoami`, plus the write
+ * approvals cached on this machine. See sign-in.mjs.
+ */
+
+import { fail, reportSdkError } from "./sdk-errors.mjs";
+import { getSdk } from "./sdk.mjs";
+import { normalizeArgv, hasHelp, assertKnownFlags, positionalArgs } from "./argparse.mjs";
+import { loadLiveControlPlaneSession, clearControlPlaneSession } from "../core-dist/control-plane-session.js";
+import { readApprovals } from "../core-dist/write-approvals.js";
+
+const HELP = `run402 whoami — who this CLI acts as
+
+Usage:
+  run402 whoami
+
+Calls GET /agent/v1/whoami. With a live sign-in session ('run402 login') it
+reads as that session and reports session.grade: loopback (full), browser, or
+device (read-only). Without one it reads as the active wallet and session is
+null. The output also lists the write approvals cached on this machine
+('run402 approve'), each with its action, target, and expiry.
+`;
+
+/** Live cached write approvals: action, target, expiry. Never the token. */
+function cachedApprovals(nowMs = Date.now()) {
+  try {
+    return readApprovals()
+      .filter((a) => a.expires_at > nowMs)
+      .map((a) => ({
+        action: a.action,
+        org_id: a.org_id ?? null,
+        project_id: a.project_id ?? null,
+        expires_at: new Date(a.expires_at).toISOString(),
+      }));
+  } catch {
+    return [];
+  }
+}
+
+export async function run(args = []) {
+  args = normalizeArgv(args);
+  if (hasHelp(args)) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  assertKnownFlags(args, ["--help", "-h"]);
+  const extra = positionalArgs(args, []);
+  if (extra.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for whoami: ${extra[0]}`, hint: "Use `run402 whoami`." });
+  }
+  const sdk = getSdk();
+  const session = loadLiveControlPlaneSession();
+  let who;
+  try {
+    who = session
+      ? await sdk.session.whoami({ token: session.control_plane_session_token })
+      : await sdk.orgs.whoami();
+  } catch (err) {
+    // A cached session the gateway no longer honours (revoked or expired
+    // server-side): drop it so the next command does not replay a dead token.
+    if (session && err && err.status === 401) {
+      clearControlPlaneSession();
+      return fail({
+        code: "SESSION_INVALID",
+        message: "The cached sign-in session is no longer valid (revoked or expired).",
+        hint: "Run 'run402 login' to sign in again.",
+        next_actions: [{ type: "authenticate", command: "run402 login" }],
+      });
+    }
+    return reportSdkError(err);
+  }
+  console.log(JSON.stringify({ ...who, write_approvals: cachedApprovals() }, null, 2));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.93.1",
+  "version": "4.94.0",
   "description": "CLI for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.",
   "type": "module",
   "bin": {

package/sdk/core-dist/config.js

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { existsSync, renameSync, mkdirSync, chmodSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, renameSync, mkdirSync, chmodSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { describeRejectedValue } from "./redact.js";
 export const DEFAULT_API_BASE = "https://api.run402.com";
@@ -118,7 +118,7 @@ export function getProfilesDir() {
  * The effective config directory for the *active* wallet. The `default` wallet
  * resolves to the base dir (zero migration for existing single-wallet
  * installs); any named wallet resolves to `{base}/profiles/<name>`. Because
- * keystore, allowance, and meta paths all derive from this, switching the
+ * keystore, wallet, and meta paths all derive from this, switching the
  * profile env var moves the whole wallet bundle atomically — and the SDK/MCP
  * inherit profile selection for free.
  */
@@ -232,27 +232,61 @@ export function isCoreApiTarget() {
         return true;
     return false;
 }
-export function getAllowancePath() {
-    if (process.env.RUN402_ALLOWANCE_PATH)
-        return process.env.RUN402_ALLOWANCE_PATH;
-    const dir = getConfigDir();
-    const newPath = join(dir, "allowance.json");
-    const oldPath = join(dir, "wallet.json");
-    // Auto-migrate from wallet.json → allowance.json. renameSync preserves the
-    // source file's mode, so a legacy world-readable wallet.json (mode 0644)
-    // would otherwise carry that mode forward and leave the private key
-    // world-readable on a shared machine. Tighten to 0600 after the rename.
-    if (!existsSync(newPath) && existsSync(oldPath)) {
-        mkdirSync(dir, { recursive: true });
-        renameSync(oldPath, newPath);
+/**
+ * The file that holds a wallet's key, in the base config dir (the `default`
+ * wallet) and in each `profiles/<name>/` directory.
+ */
+export const WALLET_FILE_NAME = "wallet.json";
+/** The name the wallet key file had before it was `wallet.json`. */
+const PREVIOUS_WALLET_FILE_NAME = "allowance.json";
+const walletFilesMovedFor = new Set();
+/**
+ * One-time local move of the wallet key file to its current name: in the base
+ * config dir and every `profiles/<name>/` directory, `allowance.json` is
+ * renamed to `wallet.json` (an atomic same-directory rename) when
+ * `wallet.json` is absent, then tightened to 0600. A directory that already
+ * holds `wallet.json` is left untouched. Runs once per base dir per process;
+ * nothing reads the previous name afterwards.
+ */
+export function moveWalletFiles() {
+    const base = getConfigBaseDir();
+    if (walletFilesMovedFor.has(base))
+        return;
+    walletFilesMovedFor.add(base);
+    const dirs = [base];
+    try {
+        for (const entry of readdirSync(join(base, "profiles"), { withFileTypes: true })) {
+            if (entry.isDirectory())
+                dirs.push(join(base, "profiles", entry.name));
+        }
+    }
+    catch {
+        // No profiles directory yet.
+    }
+    for (const dir of dirs) {
+        const from = join(dir, PREVIOUS_WALLET_FILE_NAME);
+        const to = join(dir, WALLET_FILE_NAME);
+        if (existsSync(to) || !existsSync(from))
+            continue;
+        try {
+            renameSync(from, to);
+        }
+        catch {
+            continue;
+        }
         try {
-            chmodSync(newPath, 0o600);
+            chmodSync(to, 0o600);
         }
         catch {
             // Best-effort (e.g. Windows / exotic filesystems). Read-time self-heal
-            // in readAllowance() is the backstop.
+            // in readWallet() is the backstop.
         }
     }
-    return newPath;
+}
+export function getWalletPath() {
+    if (process.env.RUN402_WALLET_PATH)
+        return process.env.RUN402_WALLET_PATH;
+    moveWalletFiles();
+    return join(getConfigDir(), WALLET_FILE_NAME);
 }
 //# sourceMappingURL=config.js.map

package/sdk/core-dist/control-plane-session.js

@@ -10,6 +10,14 @@ export function getControlPlaneSessionPath() {
     return (process.env.RUN402_CONTROL_PLANE_SESSION_PATH ||
         join(getConfigBaseDir(), "control-plane-session.json"));
 }
+/**
+ * Read a wire grade. An unknown or absent value is treated as `device` (the
+ * read-only grade) so a cache the client cannot classify never claims more
+ * authority than the gateway will grant.
+ */
+function toGrade(raw) {
+    return raw === "browser" || raw === "loopback" || raw === "device" ? raw : "device";
+}
 /** Tighten 0600 if group/other-readable, warning once. Best-effort, POSIX-only. */
 function selfHealPermissions(p) {
     if (process.platform === "win32")
@@ -50,20 +58,20 @@ export function readControlPlaneSession(path) {
         return null;
     }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error("control-plane-session.json must contain a JSON object. Delete it and run 'run402 operator login --loopback' to recreate it.");
+        throw new Error("control-plane-session.json must contain a JSON object. Delete it and run 'run402 login' to recreate it.");
     }
     const data = parsed;
     if (typeof data.control_plane_session_token !== "string" ||
         data.control_plane_session_token.length === 0) {
-        throw new Error("control-plane-session.json missing valid 'control_plane_session_token'. Run 'run402 operator login --loopback' to refresh it.");
+        throw new Error("control-plane-session.json missing valid 'control_plane_session_token'. Run 'run402 login' to refresh it.");
     }
     if (typeof data.expires_at !== "number" || !Number.isFinite(data.expires_at)) {
-        throw new Error("control-plane-session.json missing valid 'expires_at'. Run 'run402 operator login --loopback' to refresh it.");
+        throw new Error("control-plane-session.json missing valid 'expires_at'. Run 'run402 login' to refresh it.");
     }
     return {
         control_plane_session_token: data.control_plane_session_token,
         token_type: typeof data.token_type === "string" ? data.token_type : "Bearer",
-        provenance: typeof data.provenance === "string" ? data.provenance : "loopback_pkce",
+        grade: toGrade(data.grade),
         principal_id: typeof data.principal_id === "string" ? data.principal_id : "",
         amr: Array.isArray(data.amr) ? data.amr.filter((a) => typeof a === "string") : [],
         expires_at: data.expires_at,
@@ -79,7 +87,7 @@ export function saveControlPlaneSession(data, path) {
     renameSync(tmp, p);
     chmodSync(p, 0o600);
 }
-/** Delete the cached control-plane session — local half of `operator logout`. Idempotent. */
+/** Delete the cached sign-in session — local half of `run402 logout`. Idempotent. */
 export function clearControlPlaneSession(path) {
     const p = path ?? getControlPlaneSessionPath();
     try {
@@ -105,10 +113,27 @@ export function controlPlaneSessionFromTokenResponse(resp, nowMs = Date.now()) {
     return {
         control_plane_session_token: resp.control_plane_session_token,
         token_type: resp.token_type ?? "Bearer",
-        provenance: resp.provenance ?? "loopback_pkce",
+        grade: toGrade(resp.grade),
         principal_id: resp.principal_id ?? "",
         amr: Array.isArray(resp.amr) ? resp.amr.filter((a) => typeof a === "string") : [],
         expires_at: nowMs + (typeof resp.expires_in === "number" ? resp.expires_in : 0) * 1000,
     };
 }
+/**
+ * Delete the session caches of the retired email-scoped session
+ * (`{base}/operator-session.json`) and the retired approval cache file
+ * (`{base}/write-auth-session.json`). Neither is read any more; `run402 login`
+ * and `run402 logout` call this so a stale token does not linger on disk.
+ * Best-effort and idempotent.
+ */
+export function clearRetiredSessionCaches() {
+    for (const name of ["operator-session.json", "write-auth-session.json"]) {
+        try {
+            rmSync(join(getConfigBaseDir(), name), { force: true });
+        }
+        catch {
+            // Best-effort: a failed unlink never blocks login or logout.
+        }
+    }
+}
 //# sourceMappingURL=control-plane-session.js.map