run402 4.93.1 → 4.94.0

package/lib/login.mjs

@@ -0,0 +1,207 @@
+/**
+ * `run402 login [--device] [--no-open]` — sign a person in. See sign-in.mjs.
+ */
+
+import { setTimeout as sleep } from "node:timers/promises";
+import { fail, reportSdkError } from "./sdk-errors.mjs";
+import { getSdk } from "./sdk.mjs";
+import { normalizeArgv, hasHelp, assertKnownFlags, positionalArgs } from "./argparse.mjs";
+import {
+  saveControlPlaneSession,
+  controlPlaneSessionFromTokenResponse,
+  clearRetiredSessionCaches,
+} from "../core-dist/control-plane-session.js";
+import { clearApprovals } from "../core-dist/write-approvals.js";
+import { openBrowser, pkce, sessionView, startLoopbackServer } from "./sign-in.mjs";
+
+const HELP = `run402 login — sign in as a person (your sign-in session)
+
+Usage:
+  run402 login [--no-open]            browser passkey sign-in (full session)
+  run402 login --device [--no-open]   device code for a terminal with no browser (read-only)
+
+A person signs in; an agent's wallet is a separate identity ('run402 status').
+'run402 login' opens the browser, where you sign in with your passkey, and
+catches the redirect on a 127.0.0.1 port. The session it caches can write,
+and step-up works on it. 'run402 login --device' prints a code you approve in
+the console from any device; that session can only read (every write answers
+SESSION_READ_ONLY).
+
+Provisioning, deploying, and writing secrets without a wallet also need a
+write approval: 'run402 approve --action <capability> (--org <org_id> |
+--project <project_id>)'. From a terminal the CLI opens it for you.
+
+Options:
+  --device   Use the device-code flow (RFC 8628) instead of the browser redirect.
+  --no-open  Do not open the browser; print the URL only.
+
+Notes:
+  - The session is cached at the base config dir, shared across named wallets.
+  - JSON to stdout; the URL and code to open go to stderr.
+  - 'run402 whoami' shows the session's grade; 'run402 logout' ends it.
+`;
+
+const CLIENT_NAME = "run402 CLI";
+
+/** Cache a freshly minted session; a new session invalidates every approval bound to the old one. */
+function cacheSession(tokenResponse) {
+  const cached = controlPlaneSessionFromTokenResponse(tokenResponse);
+  clearApprovals();
+  clearRetiredSessionCaches();
+  saveControlPlaneSession(cached);
+  return cached;
+}
+
+/** Best-effort: surface org memberships (auto-redeemed invites land here). Never fails the login. */
+async function attachMemberships(view, token) {
+  try {
+    const who = await getSdk().session.whoami({ token });
+    const memberships = Array.isArray(who?.memberships) ? who.memberships : [];
+    view.memberships = memberships;
+    if (memberships.length) {
+      process.stderr.write(
+        `Member of ${memberships.length} org(s):\n` +
+          memberships.map((m) => `  - ${m.display_name || m.org_id || "unknown"} (${m.role}, ${m.status})`).join("\n") +
+          "\n",
+      );
+    }
+  } catch {
+    /* best-effort — the session is valid regardless of the whoami result */
+  }
+}
+
+async function loopbackLogin({ noOpen }) {
+  const sdk = getSdk();
+  const { codeVerifier, codeChallenge, state, nonce } = pkce();
+  const { ready, codePromise, close } = startLoopbackServer({ expectedState: state, timeoutMs: 300_000 });
+
+  let port;
+  try {
+    port = await ready;
+  } catch (err) {
+    close();
+    return fail({ code: "LOOPBACK_FAILED", message: `Could not start the loopback server: ${err.message}` });
+  }
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  const authorizeUrl = sdk.session.buildCliAuthorizeUrl({ redirectUri, codeChallenge, state, nonce });
+
+  process.stderr.write(`\nTo sign in, open:\n  ${authorizeUrl}\n\n`);
+  if (!noOpen && process.stderr.isTTY) {
+    openBrowser(authorizeUrl);
+    process.stderr.write("(opening your browser…)\n\n");
+  }
+  process.stderr.write("Waiting for approval…\n");
+
+  let code;
+  try {
+    code = await codePromise;
+  } catch (err) {
+    close();
+    return fail({ code: "LOGIN_FAILED", message: err.message, hint: "Run 'run402 login' to try again." });
+  }
+
+  let session;
+  try {
+    session = await sdk.session.exchangeCliToken({ code, codeVerifier, redirectUri, state });
+  } catch (err) {
+    close();
+    return reportSdkError(err);
+  }
+  // The loopback server has done its job. Tear it down (destroying any
+  // keep-alive socket) so Node's event loop drains and the CLI exits instead
+  // of hanging until Ctrl+C.
+  close();
+
+  const cached = cacheSession(session);
+  process.stderr.write(`\nSigned in (grade: ${cached.grade}).\n`);
+  const view = sessionView(cached);
+  await attachMemberships(view, session.control_plane_session_token);
+  console.log(JSON.stringify(view));
+}
+
+async function deviceLogin({ noOpen }) {
+  const sdk = getSdk();
+  let start;
+  try {
+    start = await sdk.session.deviceStart();
+  } catch (err) {
+    return reportSdkError(err);
+  }
+
+  // Human-in-the-loop prompt → stderr, so stdout stays clean for the final JSON.
+  const target = start.verification_uri_complete || start.verification_uri;
+  process.stderr.write(
+    `\nTo authorize the ${CLIENT_NAME}, open:\n  ${start.verification_uri}\n` +
+      `and enter the code:  ${start.user_code}\n\n`,
+  );
+  if (!noOpen && process.stderr.isTTY) {
+    openBrowser(target);
+    process.stderr.write("(opening your browser…)\n\n");
+  }
+  process.stderr.write("Waiting for approval…\n");
+
+  // Poll loop — honor the server interval, back off on slow_down, and stop at
+  // the device-code deadline. if/else (not switch) so the sync scanner doesn't
+  // mistake the poll states for CLI subcommands.
+  let intervalMs = Math.max(1, Number(start.interval) || 5) * 1000;
+  const deadline = Date.now() + Math.max(1, Number(start.expires_in) || 600) * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    let result;
+    try {
+      result = await sdk.session.devicePoll(start.device_code);
+    } catch (err) {
+      return reportSdkError(err);
+    }
+    if (result.kind === "approved") {
+      const cached = cacheSession(result.session);
+      process.stderr.write(`\nSigned in (grade: ${cached.grade}, read-only).\n`);
+      const view = sessionView(cached);
+      await attachMemberships(view, result.session.control_plane_session_token);
+      console.log(JSON.stringify(view));
+      return;
+    }
+    if (result.kind === "authorization_pending") continue;
+    if (result.kind === "slow_down") {
+      intervalMs += 5000;
+      continue;
+    }
+    if (result.kind === "access_denied") {
+      fail({
+        code: "LOGIN_DENIED",
+        message: "Authorization was denied in the browser.",
+        hint: "Run 'run402 login --device' to try again.",
+      });
+    }
+    if (result.kind === "expired_token") {
+      fail({
+        code: "LOGIN_EXPIRED",
+        message: "The device code expired before approval.",
+        hint: "Run 'run402 login --device' to get a fresh code.",
+      });
+    }
+    fail({ code: "LOGIN_FAILED", message: `Unexpected device poll result: ${result.kind}` });
+  }
+  fail({
+    code: "LOGIN_TIMEOUT",
+    message: "Timed out waiting for browser approval.",
+    hint: "Run 'run402 login --device' to try again.",
+  });
+}
+
+export async function run(args = []) {
+  args = normalizeArgv(args);
+  if (hasHelp(args)) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  assertKnownFlags(args, ["--help", "-h", "--no-open", "--device"]);
+  const extra = positionalArgs(args, []);
+  if (extra.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for login: ${extra[0]}`, hint: "Use `run402 login [--device] [--no-open]`." });
+  }
+  const noOpen = args.includes("--no-open");
+  if (args.includes("--device")) return deviceLogin({ noOpen });
+  return loopbackLogin({ noOpen });
+}

package/lib/logout.mjs

@@ -0,0 +1,53 @@
+/**
+ * `run402 logout` — end the sign-in session server-side and clear the local
+ * session and write-approval caches. See sign-in.mjs.
+ */
+
+import { fail } from "./sdk-errors.mjs";
+import { getSdk } from "./sdk.mjs";
+import { normalizeArgv, hasHelp, assertKnownFlags, positionalArgs } from "./argparse.mjs";
+import {
+  loadLiveControlPlaneSession,
+  clearControlPlaneSession,
+  clearRetiredSessionCaches,
+} from "../core-dist/control-plane-session.js";
+import { clearApprovals } from "../core-dist/write-approvals.js";
+
+const HELP = `run402 logout — end your sign-in session
+
+Usage:
+  run402 logout
+
+Revokes the cached sign-in session on the gateway, then deletes it and every
+cached write approval from this machine. The local cache is cleared even when
+the revoke cannot reach the gateway. A wallet is not affected.
+`;
+
+export async function run(args = []) {
+  args = normalizeArgv(args);
+  if (hasHelp(args)) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  assertKnownFlags(args, ["--help", "-h"]);
+  const extra = positionalArgs(args, []);
+  if (extra.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for logout: ${extra[0]}`, hint: "Use `run402 logout`." });
+  }
+  const session = loadLiveControlPlaneSession();
+  let revoked = false;
+  if (session) {
+    try {
+      await getSdk().session.revoke({ token: session.control_plane_session_token });
+      revoked = true;
+    } catch {
+      // Best-effort: a failed server revoke (expired token, offline) must not
+      // block clearing the local cache. The local token is removed regardless.
+      revoked = false;
+    }
+  }
+  clearControlPlaneSession();
+  clearApprovals();
+  clearRetiredSessionCaches();
+  console.log(JSON.stringify({ revoked, cleared: true }));
+}

