run402 4.93.1 → 4.94.0

package/core-dist/profiles.js

@@ -3,7 +3,7 @@
  *
  * A "wallet" is a whole config directory. The reserved `default` wallet lives
  * at the base config dir (zero migration for existing installs); every named
- * wallet lives under `{base}/profiles/<name>/` with its own `allowance.json`,
+ * wallet lives under `{base}/profiles/<name>/` with its own `wallet.json`,
  * `projects.json`, and this module's non-secret `meta.json`.
  *
  * Two levels of active state, mirroring the wallet → project model:
@@ -17,7 +17,7 @@
 import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, existsSync, readdirSync, rmSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
-import { getConfigBaseDir, getProfilesDir, DEFAULT_PROFILE, isValidProfileName, } from "./config.js";
+import { getConfigBaseDir, getProfilesDir, DEFAULT_PROFILE, isValidProfileName, moveWalletFiles, WALLET_FILE_NAME, } from "./config.js";
 import { describeRejectedValue } from "./redact.js";
 function atomicWrite(p, content, mode) {
     const dir = dirname(p);
@@ -114,17 +114,19 @@ export function writeMeta(name, meta) {
     atomicWrite(metaPath(name), JSON.stringify(meta, null, 2), 0o600);
 }
 // --- enumeration + lifecycle ---
-/** True when a wallet's `allowance.json` exists on disk. */
+/** True when a wallet's `wallet.json` exists on disk. */
 export function profileExists(name) {
-    return existsSync(join(profileDir(name), "allowance.json"));
+    moveWalletFiles();
+    return existsSync(join(profileDir(name), WALLET_FILE_NAME));
 }
 /**
- * All wallet names on disk: `default` (only if a root allowance.json exists)
+ * All wallet names on disk: `default` (only if a root wallet.json exists)
  * plus every valid directory under `profiles/`.
  */
 export function listProfileNames() {
+    moveWalletFiles();
     const names = [];
-    if (existsSync(join(getConfigBaseDir(), "allowance.json"))) {
+    if (existsSync(join(getConfigBaseDir(), WALLET_FILE_NAME))) {
         names.push(DEFAULT_PROFILE);
     }
     try {
@@ -184,7 +186,7 @@ export function renameProfile(oldName, newName) {
             /* best-effort */
         }
         const base = getConfigBaseDir();
-        for (const f of ["allowance.json", "projects.json", "meta.json"]) {
+        for (const f of [WALLET_FILE_NAME, "projects.json", "meta.json"]) {
             const src = join(base, f);
             if (existsSync(src))
                 renameSync(src, join(dest, f));

package/core-dist/{allowance-auth.js → wallet-auth.js}

@@ -1,12 +1,12 @@
 /**
- * Allowance auth helper — generates SIWX (Sign-In With X / EIP-4361) headers for Run402 API.
+ * SIWX auth helper — generates SIWX (Sign-In With X / EIP-4361) headers for Run402 API.
  * Uses @noble/curves (lighter than viem) for signing.
  */
 import { randomBytes } from "node:crypto";
 import { secp256k1 } from "@noble/curves/secp256k1.js";
 import { keccak_256 } from "@noble/hashes/sha3.js";
 import { bytesToHex } from "@noble/hashes/utils.js";
-import { readAllowance } from "./allowance.js";
+import { readWallet } from "./wallet.js";
 import { getApiBase } from "./config.js";
 /**
  * EIP-55 mixed-case checksum encoding.
@@ -21,7 +21,7 @@ export function toChecksumAddress(address) {
     return checksummed;
 }
 /**
- * EIP-191 personal_sign: sign a message with the allowance's private key.
+ * EIP-191 personal_sign: sign a message with the wallet's private key.
  */
 function personalSign(privateKeyHex, address, message) {
     const msgBytes = new TextEncoder().encode(message);
@@ -86,11 +86,11 @@ export function formatSIWEMessage(opts, address) {
     return lines.join("\n");
 }
 export function buildSIWxAuthHeaders(opts) {
-    const message = formatSIWEMessage(opts, opts.allowance.address);
-    const signature = personalSign(opts.allowance.privateKey, opts.allowance.address, message);
+    const message = formatSIWEMessage(opts, opts.wallet.address);
+    const signature = personalSign(opts.wallet.privateKey, opts.wallet.address, message);
     const payload = {
         domain: opts.domain,
-        address: toChecksumAddress(opts.allowance.address),
+        address: toChecksumAddress(opts.wallet.address),
         statement: opts.statement,
         uri: opts.uri,
         version: opts.version ?? "1",
@@ -110,18 +110,18 @@ export function buildSIWxAuthHeaders(opts) {
 }
 /**
  * Get SIWX auth headers for the Run402 API.
- * Returns null if no allowance is configured.
+ * Returns null if no local wallet is configured.
  *
  * @param path - API path (e.g. "/projects/v1") used to build the SIWE uri field.
  */
-export function getAllowanceAuthHeaders(path, allowancePath) {
-    // readAllowance throws on a malformed-shape allowance file. The
-    // CLI's higher-level readAllowance wrapper surfaces this as a structured
-    // BAD_ALLOWANCE_FILE envelope; here we preserve the public contract that
+export function getWalletAuthHeaders(path, walletPath) {
+    // readWallet throws on a malformed-shape wallet file. The
+    // CLI's higher-level readWallet wrapper surfaces this as a structured
+    // BAD_WALLET_FILE envelope; here we preserve the public contract that
     // this helper returns SIWxAuthHeaders | null. Re-throw so callers above
     // the CLI's wrapper (e.g. SDK paid-fetch) can decide whether to swallow it.
-    const allowance = readAllowance(allowancePath);
-    if (!allowance || !allowance.address || !allowance.privateKey)
+    const localWallet = readWallet(walletPath);
+    if (!localWallet || !localWallet.address || !localWallet.privateKey)
         return null;
     const apiBase = getApiBase();
     const url = new URL(apiBase);
@@ -132,7 +132,7 @@ export function getAllowanceAuthHeaders(path, allowancePath) {
     const issuedAt = now.toISOString();
     const expirationTime = new Date(now.getTime() + 5 * 60 * 1000).toISOString();
     return buildSIWxAuthHeaders({
-        allowance,
+        wallet: localWallet,
         domain,
         uri,
         statement: "Sign in to Run402",
@@ -151,4 +151,4 @@ function messageChainId(chainId) {
 function payloadChainId(chainId) {
     return typeof chainId === "number" ? `eip155:${chainId}` : chainId;
 }
-//# sourceMappingURL=allowance-auth.js.map
+//# sourceMappingURL=wallet-auth.js.map

package/{sdk/core-dist/allowance.js → core-dist/wallet.js}

@@ -1,36 +1,36 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, renameSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
-import { getAllowancePath } from "./config.js";
+import { getWalletPath } from "./config.js";
 // 0x-prefixed 40-hex EVM address.
 const ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
 // 0x-prefixed 64-hex secp256k1 private key (32 bytes).
 const PRIVATE_KEY_RE = /^0x[a-fA-F0-9]{64}$/;
 /**
- * Load the agent allowance from disk.
+ * Load the agent wallet from disk.
  *
- * Returns `null` for the two "no allowance configured" cases:
+ * Returns `null` for the two "no local wallet configured" cases:
  *   - the file does not exist
  *   - the file exists but is not parseable JSON (preserve existing UX —
- *     consumers print "no_allowance" and tell the user to run init)
+ *     consumers print "no_wallet" and tell the user to run init)
  *
  * Throws a structured `Error` when the file parses as JSON but the
  * shape is wrong (missing/wrong-type/wrong-length fields). Without this guard
  * downstream callers crash with raw stack traces:
- *   - `cli/lib/status.mjs` reaches for `allowance.address.toLowerCase()`
+ *   - `cli/lib/status.mjs` reaches for `wallet.address.toLowerCase()`
  *     and crashes with `TypeError: Cannot read properties of undefined`.
- *   - `core/src/allowance-auth.ts` passes a malformed `privateKey` to
+ *   - `core/src/wallet-auth.ts` passes a malformed `privateKey` to
  *     `@noble/curves` which throws "expected 32 bytes, got N".
  *
- * The CLI's `cli/lib/config.mjs:readAllowance()` wrapper and the MCP
+ * The CLI's `cli/lib/config.mjs:readWallet()` wrapper and the MCP
  * `src/tools/{status,init}.ts` callers translate the throw into their own
- * structured envelopes (`code: BAD_ALLOWANCE_FILE`).
+ * structured envelopes (`code: BAD_WALLET_FILE`).
  */
 /**
- * If an allowance file is readable by group or other (any of the low 0o077
+ * If a wallet file is readable by group or other (any of the low 0o077
  * bits set), tighten it to 0600 and warn once on stderr. This self-heals the
  * historical case where a legacy world-readable `wallet.json` (mode 0644) was
- * migrated to `allowance.json` via a mode-preserving rename, leaving the
+ * migrated to `wallet.json` via a mode-preserving rename, leaving the
  * private key exposed on a shared machine. Best-effort: POSIX-only and silent
  * on platforms without meaningful Unix modes (e.g. Windows).
  */
@@ -48,8 +48,8 @@ function selfHealPermissions(p) {
         // Best-effort; never block a read on a chmod/stat failure.
     }
 }
-export function readAllowance(path) {
-    const p = path ?? getAllowancePath();
+export function readWallet(path) {
+    const p = path ?? getWalletPath();
     if (!existsSync(p))
         return null;
     selfHealPermissions(p);
@@ -66,31 +66,31 @@ export function readAllowance(path) {
     }
     catch {
         // Preserve historical UX — completely unparseable input reads as "no
-        // allowance configured" rather than as an error. Consumers already handle
+        // wallet configured" rather than as an error. Consumers already handle
         // null with a friendly "run 'run402 init'" message.
         return null;
     }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error(`allowance.json must contain a JSON object (got ${Array.isArray(parsed) ? "array" : parsed === null ? "null" : typeof parsed}). Back up the file and run 'run402 init' to recreate it.`);
+        throw new Error(`wallet.json must contain a JSON object (got ${Array.isArray(parsed) ? "array" : parsed === null ? "null" : typeof parsed}). Back up the file and run 'run402 init' to recreate it.`);
     }
     const data = parsed;
     if (typeof data.address !== "string" || !ADDRESS_RE.test(data.address)) {
-        throw new Error("allowance.json missing valid 'address' (expected 0x-prefixed 40-hex string). " +
+        throw new Error("wallet.json missing valid 'address' (expected 0x-prefixed 40-hex string). " +
             "Back up the file and run 'run402 init' to recreate it.");
     }
     if (typeof data.privateKey !== "string" || !PRIVATE_KEY_RE.test(data.privateKey)) {
-        throw new Error("allowance.json missing valid 'privateKey' (expected 0x-prefixed 64-hex string). " +
+        throw new Error("wallet.json missing valid 'privateKey' (expected 0x-prefixed 64-hex string). " +
             "Back up the file and run 'run402 init' to recreate it.");
     }
     return data;
 }
-export function saveAllowance(data, path) {
-    const p = path ?? getAllowancePath();
+export function saveWallet(data, path) {
+    const p = path ?? getWalletPath();
     const dir = dirname(p);
     mkdirSync(dir, { recursive: true });
-    const tmp = join(dir, `.allowance.${randomBytes(4).toString("hex")}.tmp`);
+    const tmp = join(dir, `.wallet.${randomBytes(4).toString("hex")}.tmp`);
     writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
     renameSync(tmp, p);
     chmodSync(p, 0o600);
 }
-//# sourceMappingURL=allowance.js.map
+//# sourceMappingURL=wallet.js.map

package/{sdk/core-dist/write-auth-session.js → core-dist/write-approvals.js}

@@ -4,12 +4,12 @@ import { randomBytes, createHash } from "node:crypto";
 import { getConfigBaseDir } from "./config.js";
 const DEFAULT_TTL_MS = 30 * 60 * 1000;
 /**
- * Path to the approval cache: `{base}/write-auth-session.json`.
- * `RUN402_WRITE_AUTH_SESSION_PATH` overrides for testing.
+ * Path to the approval cache: `{base}/write-approvals.json`.
+ * `RUN402_WRITE_APPROVALS_PATH` overrides for testing.
  */
-export function getWriteAuthSessionPath() {
-    return (process.env.RUN402_WRITE_AUTH_SESSION_PATH ||
-        join(getConfigBaseDir(), "write-auth-session.json"));
+export function getWriteApprovalsPath() {
+    return (process.env.RUN402_WRITE_APPROVALS_PATH ||
+        join(getConfigBaseDir(), "write-approvals.json"));
 }
 /** Stable short hash binding an approval to a control-plane session token. */
 export function hashControlPlaneSession(token) {
@@ -34,8 +34,8 @@ function isApproval(x) {
     if (!x || typeof x !== "object")
         return false;
     const a = x;
-    return (typeof a.write_auth_token === "string" &&
-        a.write_auth_token.length > 0 &&
+    return (typeof a.write_approval_token === "string" &&
+        a.write_approval_token.length > 0 &&
         typeof a.action === "string" &&
         typeof a.api_origin === "string" &&
         typeof a.control_plane_session_hash === "string" &&
@@ -48,7 +48,7 @@ function isApproval(x) {
  * is wrong, so a corrupted cache surfaces a clear fix-it.
  */
 export function readApprovals(path) {
-    const p = path ?? getWriteAuthSessionPath();
+    const p = path ?? getWriteApprovalsPath();
     if (!existsSync(p))
         return [];
     selfHealPermissions(p);
@@ -67,19 +67,19 @@ export function readApprovals(path) {
         return [];
     }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error("write-auth-session.json must contain a JSON object. Delete it and re-run 'run402 operator approve' to recreate it.");
+        throw new Error("write-approvals.json must contain a JSON object. Delete it and re-run 'run402 approve' to recreate it.");
     }
     const approvals = parsed.approvals;
     if (!Array.isArray(approvals)) {
-        throw new Error("write-auth-session.json missing an 'approvals' array. Delete it and re-run 'run402 operator approve'.");
+        throw new Error("write-approvals.json missing an 'approvals' array. Delete it and re-run 'run402 approve'.");
     }
     return approvals.filter(isApproval);
 }
 function writeApprovals(approvals, path) {
-    const p = path ?? getWriteAuthSessionPath();
+    const p = path ?? getWriteApprovalsPath();
     const dir = dirname(p);
     mkdirSync(dir, { recursive: true });
-    const tmp = join(dir, `.write-auth-session.${randomBytes(4).toString("hex")}.tmp`);
+    const tmp = join(dir, `.write-approvals.${randomBytes(4).toString("hex")}.tmp`);
     writeFileSync(tmp, JSON.stringify({ approvals }, null, 2), { mode: 0o600 });
     renameSync(tmp, p);
     chmodSync(p, 0o600);
@@ -103,9 +103,9 @@ export function saveApproval(approval, path) {
     existing.push(approval);
     writeApprovals(existing, path);
 }
-/** Delete the whole approval cache — local half of `operator logout`. Idempotent. */
+/** Delete the whole approval cache — local half of `run402 logout`. Idempotent. */
 export function clearApprovals(path) {
-    const p = path ?? getWriteAuthSessionPath();
+    const p = path ?? getWriteApprovalsPath();
     try {
         rmSync(p, { force: true });
     }
@@ -137,7 +137,7 @@ export function loadLiveApproval(q, path, nowMs = Date.now()) {
 }
 /** Parse a gateway-returned session expiry (ISO string or epoch) to epoch ms. */
 function sessionExpiryMs(session, nowMs) {
-    const raw = session?.expires_at ?? session?.absolute_expires_at;
+    const raw = session?.idle_expires_at ?? session?.expires_at ?? session?.absolute_expires_at;
     if (typeof raw === "number" && Number.isFinite(raw))
         return raw > 1e12 ? raw : raw * 1000;
     if (typeof raw === "string") {
@@ -157,9 +157,9 @@ export function approvalFromTokenResponse(resp, binding, nowMs = Date.now()) {
         ? resp.session.amr.filter((a) => typeof a === "string")
         : undefined;
     return {
-        write_auth_token: resp.write_auth_token,
-        token_type: typeof resp.token_type === "string" ? resp.token_type : "write_auth",
-        header: typeof resp.header === "string" ? resp.header : "X-Run402-Write-Auth",
+        write_approval_token: resp.write_approval_token,
+        token_type: typeof resp.token_type === "string" ? resp.token_type : "write_approval",
+        header: typeof resp.header === "string" ? resp.header : "X-Run402-Write-Approval",
         action: binding.action,
         ...(binding.target.org_id ? { org_id: binding.target.org_id } : {}),
         ...(binding.target.project_id ? { project_id: binding.target.project_id } : {}),
@@ -171,4 +171,4 @@ export function approvalFromTokenResponse(resp, binding, nowMs = Date.now()) {
         minted_at: nowMs,
     };
 }
-//# sourceMappingURL=write-auth-session.js.map
+//# sourceMappingURL=write-approvals.js.map

package/gitvault-surface.json

@@ -1,5 +1,5 @@
 {
-  "surface_version": "4.93.1",
+  "surface_version": "4.94.0",
   "verbs": [
     "repos create",
     "repos list",

package/lib/admin.mjs

@@ -30,7 +30,7 @@ Subcommands:
                                          lease-perpetual above.
 
 Notes:
-  - All admin subcommands require platform-admin auth — the configured allowance
+  - All admin subcommands require platform-admin auth — the configured wallet
     wallet must be a platform admin, or an admin OAuth session cookie must be
     available. Regular project owners cannot run these.
   - Output is JSON.

package/lib/agent.mjs

@@ -1,4 +1,4 @@
-import { allowanceAuthHeaders } from "./config.mjs";
+import { walletAuthHeaders } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs, validateWebhookUrl, failUnknownSubcommand } from "./argparse.mjs";
@@ -12,7 +12,7 @@ Usage:
   run402 agent passkey enroll
 
 Notes:
-  - Free with allowance auth
+  - Free with SIWX auth
   - Registers contact info so Run402 can reach your agent
   - Only name is required; email and webhook are optional
   - New or changed emails start reply verification
@@ -39,7 +39,7 @@ Options:
                       agent
 
 Notes:
-  - Free with allowance auth (run an 'allowance create' first)
+  - Free with SIWX auth (run 'run402 init' first)
   - Registers contact info so Run402 can reach your agent
   - New or changed emails start a reply challenge and return
     assurance_level without exposing the challenge secret
@@ -65,13 +65,15 @@ Usage:
 Sends or reuses a reply challenge for the active contact email. The challenge
 secret is emailed and never printed.
 `,
-  passkey: `run402 agent passkey — Manage operator passkey binding
+  passkey: `run402 agent passkey — Bind a passkey to the contact
 
 Usage:
   run402 agent passkey enroll
 
-Sends a short-lived Run402 operator passkey enrollment link to the verified
-contact email. Requires assurance_level=email_verified first.
+Sends a short-lived Run402 passkey enrollment link to the verified
+contact email. Requires assurance_level=email_verified first. A person
+signed in with 'run402 login' already has passkey assurance for a contact
+whose verified email their principal holds.
 `,
 };
 
@@ -93,12 +95,12 @@ async function contact(args) {
   if (!name) {
     fail({ code: "BAD_USAGE", message: "Missing --name <name>" });
   }
-  // validate webhook scheme locally BEFORE the allowance check so
-  // bad URLs fail fast even without an allowance configured. No-op when
+  // validate webhook scheme locally BEFORE the wallet check so
+  // bad URLs fail fast even without a wallet configured. No-op when
   // --webhook is omitted (it's optional).
   validateWebhookUrl(webhook, "--webhook");
-  // Preserve the aggressive early exit when no allowance is configured.
-  allowanceAuthHeaders("/agent/v1/contact");
+  // Preserve the aggressive early exit when no local wallet is configured.
+  walletAuthHeaders("/agent/v1/contact");
 
   try {
     const data = await getSdk().admin.setAgentContact({
@@ -119,20 +121,20 @@ async function status(args = []) {
   if (extra.length > 0) {
     fail({ code: "BAD_USAGE", message: `Unexpected argument for agent status: ${extra[0]}` });
   }
-  allowanceAuthHeaders("/agent/v1/contact/status");
+  walletAuthHeaders("/agent/v1/contact/status");
 
   try {
     const sdk = getSdk();
     const data = await sdk.admin.getAgentContactStatus();
     // v1.56: augment the response with email_verification.last_challenge from
-    // /agent/v1/operator/status so the operator sees per-attempt status
+    // /agent/v1/me/status so the reader sees per-attempt status
     // (trust_rejected with which verdicts, attempts remaining, hint) without
     // a second command. Best-effort — older gateways without the v1.55+ route
     // skip the augment silently.
     try {
-      const opStatus = await sdk.admin.getOperatorStatus();
-      if (opStatus && opStatus.email_verification) {
-        data.email_verification = opStatus.email_verification;
+      const meStatus = await sdk.me.status();
+      if (meStatus && meStatus.email_verification) {
+        data.email_verification = meStatus.email_verification;
       }
     } catch {
       // Older gateway — keep the original response shape.
@@ -150,7 +152,7 @@ async function verifyEmail(args = []) {
   if (extra.length > 0) {
     fail({ code: "BAD_USAGE", message: `Unexpected argument for agent verify-email: ${extra[0]}` });
   }
-  allowanceAuthHeaders("/agent/v1/contact/verify-email");
+  walletAuthHeaders("/agent/v1/contact/verify-email");
 
   try {
     const data = await getSdk().admin.verifyAgentContactEmail();
@@ -171,10 +173,10 @@ async function passkey(args) {
   if (action !== "enroll") {
     fail({ code: "BAD_USAGE", message: "Usage: run402 agent passkey enroll" });
   }
-  allowanceAuthHeaders("/agent/v1/contact/passkey/enroll");
+  walletAuthHeaders("/agent/v1/contact/passkey/enroll");
 
   try {
-    const data = await getSdk().admin.startOperatorPasskeyEnrollment();
+    const data = await getSdk().admin.startContactPasskeyEnrollment();
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);

package/lib/approve.mjs

@@ -0,0 +1,81 @@
+/**
+ * `run402 approve --action <capability> (--org <org_id> | --project <project_id>)`
+ * — mint a passkey-signed write approval scoped to one (action, target) so a
+ * person signed in without a wallet can provision, deploy, or write secrets.
+ * See sign-in.mjs.
+ */
+
+import { fail } from "./sdk-errors.mjs";
+import { normalizeArgv, hasHelp, assertKnownFlags, flagValue, positionalArgs } from "./argparse.mjs";
+import { APPROVAL_ACTIONS, mintApproval } from "./sign-in.mjs";
+
+const HELP = `run402 approve — mint a write approval for one action on one target
+
+Usage:
+  run402 approve --action <capability> (--org <org_id> | --project <project_id>) [--no-open]
+
+A person signed in with 'run402 login' (no wallet) needs a write approval to
+provision a project, deploy, or write secrets. It is signed with your passkey,
+covers one action on one org or project, lasts 30 minutes idle (4 hours at
+most), and dies with the sign-in session. It never counts as a step-up.
+From an interactive terminal the CLI opens this ceremony for you when a write
+needs it; agents and CI relay the command instead.
+
+Actions:
+  org.project.create     --org <org_id>
+  project.deploy         --project <project_id>
+  project.secret.write   --project <project_id>
+
+Options:
+  --no-open  Do not open the browser; print the URL only.
+
+Notes:
+  - Requires 'run402 login' (a device-grade session cannot approve).
+  - 'run402 whoami' lists the approvals cached on this machine.
+`;
+
+export async function run(args = []) {
+  args = normalizeArgv(args);
+  if (hasHelp(args)) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  const valueFlags = ["--action", "--org", "--project"];
+  assertKnownFlags(args, ["--help", "-h", "--no-open", ...valueFlags], valueFlags);
+  const extra = positionalArgs(args, valueFlags);
+  if (extra.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for approve: ${extra[0]}`, hint: "Use `run402 approve --action <capability> (--org <org_id> | --project <project_id>)`." });
+  }
+  const action = flagValue(args, "--action");
+  const org = flagValue(args, "--org");
+  const project = flagValue(args, "--project");
+
+  if (!action || !APPROVAL_ACTIONS[action]) {
+    fail({
+      code: "BAD_FLAG",
+      message: `--action must be one of: ${Object.keys(APPROVAL_ACTIONS).join(", ")}`,
+      details: { flag: "--action", value: action, allowed: Object.keys(APPROVAL_ACTIONS) },
+    });
+  }
+  const scope = APPROVAL_ACTIONS[action];
+  if (scope === "org" && !org) fail({ code: "BAD_FLAG", message: `--org <org_id> is required for --action ${action}` });
+  if (scope === "project" && !project) fail({ code: "BAD_FLAG", message: `--project <project_id> is required for --action ${action}` });
+  if (scope === "org" && project) fail({ code: "BAD_FLAG", message: `--project is not valid for org-scoped --action ${action}; use --org` });
+  if (scope === "project" && org) fail({ code: "BAD_FLAG", message: `--org is not valid for project-scoped --action ${action}; use --project` });
+
+  const approval = await mintApproval({
+    action,
+    orgId: org ?? undefined,
+    projectId: project ?? undefined,
+    noOpen: args.includes("--no-open"),
+  });
+  console.log(
+    JSON.stringify({
+      approved: true,
+      action,
+      ...(org ? { org_id: org } : {}),
+      ...(project ? { project_id: project } : {}),
+      expires_at: new Date(approval.expires_at).toISOString(),
+    }),
+  );
+}

package/lib/apps.mjs

@@ -1,4 +1,4 @@
-import { allowanceAuthHeaders, saveProject } from "./config.mjs";
+import { walletAuthHeaders, saveProject } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertAllowedValue, assertKnownFlags, flagValue, normalizeArgv, positionalArgs, resolveProjectSelector, failUnknownSubcommand } from "./argparse.mjs";
@@ -185,8 +185,8 @@ async function fork(versionId, name, args) {
     fail({ code: "BAD_USAGE", message: `Unexpected argument for apps fork: ${positionals[expected]}` });
   }
   const opts = { subdomain: flagValue(parsedArgs, "--subdomain") ?? undefined };
-  // Preserve the aggressive early exit when no allowance is configured.
-  allowanceAuthHeaders("/fork/v1");
+  // Preserve the aggressive early exit when no local wallet is configured.
+  walletAuthHeaders("/fork/v1");
 
   try {
     const data = await getSdk().apps.fork({

package/lib/assets.mjs

@@ -196,7 +196,7 @@ Options:
 Output:
   - Prints the JSON envelope on stdout (parseable by agent shell loops).
   - Vantage caveat ("# probed once from gateway-us-east-1; not a global view")
-    on stderr — visible to TTY operators, ignored by piped consumers.
+    on stderr — visible to a person at a TTY, ignored by piped consumers.
 
 Exit codes:
   0   observed SHA matches the gateway's expected SHA
@@ -575,7 +575,7 @@ async function diagnose(argv) {
     const env = await getSdk().assets.diagnoseUrl(resolvedId, url);
     // Always print the JSON envelope for agent consumption (parseable).
     console.log(JSON.stringify(toCliDiagnoseEnvelope(env), null, 2));
-    // Vantage caveat to stderr so a TTY operator sees it; agent shell loops
+    // Vantage caveat to stderr so a person at a TTY sees it; agent shell loops
     // that pipe stdout into another tool aren't affected.
     process.stderr.write(
       `\n# probed once from ${env.vantage}; not a global view\n`,

package/lib/billing.mjs

@@ -12,9 +12,9 @@ Subcommands:
   create-email <email>                     Create an email organization
   link-wallet [<org_id>] <wallet_address>  Link a wallet to an email organization
   checkout <identifier> --product <p>      Create an org checkout
-  topup <identifier> --sats <n> [--wait] [--qr <file.png>]   Top up the cash balance over Lightning (a bolt11 invoice; --qr also writes a scannable PNG)
+  topup <identifier> --sats <n> [--wait] [--qr <file.png>]   Top up the allowance over Lightning (a bolt11 invoice; --qr also writes a scannable PNG)
   auto-recharge [<org_id>] <on|off> [--threshold <n>]
-  balance <identifier>                     Balance by organization id (UUID), wallet (0x...), or email
+  balance <identifier>                     The allowance, by organization id (UUID), wallet (0x...), or email
   history <identifier> [--limit <n>]       Ledger history by organization id (UUID), wallet, or email
 
 Examples:
@@ -79,14 +79,14 @@ Options:
 
 Auth:
   Requires SIWX from a wallet linked to the organization (signed automatically from
-  the local allowance), or an admin key. Email lookups require an admin key.
+  the local wallet), or an admin key. Email lookups require an admin key.
 
 Examples:
   run402 billing history user@example.com
   run402 billing history 0x1234... --limit 100
   run402 billing history 00000000-0000-4000-8000-000000000001
 `,
-  balance: `run402 billing balance — Show balance for a organization
+  balance: `run402 billing balance — Show an organization's allowance
 
 Usage:
   run402 billing balance <identifier>
@@ -97,7 +97,7 @@ Arguments:
 
 Auth:
   Requires SIWX from a wallet linked to the organization (signed automatically from
-  the local allowance), or an admin key. Email lookups require an admin key.
+  the local wallet), or an admin key. Email lookups require an admin key.
 
 Examples:
   run402 billing balance user@example.com
@@ -262,7 +262,7 @@ async function topup(args) {
     });
     console.log(JSON.stringify(final, null, 2));
     if (final.status === "paid" || final.status === "paid_late") {
-      console.error(`Received — ${final.amount_sats} sats credited $${(final.amount_usd_micros / 1_000_000).toFixed(2)} to the balance${final.status === "paid_late" ? " (paid after the invoice expired; still credited)" : ""}.`);
+      console.error(`Received — ${final.amount_sats} sats added $${(final.amount_usd_micros / 1_000_000).toFixed(2)} to the allowance${final.status === "paid_late" ? " (paid after the invoice expired; still credited)" : ""}.`);
     } else if (final.status === "expired") {
       console.error("No payment was observed before the invoice expired. If you already paid, it still credits on its own (the gateway keeps checking for an hour after expiry) — read the top-up again, or rerun with the same --idempotency-key. Otherwise mint a fresh one with the same command.");
       process.exitCode = 2;

package/lib/buzz-doctor.mjs

@@ -689,7 +689,7 @@ function consoleRepair() {
     type: "restore_run402_console_access",
     surface: "buzz_settings",
     command: "Open Buzz Desktop > Settings > Agents, select this agent, allow HTTPS access to https://console.run402.com, restart the agent, then rerun Run402 setup.",
-    why: "The no-terminal human adoption handoff requires the Run402 console origin.",
+    why: "The no-terminal human adoption offer requires the Run402 console origin.",
   });
 }
 

package/lib/buzz-notifications.mjs

@@ -69,7 +69,7 @@ What can be routed:
   Omitting --event-type/--event-class routes every registered type / every
   non-forbidden class. There is no empty filter: the gateway rejects [].
 
-Buzz is never a deadman channel: mandatory operator notifications keep their
+Buzz is never a deadman channel: mandatory owner notifications keep their
 human paths (email, Telegram) regardless of route state, and a Buzz delivery
 acknowledges nothing.
 

package/lib/buzz.mjs

@@ -122,7 +122,7 @@ async function adopt(args) {
     assertKnownFlags(a, values, values);
     const [id] = requirePositionalCount(a, values, { min: 1, max: 1, command: "run402 buzz adopt complete <buzzha_id> --event-file <json>" });
     const event = readJsonFile(requiredFlag(a, "--event-file"), "--event-file");
-    return invoke(() => getSdk({ authMode: "operator" }).buzz.humanAdoptions.complete(id, event, flagValue(a, "--idempotency-key") ?? undefined));
+    return invoke(() => getSdk({ authMode: "session" }).buzz.humanAdoptions.complete(id, event, flagValue(a, "--idempotency-key") ?? undefined));
   }
   if (operation === "cancel") {
     const a = normalizeArgv(rest);