run402 2.39.4 → 2.41.0

package/lib/org.mjs

@@ -1,42 +1,49 @@
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 import {
   normalizeArgv,
   assertKnownFlags,
   flagValue,
+  parseIntegerFlag,
   requirePositionalCount,
 } from "./argparse.mjs";
 
-const HELP = `run402 org — org-owned control plane: identity, membership, roles
+const ROLE_LIST = "owner | admin | developer | billing | viewer";
+
+const HELP = `run402 org — org-owned control plane: identity, membership, invites
 
 Usage:
-  run402 org <subcommand> [args...]
+  run402 org whoami
+  run402 org list
+  run402 org audit <billing_account> [--limit N] [--before <cursor>]
+  run402 org member list <billing_account>
+  run402 org member add  <billing_account> <wallet> [--role <role>]
+  run402 org member role <billing_account> <principal_id> <role>
+  run402 org member rm   <billing_account> <principal_id>
+  run402 org invite list   <billing_account>
+  run402 org invite create <billing_account> <email> [--role <role>] [--ttl-hours N]
+  run402 org invite rm     <billing_account> <principal_id>
 
 Subcommands:
-  whoami                                       Resolved principal + org memberships (GET /agent/v1/whoami)
-  list                                         Orgs you are a member of
-  members <billing_account>                    Members + roles of an org
-  add-member <billing_account> <wallet> [--role <role>]
-                                               Add a member by wallet (owner-gated; role defaults to developer)
-  set-role <billing_account> <principal_id> <role>
-                                               Change a member's role (owner-gated)
-  remove-member <billing_account> <principal_id>
-                                               Remove a member (owner-gated)
+  whoami      Resolved principal + org memberships (GET /agent/v1/whoami)
+  list        Orgs you are a member of
+  member      Manage members (list, add, role, rm) — mutations require owner
+  invite      Manage email invites (list, create, rm) — mutations require owner
+  audit       Control-plane audit trail for an org (admin+)
 
 Notes:
   - A wallet AUTHENTICATES; the org (billing account) owns projects. Membership/role authorizes.
-  - Roles: owner > admin > developer > billing > viewer. Member changes need an active owner.
-  - "add-member" is by WALLET (email-first invite is a separate, not-yet-shipped flow).
+  - Roles: ${ROLE_LIST}. Member/invite changes need an active owner.
   - Removing/demoting the org's only active owner fails with 409 LAST_OWNER.
   - JSON in, JSON out.
 
 Examples:
   run402 org whoami
-  run402 org list
-  run402 org members ba_abc
-  run402 org add-member ba_abc 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --role admin
-  run402 org set-role ba_abc prn_xyz owner
-  run402 org remove-member ba_abc prn_xyz
+  run402 org member list ba_abc
+  run402 org member add ba_abc 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --role admin
+  run402 org member role ba_abc prn_xyz owner
+  run402 org invite create ba_abc dev@example.com --role developer
+  run402 org audit ba_abc --limit 50
 `;
 
 const SUB_HELP = {
@@ -46,57 +53,46 @@ Usage:
   run402 org whoami
 
 Calls GET /agent/v1/whoami. Returns the control-plane principal (id/type/displayName/createdAt),
-authenticator_id, and every org membership with role + status. This is the REMOTE
-identity; for local wallet/profile state use \`run402 status\`.
+authenticator_id, and every org membership with role + status. REMOTE identity; for local
+wallet/profile state use 'run402 status'.
 `,
   list: `run402 org list — orgs you are a member of
 
 Usage:
   run402 org list
-
-Returns each org (billing account) you belong to with your role and membership status.
-`,
-  members: `run402 org members — members + roles of an org
-
-Usage:
-  run402 org members <billing_account>
-
-Arguments:
-  <billing_account>   Org (billing account) id, e.g. ba_...
 `,
-  "add-member": `run402 org add-member — add a member by wallet (owner-gated)
+  member: `run402 org member — manage org members
 
 Usage:
-  run402 org add-member <billing_account> <wallet> [--role <role>]
+  run402 org member list <billing_account>
+  run402 org member add  <billing_account> <wallet> [--role <role>]
+  run402 org member role <billing_account> <principal_id> <role>
+  run402 org member rm   <billing_account> <principal_id>
 
