run402 2.27.0 → 2.29.0

package/lib/functions.mjs

@@ -25,6 +25,10 @@ Subcommands:
                                        Get function logs
   update <id> <name> [--schedule <cron>] [--schedule-remove] [--timeout <s>] [--memory <mb>]
                                        Update function schedule or config without re-deploying
+  rebuild <id> [<name>] [--all]        Refresh function(s) onto the current platform
+                                       runtime (re-bundles from stored source; no
+                                       source change). Pass <name> for one function
+                                       or --all for every function in the project.
   list   <id>                          List all functions for a project
   delete <id> <name>                   Delete a function
 
@@ -40,12 +44,17 @@ Examples:
   run402 functions update prj_abc123 send-reminders --schedule '0 */4 * * *'
   run402 functions update prj_abc123 send-reminders --schedule-remove
   run402 functions update prj_abc123 my-func --timeout 15 --memory 256
+  run402 functions rebuild prj_abc123 stripe-webhook
+  run402 functions rebuild prj_abc123 --all
   run402 functions list prj_abc123
   run402 functions delete prj_abc123 stripe-webhook
 
 Notes:
   - Code must export a default async function: export default async (req: Request) => Response
   - Deploy may require payment if the project lease has expired
+  - 'rebuild' is opt-in and never changes your source: it re-bundles the stored
+    source against the current platform runtime so a gateway-side wrapper fix
+    reaches an already-deployed function. 'run402 doctor' flags stale functions.
 `;
 
 const SUB_HELP = {
@@ -166,6 +175,45 @@ Examples:
   run402 functions update prj_abc123 send-reminders --schedule '0 */4 * * *'
   run402 functions update prj_abc123 send-reminders --schedule-remove
   run402 functions update prj_abc123 my-func --timeout 15 --memory 256
+`,
+  rebuild: `run402 functions rebuild — Refresh function(s) onto the current platform runtime
+
+Usage:
+  run402 functions rebuild <project_id> <name>
+  run402 functions rebuild <project_id> --all
+
+Arguments:
+  <project_id>        Target project ID
+  <name>              Function name to rebuild (omit when using --all)
+
+Options:
+  --all               Rebuild every function in the project
+
+What it does:
+  Re-bundles a function from its STORED source against the platform's current
+  entry wrapper + bundled runtime, with dependencies pinned to the exact
+  versions recorded at deploy time. The only thing that changes is the platform
+  runtime/wrapper — your source 'code_hash' is unchanged and no new release is
+  created. This is how a gateway-side wrapper fix (e.g. an SSR auth.* fix)
+  reaches a function that was already deployed: a plain redeploy with unchanged
+  source does NOT pick it up. Strictly opt-in — the platform never auto-rebuilds.
+
+  Allowed during billing grace (past_due / frozen / dormant).
+
+Output:
+  Single: a JSON object { name, rebuilt, old_fingerprint, new_fingerprint,
+    runtime_version_before, runtime_version_after, code_hash }.
+  --all:  a JSON object { rebuilt_count, total, results: [...] }; each result is
+    either a rebuild record or { name, rebuilt: false, code?, error }. Functions
+    deployed before dependency locking report code CANNOT_REBUILD_UNLOCKED_DEPS
+    — redeploy them from source ('run402 functions deploy') to refresh instead.
+
+Notes:
+  - Run 'run402 doctor' to see which functions are on a stale runtime.
+
+Examples:
+  run402 functions rebuild prj_abc123 stripe-webhook
+  run402 functions rebuild prj_abc123 --all
 `,
   list: `run402 functions list — List all functions for a project
 
@@ -418,6 +466,85 @@ async function update(projectId, name, args) {
   }
 }
 
+const UNLOCKED_DEPS_HINT =
+  "Function was deployed before dependency locking — redeploy from source " +
+  "(run402 functions deploy <id> <name> --file <file>) to refresh its runtime instead.";
+
+// Annotate a `rebuild --all` batch with an actionable hint on per-function
+// CANNOT_REBUILD_UNLOCKED_DEPS refusals. The batch endpoint returns 200 with
+// per-function outcomes (failures never abort the batch), so these arrive as
+// data, not a thrown error.
+function annotateRebuildBatch(data) {
+  if (!data || !Array.isArray(data.results)) return data;
+  return {
+    ...data,
+    results: data.results.map((entry) =>
+      entry && entry.rebuilt === false && entry.code === "CANNOT_REBUILD_UNLOCKED_DEPS"
+        ? { ...entry, hint: UNLOCKED_DEPS_HINT }
+        : entry,
+    ),
+  };
+}
+
+async function rebuild(projectId, args = []) {
+  assertRequiredProject(projectId, "run402 functions rebuild <project_id> [<name>] [--all]");
+  assertKnownFlags(args, ["--all", "--help", "-h"]);
+  let all = false;
+  const positionals = [];
+  for (const arg of args) {
+    if (arg === "--all") { all = true; continue; }
+    positionals.push(arg);
+  }
+  if (positionals.length > 1) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Unexpected argument: ${positionals[1]}`,
+      hint: "run402 functions rebuild <project_id> [<name>] [--all]",
+      details: { argument: positionals[1] },
+    });
+  }
+  const name = positionals[0];
+  if (all && name) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Pass either <name> or --all, not both.",
+      hint: "run402 functions rebuild <project_id> [<name>] [--all]",
+    });
+  }
+  if (!all && !name) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Provide a function <name>, or pass --all to rebuild every function in the project.",
+      hint: "run402 functions rebuild <project_id> [<name>] [--all]",
+    });
+  }
+
+  try {
+    if (all) {
+      const data = await getSdk().functions.rebuildAll(projectId);
+      console.log(JSON.stringify(annotateRebuildBatch(data), null, 2));
+    } else {
+      const data = await getSdk().functions.rebuild(projectId, name);
+      console.log(JSON.stringify(data, null, 2));
+    }
+  } catch (err) {
+    // Map the single-function unlocked-deps refusal to a clear, actionable
+    // envelope. The gateway returns 409 with code CANNOT_REBUILD_UNLOCKED_DEPS
+    // for functions deployed before dependency locking.
+    if (err?.status === 409 && err?.body && typeof err.body === "object" && err.body.code === "CANNOT_REBUILD_UNLOCKED_DEPS") {
+      fail({
+        code: "CANNOT_REBUILD_UNLOCKED_DEPS",
+        message: err.body.error || err.body.message || "Function was deployed before dependency locking.",
+        hint: UNLOCKED_DEPS_HINT,
+        next_actions: [`run402 functions deploy ${projectId} ${name} --file <file>`],
+        retryable: false,
+        safe_to_retry: false,
+      });
+    }
+    reportSdkError(err);
+  }
+}
+
 async function list(projectId, args = []) {
   assertRequiredProject(projectId, "run402 functions list <project_id>");
   assertKnownFlags(args, ["--help", "-h"]);
@@ -454,6 +581,7 @@ export async function run(sub, args) {
     case "invoke": await invoke(args[0], args[1], args.slice(2)); break;
     case "logs":   await logs(args[0], args[1], args.slice(2)); break;
     case "update": await update(args[0], args[1], args.slice(2)); break;
+    case "rebuild": await rebuild(args[0], args.slice(1)); break;
     case "list":   await list(args[0], args.slice(1)); break;
     case "delete": await deleteFunction(args[0], args[1], args.slice(2)); break;
     default:

package/lib/init.mjs

@@ -1,4 +1,4 @@
-import { readAllowance, saveAllowance, loadKeyStore, CONFIG_DIR } from "./config.mjs";
+import { readAllowance, saveAllowance, loadKeyStore, configDir } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { fail } from "./sdk-errors.mjs";
 import { mkdirSync } from "fs";
@@ -64,6 +64,10 @@ export async function run(args = []) {
 
   if (args.includes("--help") || args.includes("-h")) { console.log(HELP); process.exit(0); }
 
+  // Resolve once for this invocation — reflects the active wallet/profile that
+  // cli.mjs published to RUN402_WALLET before this module loaded.
+  const CONFIG_DIR = configDir();
+
   const isMpp = args[0] === "mpp";
   const requestedRail = isMpp ? "mpp" : "x402";
   const switchRailConfirmed = args.includes("--switch-rail");

package/lib/status.mjs

@@ -1,6 +1,8 @@
 import { readAllowance, loadKeyStore, getActiveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { assertKnownFlags, hasHelp, normalizeArgv } from "./argparse.mjs";
+import { getActiveProfile } from "../core-dist/config.js";
+import { readMeta } from "../core-dist/profiles.js";
 
 const HELP = `run402 status — Show full account state in one shot
 
@@ -104,7 +106,18 @@ export async function run(args = []) {
     ? remote.projects.map(normalizeProject)
     : Object.keys(store.projects).map(id => ({ project_id: id }));
 
+  // Which named wallet this state belongs to. `name` is the active profile
+  // (default for single-wallet installs); `label` is the cached server-side
+  // display name (null until set / when offline).
+  const walletName = getActiveProfile();
+  const walletMeta = readMeta(walletName);
+
   const result = {
+    wallet: {
+      name: walletName,
+      address: allowance.address,
+      label: walletMeta?.label ?? null,
+    },
     allowance: {
       address: allowance.address,
       funded: allowance.funded || false,

package/lib/wallet-context.mjs

@@ -0,0 +1,223 @@
+/**
+ * Active-wallet (profile) resolution for the CLI edge.
+ *
+ * Runs at the top of cli.mjs BEFORE any subcommand module (and therefore
+ * before cli/lib/config.mjs snapshots its paths) is loaded. Resolves which
+ * named wallet a command operates on, sets `process.env.RUN402_WALLET` so all
+ * core path functions resolve under it, and emits a provenance line for
+ * non-default selections. Core itself stays env-only — the `--wallet` flag and
+ * the per-directory `.run402.json` binding are translated into the env var
+ * here, at the edge.
+ *
+ * Precedence (highest first):
+ *   1. --wallet <name> / --profile <name>   (flag)
+ *   2. RUN402_WALLET / RUN402_PROFILE        (env)
+ *   3. nearest .run402.local.json/.run402.json (directory binding, walk up)
+ *   4. config.json active_wallet              (global `wallets use`)
+ *   5. "default"                              (root wallet)
+ *
+ * The flag is also the conflict resolver: when env and binding name different
+ * wallets and no flag is given, that is a hard error (not a silent pick).
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname, resolve } 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";
+
+const DEFAULT = "default";
+const GLOBAL_FLAGS = new Set(["--wallet", "--profile"]);
+// The `wallets` group is the management + escape surface — it must work even
+// when selection is ambiguous (so you can `wallets unbind`), and it validates
+// its own positional targets. `init` creates wallets, so it must not fail
+// closed on a not-yet-existing name.
+const CONFLICT_EXEMPT = new Set(["wallets"]);
+const EXISTENCE_EXEMPT = new Set(["wallets", "init"]);
+
+/**
+ * Split the global --wallet/--profile flag (and its value) out of argv so the
+ * subcommand never sees it. Pure: no core imports, no side effects. Returns
+ * the cleaned argv and the selected flag (`{ flag, value }` or null). Last
+ * occurrence wins. A missing value is left as `value: undefined` for
+ * resolveWallet to reject with a precise error.
+ */
+export function splitWalletFlag(rawArgv = []) {
+  const argv = [];
+  let flag = null;
+  for (let i = 0; i < rawArgv.length; i++) {
+    const a = rawArgv[i];
+    if (typeof a === "string" && a.startsWith("--") && a.includes("=")) {
+      const name = a.slice(0, a.indexOf("="));
+      if (GLOBAL_FLAGS.has(name)) {
+        flag = { flag: name, value: a.slice(a.indexOf("=") + 1) };
+        continue;
+      }
+    }
+    if (typeof a === "string" && GLOBAL_FLAGS.has(a)) {
+      const next = rawArgv[i + 1];
+      if (next === undefined || (typeof next === "string" && next.startsWith("-"))) {
+        flag = { flag: a, value: undefined };
+      } else {
+        flag = { flag: a, value: next };
+        i += 1;
+      }
+      continue;
+    }
+    argv.push(a);
+  }
+  return { argv, walletFlag: flag };
+}
+
+function readBindingFrom(dir) {
+  // .run402.local.json (gitignored personal override) beats .run402.json.
+  for (const fname of [".run402.local.json", ".run402.json"]) {
+    const p = join(dir, fname);
+    try {
+      const parsed = JSON.parse(readFileSync(p, "utf8"));
+      const w = parsed?.wallet;
+      if (typeof w === "string" && w.trim()) return { wallet: w.trim(), file: p };
+    } catch {
+      /* missing / unreadable / malformed → skip */
+    }
+  }
+  return null;
+}
+
+/** Nearest binding walking up from `startDir` to the filesystem root. */
+export function findBinding(startDir) {
+  let dir = resolve(startDir);
+  for (;;) {
+    const b = readBindingFrom(dir);
+    if (b) return b;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function assertValidName(name, origin) {
+  if (name === DEFAULT || isValidProfileName(name)) return;
+  fail({
+    code: "BAD_WALLET_NAME",
+    message: `Invalid wallet name ${JSON.stringify(name)} (from ${origin}).`,
+    hint: "Wallet names must match /^[a-z0-9][a-z0-9_-]{0,63}$/ (lowercase letters, digits, '_' and '-').",
+    details: { name, origin },
+  });
+}
+
+/** Pure precedence resolution + conflict detection. Returns { name, source, sourceDetail }. */
+export function resolveWallet({ walletFlag, env = {}, cwd = process.cwd(), cmd } = {}) {
+  if (walletFlag) {
+    if (walletFlag.value === undefined || walletFlag.value === "") {
+      fail({ code: "BAD_FLAG", message: `${walletFlag.flag} requires a value`, details: { flag: walletFlag.flag } });
+    }
+    assertValidName(walletFlag.value, walletFlag.flag);
+    return { name: walletFlag.value, source: "flag", sourceDetail: walletFlag.flag };
+  }
+
+  const envRaw = env.RUN402_WALLET ?? env.RUN402_PROFILE;
+  const envName = typeof envRaw === "string" && envRaw.trim() ? envRaw.trim() : null;
+  const binding = findBinding(cwd);
+
+  if (envName && binding && envName !== binding.wallet && !CONFLICT_EXEMPT.has(cmd)) {
+    fail({
+      code: "WALLET_SELECTION_CONFLICT",
+      message: `Ambiguous wallet: RUN402_WALLET=${envName} but ${binding.file} selects '${binding.wallet}'.`,
+      hint: "Resolve with one of: pass --wallet <name>, unset RUN402_WALLET, or run402 wallets unbind.",
+      details: { env_wallet: envName, binding_wallet: binding.wallet, binding_file: binding.file },
+    });
+  }
+
+  if (envName) {
+    assertValidName(envName, "RUN402_WALLET");
+    return { name: envName, source: "env", sourceDetail: "RUN402_WALLET" };
+  }
+  if (binding) {
+    assertValidName(binding.wallet, binding.file);
+    return { name: binding.wallet, source: "binding", sourceDetail: binding.file };
+  }
+  const def = getDefaultWallet();
+  if (def && def !== DEFAULT) return { name: def, source: "config", sourceDetail: "wallets use" };
+  return { name: DEFAULT, source: "default", sourceDetail: null };
+}
+
+function looksLikeAddress(s) {
+  return typeof s === "string" && /^0x[a-fA-F0-9]{40}$/.test(s);
+}
+
+/** Fail closed when a non-default selection names a wallet that does not exist locally. */
+export function enforceWalletExists({ name, source }, cmd) {
+  if (name === DEFAULT) return;
+  if (EXISTENCE_EXEMPT.has(cmd)) return;
+  if (profileExists(name)) return;
+  const hint = looksLikeAddress(name)
+    ? `'${name}' looks like an address. For billing use: run402 billing ... --wallet-address ${name}`
+    : `Run 'run402 wallets list' to see wallets, or 'run402 wallets new ${name}' to create it.`;
+  fail({
+    code: "WALLET_NOT_FOUND",
+    message: `No local wallet named '${name}'.`,
+    hint,
+    details: { wallet: name, source },
+  });
+}
+
+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. */
+function walletAddress(name) {
+  const meta = readMeta(name);
+  if (meta?.address) return meta.address;
+  try {
+    return readAllowance(join(profileDir(name), "allowance.json"))?.address ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Emit the stderr provenance line for non-default selections (silent for default). */
+export function emitProvenance({ name, source, sourceDetail }, { cmd, quiet } = {}) {
+  if (quiet) return;
+  if (name === DEFAULT) return;
+  if (cmd === "wallets") return; // the wallets group reports its own context
+  const where =
+    source === "env" ? "RUN402_WALLET" :
+    source === "config" ? "wallets use" :
+    sourceDetail || source;
+  const addr = walletAddress(name);
+  const addrPart = addr ? ` (${shortAddr(addr)})` : "";
+  process.stderr.write(`  ↪ wallet: ${name}${addrPart}   ← ${where}\n`);
+}
+
+/**
+ * Orchestrate edge resolution: resolve → fail-closed → publish to the env so
+ * core paths resolve → provenance. Returns the resolved selection.
+ */
+export function applyWalletSelection({ walletFlag, cmd, cwd = process.cwd(), env = process.env, quiet = false } = {}) {
+  // Capture the pre-resolution signals so `wallets current` can report
+  // provenance and any env-vs-binding divergence (it can't recompute them once
+  // we overwrite RUN402_WALLET below).
+  const envRaw = env.RUN402_WALLET ?? env.RUN402_PROFILE;
+  const envName = typeof envRaw === "string" && envRaw.trim() ? envRaw.trim() : null;
+  const binding = findBinding(cwd);
+
+  const resolved = resolveWallet({ walletFlag, env, cwd, cmd });
+  enforceWalletExists(resolved, cmd);
+
+  // Publish to the env so all core path functions resolve under this wallet.
+  env.RUN402_WALLET = resolved.name;
+  env.RUN402_ACTIVE_WALLET_JSON = JSON.stringify({
+    name: resolved.name,
+    source: resolved.source,
+    sourceDetail: resolved.sourceDetail,
+    binding: binding ? { wallet: binding.wallet, file: binding.file } : null,
+    envName,
+    diverged: !!(envName && binding && envName !== binding.wallet),
+  });
+
+  emitProvenance(resolved, { cmd, quiet });
+  return resolved;
+}

package/lib/wallet-context.test.mjs

@@ -0,0 +1,228 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import {
+  splitWalletFlag,
+  findBinding,
+  resolveWallet,
+  enforceWalletExists,
+  emitProvenance,
+} from "./wallet-context.mjs";
+import { ensureProfileDir, setDefaultWallet } from "../core-dist/profiles.js";
+
+const origConfigDir = process.env.RUN402_CONFIG_DIR;
+let tmp;
+
+beforeEach(() => {
+  tmp = mkdtempSync(join(tmpdir(), "wallet-ctx-"));
+  process.env.RUN402_CONFIG_DIR = tmp;
+});
+
+afterEach(() => {
+  rmSync(tmp, { recursive: true, force: true });
+  if (origConfigDir !== undefined) process.env.RUN402_CONFIG_DIR = origConfigDir;
+  else delete process.env.RUN402_CONFIG_DIR;
+});
+
+// Capture a fail() invocation: fail() does console.error(envelope) + process.exit.
+function captureFail(fn) {
+  const origExit = process.exit;
+  const origErr = console.error;
+  let envelope = null;
+  let exited = false;
+  console.error = (s) => { try { envelope = JSON.parse(s); } catch { envelope = s; } };
+  process.exit = () => { exited = true; throw new Error("__EXIT__"); };
+  try {
+    fn();
+  } catch (e) {
+    if (!String(e?.message).startsWith("__EXIT__")) throw e;
+  } finally {
+    process.exit = origExit;
+    console.error = origErr;
+  }
+  return { envelope, exited };
+}
+
+function bindingDir(wallet, localWallet) {
+  const dir = mkdtempSync(join(tmpdir(), "binding-"));
+  if (wallet) writeFileSync(join(dir, ".run402.json"), JSON.stringify({ wallet }));
+  if (localWallet) writeFileSync(join(dir, ".run402.local.json"), JSON.stringify({ wallet: localWallet }));
+  return dir;
+}
+
+describe("splitWalletFlag", () => {
+  it("passes through argv with no global flag", () => {
+    assert.deepEqual(splitWalletFlag(["status"]), { argv: ["status"], walletFlag: null });
+  });
+  it("strips --wallet <value>", () => {
+    const r = splitWalletFlag(["--wallet", "kychon", "status"]);
+    assert.deepEqual(r.argv, ["status"]);
+    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"]);
+    assert.equal(r.walletFlag.value, "foo");
+  });
+  it("accepts --profile as an alias", () => {
+    const r = splitWalletFlag(["--profile", "p", "status"]);
+    assert.equal(r.walletFlag.flag, "--profile");
+    assert.equal(r.walletFlag.value, "p");
+  });
+  it("last occurrence wins", () => {
+    const r = splitWalletFlag(["--wallet", "a", "--wallet", "b", "status"]);
+    assert.equal(r.walletFlag.value, "b");
+    assert.deepEqual(r.argv, ["status"]);
+  });
+  it("records a missing value as undefined", () => {
+    const r = splitWalletFlag(["status", "--wallet"]);
+    assert.deepEqual(r.argv, ["status"]);
+    assert.equal(r.walletFlag.value, undefined);
+  });
+});
+
+describe("findBinding", () => {
+  it("finds the nearest .run402.json walking up", () => {
+    const root = bindingDir("client-a");
+    const sub = join(root, "api");
+    mkdirSync(sub);
+    const b = findBinding(sub);
+    assert.equal(b.wallet, "client-a");
+    rmSync(root, { recursive: true, force: true });
+  });
+  it(".run402.local.json overrides .run402.json in the same dir", () => {
+    const dir = bindingDir("client-a", "client-a-staging");
+    assert.equal(findBinding(dir).wallet, "client-a-staging");
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("returns null when no binding exists in the tree", () => {
+    const dir = mkdtempSync(join(tmpdir(), "nobind-"));
+    assert.equal(findBinding(dir), null);
+    rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+describe("resolveWallet — precedence", () => {
+  it("flag beats everything", () => {
+    const dir = bindingDir("client-a");
+    const r = resolveWallet({ walletFlag: { flag: "--wallet", value: "kychon" }, env: { RUN402_WALLET: "personal" }, cwd: dir, cmd: "status" });
+    assert.equal(r.name, "kychon");
+    assert.equal(r.source, "flag");
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("env beats binding when they agree is moot; env returned when no binding", () => {
+    const dir = mkdtempSync(join(tmpdir(), "nobind-"));
+    const r = resolveWallet({ env: { RUN402_WALLET: "kychon" }, cwd: dir, cmd: "status" });
+    assert.equal(r.name, "kychon");
+    assert.equal(r.source, "env");
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("binding used when no flag/env", () => {
+    const dir = bindingDir("client-a");
+    const r = resolveWallet({ env: {}, cwd: dir, cmd: "status" });
+    assert.equal(r.name, "client-a");
+    assert.equal(r.source, "binding");
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("global default (wallets use) applies when no flag/env/binding", () => {
+    setDefaultWallet("kychon");
+    const dir = mkdtempSync(join(tmpdir(), "nobind-"));
+    const r = resolveWallet({ env: {}, cwd: dir, cmd: "status" });
+    assert.equal(r.name, "kychon");
+    assert.equal(r.source, "config");
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("falls back to default when nothing selects", () => {
+    const dir = mkdtempSync(join(tmpdir(), "nobind-"));
+    const r = resolveWallet({ env: {}, cwd: dir, cmd: "status" });
+    assert.equal(r.name, "default");
+    assert.equal(r.source, "default");
+    rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+describe("resolveWallet — conflict + validation", () => {
+  it("env vs binding mismatch is a hard error (non-wallets command)", () => {
+    const dir = bindingDir("client-a");
+    const { envelope, exited } = captureFail(() =>
+      resolveWallet({ env: { RUN402_WALLET: "personal" }, cwd: dir, cmd: "deploy" }));
+    assert.ok(exited);
+    assert.equal(envelope.code, "WALLET_SELECTION_CONFLICT");
+    assert.match(envelope.message, /personal/);
+    assert.match(envelope.message, /client-a/);
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("matching env and binding proceed without error", () => {
+    const dir = bindingDir("client-a");
+    const r = resolveWallet({ env: { RUN402_WALLET: "client-a" }, cwd: dir, cmd: "deploy" });
+    assert.equal(r.name, "client-a");
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("the wallets group is exempt from the conflict error", () => {
+    const dir = bindingDir("client-a");
+    const r = resolveWallet({ env: { RUN402_WALLET: "personal" }, cwd: dir, cmd: "wallets" });
+    assert.equal(r.name, "personal"); // env still wins; no error
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("rejects an invalid wallet name", () => {
+    const dir = mkdtempSync(join(tmpdir(), "nobind-"));
+    const { envelope } = captureFail(() =>
+      resolveWallet({ env: { RUN402_WALLET: "../evil" }, cwd: dir, cmd: "status" }));
+    assert.equal(envelope.code, "BAD_WALLET_NAME");
+    rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+describe("enforceWalletExists — fail closed", () => {
+  it("no-op for default", () => {
+    assert.doesNotThrow(() => enforceWalletExists({ name: "default", source: "default" }, "deploy"));
+  });
+  it("no-op for an existing wallet", () => {
+    ensureProfileDir("client-a");
+    writeFileSync(join(tmp, "profiles", "client-a", "allowance.json"), "{}");
+    assert.doesNotThrow(() => enforceWalletExists({ name: "client-a", source: "binding" }, "deploy"));
+  });
+  it("fails closed for a missing wallet on a normal command", () => {
+    const { envelope, exited } = captureFail(() =>
+      enforceWalletExists({ name: "ghost", source: "binding" }, "deploy"));
+    assert.ok(exited);
+    assert.equal(envelope.code, "WALLET_NOT_FOUND");
+  });
+  it("wallets + init are exempt (create paths)", () => {
+    assert.doesNotThrow(() => enforceWalletExists({ name: "ghost", source: "flag" }, "wallets"));
+    assert.doesNotThrow(() => enforceWalletExists({ name: "ghost", source: "flag" }, "init"));
+  });
+  it("address-looking name hints at billing --wallet-address", () => {
+    const { envelope } = captureFail(() =>
+      enforceWalletExists({ name: "0x" + "a".repeat(40), source: "flag" }, "deploy"));
+    assert.match(envelope.hint, /--wallet-address/);
+  });
+});
+
+describe("emitProvenance", () => {
+  function captureStderr(fn) {
+    const orig = process.stderr.write.bind(process.stderr);
+    let out = "";
+    process.stderr.write = (c) => { out += typeof c === "string" ? c : Buffer.from(c).toString("utf8"); return true; };
+    try { fn(); } finally { process.stderr.write = orig; }
+    return out;
+  }
+  it("stays silent for the default wallet", () => {
+    assert.equal(captureStderr(() => emitProvenance({ name: "default", source: "default" }, { cmd: "status" })), "");
+  });
+  it("emits a provenance line for a named wallet", () => {
+    ensureProfileDir("kychon");
+    writeFileSync(join(tmp, "profiles", "kychon", "meta.json"), JSON.stringify({ name: "kychon", address: "0x1234567890abcdef" }));
+    const out = captureStderr(() => emitProvenance({ name: "kychon", source: "env", sourceDetail: "RUN402_WALLET" }, { cmd: "status" }));
+    assert.match(out, /wallet: kychon/);
+    assert.match(out, /RUN402_WALLET/);
+  });
+  it("honors --quiet", () => {
+    assert.equal(captureStderr(() => emitProvenance({ name: "kychon", source: "env" }, { cmd: "status", quiet: true })), "");
+  });
+  it("stays silent for the wallets group", () => {
+    assert.equal(captureStderr(() => emitProvenance({ name: "kychon", source: "flag" }, { cmd: "wallets" })), "");
+  });
+});