package/lib/next-actions.mjs

@@ -35,7 +35,7 @@ export function retryAction(command, why) {
 export function initializeWalletAction() {
   return nextAction("initialize_wallet", {
     command: "run402 init",
-    why: "Create and fund an agent allowance, then retry.",
+    why: "Create and fund a local wallet, then retry.",
   });
 }
 
@@ -56,54 +56,54 @@ export function selectProjectAction() {
 export function setTierAction(tier = "prototype") {
   return nextAction("renew_tier", {
     command: `run402 tier set ${tier}`,
-    why: "Subscribe the account to a tier (free on testnet), then retry.",
+    why: "Set a tier for the organization (prototype is free), then retry.",
   });
 }
 
 export function deployAction() {
   return nextAction("deploy", {
-    command: "run402 deploy apply --manifest app.json",
-    why: "Apply your release manifest to deploy.",
+    command: "run402 deploy --manifest app.json",
+    why: "Deploy your release manifest.",
   });
 }
 
 /**
  * The cold-start deploy when the account holds no tier yet: `run402 up -y`
- * subscribes the prototype tier itself as part of the first deploy, so `init`
+ * sets the prototype tier itself as part of the first deploy, so `init`
  * hands the agent ONE command instead of `tier set` + a separate deploy.
  * `tier set prototype` stays named as the standalone alternative.
  */
 export function upDeployAction() {
   return nextAction("deploy", {
     command: "run402 up -y",
-    why: "Deploy with run402 up -y — it subscribes the prototype tier (free on testnet) as part of the first deploy. Or subscribe separately: run402 tier set prototype.",
+    why: "Deploy with run402 up -y — it sets the prototype tier (free on testnet) as part of the first deploy. Or set it separately: run402 tier set prototype.",
   });
 }
 
 /**
- * `repos create` (and `gitvault init`) on an org with no claimed slug: the
+ * `repos create` (and `gitvault init`) on an org with no slug set: the
  * response's `address: null` had no pointer to WHY, or to the named-addressing
  * feature at all. Owner-only. Wording deliberately
  * omits a price: the first slug per org is free, and renames/re-claims cost
  * $1 — a gateway change lands the fee separately, so this stays true under
  * both the old and new pricing rule.
  */
-export function claimOrgSlugAction() {
-  return nextAction("claim_org_slug", {
+export function setOrgSlugAction() {
+  return nextAction("set_org_slug", {
     command: "run402 org slug <slug>",
-    why: "This organization has no claimed slug yet, so its repos have no run402::<slug>/<name> address. Owner-only.",
+    why: "This organization has no slug set yet, so its repos have no run402::<slug>/<name> address. Owner-only.",
   });
 }
 
 /**
  * The org already has a slug, but this project's address-form repo name was
- * not claimed this time (a collision, or the best-effort claim failed for
- * some other reason) — point at the explicit claim verb instead of leaving
+ * not set this time (a collision, or the best-effort set failed for
+ * some other reason) — point at the explicit set verb instead of leaving
  * `address: null` unexplained.
  */
-export function claimRepoNameAction(projectId) {
-  return nextAction("claim_repo_name", {
+export function setRepoNameAction(projectId) {
+  return nextAction("set_repo_name", {
     command: `run402 repos name <name> --project ${projectId}`,
-    why: "The owning organization has a slug, but this project has no claimed address-form name yet.",
+    why: "The owning organization has a slug, but this project has no address-form name set yet.",
   });
 }

package/lib/org.mjs

@@ -33,6 +33,7 @@ Usage:
   run402 org rename [<org_id>] --name <display_name>   (or: --clear to remove the label)
   run402 org payout-wallet [<org_id>] <wallet_address>  (or: --clear to remove the explicit default)
   run402 org slug   <slug> [--org <org_id>]
+  run402 org adopt  [--org <org_id>] [--name <label>]
   run402 org whoami
   run402 org whoami --set-name <name>
   run402 org use     <org_id>
@@ -59,11 +60,11 @@ The second attribute may also be passed positionally (run402 org member add <wal
 
 Subcommands:
   create      Create an empty org on the prototype tier (you become owner)
-  list        Orgs you are a member of
+  list        Your orgs: role, tier, lifecycle, quotas, allowance, advisories
   get         Read one org (label + tier/lease + your role)
   rename      Set or clear an org's display label (owner-only)
   slug        Claim or rename the org's globally-unique, address-form slug
-              (owner-only). A genesis claim spends a one-time claim fee; a
+              (owner-only). A genesis set spends a one-time fee; a
               rename releases the old slug into a ~90-day cooldown.
   use         Select the current org for this wallet profile
   current     Report the resolved current org and where it came from
@@ -110,10 +111,19 @@ created org's prototype tier plus lease_started_at / lease_expires_at. Paid
 tiers are a separate flow. Step-up gated for control-plane sessions; the
 free-org cap may apply.
 `,
-  list: `run402 org list — orgs you are a member of
+  list: `run402 org list — your orgs, with the account overview
 
 Usage:
   run402 org list
+
+Lists every org you are a member of (GET /orgs/v1) and joins each row with
+the account overview (GET /agent/v1/me/overview): tier, lifecycle state,
+lease, quotas, allowance. The output also carries the overview's wallets,
+rollup, and advisories, plus scope and session (the sign-in session's grade,
+or null when a wallet reads). Both reads use the CLI's credential: the active
+wallet when there is one, else the sign-in session from 'run402 login'. When the overview
+read is refused (a grant key, for one), the memberships still print and
+'overview' is null.
 `,
   get: `run402 org get — read one org (label + tier/lease + your role)
 
@@ -135,17 +145,17 @@ Legacy (still supported):
 Owner-only + step-up gated. Pass --clear (or an empty display_name) to remove
 the label. Output includes the updated tier and lease timestamps.
 `,
-  slug: `run402 org slug — claim or rename the org's address-form slug
+  slug: `run402 org slug — set or rename the org's address-form slug
 
 Usage:
   run402 org slug <slug> [--org <org_id>] [--idempotency-key <key>]
 
-The slug is a globally-unique, claimable, address-form handle for the org
+The slug is a globally-unique, address-form handle for the org
 (repo-first-onramp design D6) — the <org-slug> half of a named repo address
 run402::<org-slug>/<name>. Grammar: lowercase [a-z0-9-], no leading/trailing/
 double hyphen, max 39 chars. Owner-only.
 
-A genesis claim (the org had no prior slug) spends a one-time claim fee off
+A genesis set (the org had no prior slug) spends a one-time fee off
 the org's balance. A rename is free but releases the OLD slug into a ~90-day
 cooldown: it stops resolving, with a typed SLUG_RELEASED refusal naming the
 new slug as successor — there is no redirect, so update every remote and
@@ -330,11 +340,35 @@ async function list(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, ["--help", "-h"]);
   requirePositionalCount(a, [], { min: 0, max: 0, command: "run402 org list" });
+  const sdk = getSdk();
+  let orgs;
   try {
-    console.log(JSON.stringify({ orgs: await getSdk().orgs.list() }, null, 2));
+    orgs = await sdk.orgs.list();
   } catch (err) {
-    reportSdkError(err);
+    return reportSdkError(err);
+  }
+  // The account overview is the richer read, made with the same credential as
+  // the membership list; a caller the overview does not accept (a grant key)
+  // still gets its memberships.
+  let overview = null;
+  try {
+    overview = await sdk.me.overview();
+  } catch {
+    overview = null;
   }
+  const byId = new Map((overview?.organizations ?? []).map((o) => [o.id, o]));
+  console.log(JSON.stringify({
+    orgs: orgs.map((m) => (byId.has(m.org_id) ? { ...m, overview: byId.get(m.org_id) } : m)),
+    ...(overview
+      ? {
+          scope: overview.scope ?? null,
+          session: overview.session ?? null,
+          rollup: overview.rollup ?? null,
+          wallets: overview.wallets ?? [],
+          advisories: overview.advisories ?? [],
+        }
+      : { overview: null }),
+  }, null, 2));
 }
 
 async function whoami(args) {
@@ -555,13 +589,65 @@ async function payoutWallet(args) {
 }
 
 /**
- * `run402 org slug <slug>` — claim or rename the org's address-form slug.
- * Owner-only, and a genesis claim spends a one-time claim fee — this is a
+ * `run402 org slug <slug>` — set or rename the org's address-form slug.
+ * Owner-only, and a genesis set spends a one-time fee — this is a
  * PAID, side-effecting mutation, so it
  * requires `Idempotency-Key`; the SDK generates one client-side when
  * `--idempotency-key` is omitted, so a retried call after a dropped response
  * can never double-bill.
  */
+/**
+ * `run402 org adopt` — become the owner of the org your wallet's agent
+ * created (an ownership transfer on org memberships; the wallet stays on the
+ * agent, which is downgraded to developer). Dual proof: the write-capable
+ * sign-in session + a fresh signature from the active wallet over a server
+ * nonce. The Node convenience runs the whole dance (read session → challenge
+ * → sign → submit). Step-up failures and the multi-org `select_org`
+ * round-trip are surfaced here, not thrown at the user.
+ */
+async function adopt(args) {
+  const a = normalizeArgv(args);
+  const valueFlags = ["--org", "--name"];
+  assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
+  requirePositionalCount(a, valueFlags, { min: 0, max: 0, command: "run402 org adopt [--org <org_id>] [--name <label>]" });
+  const orgId = flagValue(a, "--org");
+  const name = flagValue(a, "--name");
+  try {
+    const { adoptOrg } = await import("#sdk/node");
+    const result = await adoptOrg(getSdk(), {
+      orgId: orgId ?? undefined,
+      displayName: name ?? undefined,
+    });
+    // CLI output contract (cli-output-shape): no top-level `status` envelope.
+    // The gateway's discriminator becomes an explicit `adopted` boolean.
+    if (result && result.status === "select_org") {
+      console.log(JSON.stringify({
+        adopted: false,
+        selectable_orgs: result.selectable_orgs,
+        hint: "Your wallet's agent owns more than one org. Re-run with --org <org_id> to adopt one.",
+      }, null, 2));
+      return;
+    }
+    console.log(JSON.stringify({
+      adopted: true,
+      org_id: result.org_id,
+      display_name: result.display_name,
+      role: result.role,
+      already_owned: result.already_owned ?? false,
+    }, null, 2));
+  } catch (err) {
+    const { isStepUpRequired } = await import("#sdk/node");
+    if (isStepUpRequired(err)) {
+      return fail({
+        code: "STEP_UP_REQUIRED",
+        message: "Adopting an org needs a fresh passkey step-up.",
+        hint: "Run 'run402 login' (a fresh passkey sign-in), then re-run 'run402 org adopt'.",
+      });
+    }
+    reportSdkError(err);
+  }
+}
+
 async function slug(args) {
   const a = normalizeArgv(args);
   const valueFlags = ["--org", "--idempotency-key"];
@@ -576,16 +662,16 @@ async function slug(args) {
   if (!org) {
     fail({
       code: "ORG_UNRESOLVED",
-      message: "Could not resolve which organization to claim this slug for.",
+      message: "Could not resolve which organization to set this slug for.",
       hint: "Pass --org <org_id>, or select one first with `run402 org use <id>`.",
     });
   }
   const idempotencyKey = flagValue(a, "--idempotency-key");
   try {
-    const result = await getSdk().org(org.orgId).claimSlug(newSlug, idempotencyKey != null ? { idempotencyKey } : {});
+    const result = await getSdk().org(org.orgId).setSlug(newSlug, idempotencyKey != null ? { idempotencyKey } : {});
     console.log(JSON.stringify(result, null, 2));
     if (result.created) {
-      console.error(`slug "${result.slug}" claimed for ${org.orgId} — a one-time claim fee was debited from the org's balance.`);
+      console.error(`slug "${result.slug}" set for ${org.orgId} — a one-time fee was debited from the org's balance.`);
     } else if (result.previous_slug && result.previous_slug !== result.slug) {
       console.error(
         `org ${org.orgId} renamed from "${result.previous_slug}" to "${result.slug}" — no fee. ` +
@@ -894,6 +980,7 @@ export async function run(sub, args) {
     case "rename": await rename(args); break;
     case "payout-wallet": await payoutWallet(args); break;
     case "slug": await slug(args); break;
+    case "adopt": await adopt(args); break;
     case "whoami": await whoami(args); break;
     case "use": await use(args); break;
     case "current": await current(args); break;

package/lib/pay.mjs

@@ -30,7 +30,7 @@ Examples:
   run402 pay https://seller.example/translate --method POST \
     --body '{"text":"hello"}' --max-usd 0.05 --idempotency-key translation:1
 
-The command uses the same allowance wallet and bounded x402 buyer as the SDK.
+The command uses the same wallet and bounded x402 buyer as the SDK.
 An unpriced URL is passed through with payment: null.
 On trusted Run402 PAYMENT_INTENT_PENDING, wait for Retry-After and repeat this
 identical command with the same payer and --idempotency-key. Never change the key.

package/lib/projects.mjs

@@ -1,8 +1,7 @@
 import { readFileSync } from "fs";
-import { allowanceAuthHeaders, resolveProjectId, getActiveProjectId, isCoreApiTarget } from "./config.mjs";
-import { loadLiveOperatorSession } from "../core-dist/operator-session.js";
+import { walletAuthHeaders, resolveProjectId, getActiveProjectId, isCoreApiTarget } from "./config.mjs";
 import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
-import { withAutoApprove } from "./operator.mjs";
+import { withAutoApprove } from "./sign-in.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail, parseFlagJson } from "./sdk-errors.mjs";
 import { stampOrgFromProject } from "./org-context.mjs";
@@ -76,15 +75,15 @@ Notes:
     Local project keys live under 'run402 credentials project-keys ...'.
   - 'list' is a SERVER read, not the local key cache: it shows every project the
     active wallet can reach (membership-scoped), with name, site_url, custom
-    domains, and org_id. '--org <id>' filters to one org; '--all' reads the
-    cross-wallet inventory for every wallet controlling your operator email
-    (run 'run402 operator login' first for the union, else it falls back to the
-    current wallet's slice). The 'active' marker still comes from local state.
+    domains, and org_id. '--org <id>' filters to one org; '--all' reads every
+    project you can reach across all your orgs (as your sign-in session after
+    'run402 login', else as the current wallet). The 'active' marker still
+    comes from local state.
   - 'rename' fixes a project's display name. You must be an org admin (or hold a
     project:write grant) on the owning org; it works even if the project was
     never provisioned from this machine.
   - 'rest' uses PostgREST query syntax (table name + optional query string)
-  - 'provision' requires a funded allowance on Run402 Cloud. Against a
+  - 'provision' requires a funded wallet on Run402 Cloud. Against a
     configured Run402 Core target, it creates a local Core project without
     payment.
   - 'apply-expose' declares the full authorization surface (tables, views, RPCs)
@@ -115,11 +114,10 @@ Options:
   --org <id>          Filter to projects owned by one org (organization).
                       Authorize-before-reveal: a non-member or guessed id is a
                       403; a non-UUID id is a 400.
-  --all               Read the cross-wallet inventory across every wallet
-                      controlling your operator email. Run 'run402 operator
-                      login' first for the union; without a session it falls
-                      back to the current wallet's slice. Mutually exclusive
-                      with --org.
+  --all               Read every project you can reach across all your orgs
+                      (GET /agent/v1/me/projects). After 'run402 login' it
+                      reads as your sign-in session; without one, as the
+                      current wallet. Mutually exclusive with --org.
 
 Notes:
   - This is a SERVER read (membership-scoped), not the local keystore. Each row
@@ -197,8 +195,8 @@ Options:
                       from --name when omitted; an unnamed provision stays un-keyed.
 
 Notes:
-  - Payment is automatic via x402 on Run402 Cloud; requires a funded allowance.
-    Against a configured Run402 Core target, no Cloud tier/allowance/payment is
+  - Payment is automatic via x402 on Run402 Cloud; requires a funded wallet.
+    Against a configured Run402 Core target, no Cloud tier/wallet/payment is
     required.
   - The new project becomes the active project after provisioning
 
@@ -246,7 +244,7 @@ Environment:
   RUN402_ADMIN_COOKIE Optional admin OAuth cookie header, e.g. "run402_admin=..."
 
 Notes:
-  - Platform-admin only. The configured allowance wallet must be an admin
+  - Platform-admin only. The configured wallet must be an admin
     wallet, or RUN402_ADMIN_COOKIE must contain an admin OAuth cookie.
   - Project service keys are not enough for this endpoint.
   - Output is the gateway's per-project finance JSON: revenue, direct cost,
@@ -361,10 +359,10 @@ async function provision(args) {
       });
     }
   }
-  // Aggressive early exit when no agent allowance is configured — but only when
-  // there's also no operator (control-plane) session, since a wallet-less human
-  // provisions into an org via their operator approval instead of a wallet.
-  if (!isCoreApiTarget() && !loadLiveControlPlaneSession()) allowanceAuthHeaders("/projects/v1");
+  // Aggressive early exit when no local wallet is configured — but only when
+  // there's also no sign-in session, since a wallet-less person provisions
+  // into an org via a write approval instead of a wallet.
+  if (!isCoreApiTarget() && !loadLiveControlPlaneSession()) walletAuthHeaders("/projects/v1");
 
   const activeBefore = getActiveProjectId();
   try {
@@ -495,7 +493,7 @@ async function validateExpose(args = []) {
   }
   const activeProjectId = getActiveProjectId();
   const project = projectFlag || projectId || activeProjectId || undefined;
-  if (!project) allowanceAuthHeaders("/projects/v1/expose/validate");
+  if (!project) walletAuthHeaders("/projects/v1/expose/validate");
   const migration = migrationFile ? readFileSync(migrationFile, "utf-8") : migrationSql;
 
   try {
@@ -525,25 +523,24 @@ async function list(args = []) {
     fail({
       code: "BAD_USAGE",
       message: "--all and --org are mutually exclusive.",
-      hint: "--all reads the cross-wallet operator inventory; --org filters the membership-scoped list to one org.",
+      hint: "--all reads every project across all your orgs; --org filters the membership-scoped list to one org.",
     });
   }
 
-  // `--all` reads the operator email-union inventory across every wallet
-  // controlling your verified email. Pass the cached operator-session token
-  // when present (cross-wallet union); otherwise the SDK falls back to SIWX
-  // wallet auth and the gateway returns just this wallet's slice.
+  // `--all` reads every project the caller can reach across all its orgs.
+  // Pass the cached sign-in session token when present; otherwise the SDK
+  // uses the credential provider and the gateway returns this wallet's slice.
   const opts = {};
   if (all) {
     opts.all = true;
-    const session = loadLiveOperatorSession();
-    if (session) opts.token = session.operator_session_token;
+    const session = loadLiveControlPlaneSession();
+    if (session) opts.token = session.control_plane_session_token;
   } else if (org) {
     opts.org = org;
   }
 
   // Active marker comes from local state; the inventory itself is the server
-  // read (NOT the keystore), so it surfaces every project the wallet/email can
+  // read (NOT the keystore), so it surfaces every project the principal can
   // reach — including ones never provisioned from this machine.
   const activeId = getActiveProjectId();