run402 4.93.1 → 4.94.0

package/lib/sign-in.mjs

@@ -0,0 +1,296 @@
+/**
+ * Shared machinery for a person's command-line sign-in: `run402 login`,
+ * `run402 logout`, `run402 whoami`, and `run402 approve`.
+ *
+ * One sign-in session (wire token class `control_plane_session`), bound to the
+ * principal and graded by how it was minted:
+ *   - `run402 login` — loopback PKCE (RFC 8252): the browser runs the passkey
+ *     ceremony and redirects to a 127.0.0.1 listener. Grade `loopback`: full and
+ *     step-up-able.
+ *   - `run402 login --device` — RFC 8628 device authorization for a terminal
+ *     with no browser. Grade `device`: read-only (every mutation answers
+ *     `SESSION_READ_ONLY`).
+ *
+ * Provisioning, deploying, and writing secrets without a wallet additionally
+ * need a **write approval** — passkey-signed, scoped to one (action, target),
+ * minted by `run402 approve` and sent as `X-Run402-Write-Approval`. A write
+ * approval never satisfies step-up.
+ *
+ * The session and approvals are cached at the BASE config dir (principal-
+ * scoped, shared across named wallets), mode 0600. Agent-first: JSON to stdout;
+ * the URL and code a person must open go to stderr.
+ */
+
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { randomBytes, createHash } from "node:crypto";
+import { fail, reportSdkError } from "./sdk-errors.mjs";
+import { getSdk } from "./sdk.mjs";
+import { isWriteApprovalRequired } from "#sdk/node";
+import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
+import {
+  saveApproval,
+  hashControlPlaneSession,
+  approvalFromTokenResponse,
+} from "../core-dist/write-approvals.js";
+import { getApiBase } from "../core-dist/config.js";
+
+/** Gateway write-approval capabilities → required target scope. */
+export const APPROVAL_ACTIONS = {
+  "org.project.create": "org",
+  "project.deploy": "project",
+  "project.secret.write": "project",
+};
+
+/** True when `url` is same-origin as the API base (confirm_url validation). */
+function sameApiOrigin(url) {
+  try {
+    return new URL(url).origin === new URL(getApiBase()).origin;
+  } catch {
+    return false;
+  }
+}
+
+/** Best-effort, cross-platform browser open. Never throws. */
+export function openBrowser(url) {
+  try {
+    let cmd;
+    let cmdArgs;
+    if (process.platform === "darwin") {
+      cmd = "open";
+      cmdArgs = [url];
+    } else if (process.platform === "win32") {
+      cmd = "cmd";
+      cmdArgs = ["/c", "start", "", url];
+    } else {
+      cmd = "xdg-open";
+      cmdArgs = [url];
+    }
+    const child = spawn(cmd, cmdArgs, { stdio: "ignore", detached: true });
+    child.on("error", () => {}); // ignore: the URL is also printed to stderr
+    child.unref();
+  } catch {
+    // Best-effort only — the person can always copy the printed URL.
+  }
+}
+
+/** Output shape for a cached sign-in session. NEVER includes the token. */
+export function sessionView(session, nowMs = Date.now()) {
+  return {
+    logged_in: true,
+    grade: session.grade,
+    read_only: session.grade === "device",
+    principal_id: session.principal_id || null,
+    amr: session.amr,
+    expires_at: new Date(session.expires_at).toISOString(),
+    expires_in_seconds: Math.max(0, Math.round((session.expires_at - nowMs) / 1000)),
+  };
+}
+
+const base64url = (buf) => buf.toString("base64url");
+
+/** Generate PKCE (S256) + CSRF state + replay nonce for the loopback flow. */
+export function pkce() {
+  const codeVerifier = base64url(randomBytes(32));
+  const codeChallenge = base64url(createHash("sha256").update(codeVerifier).digest());
+  return { codeVerifier, codeChallenge, state: base64url(randomBytes(16)), nonce: base64url(randomBytes(16)) };
+}
+
+/**
+ * Start a 127.0.0.1 loopback server (RFC 8252) that captures exactly one
+ * redirect. Returns the bound port (via `ready`), a promise for the auth code,
+ * and a `close()`. State is validated here to reject CSRF before exchange.
+ */
+export function startLoopbackServer({ expectedState, timeoutMs }) {
+  let resolveCode;
+  let rejectCode;
+  const codePromise = new Promise((res, rej) => {
+    resolveCode = res;
+    rejectCode = rej;
+  });
+  let timer;
+  // Track live sockets: server.close() alone stops NEW connections but leaves
+  // the browser's keep-alive socket open, which keeps Node's event loop alive
+  // and hangs the CLI after a successful login. close() must destroy them.
+  const sockets = new Set();
+  const server = createServer((req, res) => {
+    let u;
+    try {
+      u = new URL(req.url, "http://127.0.0.1");
+    } catch {
+      res.writeHead(400).end("bad request");
+      return;
+    }
+    if (u.pathname !== "/callback") {
+      res.writeHead(404).end("not found");
+      return;
+    }
+    const code = u.searchParams.get("code");
+    const gotState = u.searchParams.get("state");
+    const errParam = u.searchParams.get("error");
+    // `connection: close` so the browser does not keep the socket alive.
+    res.writeHead(200, { "content-type": "text/html", connection: "close" });
+    res.end(
+      "<!doctype html><html><body style=\"font-family:system-ui;padding:3rem\">" +
+        "<h2>run402 - you're signed in.</h2><p>You can close this window and return to your terminal.</p></body></html>",
+    );
+    // Do NOT tear down here — let the response flush. The caller calls close()
+    // once it has the code (or on any failure path).
+    if (errParam) rejectCode(new Error(`authorization error: ${errParam}`));
+    else if (!code) rejectCode(new Error("no authorization code on the loopback redirect"));
+    else if (gotState !== expectedState) rejectCode(new Error("state mismatch on the loopback redirect (possible CSRF) - aborted"));
+    else resolveCode(code);
+  });
+  server.on("connection", (s) => {
+    sockets.add(s);
+    s.once("close", () => sockets.delete(s));
+  });
+  function close() {
+    clearTimeout(timer);
+    for (const s of sockets) {
+      try {
+        s.destroy();
+      } catch {
+        // already gone
+      }
+    }
+    try {
+      server.close();
+    } catch {
+      // already closing
+    }
+  }
+  timer = setTimeout(() => {
+    close();
+    rejectCode(new Error("timed out waiting for browser approval"));
+  }, timeoutMs);
+  server.on("error", (e) => {
+    close();
+    rejectCode(e);
+  });
+  const ready = new Promise((res, rej) => {
+    server.once("error", rej);
+    server.listen(0, "127.0.0.1", () => res(server.address().port));
+  });
+  return { ready, codePromise, close };
+}
+
+/**
+ * Run the write-approval ceremony (loopback + passkey) and cache the minted
+ * approval. Requires a live, write-capable sign-in session. Returns the cached
+ * approval (or exits non-zero via fail/reportSdkError). Reused by
+ * `run402 approve` AND the TTY auto-approve path in provision/deploy.
+ */
+export async function mintApproval({ action, orgId, projectId, noOpen = false }) {
+  const cp = loadLiveControlPlaneSession();
+  if (!cp) {
+    return fail({
+      code: "LOGIN_REQUIRED",
+      message: "No sign-in session. Run 'run402 login' first, then approve.",
+      hint: "A write approval is minted on top of your sign-in session.",
+      next_actions: [{ type: "authenticate", command: "run402 login" }],
+    });
+  }
+  if (cp.grade === "device") {
+    return fail({
+      code: "SESSION_READ_ONLY",
+      message: "This sign-in session came from 'run402 login --device' and can only read; it cannot mint a write approval.",
+      hint: "Run 'run402 login' (the browser passkey sign-in), then approve.",
+      next_actions: [{ type: "authenticate", command: "run402 login" }],
+    });
+  }
+  const sdk = getSdk();
+  const { codeVerifier, codeChallenge, state } = pkce();
+  const { ready, codePromise, close } = startLoopbackServer({ expectedState: state, timeoutMs: 300_000 });
+
+  let port;
+  try {
+    port = await ready;
+  } catch (err) {
+    close();
+    return fail({ code: "APPROVE_FAILED", message: `Could not start the loopback server: ${err.message}` });
+  }
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+  let challenge;
+  try {
+    challenge = await sdk.writeApproval.requestChallenge({
+      action,
+      orgId: orgId ?? undefined,
+      projectId: projectId ?? undefined,
+      cliRedirectUri: redirectUri,
+      codeChallenge,
+      state,
+      token: cp.control_plane_session_token,
+    });
+  } catch (err) {
+    close();
+    return reportSdkError(err);
+  }
+
+  const confirmUrl = challenge?.confirm_url;
+  if (!confirmUrl || !sameApiOrigin(confirmUrl)) {
+    close();
+    return fail({
+      code: "APPROVE_BAD_CONFIRM_URL",
+      message: "The gateway returned a confirm_url that is not same-origin as the API base; aborting.",
+    });
+  }
+  const targetLabel = orgId ? `org ${orgId}` : projectId ? `project ${projectId}` : "(no target)";
+  process.stderr.write(
+    `\nTo approve '${action}' for ${targetLabel}, open and approve with your passkey:\n  ${confirmUrl}\n\n`,
+  );
+  if (!noOpen && process.stderr.isTTY) {
+    openBrowser(confirmUrl);
+    process.stderr.write("(opening your browser…)\n\n");
+  }
+  process.stderr.write("Waiting for passkey approval…\n");
+
+  let code;
+  try {
+    code = await codePromise;
+  } catch (err) {
+    close();
+    return fail({ code: "APPROVE_FAILED", message: err.message, hint: "Run 'run402 approve' to try again." });
+  }
+
+  let token;
+  try {
+    token = await sdk.writeApproval.exchangeClaimCode({ code, codeVerifier, state });
+  } catch (err) {
+    close();
+    return reportSdkError(err);
+  }
+  close();
+
+  const approval = approvalFromTokenResponse(token, {
+    action,
+    target: { org_id: orgId ?? undefined, project_id: projectId ?? undefined },
+    apiOrigin: new URL(getApiBase()).origin,
+    controlPlaneSessionHash: hashControlPlaneSession(cp.control_plane_session_token),
+    controlPlanePrincipalId: cp.principal_id || "",
+  });
+  saveApproval(approval);
+  process.stderr.write(`\nApproved '${action}' for ${targetLabel}.\n`);
+  return approval;
+}
+
+/**
+ * Run a write action; on `WriteApprovalRequiredError` AND an interactive TTY
+ * (CLI), run the scoped approval ceremony and retry once. In MCP / CI /
+ * non-TTY the typed error is rethrown unchanged — the agent relays the resolved
+ * `run402 approve …` command rather than a browser opening unexpectedly.
+ */
+export async function withAutoApprove(fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (!isWriteApprovalRequired(err) || !process.stderr.isTTY) throw err;
+    const action = err.capability;
+    const target = err.target || {};
+    if (!action) throw err;
+    process.stderr.write(`\nThis '${action}' needs a one-time write approval. Opening the browser to approve…\n`);
+    await mintApproval({ action, orgId: target.org_id ?? undefined, projectId: target.project_id ?? undefined });
+    return await fn(); // retry once with the now-cached approval
+  }
+}

