run402 3.7.6 → 3.7.8

package/cli.mjs

@@ -330,8 +330,8 @@ switch (cmd) {
     break;
   }
   case "webhook-secret": {
-    const { runWebhookSecret } = await import("./lib/notifications.mjs");
-    await runWebhookSecret(sub, rest);
+    const { run } = await import("./lib/webhook-secret.mjs");
+    await run(sub, rest);
     break;
   }
   case "logs": {
@@ -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/archives.mjs

@@ -23,7 +23,12 @@ export async function run(sub, rawArgs = []) {
     case "inspect": return inspect(rawArgs);
     case "verify": return verify(rawArgs);
     default:
-      fail({ code: "BAD_USAGE", message: "Usage: run402 archives <inspect|verify> <archive-path> [--json]" });
+      fail({
+        code: "UNKNOWN_SUBCOMMAND",
+        message: `Unknown archives subcommand: ${sub}`,
+        hint: "Run `run402 archives --help` for usage.",
+        details: { command: "archives", 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/cache.mjs

@@ -100,8 +100,10 @@ export async function run(sub, args) {
       break;
     default:
       fail({
-        code: "BAD_USAGE",
+        code: "UNKNOWN_SUBCOMMAND",
         message: `Unknown cache subcommand: ${sub}`,
+        hint: "Run `run402 cache --help` for usage.",
+        details: { command: "cache", subcommand: sub },
         next_actions: [editRequestAction("run402 cache --help", "Choose a supported cache subcommand.")],
       });
   }

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/cloud.mjs

@@ -56,8 +56,10 @@ export async function run(sub, args = []) {
   }
   if (sub !== "archives") {
     fail({
-      code: "BAD_USAGE",
-      message: "Usage: run402 cloud archives <create|download|status> ...",
+      code: "UNKNOWN_SUBCOMMAND",
+      message: `Unknown cloud subcommand: ${sub}`,
+      hint: "Run `run402 cloud --help` for usage.",
+      details: { command: "cloud", subcommand: sub },
       next_actions: [{ type: "run_command", command: "run402 cloud archives --help" }],
     });
   }
@@ -67,8 +69,10 @@ export async function run(sub, args = []) {
   if (action === "download") return download(rest);
   if (action === "status") return status(rest);
   fail({
-    code: "BAD_USAGE",
-    message: "Usage: run402 cloud archives <create|download|status> ...",
+    code: "UNKNOWN_SUBCOMMAND",
+    message: `Unknown cloud archives subcommand: ${action}`,
+    hint: "Run `run402 cloud archives --help` for usage.",
+    details: { command: "cloud archives", subcommand: action },
     next_actions: [{ type: "run_command", command: "run402 cloud archives --help" }],
   });
 }

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/core.mjs

@@ -28,11 +28,21 @@ export async function run(sub, args = []) {
     return;
   }
   if (sub !== "projects") {
-    fail({ code: "BAD_USAGE", message: "Usage: run402 core projects import <archive-path> [options]" });
+    fail({
+      code: "UNKNOWN_SUBCOMMAND",
+      message: `Unknown core subcommand: ${sub}`,
+      hint: "Run `run402 core --help` for usage.",
+      details: { command: "core", subcommand: sub },
+    });
   }
   const action = args[0];
   if (action === "import") return importProject(args.slice(1));
-  fail({ code: "BAD_USAGE", message: "Usage: run402 core projects import <archive-path> [options]" });
+  fail({
+    code: "UNKNOWN_SUBCOMMAND",
+    message: `Unknown core projects subcommand: ${action}`,
+    hint: "Run `run402 core projects --help` for usage.",
+    details: { command: "core projects", subcommand: action },
+  });
 }
 
 async function importProject(rawArgs) {

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/notifications.mjs

@@ -166,7 +166,12 @@ export async function run(sub, args) {
       await test(args);
       return;
     default:
-      fail({ code: "BAD_USAGE", message: `Unknown notifications subcommand: ${sub}\n\n${HELP}` });
+      fail({
+        code: "UNKNOWN_SUBCOMMAND",
+        message: `Unknown notifications subcommand: ${sub}`,
+        hint: "Run `run402 notifications --help` for usage.",
+        details: { command: "notifications", subcommand: sub },
+      });
   }
 }
 

package/lib/operator.mjs

@@ -767,9 +767,10 @@ export async function run(sub, args = []) {
       break;
     default:
       fail({
-        code: "BAD_USAGE",
-        message: `Unknown subcommand: operator ${sub}`,
-        hint: "Run 'run402 operator --help' for usage.",
+        code: "UNKNOWN_SUBCOMMAND",
+        message: `Unknown operator subcommand: ${sub}`,
+        hint: "Run `run402 operator --help` for usage.",
+        details: { command: "operator", subcommand: sub },
       });
   }
 }

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;
 }