run402 3.7.5 → 3.7.7

package/README.md

@@ -103,7 +103,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Deploy to run402
-        run: npx --yes run402@1.60.0 deploy apply --manifest 'run402.deploy.json' --project 'prj_...'
+        run: npx --yes run402@3.7.5 deploy apply --manifest 'run402.deploy.json' --project 'prj_...'
 ```
 
 CI deploys can ship `site`, `functions`, `database`, and absent/current `base` changes. Route declarations are allowed only when the binding was linked with covering `--route-scope` patterns (`/admin` exact, `/api/*` final wildcard); no scopes means no CI route authority. Keep secrets, domains, subdomains, checks, non-current base changes, and out-of-scope routes in a local `run402 deploy apply` where the full allowance-backed authority is present.
@@ -138,7 +138,7 @@ run402 functions rebuild <id> --all      # refresh every function in the project
 Functions run on Node 22 with `@run402/functions` auto-bundled. Inside the handler:
 
 ```ts
-import { db, adminDb, getUser, email, ai } from "@run402/functions";
+import { db, adminDb, auth, email, ai } from "@run402/functions";
 ```
 
 `db(req)` is the caller-context client (RLS applies); `adminDb()` bypasses RLS for platform-authored writes.
@@ -266,14 +266,15 @@ Same content also at [`cli/llms-cli.txt`](./llms-cli.txt) in the repo. Treat tha
 
 ## Other interfaces
 
-`run402` is one of five surfaces:
+`run402` is one of the public Run402 surfaces:
 
 - [`@run402/sdk`](https://www.npmjs.com/package/@run402/sdk) — typed TypeScript client (isomorphic + Node entry)
 - [`run402-mcp`](https://www.npmjs.com/package/run402-mcp) — MCP server (Claude Desktop, Cursor, Cline, Claude Code)
 - [`@run402/functions`](https://www.npmjs.com/package/@run402/functions) — in-function helper imported inside deployed functions
+- [`@run402/astro`](https://www.npmjs.com/package/@run402/astro) — Astro SSR, ISR cache, hosted auth, and image integration
 - OpenClaw skill — script-based skill for OpenClaw agents
 
-All five release in lockstep at the same version and share `@run402/sdk` as the kernel.
+The in-repo packages `run402`, `run402-mcp`, and `@run402/sdk` release in lockstep. `@run402/astro` and `@run402/functions` publish on their own cadences.
 
 ## License
 

package/cli.mjs

@@ -344,9 +344,14 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
-  default:
-    console.error(`Unknown command: ${cmd}\n`);
-    console.log(HELP);
-    process.exit(1);
+  default: {
+    const { fail } = await import("./lib/sdk-errors.mjs");
+    fail({
+      code: "UNKNOWN_COMMAND",
+      message: `Unknown command: ${cmd}`,
+      hint: "Run `run402 --help` for the command list.",
+      details: { command: cmd },
+    });
+  }
 }
 }

package/lib/admin.mjs

@@ -192,8 +192,6 @@ export async function run(sub, args) {
     case "archive":         await archive(args); break;
     case "reactivate":      await reactivate(args); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown admin subcommand: ${sub}`, hint: "Run `run402 admin --help` for usage.", details: { command: "admin", subcommand: sub } });
   }
 }

package/lib/agent.mjs

@@ -201,8 +201,6 @@ export async function run(sub, args) {
       await passkey(args);
       return;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown agent subcommand: ${sub}`, hint: "Run `run402 agent --help` for usage.", details: { command: "agent", subcommand: sub } });
   }
 }

package/lib/ai.mjs

@@ -230,8 +230,6 @@ export async function run(sub, args) {
     case "moderate":  await moderate(args); break;
     case "usage":     await usage(args); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown ai subcommand: ${sub}`, hint: "Run `run402 ai --help` for usage.", details: { command: "ai", subcommand: sub } });
   }
 }

package/lib/allowance.mjs

@@ -337,8 +337,6 @@ export async function run(sub, args) {
     case "checkout": await checkout(args); break;
     case "history":  await history(args); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown allowance subcommand: ${sub}`, hint: "Run `run402 allowance --help` for usage.", details: { command: "allowance", subcommand: sub } });
   }
 }

package/lib/apps.mjs

@@ -312,8 +312,6 @@ export async function run(sub, args) {
     case "update":   await update(args[0], args[1], args.slice(2)); break;
     case "delete":   await deleteVersion(args[0], args[1], args.slice(2)); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown apps subcommand: ${sub}`, hint: "Run `run402 apps --help` for usage.", details: { command: "apps", subcommand: sub } });
   }
 }

package/lib/assets.mjs

@@ -683,8 +683,6 @@ export async function run(sub, args) {
     case "sign":     await sign(defaultProject, args); break;
     case "diagnose": await diagnose(defaultProject, args); break;
     default:
-      console.error(`Unknown subcommand: ${sub}`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown assets subcommand: ${sub}`, hint: "Run `run402 assets --help` for usage.", details: { command: "assets", subcommand: sub } });
   }
 }

package/lib/auth.mjs

@@ -757,8 +757,6 @@ export async function run(sub, args) {
     case "providers": await providers(args); break;
     case "scaffold-roles": scaffoldRoles(args); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown auth subcommand: ${sub}`, hint: "Run `run402 auth --help` for usage.", details: { command: "auth", subcommand: sub } });
   }
 }

package/lib/billing.mjs

@@ -355,8 +355,6 @@ export async function run(sub, args) {
     case "balance": await balance(args); break;
     case "history": await history(args); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown billing subcommand: ${sub}`, hint: "Run `run402 billing --help` for usage.", details: { command: "billing", subcommand: sub } });
   }
 }

package/lib/cdn.mjs

@@ -135,8 +135,6 @@ export async function run(sub, args) {
       await waitFresh(defaultProject, args);
       break;
     default:
-      console.error(`Unknown subcommand: ${sub}`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown cdn subcommand: ${sub}`, hint: "Run `run402 cdn --help` for usage.", details: { command: "cdn", subcommand: sub } });
   }
 }

package/lib/ci.mjs

@@ -457,8 +457,6 @@ export async function run(sub, args) {
     case "revoke": await revoke(args); break;
     case "set-asset-scopes": await setAssetScopes(args); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown ci subcommand: ${sub}`, hint: "Run `run402 ci --help` for usage.", details: { command: "ci", subcommand: sub } });
   }
 }

package/lib/contracts.mjs

@@ -483,8 +483,6 @@ export async function run(sub, args) {
     case "drain":            await drain(args[0], args[1], args.slice(2)); break;
     case "delete":           await deleteSigner(args[0], args[1], args.slice(2)); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown contracts subcommand: ${sub}`, hint: "Run `run402 contracts --help` for usage.", details: { command: "contracts", subcommand: sub } });
   }
 }

package/lib/domains.mjs

@@ -208,8 +208,6 @@ export async function run(sub, args) {
     case "status": await status(args); break;
     case "delete": await deleteDomain(args); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown domains subcommand: ${sub}`, hint: "Run `run402 domains --help` for usage.", details: { command: "domains", subcommand: sub } });
   }
 }

package/lib/email.mjs

@@ -791,8 +791,6 @@ export async function run(sub, args) {
       break;
     }
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown email subcommand: ${sub}`, hint: "Run `run402 email --help` for usage.", details: { command: "email", subcommand: sub } });
   }
 }

package/lib/functions.mjs

@@ -823,9 +823,7 @@ export async function run(sub, args) {
     case "list":   await list(args[0], args.slice(1)); break;
     case "delete": await deleteFunction(args[0], args[1], args.slice(2)); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown functions subcommand: ${sub}`, hint: "Run `run402 functions --help` for usage.", details: { command: "functions", subcommand: sub } });
   }
 }
 

package/lib/grants.mjs

@@ -1,5 +1,5 @@
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError, parseFlagJson } from "./sdk-errors.mjs";
+import { reportSdkError, parseFlagJson, fail } from "./sdk-errors.mjs";
 import {
   normalizeArgv,
   assertKnownFlags,
@@ -110,8 +110,6 @@ export async function run(sub, args) {
     case "create": await create(args); break;
     case "revoke": await revoke(args); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown grants subcommand: ${sub}`, hint: "Run `run402 grants --help` for usage.", details: { command: "grants", subcommand: sub } });
   }
 }

package/lib/image.mjs

@@ -67,9 +67,7 @@ export async function run(sub, args) {
   }
 
   if (sub !== "generate") {
-    console.error(`Unknown subcommand: ${sub}\n`);
-    console.log(HELP);
-    process.exit(1);
+    fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown image subcommand: ${sub}`, hint: "Run `run402 image --help` for usage.", details: { command: "image", subcommand: sub } });
   }
 
   const parsedArgs = normalizeArgv(args);

package/lib/jobs.mjs

@@ -421,9 +421,7 @@ async function artifacts(args = []) {
     await artifactsGet(args.slice(1));
     return;
   }
-  console.error(`Unknown jobs artifacts action: ${action}\n`);
-  console.log(SUB_HELP.artifacts);
-  process.exit(1);
+  fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown jobs artifacts action: ${action}`, hint: "Run `run402 jobs artifacts --help` for usage.", details: { command: "jobs artifacts", subcommand: action } });
 }
 
 function splitJobIdArg(args = [], valueFlags = []) {
@@ -486,8 +484,6 @@ export async function run(sub, args = []) {
       await purge(args);
       break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown jobs subcommand: ${sub}`, hint: "Run `run402 jobs --help` for usage.", details: { command: "jobs", subcommand: sub } });
   }
 }

package/lib/message.mjs

@@ -84,9 +84,7 @@ export async function run(sub, args) {
     process.exit(0);
   }
   if (sub !== "send") {
-    console.error(`Unknown subcommand: ${sub}\n`);
-    console.log(HELP);
-    process.exit(1);
+    fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown message subcommand: ${sub}`, hint: "Run `run402 message --help` for usage.", details: { command: "message", subcommand: sub } });
   }
   const parsedArgs = normalizeArgv(args);
   assertKnownFlags(parsedArgs, ["--help", "-h"]);

package/lib/org.mjs

@@ -396,8 +396,6 @@ export async function run(sub, args) {
     case "whoami": await whoami(args); break;
     case "audit": await audit(args); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown org subcommand: ${sub}`, hint: "Run `run402 org --help` for usage.", details: { command: "org", subcommand: sub } });
   }
 }

package/lib/projects.mjs

@@ -810,8 +810,6 @@ export async function run(sub, args) {
     case "promote-user": { const { projectId, rest } = resolvePositionalProject(args); await promoteUser(projectId, rest[0]); break; }
     case "demote-user":  { const { projectId, rest } = resolvePositionalProject(args); await demoteUser(projectId, rest[0]); break; }
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown projects subcommand: ${sub}`, hint: "Run `run402 projects --help` for usage.", details: { command: "projects", subcommand: sub } });
   }
 }

package/lib/secrets.mjs

@@ -218,8 +218,6 @@ export async function run(sub, args) {
     case "list":   await list(args[0], args.slice(1)); break;
     case "delete": await deleteSecret(args[0], args[1], args.slice(2)); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown secrets subcommand: ${sub}`, hint: "Run `run402 secrets --help` for usage.", details: { command: "secrets", subcommand: sub } });
   }
 }

package/lib/sender-domain.mjs

@@ -209,8 +209,6 @@ export async function run(sub, args) {
     case "inbound-enable": await inboundToggle("enable", args); break;
     case "inbound-disable": await inboundToggle("disable", args); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown sender-domain subcommand: ${sub}`, hint: "Run `run402 sender-domain --help` for usage.", details: { command: "sender-domain", subcommand: sub } });
   }
 }

package/lib/service.mjs

@@ -1,5 +1,5 @@
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 service — Run402 service health and availability
 
@@ -70,8 +70,6 @@ export async function run(sub, args) {
     case "status": await status(); break;
     case "health": await health(); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown service subcommand: ${sub}`, hint: "Run `run402 service --help` for usage.", details: { command: "service", subcommand: sub } });
   }
 }

package/lib/sites.mjs

@@ -364,8 +364,6 @@ export async function run(sub, args) {
     case "deploy":      await deploy(args); break;
     case "deploy-dir":  await deployDir(args); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown sites subcommand: ${sub}`, hint: "Run `run402 sites --help` for usage.", details: { command: "sites", subcommand: sub } });
   }
 }

package/lib/status.mjs

@@ -14,7 +14,7 @@ import { readMeta } from "../core-dist/profiles.js";
 const HELP = `run402 status — Show full organization state in one shot
 
 Usage:
-  run402 status
+  run402 status [--json]
 
 Displays:
   - Wallet identity (local_label, server_label, address)
@@ -25,8 +25,9 @@ Displays:
   - Active project ID
   - Active API target
 
-Output is JSON. Run402 Cloud status requires an allowance; Core target status
-can still report local project state without one.
+Output is JSON by default. --json is accepted as a compatibility no-op.
+Run402 Cloud status requires an allowance; Core target status can still report
+local project state without one.
 `;
 
 // USDC / pathUSD constants (match allowance.mjs)
@@ -89,7 +90,7 @@ function normalizeProject(raw) {
 export async function run(args = []) {
   args = normalizeArgv(args);
   if (hasHelp(args)) { console.log(HELP); process.exit(0); }
-  assertKnownFlags(args, ["--help", "-h"]);
+  assertKnownFlags(args, ["--help", "-h", "--json"]);
   const allowance = readAllowance();
   const target = {
     api_base: apiBase(),

package/lib/subdomains.mjs

@@ -197,8 +197,6 @@ export async function run(sub, args) {
     case "delete": await deleteSubdomain(args); break;
     case "list":   await list(args); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown subdomains subcommand: ${sub}`, hint: "Run `run402 subdomains --help` for usage.", details: { command: "subdomains", subcommand: sub } });
   }
 }

package/lib/tier.mjs

@@ -160,8 +160,6 @@ export async function run(sub, args) {
     case "status": await status(args); break;
     case "set":    await set(args); break;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown tier subcommand: ${sub}`, hint: "Run `run402 tier --help` for usage.", details: { command: "tier", subcommand: sub } });
   }
 }

package/lib/transfer.mjs

@@ -391,8 +391,6 @@ export async function run(sub, args) {
       await cancel(args);
       return;
     default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown transfer subcommand: ${sub}`, hint: "Run `run402 transfer --help` for usage.", details: { command: "transfer", subcommand: sub } });
   }
 }

package/lib/up.mjs

@@ -7,7 +7,7 @@ import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs } from "./ar
 const HELP = `run402 up — Provision/link/deploy the current app
 
 Usage:
-  run402 up [repo-or-path] [--name <name>] [--project <id>] [--manifest <path>] [--dir <path>] [--tier <tier>] [-y|--yes] [--check|--print-spec|--plan|--require-plan <id>] [--json|--json-stream] [--quiet]
+  run402 up [repo-or-path] [--name <name>] [--project <id>] [--manifest <path>] [--dir <path>] [--tier <tier>] [-y|--yes] [--check|--print-spec|--plan|--require-plan <id>] [--human|--json-stream] [--quiet]
 
 Options:
   repo-or-path        Local app directory or public Git repository URL. Defaults
@@ -15,8 +15,8 @@ Options:
   --name <name>       Project display name when up needs to create a project.
                       Not a deploy manifest field and never renames a project.
   --project <id>      Explicit project id. Highest-priority project selector.
-  --manifest <path>   Deploy manifest path. Defaults to run402.deploy.json,
-                      then app.json in --dir/current directory.
+  --manifest <path>   Manifest path. Defaults to run402.json, then
+                      run402.deploy.json, then app.json in --dir/current directory.
   --dir <path>        Workspace directory to inspect (default: current dir).
   --tier <tier>       Bootstrap tier if no active Cloud tier exists
                       (prototype, hobby, team; default prototype).
@@ -39,7 +39,8 @@ Options:
   --max-spend-usd <n> Maximum spend up may approve for app readiness.
   --build-mode <mode> Override app build mode: local, remote, or sandbox.
   --allow-shell-build Approve shell-string build commands in run402.json.
-  --json              Emit one final JSON object on stdout.
+  --json              Emit one final JSON object on stdout (default; compatibility no-op).
+  --human             Emit the legacy human success/blocking summary on stdout.
   --json-stream       Emit NDJSON progress events on stdout and a final result event.
   --quiet             Suppress action progress events on stderr.
 
@@ -81,6 +82,7 @@ export async function run(args = []) {
       "--allow-prune",
       "--allow-shell-build",
       "--json",
+      "--human",
       "--json-stream",
     ],
     [
@@ -156,9 +158,17 @@ export async function run(args = []) {
 
   const yes = parsed.includes("-y") || parsed.includes("--yes");
   const jsonStream = parsed.includes("--json-stream");
+  const human = parsed.includes("--human");
   const quiet = parsed.includes("--quiet") || parsed.includes("--final-only") || jsonStream;
   const mode = parseExecutionMode(parsed);
   const dryRun = parsed.includes("--dry-run");
+  if (human && (parsed.includes("--json") || jsonStream)) {
+    fail({
+      code: "BAD_USAGE",
+      message: "--human cannot be combined with --json or --json-stream.",
+      details: { flags: parsed.filter((arg) => arg === "--human" || arg === "--json" || arg === "--json-stream") },
+    });
+  }
   if (dryRun && mode !== undefined) {
     fail({
       code: "BAD_USAGE",
@@ -207,9 +217,9 @@ export async function run(args = []) {
       console.log(JSON.stringify({ type: "run402.up.result", result }));
     } else if (mode === "printSpec") {
       console.log(JSON.stringify(result.result?.spec ?? null, null, 2));
-    } else if (result?.result?.app_result && !parsed.includes("--json")) {
+    } else if (human && result?.result?.app_result) {
       console.log(formatAppUpHuman(result.result.app_result));
-    } else if (!parsed.includes("--json") && shouldRenderHumanSuccess(result)) {
+    } else if (human && shouldRenderHumanSuccess(result)) {
       console.log(formatLegacyUpSuccess(result));
     } else {
       console.log(JSON.stringify(result, null, 2));

package/lib/wallet-context.mjs

@@ -4,10 +4,9 @@
  * 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.
+ * core path functions resolve under it. 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)
@@ -178,8 +177,9 @@ function walletAddress(name) {
   }
 }
 
-/** Emit the stderr provenance line for non-default selections (silent for default). */
-export function emitProvenance({ name, source, sourceDetail }, { cmd, quiet } = {}) {
+/** Emit the stderr provenance line for non-default selections when explicitly requested. */
+export function emitProvenance({ name, source, sourceDetail }, { cmd, quiet, showProvenance = false } = {}) {
+  if (!showProvenance) return;
   if (quiet) return;
   if (name === DEFAULT) return;
   if (cmd === "wallets") return; // the wallets group reports its own context
@@ -218,6 +218,10 @@ export function applyWalletSelection({ walletFlag, cmd, cwd = process.cwd(), env
     diverged: !!(envName && binding && envName !== binding.wallet),
   });
 
-  emitProvenance(resolved, { cmd, quiet });
+  emitProvenance(resolved, {
+    cmd,
+    quiet,
+    showProvenance: env.RUN402_WALLET_PROVENANCE === "1",
+  });
   return resolved;
 }

package/lib/wallet-context.test.mjs

@@ -212,15 +212,27 @@ describe("emitProvenance", () => {
   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", () => {
+  it("stays silent for a named wallet by default", () => {
     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.equal(out, "");
+  });
+  it("can emit a provenance line when explicitly requested", () => {
+    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", showProvenance: true },
+    ));
     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 })), "");
+    assert.equal(captureStderr(() => emitProvenance(
+      { name: "kychon", source: "env" },
+      { cmd: "status", quiet: true, showProvenance: true },
+    )), "");
   });
   it("stays silent for the wallets group", () => {
     assert.equal(captureStderr(() => emitProvenance({ name: "kychon", source: "flag" }, { cmd: "wallets" })), "");

package/lib/webhooks.mjs

@@ -262,8 +262,6 @@ export async function run(sub, args) {
     case "deliveries": await deliveries(args); break;
     case "redrive":    await redrive(args); break;
     default:
-      console.error(`Unknown webhooks action: ${sub}\n`);
-      console.log(HELP);
-      process.exit(1);
+      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown webhooks action: ${sub}`, hint: "Run `run402 webhooks --help` for usage.", details: { command: "webhooks", subcommand: sub } });
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "3.7.5",
+  "version": "3.7.7",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {

package/sdk/dist/actions.d.ts

@@ -72,7 +72,7 @@ export interface Run402ActionApprovalRequest {
     message: string;
     mutations: Run402ActionMutation[];
 }
-export type Run402ActionMutation = "allowance.create" | "allowance.faucet" | "tier.set" | "projects.provision" | "workspace.link.write" | "app.source.resolve" | "app.install" | "deploy.apply";
+export type Run402ActionMutation = "allowance.create" | "allowance.faucet" | "tier.set" | "projects.provision" | "workspace.link.write" | "app.source.resolve" | "app.install" | "app.mailbox.ensure" | "app.secret.ensure" | "app.build" | "app.webhook.ensure" | "app.verify" | "deploy.apply";
 export interface Run402ActionRunOptions {
     /**
      * Canonical execution mode for typed-config workflows.

package/sdk/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}

package/sdk/dist/index.d.ts

@@ -49,6 +49,7 @@ export interface Run402Options {
 }
 export declare class Run402 {
     #private;
+    readonly apiBase: string;
     readonly projects: Projects;
     readonly assets: Assets;
     readonly functions: Functions;