package/lib/sites.mjs

@@ -2,7 +2,7 @@ import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs"
 import { tmpdir } from "os";
 import { dirname, join, resolve } from "path";
 import { fileSetFromDir, delegateTokenFromEnv } from "#sdk/node";
-import { allowanceAuthHeaders, resolveProjectId, updateProject } from "./config.mjs";
+import { walletAuthHeaders, resolveProjectId, updateProject } from "./config.mjs";
 import { resolveFilePathsInManifest } from "./manifest.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
@@ -64,7 +64,7 @@ Notes:
   - Progress events are emitted as JSON-line objects on stderr by default
     (one object per line). Final result envelope goes to stdout. Pass --quiet
     to silence stderr.
-  - Free with active tier - requires allowance auth
+  - Free with active tier - requires SIWX auth
 `;
 
 const SUB_HELP = {
@@ -90,7 +90,7 @@ Manifest format (JSON):
 
 Notes:
   - Must include at least index.html in the files array
-  - Free with active tier - requires allowance auth
+  - Free with active tier - requires SIWX auth
 
 Examples:
   run402 sites deploy --manifest site.json
@@ -139,7 +139,7 @@ Progress events:
 Notes:
   - Re-deploying an unchanged tree makes no S3 PUTs (returns immediately
     with bytes_uploaded: 0)
-  - Free with active tier - requires allowance auth
+  - Free with active tier - requires SIWX auth
 
 Examples:
   run402 sites deploy-dir ./dist --project prj_abc
@@ -219,10 +219,10 @@ async function deploy(args) {
   const manifest = JSON.parse(raw);
   if (opts.manifest) resolveFilePathsInManifest(manifest, dirname(resolve(opts.manifest)));
 
-  // Preserve the aggressive early exit when no allowance is configured.
+  // Preserve the aggressive early exit when no local wallet is configured.
   // A delegate holds `deploy` and /apply/v1/plans accepts it; refusing locally
   // would tell a wallet-less holder to run `run402 init` (see 4.11.2).
-  if (!delegateTokenFromEnv()) allowanceAuthHeaders("/apply/v1/plans");
+  if (!delegateTokenFromEnv()) walletAuthHeaders("/apply/v1/plans");
 
   const stage = stageFilesToTempDir(manifest.files || []);
   try {
@@ -288,10 +288,10 @@ async function deployDir(args) {
   const projectId = resolveProjectId(opts.project);
   if (opts.target !== undefined) failUnsupportedTarget();
 
-  // Preserve the aggressive early exit when no allowance is configured.
+  // Preserve the aggressive early exit when no local wallet is configured.
   // A delegate holds `deploy` and /apply/v1/plans accepts it; refusing locally
   // would tell a wallet-less holder to run `run402 init` (see 4.11.2).
-  if (!delegateTokenFromEnv()) allowanceAuthHeaders("/apply/v1/plans");
+  if (!delegateTokenFromEnv()) walletAuthHeaders("/apply/v1/plans");
 
   let fileSet;
   try {

package/lib/stats.mjs

@@ -8,7 +8,7 @@
  * line per request to stderr, automatically, for every SDK caller (CLI, MCP,
  * `git-remote-run402`). This module is the thin CLI-edge reader of that
  * per-instance accumulator: it turns `sdk.stats()` into the `stats` envelope
- * field every `repos` verb's result and `deploy apply`'s final result carry
+ * field every `repos` verb's result and `deploy`'s final result carry
  * (always on), plus the `-v`/`--verbose` stderr summary line.
  *
  * `sdk.stats()` reflects only calls made through the ONE `Run402` instance
@@ -47,7 +47,7 @@ function writeVerboseStatsLine(sdk) {
 /**
  * One stderr summary line, only when verbose was requested. Coexists with
  * `--human`. `verbose` is either normalized argv (checked for `-v`/
- * `--verbose`) or a plain boolean, for callers (e.g. `deploy apply`) that
+ * `--verbose`) or a plain boolean, for callers (e.g. `deploy`) that
  * already parsed their own flags into an options object.
  */
 export function printVerboseStats(verbose, sdk) {

package/lib/status.mjs

@@ -1,6 +1,6 @@
 import { readRemoteStatus } from "#sdk/node";
 import {
-  readAllowance,
+  readWallet,
   loadKeyStore,
   getActiveProjectId,
   apiBase,
@@ -21,8 +21,8 @@ Usage:
 Displays:
   - Wallet identity (local_label, server_label, address)
   - Payment rail (x402 | mpp)
-  - Balances (on_chain_usd_micros + on_chain_token, prepaid_credit_usd_micros, held_usd_micros)
-  - Tier subscription (name, status, expiry)
+  - Balances (on_chain_usd_micros + on_chain_token, allowance_usd_micros, held_usd_micros)
+  - Tier and lease (name, status, expiry)
   - Projects (from server, with fallback to local keystore)
   - Active project ID
   - Active API target
@@ -31,11 +31,11 @@ Output is JSON by default. --json is accepted as a compatibility no-op.
 --human renders a compact human summary instead (wallet, API target, tier,
 active project, balance, and the next action); it cannot be combined with
 --json.
-Run402 Cloud status requires an allowance; Core target status can still report
+Run402 Cloud status requires a wallet; Core target status can still report
 local project state without one.
 `;
 