-Arguments:
-  <billing_account>   Org (billing account) id
-  <wallet>            EVM address or named wallet (a new wallet is provisioned as a human principal)
-
-Options:
-  --role <role>       owner | admin | developer | billing | viewer (default: developer)
+Roles: ${ROLE_LIST} (add defaults to developer). Mutations require an active owner.
+Demoting/removing the org's only active owner fails with 409 LAST_OWNER.
 `,
-  "set-role": `run402 org set-role — change a member's role (owner-gated)
+  invite: `run402 org invite — manage email invites
 
 Usage:
-  run402 org set-role <billing_account> <principal_id> <role>
-
-Arguments:
-  <billing_account>   Org (billing account) id
-  <principal_id>      Member principal id (prn_..., from \`run402 org members\`)
-  <role>              owner | admin | developer | billing | viewer
+  run402 org invite list   <billing_account>
+  run402 org invite create <billing_account> <email> [--role <role>] [--ttl-hours N]
+  run402 org invite rm     <billing_account> <principal_id>
 
-Demoting the org's only active owner fails with 409 LAST_OWNER.
+An invite is claimed at the recipient's first login. Mutations require an active owner
+(plus step-up when driven by a control-plane session).
 `,
-  "remove-member": `run402 org remove-member — remove a member (owner-gated)
+  audit: `run402 org audit — control-plane audit trail
 
 Usage:
-  run402 org remove-member <billing_account> <principal_id>
+  run402 org audit <billing_account> [--limit N] [--before <cursor>]
 
-Removing the org's only active owner fails with 409 LAST_OWNER.
+Requires an admin+ membership on the org. Newest-first; page with --before.
 `,
 };
 
+// ── Top-level: whoami / list / audit ───────────────────────────────────────────
+
 async function whoami(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, ["--help", "-h"]);
@@ -119,70 +115,169 @@ async function list(args) {
   }
 }
 
-async function members(args) {
+async function audit(args) {
   const a = normalizeArgv(args);
-  assertKnownFlags(a, ["--help", "-h"]);
-  const [ba] = requirePositionalCount(a, [], {
+  const valueFlags = ["--limit", "--before"];
+  assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
+  const [ba] = requirePositionalCount(a, valueFlags, {
     min: 1,
     max: 1,
-    command: "run402 org members <billing_account>",
+    command: "run402 org audit <billing_account>",
     missing: "Missing <billing_account>.",
   });
+  const limitFlag = flagValue(a, "--limit");
+  const before = flagValue(a, "--before");
+  const limit = limitFlag === null ? undefined : parseIntegerFlag("--limit", limitFlag, { min: 1, max: 1000 });
   try {
-    console.log(JSON.stringify({ members: await getSdk().org.members(ba) }, null, 2));
+    const events = await getSdk().org.audit(ba, { limit, before: before ?? undefined });
+    console.log(JSON.stringify({ events }, null, 2));
   } catch (err) {
     reportSdkError(err);
   }
 }
 
-async function addMember(args) {
-  const a = normalizeArgv(args);
-  assertKnownFlags(a, ["--role", "--help", "-h"], ["--role"]);
-  const role = flagValue(a, "--role");
-  const [ba, wallet] = requirePositionalCount(a, ["--role"], {
-    min: 2,
-    max: 2,
-    command: "run402 org add-member <billing_account> <wallet> [--role <role>]",
-    missing: "Missing <billing_account> and/or <wallet>.",
-  });
-  try {
-    const res = await getSdk().org.addMember(ba, { wallet, role: role || undefined });
-    console.log(JSON.stringify(res, null, 2));
-  } catch (err) {
-    reportSdkError(err);
+// ── Member group ───────────────────────────────────────────────────────────────
+
+async function runMember(args) {
+  const memberAction = args[0];
+  const rest = args.slice(1);
+  if (!memberAction || memberAction === "--help" || memberAction === "-h") {
+    console.log(SUB_HELP.member);
+    process.exit(memberAction ? 0 : 1);
+  }
+  if (rest.includes("--help") || rest.includes("-h")) {
+    console.log(SUB_HELP.member);
+    process.exit(0);
   }
-}
 
-async function setRole(args) {
-  const a = normalizeArgv(args);
-  assertKnownFlags(a, ["--help", "-h"]);
-  const [ba, principalId, role] = requirePositionalCount(a, [], {
-    min: 3,
-    max: 3,
-    command: "run402 org set-role <billing_account> <principal_id> <role>",
-    missing: "Missing <billing_account>, <principal_id>, and/or <role>.",
-  });
-  try {
-    console.log(JSON.stringify(await getSdk().org.setRole(ba, principalId, role), null, 2));
-  } catch (err) {
-    reportSdkError(err);
+  if (memberAction === "list") {
+    const a = normalizeArgv(rest);
+    assertKnownFlags(a, ["--help", "-h"]);
+    const [ba] = requirePositionalCount(a, [], {
+      min: 1, max: 1, command: "run402 org member list <billing_account>", missing: "Missing <billing_account>.",
+    });
+    try {
+      console.log(JSON.stringify({ members: await getSdk().org.members.list(ba) }, null, 2));
+    } catch (err) {
+      reportSdkError(err);
+    }
+    return;
+  }
+
+  if (memberAction === "add") {
+    const a = normalizeArgv(rest);
+    assertKnownFlags(a, ["--role", "--help", "-h"], ["--role"]);
+    const role = flagValue(a, "--role");
+    const [ba, wallet] = requirePositionalCount(a, ["--role"], {
+      min: 2, max: 2, command: "run402 org member add <billing_account> <wallet> [--role <role>]",
+      missing: "Missing <billing_account> and/or <wallet>.",
+    });
+    try {
+      const res = await getSdk().org.members.add(ba, { wallet, role: role || undefined });
+      console.log(JSON.stringify(res, null, 2));
+    } catch (err) {
+      reportSdkError(err);
+    }
+    return;
+  }
+
+  if (memberAction === "role") {
+    const a = normalizeArgv(rest);
+    assertKnownFlags(a, ["--help", "-h"]);
+    const [ba, principalId, role] = requirePositionalCount(a, [], {
+      min: 3, max: 3, command: "run402 org member role <billing_account> <principal_id> <role>",
+      missing: "Missing <billing_account>, <principal_id>, and/or <role>.",
+    });
+    try {
+      console.log(JSON.stringify(await getSdk().org.members.setRole(ba, principalId, role), null, 2));
+    } catch (err) {
+      reportSdkError(err);
+    }
+    return;
+  }
+
+  if (memberAction === "rm") {
+    const a = normalizeArgv(rest);
+    assertKnownFlags(a, ["--help", "-h"]);
+    const [ba, principalId] = requirePositionalCount(a, [], {
+      min: 2, max: 2, command: "run402 org member rm <billing_account> <principal_id>",
+      missing: "Missing <billing_account> and/or <principal_id>.",
+    });
+    try {
+      console.log(JSON.stringify(await getSdk().org.members.revoke(ba, principalId), null, 2));
+    } catch (err) {
+      reportSdkError(err);
+    }
+    return;
   }
+
+  fail({ code: "BAD_USAGE", message: `Unknown 'org member' action: ${memberAction}. Try list | add | role | rm.` });
 }
 
-async function removeMember(args) {
-  const a = normalizeArgv(args);
-  assertKnownFlags(a, ["--help", "-h"]);
-  const [ba, principalId] = requirePositionalCount(a, [], {
-    min: 2,
-    max: 2,
-    command: "run402 org remove-member <billing_account> <principal_id>",
-    missing: "Missing <billing_account> and/or <principal_id>.",
-  });
-  try {
-    console.log(JSON.stringify(await getSdk().org.removeMember(ba, principalId), null, 2));
-  } catch (err) {
-    reportSdkError(err);
+// ── Invite group ─────────────────────────────────────────────────────────────────
+
+async function runInvite(args) {
+  const inviteAction = args[0];
+  const rest = args.slice(1);
+  if (!inviteAction || inviteAction === "--help" || inviteAction === "-h") {
+    console.log(SUB_HELP.invite);
+    process.exit(inviteAction ? 0 : 1);
+  }
+  if (rest.includes("--help") || rest.includes("-h")) {
+    console.log(SUB_HELP.invite);
+    process.exit(0);
   }
+
+  if (inviteAction === "list") {
+    const a = normalizeArgv(rest);
+    assertKnownFlags(a, ["--help", "-h"]);
+    const [ba] = requirePositionalCount(a, [], {
+      min: 1, max: 1, command: "run402 org invite list <billing_account>", missing: "Missing <billing_account>.",
+    });
+    try {
+      console.log(JSON.stringify({ invites: await getSdk().org.invites.list(ba) }, null, 2));
+    } catch (err) {
+      reportSdkError(err);
+    }
+    return;
+  }
+
+  if (inviteAction === "create") {
+    const a = normalizeArgv(rest);
+    const valueFlags = ["--role", "--ttl-hours"];
+    assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
+    const role = flagValue(a, "--role");
+    const ttlFlag = flagValue(a, "--ttl-hours");
+    const [ba, email] = requirePositionalCount(a, valueFlags, {
+      min: 2, max: 2, command: "run402 org invite create <billing_account> <email> [--role <role>]",
+      missing: "Missing <billing_account> and/or <email>.",
+    });
+    const inviteTtlHours = ttlFlag === null ? undefined : parseIntegerFlag("--ttl-hours", ttlFlag, { min: 1, max: 8760 });
+    try {
+      const res = await getSdk().org.invites.create(ba, { email, role: role || "developer", inviteTtlHours });
+      console.log(JSON.stringify(res, null, 2));
+    } catch (err) {
+      reportSdkError(err);
+    }
+    return;
+  }
+
+  if (inviteAction === "rm") {
+    const a = normalizeArgv(rest);
+    assertKnownFlags(a, ["--help", "-h"]);
+    const [ba, principalId] = requirePositionalCount(a, [], {
+      min: 2, max: 2, command: "run402 org invite rm <billing_account> <principal_id>",
+      missing: "Missing <billing_account> and/or <principal_id>.",
+    });
+    try {
+      console.log(JSON.stringify(await getSdk().org.invites.revoke(ba, principalId), null, 2));
+    } catch (err) {
+      reportSdkError(err);
+    }
+    return;
+  }
+
+  fail({ code: "BAD_USAGE", message: `Unknown 'org invite' action: ${inviteAction}. Try list | create | rm.` });
 }
 
 export async function run(sub, args) {
@@ -190,17 +285,24 @@ export async function run(sub, args) {
     console.log(HELP);
     process.exit(0);
   }
-  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
-    console.log(SUB_HELP[sub] || HELP);
+  // Nested groups use `if (sub === ...)` (not `case`) so the sync test extracts
+  // their leaf actions via the dedicated memberAction/inviteAction parsers.
+  if (sub === "member" || sub === "members") {
+    await runMember(args ?? []);
+    return;
+  }
+  if (sub === "invite" || sub === "invites") {
+    await runInvite(args ?? []);
+    return;
+  }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h")) && SUB_HELP[sub]) {
+    console.log(SUB_HELP[sub]);
     process.exit(0);
   }
   switch (sub) {
     case "whoami": await whoami(args); break;
     case "list": await list(args); break;
-    case "members": await members(args); break;
-    case "add-member": await addMember(args); break;
-    case "set-role": await setRole(args); break;
-    case "remove-member": await removeMember(args); break;
+    case "audit": await audit(args); break;
     default:
       console.error(`Unknown subcommand: ${sub}\n`);
       console.log(HELP);

package/lib/transfer.mjs

@@ -13,18 +13,21 @@ import {
 const HELP = `run402 transfer — Two-party project transfer (v1.59)
 
 Usage:
-  run402 transfer init --to <wallet> [--project <id>] [--billing-policy migrate] [--message <text>] [--kysigned <record_id>]
+  run402 transfer init --to <wallet|email> [--project <id>] [--billing-policy migrate] [--message <text>] [--kysigned <record_id>]
   run402 transfer preview <transfer_id>
   run402 transfer list [--incoming | --outgoing] [--limit N] [--offset N]
   run402 transfer accept <transfer_id>
-  run402 transfer cancel <transfer_id> [--reason <text>]
+  run402 transfer claim <transfer_id> [--into <billing_account_id>]
+  run402 transfer cancel <transfer_id> [--reason <text>] [--handoff]
 
 Subcommands:
-  init        Initiate a transfer to a new owner (you must currently own the project)
-  preview     Fetch the safe review document (either party may view)
-  list        List pending transfers (incoming by default, or --outgoing)
-  accept      Accept an incoming transfer (your wallet must be the to_wallet)
-  cancel      Cancel a pending transfer (either party may cancel)
+  init        Initiate ownership change. --to <wallet> = two-party wallet transfer;
+              --to <email> = email->org handoff (the recipient claims it).
+  preview     Fetch the safe review document (add --handoff for an email handoff)
+  list        List pending transfers (incoming default, --outgoing, or --handoffs)
+  accept      Accept an incoming wallet transfer (your wallet must be the to_wallet)
+  claim       Claim an incoming email handoff into an org (--into <id>; omit = new org)
+  cancel      Cancel a pending transfer/handoff (--handoff routes to a handoff)
 
 Notes:
   - Owner-side mutations on a project with a pending transfer return 409
@@ -38,7 +41,7 @@ const SUB_HELP = {
   init: `run402 transfer init — Initiate a project transfer
 
 Usage:
-  run402 transfer init --to <wallet> [--project <id>] [--billing-policy migrate] [--message <text>] [--kysigned <record_id>]
+  run402 transfer init --to <wallet|email> [--project <id>] [--billing-policy migrate] [--message <text>] [--kysigned <record_id>]
 
 Options:
   --project <id>         Project id (defaults to the active project)
@@ -85,10 +88,19 @@ project, enqueues notifications to both parties, and stamps a
   cancel: `run402 transfer cancel — Cancel a pending transfer
 
 Usage:
-  run402 transfer cancel <transfer_id> [--reason <text>]
+  run402 transfer cancel <transfer_id> [--reason <text>] [--handoff]
 
 Either the from_wallet or the to_wallet may cancel. Already-processed
-transfers return 409 TRANSFER_ALREADY_PROCESSED.
+transfers return 409 TRANSFER_ALREADY_PROCESSED. Pass --handoff to cancel an
+email->org handoff instead of a wallet transfer.
+`,
+  claim: `run402 transfer claim — Claim an incoming email handoff
+
+Usage:
+  run402 transfer claim <transfer_id> [--into <billing_account_id>]
+
+Claims a handoff addressed to your email into an org you own. Omit --into to
+claim into a brand-new org. This is the email-handoff analog of 'accept'.
 `,
 };
 
@@ -122,16 +134,27 @@ async function init(args) {
   const message = flagValue(parsedArgs, "--message");
   const kysigned = flagValue(parsedArgs, "--kysigned");
 
-  allowanceAuthHeaders(`/projects/v1/${projectId}/transfers`);
+  // One noun, two rails: an email recipient routes to the email->org handoff;
+  // a wallet recipient routes to the two-party wallet transfer.
+  const isEmail = toWallet.includes("@");
+  allowanceAuthHeaders(
+    isEmail ? `/projects/v1/${projectId}/handoffs` : `/projects/v1/${projectId}/transfers`,
+  );
 
   try {
-    const res = await getSdk().admin.transfers.initiate({
-      projectId,
-      toWallet,
-      billingPolicy: billingPolicy ?? undefined,
-      message: message ?? undefined,
-      kysignedRecordId: kysigned ?? undefined,
-    });
+    const res = isEmail
+      ? await getSdk().admin.transfers.initiateHandoff({
+          projectId,
+          toEmail: toWallet,
+          message: message ?? undefined,
+        })
+      : await getSdk().admin.transfers.initiate({
+          projectId,
+          toWallet,
+          billingPolicy: billingPolicy ?? undefined,
+          message: message ?? undefined,
+          kysignedRecordId: kysigned ?? undefined,
+        });
     console.log(JSON.stringify(res, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -140,16 +163,19 @@ async function init(args) {
 
 async function preview(args) {
   const parsedArgs = normalizeArgv(args);
-  assertKnownFlags(parsedArgs, ["--help", "-h"]);
+  assertKnownFlags(parsedArgs, ["--handoff", "--help", "-h"]);
   const positionals = positionalArgs(parsedArgs);
   if (positionals.length !== 1) {
-    fail({ code: "BAD_USAGE", message: "Usage: run402 transfer preview <transfer_id>" });
+    fail({ code: "BAD_USAGE", message: "Usage: run402 transfer preview <transfer_id> [--handoff]" });
   }
   const transferId = positionals[0];
-  allowanceAuthHeaders(`/agent/v1/transfers/${transferId}`);
+  const handoff = parsedArgs.includes("--handoff");
+  allowanceAuthHeaders(`/agent/v1/${handoff ? "handoffs" : "transfers"}/${transferId}`);
 
   try {
-    const data = await getSdk().admin.transfers.preview(transferId);
+    const data = handoff
+      ? await getSdk().admin.transfers.previewHandoff(transferId)
+      : await getSdk().admin.transfers.preview(transferId);
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -159,11 +185,24 @@ async function preview(args) {
 async function list(args) {
   const parsedArgs = normalizeArgv(args);
   const valueFlags = ["--limit", "--offset"];
-  assertKnownFlags(parsedArgs, [...valueFlags, "--incoming", "--outgoing", "--help", "-h"], valueFlags);
+  assertKnownFlags(parsedArgs, [...valueFlags, "--incoming", "--outgoing", "--handoffs", "--help", "-h"], valueFlags);
   const extra = positionalArgs(parsedArgs, valueFlags);
   if (extra.length > 0) {
     fail({ code: "BAD_USAGE", message: `Unexpected argument for transfer list: ${extra[0]}` });
   }
+
+  // Email->org handoffs ride the same rail but have their own incoming inbox.
+  if (parsedArgs.includes("--handoffs")) {
+    allowanceAuthHeaders("/agent/v1/handoffs/incoming");
+    try {
+      const handoffs = await getSdk().admin.transfers.listIncomingHandoffs();
+      console.log(JSON.stringify({ kind: "handoffs", handoffs }, null, 2));
+    } catch (err) {
+      reportSdkError(err);
+    }
+    return;
+  }
+
   const incoming = parsedArgs.includes("--incoming");
   const outgoing = parsedArgs.includes("--outgoing");
   if (incoming && outgoing) {
@@ -216,17 +255,42 @@ async function accept(args) {
 async function cancel(args) {
   const parsedArgs = normalizeArgv(args);
   const valueFlags = ["--reason"];
-  assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
+  assertKnownFlags(parsedArgs, [...valueFlags, "--handoff", "--help", "-h"], valueFlags);
   const positionals = positionalArgs(parsedArgs, valueFlags);
   if (positionals.length !== 1) {
-    fail({ code: "BAD_USAGE", message: "Usage: run402 transfer cancel <transfer_id> [--reason <text>]" });
+    fail({ code: "BAD_USAGE", message: "Usage: run402 transfer cancel <transfer_id> [--reason <text>] [--handoff]" });
   }
   const transferId = positionals[0];
   const reason = flagValue(parsedArgs, "--reason");
-  allowanceAuthHeaders(`/agent/v1/transfers/${transferId}/cancel`);
+  const handoff = parsedArgs.includes("--handoff");
+  allowanceAuthHeaders(`/agent/v1/${handoff ? "handoffs" : "transfers"}/${transferId}/cancel`);
+
+  try {
+    const data = handoff
+      ? await getSdk().admin.transfers.cancelHandoff(transferId)
+      : await getSdk().admin.transfers.cancel(transferId, reason ?? undefined);
+    console.log(JSON.stringify(data, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function claim(args) {
+  const parsedArgs = normalizeArgv(args);
+  const valueFlags = ["--into"];
+  assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
+  const positionals = positionalArgs(parsedArgs, valueFlags);
+  if (positionals.length !== 1) {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 transfer claim <transfer_id> [--into <billing_account_id>]" });
+  }
+  const transferId = positionals[0];
+  const into = flagValue(parsedArgs, "--into");
+  allowanceAuthHeaders(`/agent/v1/handoffs/${transferId}/claim`);
 
   try {
-    const data = await getSdk().admin.transfers.cancel(transferId, reason ?? undefined);
+    const data = await getSdk().admin.transfers.claimHandoff(transferId, {
+      billingAccountId: into ?? undefined,
+    });
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -255,6 +319,9 @@ export async function run(sub, args) {
     case "accept":
       await accept(args);
       return;
+    case "claim":
+      await claim(args);
+      return;
     case "cancel":
       await cancel(args);
       return;

package/package.json

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