-// USDC / pathUSD constants (match allowance.mjs)
+// USDC / pathUSD constants (match wallet.mjs)
 const USDC_ABI = [{ name: "balanceOf", type: "function", stateMutability: "view", inputs: [{ name: "account", type: "address" }], outputs: [{ name: "", type: "uint256" }] }];
 const USDC_MAINNET = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
 const USDC_SEPOLIA = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
@@ -105,13 +105,13 @@ export async function run(args = []) {
       hint: "JSON is the default; drop --json to keep it, or keep --human alone for the rendered view.",
     });
   }
-  const allowance = readAllowance();
+  const localWallet = readWallet();
   const target = {
     api_base: apiBase(),
     api_base_source: apiBaseSource(),
     kind: apiTargetKind(),
   };
-  if (!allowance) {
+  if (!localWallet) {
     const store = loadKeyStore();
     const bare = {
       wallet: null,
@@ -128,16 +128,16 @@ export async function run(args = []) {
     return;
   }
 
-  const wallet = allowance.address.toLowerCase();
-  const rail = allowance.rail || "x402";
+  const wallet = localWallet.address.toLowerCase();
+  const rail = localWallet.rail || "x402";
 
-  // Parallel API calls: tier + billing balance + server-side projects + on-chain wallet balance.
+  // Parallel API calls: tier + allowance + server-side projects + on-chain wallet balance.
   // projects.list() is the membership-scoped named inventory (project-findability);
-  // SIWX wallet auth is signed from the allowance. Best-effort — a missing
-  // allowance yields null and we fall back to the local keystore below.
+  // SIWX wallet auth is signed from the wallet. Best-effort — a missing
+  // wallet yields null and we fall back to the local keystore below.
   const [status, walletBalance] = await Promise.all([
     readRemoteStatus(getSdk(), wallet),
-    readWalletBalanceUsdMicros(rail, allowance.address),
+    readWalletBalanceUsdMicros(rail, localWallet.address),
   ]);
   const { tier, billing, remote } = status;
 
@@ -155,18 +155,18 @@ export async function run(args = []) {
   const walletName = getActiveProfile();
   const walletMeta = readMeta(walletName);
 
-  // Balances are grouped under one object so the on-chain and
-  // prepaid-credit numbers are unambiguous and rail-legible.
+  // Balances are grouped under one object so the on-chain (wallet) and
+  // allowance numbers are unambiguous and rail-legible.
   //   - on_chain_usd_micros / on_chain_token: on-chain USDC (x402) or pathUSD
-  //     (mpp), null if the RPC read failed
-  //   - prepaid_credit_usd_micros / held_usd_micros: Run402-held credits,
-  //     rail-independent, null when no organization exists
+  //     (mpp) in the wallet, null if the RPC read failed
+  //   - allowance_usd_micros / held_usd_micros: the organization's Run402-held
+  //     allowance, rail-independent, null when no organization exists
   const hasBilling = billing && billing.exists !== false;
   const result = {
     wallet: {
       local_label: walletName,
       server_label: walletMeta?.label ?? null,
-      address: allowance.address,
+      address: localWallet.address,
     },
     rail,
     remote_status: status.availability,
@@ -175,7 +175,7 @@ export async function run(args = []) {
     balances: {
       on_chain_usd_micros: walletBalance,
       on_chain_token: rail === "mpp" ? "pathUSD" : "USDC",
-      prepaid_credit_usd_micros: hasBilling ? billing.available_usd_micros : null,
+      allowance_usd_micros: hasBilling ? billing.allowance_usd_micros : null,
       held_usd_micros: hasBilling ? (billing.held_usd_micros ?? 0) : null,
     },
     tier: tier && tier.tier
@@ -205,7 +205,7 @@ function usdFromMicros(micros) {
 
 /**
  * The one next action for the human view, derived from the same state the
- * JSON carries. Mirrors `init`: `run402 up -y` subscribes the prototype tier
+ * JSON carries. Mirrors `init`: `run402 up -y` sets the prototype tier
  * itself as part of the first deploy, so a tier-less account gets ONE command.
  */
 function statusNextAction(result) {
@@ -214,7 +214,7 @@ function statusNextAction(result) {
   }
   if (result.remote_status?.tier?.state === "unavailable") return "Check connectivity/authentication and retry run402 status; tier state is unavailable.";
   if (!result.tier) {
-    return "run402 up -y  (subscribes the prototype tier, free on testnet, as part of the first deploy; or: run402 tier set prototype)";
+    return "run402 up -y  (sets the prototype tier, free on testnet, as part of the first deploy; or: run402 tier set prototype)";
   }
   if (!result.active_project) {
     return "run402 up --name <name> -y  (or select an existing project: run402 projects use <project_id>)";
@@ -230,7 +230,7 @@ function statusNextAction(result) {
 export function formatStatusHuman(result) {
   const lines = [];
   if (!result.wallet) {
-    lines.push("Wallet:   none (no allowance on this machine)");
+    lines.push("Wallet:   none (no local wallet on this machine)");
   } else {
     const label = result.wallet.server_label
       ? `${result.wallet.local_label} (${result.wallet.server_label})`
@@ -262,8 +262,8 @@ export function formatStatusHuman(result) {
     const parts = [];
     const onChain = usdFromMicros(result.balances.on_chain_usd_micros);
     if (onChain) parts.push(`${onChain} ${result.balances.on_chain_token} on-chain`);
-    const credit = usdFromMicros(result.balances.prepaid_credit_usd_micros);
-    if (credit) parts.push(`${credit} prepaid credit`);
+    const allowance = usdFromMicros(result.balances.allowance_usd_micros);
+    if (allowance) parts.push(`${allowance} allowance`);
     if (parts.length) lines.push(`Balance:  ${parts.join(", ")}`);
   }
   lines.push(`Next:     ${statusNextAction(result)}`);

package/lib/subdomains.mjs

@@ -9,16 +9,16 @@ Usage:
   run402 subdomains <subcommand> [args...]
 
 Subcommands:
-  claim  <name> [--project <id>] [--release <id> | --deployment <id>]   Claim a subdomain
+  add    <name> [--project <project_id>] [--release <release_id> | --deployment <deployment_id>]   Add a subdomain
   delete <name> --confirm [--project <id>]                              Release a subdomain. Requires --confirm.
   list   [--project <id>]                                               List subdomains for a project
 
 Options default to the active project. With neither --release nor
---deployment, claim binds the project's live release.
+--deployment, add binds the project's live release.
 
 Examples:
-  run402 subdomains claim myapp
-  run402 subdomains claim myapp --release rel_abc123 --project prj_abc123
+  run402 subdomains add myapp
+  run402 subdomains add myapp --release rel_abc123 --project prj_abc123
   run402 subdomains delete myapp --confirm
   run402 subdomains list
 
@@ -29,10 +29,10 @@ Notes:
 `;
 
 const SUB_HELP = {
-  claim: `run402 subdomains claim — Claim a custom subdomain for a release
+  add: `run402 subdomains add — Add a subdomain for a release
 
 Usage:
-  run402 subdomains claim <name> [--project <id>] [--release <id> | --deployment <id>]
+  run402 subdomains add <name> [--project <project_id>] [--release <release_id> | --deployment <deployment_id>]
 
 Arguments:
   <name>              Subdomain name (3-63 chars, lowercase alphanumeric +
@@ -51,10 +51,10 @@ Notes:
   - A deploy manifest can declare the same thing: "subdomains": { "set": ["<name>"] }
 
 Examples:
-  run402 subdomains claim myapp
-  run402 subdomains claim myapp --release rel_abc123 --project prj_abc123
+  run402 subdomains add myapp
+  run402 subdomains add myapp --release rel_abc123 --project prj_abc123
 `,
-  list: `run402 subdomains list — List subdomains claimed by a project
+  list: `run402 subdomains list — List a project's subdomains
 
 Usage:
   run402 subdomains list [--project <id>]
@@ -66,7 +66,7 @@ Examples:
   run402 subdomains list
   run402 subdomains list --project prj_abc123
 `,
-  delete: `run402 subdomains delete — Release a claimed subdomain
+  delete: `run402 subdomains delete — Release a subdomain
 
 Usage:
   run402 subdomains delete <name> --confirm [--project <id>]
@@ -76,7 +76,7 @@ Arguments:
 
 Options:
   --confirm           Required: releasing a subdomain is irreversible and
-                      makes it available for any other project to claim
+                      makes it available for any other project to add
   --project <id>      Project ID (defaults to the active project)
 
 Examples:
@@ -85,7 +85,7 @@ Examples:
 `,
 };
 
-async function claim(args) {
+async function add(args) {
   const parsedArgs = normalizeArgv(args);
   const valueFlags = ["--project", "--deployment", "--release"];
   assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
@@ -99,8 +99,8 @@ async function claim(args) {
   if (positionals.length > 1) {
     fail({
       code: "BAD_USAGE",
-      message: `Unexpected argument for subdomains claim: ${positionals[1]}`,
-      hint: "Use `run402 subdomains claim <name> [--release <rel_id>]`.",
+      message: `Unexpected argument for subdomains add: ${positionals[1]}`,
+      hint: "Use `run402 subdomains add <name> [--release <rel_id>]`.",
     });
   }
   if (positionals.length === 1) {
@@ -110,14 +110,14 @@ async function claim(args) {
     fail({
       code: "BAD_USAGE",
       message: "Missing <name>.",
-      hint: "run402 subdomains claim <name> [--project <id>] [--release <id> | --deployment <id>]",
+      hint: "run402 subdomains add <name> [--project <project_id>] [--release <release_id> | --deployment <deployment_id>]",
     });
   }
   if (opts.deployment && opts.release) {
     fail({
       code: "BAD_USAGE",
       message: "Pass either --release or --deployment, not both.",
-      hint: "run402 subdomains claim <name> [--release <id> | --deployment <id>]",
+      hint: "run402 subdomains add <name> [--release <id> | --deployment <id>]",
     });
   }
   const projectId = resolveProjectId(opts.project);
@@ -129,7 +129,7 @@ async function claim(args) {
   const deploymentId = opts.deployment || (opts.release ? undefined : p.last_deployment_id) || undefined;
   const releaseId = opts.release || undefined;
   try {
-    const data = await getSdk().subdomains.claim({ name, deploymentId, releaseId, projectId });
+    const data = await getSdk().subdomains.add({ name, deploymentId, releaseId, projectId });
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -156,7 +156,7 @@ async function deleteSubdomain(allArgs) {
   if (!argList.includes("--confirm")) {
     fail({
       code: "CONFIRMATION_REQUIRED",
-      message: `Destructive: releasing subdomain '${name}' makes it available for any other project to claim. This is irreversible. Re-run with --confirm to proceed.`,
+      message: `Destructive: releasing subdomain '${name}' makes it available for any other project to add. This is irreversible. Re-run with --confirm to proceed.`,
       details: { name },
     });
   }
@@ -202,7 +202,7 @@ export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
   if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) { console.log(SUB_HELP[sub] || HELP); process.exit(0); }
   switch (sub) {
-    case "claim": await claim(args); break;
+    case "add": await add(args); break;
     case "delete": await deleteSubdomain(args); break;
     case "list":   await list(args); break;
     default: