run402 4.68.3 → 4.69.1

package/lib/org.mjs

@@ -5,6 +5,8 @@ import { nextAction } from "./next-actions.mjs";
 import {
   requireOrgIdShape,
   resolveOrg,
+  takeOrgPositional,
+  requireRest,
   orgProvenance,
   getSelectedOrgId,
   setSelectedOrgId,
@@ -27,9 +29,9 @@ const HELP = `run402 org — organizations: create, label, membership, invites
 Usage:
   run402 org create [--name <label>]
   run402 org list
-  run402 org get    <org_id>
-  run402 org rename <org_id> --name <display_name>   (or: --clear to remove the label)
-  run402 org payout-wallet <org_id> --wallet <wallet_address>  (or: --clear to remove the explicit default)
+  run402 org get    [<org_id>]
+  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 whoami
   run402 org use     <org_id>
@@ -37,17 +39,22 @@ Usage:
   run402 org clear
   run402 org bind   [--org <org_id>] [--room <key>]
   run402 org unbind
-  run402 org audit  <org_id> [--limit N] [--after <cursor>] [--before <cursor>]
-  run402 org member list <org_id>
-  run402 org member add  <org_id> --wallet <wallet_address> [--role <role>]
-  run402 org member role <org_id> --principal <principal_id> --role <role>
-  run402 org member rm   <org_id> --principal <principal_id>
-  run402 org invite list   <org_id>
-  run402 org invite create <org_id> --email <email> [--role <role>] [--ttl-hours N]
-  run402 org invite rm     <org_id> --principal <principal_id>
-
-Legacy (still supported): the second attribute may also be passed positionally,
-e.g. run402 org member add <org_id> <wallet_address>.
+  run402 org audit  [<org_id>] [--limit N] [--after <cursor>] [--before <cursor>]
+  run402 org member list [<org_id>]
+  run402 org member add  [<org_id>] <wallet_address> [--role <role>]
+  run402 org member role [<org_id>] --principal <principal_id> --role <role>
+  run402 org member rm   [<org_id>] --principal <principal_id>
+  run402 org member revoke-key [<org_id>] --principal <principal_id> [--reason <why>]   (owner + step-up; revokes the member's gitvault encryption key — its next gitvault operation enrolls afresh)
+  run402 org invite list   [<org_id>]
+  run402 org invite create [<org_id>] --email <email> [--role <role>] [--ttl-hours N]
+  run402 org invite rm     [<org_id>] --principal <principal_id>
+
+<org_id> is optional everywhere: a leading UUID positional addresses that org;
+omit it and the org comes from --org, then RUN402_ORG, then the .run402.json
+binding, then 'run402 org use'. Inside a bound checkout two agents add each
+other with nothing to look up: run402 org member add <wallet_address> --role developer.
+A developer-or-above add REFUSES (GITVAULT_WRITER_NOT_ADMITTED) unless this session's key is an admitted writer on every vault of the org, so the new member can push at once; a current writer admits your key with run402 repos access sync.
+The second attribute may also be passed positionally (run402 org member add <wallet_address>).
 
 Subcommands:
   create      Create an empty org on the prototype tier (you become owner)
@@ -78,14 +85,16 @@ Notes:
 Examples:
   run402 org create --name "Kychee"
   run402 org list
-  run402 org get org_abc
-  run402 org rename org_abc "New Name"
-  run402 org rename org_abc --clear
-  run402 org payout-wallet org_abc 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
-  run402 org payout-wallet org_abc --clear
-  run402 org member add org_abc 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --role admin
-  run402 org invite create org_abc dev@example.com --role developer
-  run402 org audit org_abc --limit 50
+  run402 org get                      # the current org (binding / org use)
+  run402 org get 8f14e45f-ceea-4b7a-9d3c-0b2a6e6f1c2d
+  run402 org rename --name "New Name"
+  run402 org rename --clear
+  run402 org payout-wallet 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
+  run402 org payout-wallet --clear
+  run402 org member add 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --role admin
+  run402 org member add 8f14e45f-ceea-4b7a-9d3c-0b2a6e6f1c2d 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --role admin
+  run402 org invite create dev@example.com --role developer
+  run402 org audit --limit 50
 `;
 
 const SUB_HELP = {
@@ -108,7 +117,7 @@ Usage:
   get: `run402 org get — read one org (label + tier/lease + your role)
 
 Usage:
-  run402 org get <org_id>
+  run402 org get [<org_id>]
 
 Any active member may read. A non-member (including a guessed id) gets the same
 non-revealing 403.
@@ -116,11 +125,11 @@ non-revealing 403.
   rename: `run402 org rename — set or clear an org's display label (owner-only)
 
 Usage:
-  run402 org rename <org_id> --name <display_name>
-  run402 org rename <org_id> --clear
+  run402 org rename [<org_id>] --name <display_name>
+  run402 org rename [<org_id>] --clear
 
 Legacy (still supported):
-  run402 org rename <org_id> <display_name>
+  run402 org rename [<org_id>] <display_name>
 
 Owner-only + step-up gated. Pass --clear (or an empty display_name) to remove
 the label. Output includes the updated tier and lease timestamps.
@@ -148,11 +157,11 @@ call after a dropped response can never double-bill.
   "payout-wallet": `run402 org payout-wallet — set or clear the tenant route payout wallet
 
 Usage:
-  run402 org payout-wallet <org_id> --wallet <wallet_address>
-  run402 org payout-wallet <org_id> --clear
+  run402 org payout-wallet [<org_id>] <wallet_address>
+  run402 org payout-wallet [<org_id>] --clear
 
 Legacy (still supported):
-  run402 org payout-wallet <org_id> <wallet_address>
+  run402 org payout-wallet [<org_id>] <wallet_address>
 
 Admin/owner-only + step-up gated. The wallet must already be active and linked
 to the same org. This wallet receives x402 settlement for function web routes
@@ -174,10 +183,11 @@ for local wallet/profile state use 'run402 status'.
   member: `run402 org member — manage org members
 
 Usage:
-  run402 org member list <org_id>
-  run402 org member add  <org_id> --wallet <wallet_address> [--role <role>]
-  run402 org member role <org_id> --principal <principal_id> --role <role>
-  run402 org member rm   <org_id> --principal <principal_id>
+  run402 org member list [<org_id>]
+  run402 org member add  [<org_id>] <wallet_address> [--role <role>]
+  run402 org member role [<org_id>] --principal <principal_id> --role <role>
+  run402 org member rm   [<org_id>] --principal <principal_id>
+  run402 org member revoke-key [<org_id>] --principal <principal_id> [--reason <why>]   (owner + step-up; revokes the member's gitvault encryption key — its next gitvault operation enrolls afresh)
 
 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.
@@ -185,12 +195,16 @@ Demoting/removing the org's only active owner fails with 409 LAST_OWNER.
   invite: `run402 org invite — manage email invites
 
 Usage:
-  run402 org invite list   <org_id>
-  run402 org invite create <org_id> --email <email> [--role <role>] [--ttl-hours N]
-  run402 org invite rm     <org_id> --principal <principal_id>
+  run402 org invite list   [<org_id>]
+  run402 org invite create [<org_id>] --email <email> [--role <role>] [--ttl-hours N]
+  run402 org invite rm     [<org_id>] --principal <principal_id>
 
-Legacy (still supported): the second attribute may also be passed positionally,
-e.g. run402 org member add <org_id> <wallet_address>.
+<org_id> is optional everywhere: a leading UUID positional addresses that org;
+omit it and the org comes from --org, then RUN402_ORG, then the .run402.json
+binding, then 'run402 org use'. Inside a bound checkout two agents add each
+other with nothing to look up: run402 org member add <wallet_address> --role developer.
+A developer-or-above add REFUSES (GITVAULT_WRITER_NOT_ADMITTED) unless this session's key is an admitted writer on every vault of the org, so the new member can push at once; a current writer admits your key with run402 repos access sync.
+The second attribute may also be passed positionally (run402 org member add <wallet_address>).
 
 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).
@@ -198,7 +212,7 @@ An invite is claimed at the recipient's first login. Mutations require an active
   audit: `run402 org audit — control-plane audit trail
 
 Usage:
-  run402 org audit <org_id> [--limit N] [--after <cursor>] [--before <cursor>]
+  run402 org audit [<org_id>] [--limit N] [--after <cursor>] [--before <cursor>]
 
 Requires an admin+ membership on the org. Newest-first. Page forward with --after
 (next_cursor from a prior page); --before is the legacy cursor. Returns
@@ -208,6 +222,50 @@ Requires an admin+ membership on the org. Newest-first. Page forward with --afte
 
 // ── Top-level: create / list / get / rename / whoami / audit ────────────────────
 
+
+/**
+ * gitvault-multi-writer (rev 47) task 6.3 / design D3 — decided 2026-09-03
+ * (Tal): `org member add` REFUSES a writer-eligible add (developer or
+ * above) when this session's own key is not an admitted writer on EVERY
+ * vault of the org, because a developer who cannot push is not the member
+ * the caller meant, and a half-usable membership is exactly the silent
+ * failure the multi-writer change exists to end. No warn path, no escape
+ * flag: the fix is for a current writer of the named vault(s) to admit this
+ * key (`run402 repos access sync`, or any push) and re-run — or to run
+ * the add themselves. Viewer/billing adds never reach this gate; an org
+ * with no vaults has nothing to admit; a vault in the read-only terminal
+ * state (its last writer gone) is skipped, since nobody can admit there.
+ * Every read failure REFUSES too (an unverifiable gate is not a passed one).
+ */
+async function assertCallerCanAdmitWritersEverywhere(sdk, orgId, effectiveRole) {
+  const listing = await sdk.gitvault.listByOrg(orgId);
+  const vaults = listing?.vaults ?? [];
+  const blocked = [];
+  for (const v of vaults) {
+    const st = await sdk.gitvault.status({ repo_id: v.repo_id, reconcile: "forbidden" });
+    const vault = st?.vault ?? null;
+    if (!vault || vault.read_only_terminal) continue;
+    const me = st?.keystore?.identity_fingerprint ?? null;
+    const writers = vault.writer_set?.writers ?? [];
+    if (!me || !writers.some((w) => w.writer_key_id === me)) blocked.push({ repo_id: v.repo_id, repo_name: v.repo_name ?? null, project_id: v.project_id ?? null });
+  }
+  if (blocked.length > 0) {
+    fail({
+      code: "GITVAULT_WRITER_NOT_ADMITTED",
+      message: `refusing to add a ${effectiveRole}: this session's key is not an admitted writer on ${blocked.length} of this org's ${vaults.length} vault(s), so the new member could not push there`,
+      details: { role: effectiveRole, vaults: blocked, checked: vaults.length },
+      next_actions: [
+        {
+          type: "request_writer_sync",
+          why: "A current writer of the named vault(s) admits YOUR key by running `run402 repos access sync` there (any push does it too); then re-run this command — or have that writer run it.",
+          safe_to_auto_execute: false,
+        },
+      ],
+    });
+  }
+  return { checked: vaults.length };
+}
+
 async function create(args) {
   const a = normalizeArgv(args);
   const valueFlags = ["--name"];
@@ -384,10 +442,9 @@ async function current(args) {
 
 async function get(args) {
   const a = normalizeArgv(args);
-  assertKnownFlags(a, ["--help", "-h"]);
-  const [org] = requirePositionalCount(a, [], {
-    min: 1, max: 1, command: "run402 org get <org_id>", missing: "Missing <org_id>.",
-  });
+  assertKnownFlags(a, ["--org", "--help", "-h"], ["--org"]);
+  const { orgId: org, rest: pos } = await takeOrgPositional(a, ["--org"], { cmd: "org" });
+  requireRest(pos, { max: 0, command: "run402 org get [<org_id>]" });
   try {
     console.log(JSON.stringify(await getSdk().org(org).get(), null, 2));
   } catch (err) {
@@ -397,18 +454,18 @@ async function get(args) {
 
 async function rename(args) {
   const a = normalizeArgv(args);
-  assertKnownFlags(a, ["--name", "--clear", "--help", "-h"], ["--name"]);
+  assertKnownFlags(a, ["--org", "--name", "--clear", "--help", "-h"], ["--org", "--name"]);
   const clear = a.includes("--clear");
   const nameFlag = flagValue(a, "--name");
   const single = clear || nameFlag !== null;
-  const positionals = requirePositionalCount(a, ["--name"], {
-    min: single ? 1 : 2,
-    max: single ? 1 : 2,
-    command: "run402 org rename <org_id> --name <display_name>",
-    missing: single ? "Missing <org_id>." : "Missing <org_id> and/or <display_name> (use --name, or pass --clear).",
+  const { orgId: org, rest: pos } = await takeOrgPositional(a, ["--org", "--name"], { cmd: "org" });
+  requireRest(pos, {
+    min: single ? 0 : 1,
+    max: single ? 0 : 1,
+    command: "run402 org rename [<org_id>] --name <display_name>",
+    missing: "Missing <display_name> (use --name, or pass --clear).",
   });
-  const org = positionals[0];
-  const displayName = clear ? null : (nameFlag ?? positionals[1]);
+  const displayName = clear ? null : (nameFlag ?? pos[0]);
   try {
     console.log(JSON.stringify(await getSdk().org(org).rename(displayName), null, 2));
   } catch (err) {
@@ -418,18 +475,18 @@ async function rename(args) {
 
 async function payoutWallet(args) {
   const a = normalizeArgv(args);
-  assertKnownFlags(a, ["--wallet", "--clear", "--help", "-h"], ["--wallet"]);
+  assertKnownFlags(a, ["--org", "--address", "--clear", "--help", "-h"], ["--org", "--address"]);
   const clear = a.includes("--clear");
-  const walletFlag = flagValue(a, "--wallet");
+  const walletFlag = flagValue(a, "--address");
   const single = clear || walletFlag !== null;
-  const positionals = requirePositionalCount(a, ["--wallet"], {
-    min: single ? 1 : 2,
-    max: single ? 1 : 2,
-    command: "run402 org payout-wallet <org_id> --wallet <wallet_address>",
-    missing: single ? "Missing <org_id>." : "Missing <org_id> and/or <wallet_address> (use --wallet, or pass --clear).",
+  const { orgId: org, rest: pos } = await takeOrgPositional(a, ["--org", "--address"], { cmd: "org" });
+  requireRest(pos, {
+    min: single ? 0 : 1,
+    max: single ? 0 : 1,
+    command: "run402 org payout-wallet [<org_id>] --address <wallet_address>",
+    missing: "Missing <wallet_address> (use --address, or pass --clear).",
   });
-  const org = positionals[0];
-  const walletAddress = clear ? null : (walletFlag ?? positionals[1]);
+  const walletAddress = clear ? null : (walletFlag ?? pos[0]);
   try {
     console.log(JSON.stringify(await getSdk().org(org).setPayoutWallet({ walletAddress }), null, 2));
   } catch (err) {
@@ -484,14 +541,10 @@ async function slug(args) {
 
 async function audit(args) {
   const a = normalizeArgv(args);
-  const valueFlags = ["--limit", "--after", "--before"];
+  const valueFlags = ["--org", "--limit", "--after", "--before"];
   assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
-  const [org] = requirePositionalCount(a, valueFlags, {
-    min: 1,
-    max: 1,
-    command: "run402 org audit <org_id>",
-    missing: "Missing <org_id>.",
-  });
+  const { orgId: org, rest: pos } = await takeOrgPositional(a, valueFlags, { cmd: "org" });
+  requireRest(pos, { max: 0, command: "run402 org audit [<org_id>]" });
   const limitFlag = flagValue(a, "--limit");
   const after = flagValue(a, "--after");
   const before = flagValue(a, "--before");
@@ -524,10 +577,9 @@ async function runMember(args) {
 
   if (memberAction === "list") {
     const a = normalizeArgv(rest);
-    assertKnownFlags(a, ["--help", "-h"]);
-    const [org] = requirePositionalCount(a, [], {
-      min: 1, max: 1, command: "run402 org member list <org_id>", missing: "Missing <org_id>.",
-    });
+    assertKnownFlags(a, ["--org", "--help", "-h"], ["--org"]);
+    const { orgId: org, rest: pos } = await takeOrgPositional(a, ["--org"], { cmd: "org" });
+    requireRest(pos, { max: 0, command: "run402 org member list [<org_id>]" });
     try {
       console.log(JSON.stringify({ members: await getSdk().org(org).members.list() }, null, 2));
     } catch (err) {
@@ -538,19 +590,85 @@ async function runMember(args) {
 
   if (memberAction === "add") {
     const a = normalizeArgv(rest);
-    assertKnownFlags(a, ["--role", "--wallet", "--help", "-h"], ["--role", "--wallet"]);
+    assertKnownFlags(a, ["--org", "--role", "--address", "--help", "-h"], ["--org", "--role", "--address"]);
     const role = flagValue(a, "--role");
-    const walletFlag = flagValue(a, "--wallet");
-    const count = walletFlag ? 1 : 2;
-    const pos = requirePositionalCount(a, ["--role", "--wallet"], {
-      min: count, max: count, command: "run402 org member add <org_id> --wallet <wallet_address> [--role <role>]",
-      missing: walletFlag ? "Missing <org_id>." : "Missing <org_id> and/or <wallet_address> (use --wallet).",
+    const walletFlag = flagValue(a, "--address");
+    const count = walletFlag ? 0 : 1;
+    const { orgId: org, rest: pos } = await takeOrgPositional(a, ["--org", "--role", "--address"], { cmd: "org" });
+    requireRest(pos, {
+      min: count, max: count, command: "run402 org member add [<org_id>] <wallet_address> [--role <role>]",
+      missing: "Missing <wallet_address> (positional, or --address).",
     });
-    const org = pos[0];
-    const wallet = walletFlag ?? pos[1];
+    const wallet = walletFlag ?? pos[0];
     try {
-      const res = await getSdk().org(org).members.add({ wallet, role: role || undefined });
-      console.log(JSON.stringify(res, null, 2));
+      const sdk = getSdk();
+      // The gateway's own default role for a wallet add is developer — a
+      // writer-eligible role — so an add with no --role is gated too.
+      const effectiveRole = role || "developer";
+      if (["owner", "admin", "developer"].includes(effectiveRole)) {
+        await assertCallerCanAdmitWritersEverywhere(sdk, org, effectiveRole);
+      }
+      const res = await sdk.org(org).members.add({ wallet, role: role || undefined });
+      // gitvault-multi-writer (rev 47) task 6.3 — the gateway names which of
+      // this org's vaults now have a pending writer candidate (D3: there is
+      // no server-side writer admission — the client holds the keys) via a
+      // `sync_writers` next_action carrying `vault_ids[]`. Run the ACTUAL
+      // reconcile against each one now, so a single `org member add` finishes
+      // the whole job when the caller can. `reconcile()` is ALREADY a
+      // fast, network-free no-op per vault when this session's own key
+      // isn't a writer there (task 5.7's own `eligible` gate). For a
+      // writer-eligible add the gate above already proved this session IS
+      // a writer on every vault, so `not_eligible` here can only name a
+      // vault that changed under us in the meantime — reported, never
+      // silently dropped.
+      const syncTarget = res.next_actions?.find((n) => n?.type === "sync_writers");
+      let writerSync = null;
+      if (syncTarget?.vault_ids?.length > 0) {
+        const admitted = [];
+        const notEligible = [];
+        const errors = [];
+        for (const vaultId of syncTarget.vault_ids) {
+          try {
+            const r = await sdk.gitvault.reconcile({ repo_id: vaultId });
+            if (!r.eligible) notEligible.push(vaultId);
+            else if (r.admitted.length > 0) admitted.push({ repo_id: vaultId, admitted: r.admitted });
+          } catch (err) {
+            errors.push({ repo_id: vaultId, error: err?.message ?? String(err) });
+          }
+        }
+        writerSync = { attempted: syncTarget.vault_ids.length, admitted, not_eligible: notEligible, errors };
+      }
+      console.log(JSON.stringify(writerSync ? { ...res, writer_sync: writerSync } : res, null, 2));
+      if (writerSync?.not_eligible.length > 0) {
+        console.error(`writer sync: this session is not (yet) a writer on ${writerSync.not_eligible.length} vault(s) — the new member is a pending writer candidate there until a CURRENT writer's next gitvault operation admits them.`);
+      }
+      if (writerSync?.errors.length > 0) {
+        for (const e of writerSync.errors) console.error(`writer sync: ${e.repo_id} — ${e.error}`);
+      }
+    } catch (err) {
+      reportSdkError(err);
+    }
+    return;
+  }
+
+  if (memberAction === "revoke-key") {
+    // gitvault-agent-envelopes D3: owner + step-up revokes a member's current
+    // gitvault encryption key — the ONLY rotation path for a member that shares
+    // an org with another custodian (a lost/rebuilt keystore fails
+    // GITVAULT_KEY_ROTATION_REQUIRED and points here). Adapter only.
+    const a = normalizeArgv(rest);
+    assertKnownFlags(a, ["--org", "--principal", "--reason", "--help", "-h"], ["--org", "--principal", "--reason"]);
+    const principalFlag = flagValue(a, "--principal");
+    const reason = flagValue(a, "--reason");
+    const count = principalFlag ? 0 : 1;
+    const { orgId: org, rest: pos } = await takeOrgPositional(a, ["--org", "--principal", "--reason"], { cmd: "org" });
+    requireRest(pos, {
+      min: count, max: count, command: "run402 org member revoke-key [<org_id>] --principal <principal_id> [--reason <why>]",
+      missing: "Missing <principal_id> (--principal).",
+    });
+    const principalId = principalFlag ?? pos[0];
+    try {
+      console.log(JSON.stringify(await getSdk().org(org).members.revokeEncryptionKey(principalId, reason ? { reason } : {}), null, 2));
     } catch (err) {
       reportSdkError(err);
     }
@@ -559,17 +677,17 @@ async function runMember(args) {
 
   if (memberAction === "role") {
     const a = normalizeArgv(rest);
-    assertKnownFlags(a, ["--principal", "--role", "--help", "-h"], ["--principal", "--role"]);
+    assertKnownFlags(a, ["--org", "--principal", "--role", "--help", "-h"], ["--org", "--principal", "--role"]);
     const principalFlag = flagValue(a, "--principal");
     const roleFlag = flagValue(a, "--role");
-    const count = 3 - (principalFlag ? 1 : 0) - (roleFlag ? 1 : 0);
-    const pos = requirePositionalCount(a, ["--principal", "--role"], {
-      min: count, max: count, command: "run402 org member role <org_id> --principal <principal_id> --role <role>",
-      missing: "Missing <org_id>, <principal_id> (--principal), and/or <role> (--role).",
+    const count = 2 - (principalFlag ? 1 : 0) - (roleFlag ? 1 : 0);
+    const { orgId: org, rest: pos } = await takeOrgPositional(a, ["--org", "--principal", "--role"], { cmd: "org" });
+    requireRest(pos, {
+      min: count, max: count, command: "run402 org member role [<org_id>] --principal <principal_id> --role <role>",
+      missing: "Missing <principal_id> (--principal) and/or <role> (--role).",
     });
-    const org = pos[0];
-    const principalId = principalFlag ?? pos[1];
-    const role = roleFlag ?? (principalFlag ? pos[1] : pos[2]);
+    const principalId = principalFlag ?? pos[0];
+    const role = roleFlag ?? (principalFlag ? pos[0] : pos[1]);
     try {
       console.log(JSON.stringify(await getSdk().org(org).members.setRole(principalId, { role }), null, 2));
     } catch (err) {
@@ -580,15 +698,15 @@ async function runMember(args) {
 
   if (memberAction === "rm") {
     const a = normalizeArgv(rest);
-    assertKnownFlags(a, ["--principal", "--help", "-h"], ["--principal"]);
+    assertKnownFlags(a, ["--org", "--principal", "--help", "-h"], ["--org", "--principal"]);
     const principalFlag = flagValue(a, "--principal");
-    const count = principalFlag ? 1 : 2;
-    const pos = requirePositionalCount(a, ["--principal"], {
-      min: count, max: count, command: "run402 org member rm <org_id> --principal <principal_id>",
-      missing: principalFlag ? "Missing <org_id>." : "Missing <org_id> and/or <principal_id> (use --principal).",
+    const count = principalFlag ? 0 : 1;
+    const { orgId: org, rest: pos } = await takeOrgPositional(a, ["--org", "--principal"], { cmd: "org" });
+    requireRest(pos, {
+      min: count, max: count, command: "run402 org member rm [<org_id>] --principal <principal_id>",
+      missing: "Missing <principal_id> (use --principal).",
     });
-    const org = pos[0];
-    const principalId = principalFlag ?? pos[1];
+    const principalId = principalFlag ?? pos[0];
     try {
       console.log(JSON.stringify(await getSdk().org(org).members.revoke(principalId), null, 2));
     } catch (err) {
@@ -616,10 +734,9 @@ async function runInvite(args) {
 
   if (inviteAction === "list") {
     const a = normalizeArgv(rest);
-    assertKnownFlags(a, ["--help", "-h"]);
-    const [org] = requirePositionalCount(a, [], {
-      min: 1, max: 1, command: "run402 org invite list <org_id>", missing: "Missing <org_id>.",
-    });
+    assertKnownFlags(a, ["--org", "--help", "-h"], ["--org"]);
+    const { orgId: org, rest: pos } = await takeOrgPositional(a, ["--org"], { cmd: "org" });
+    requireRest(pos, { max: 0, command: "run402 org invite list [<org_id>]" });
     try {
       console.log(JSON.stringify({ invites: await getSdk().org(org).invites.list() }, null, 2));
     } catch (err) {
@@ -630,18 +747,18 @@ async function runInvite(args) {
 
   if (inviteAction === "create") {
     const a = normalizeArgv(rest);
-    const valueFlags = ["--role", "--ttl-hours", "--email"];
+    const valueFlags = ["--org", "--role", "--ttl-hours", "--email"];
     assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
     const role = flagValue(a, "--role");
     const ttlFlag = flagValue(a, "--ttl-hours");
     const emailFlag = flagValue(a, "--email");
-    const count = emailFlag ? 1 : 2;
-    const pos = requirePositionalCount(a, valueFlags, {
-      min: count, max: count, command: "run402 org invite create <org_id> --email <email> [--role <role>]",
-      missing: emailFlag ? "Missing <org_id>." : "Missing <org_id> and/or <email> (use --email).",
+    const count = emailFlag ? 0 : 1;
+    const { orgId: org, rest: pos } = await takeOrgPositional(a, valueFlags, { cmd: "org" });
+    requireRest(pos, {
+      min: count, max: count, command: "run402 org invite create [<org_id>] --email <email> [--role <role>]",
+      missing: "Missing <email> (use --email).",
     });
-    const org = pos[0];
-    const email = emailFlag ?? pos[1];
+    const email = emailFlag ?? pos[0];
     const inviteTtlHours = ttlFlag === null ? undefined : parseIntegerFlag("--ttl-hours", ttlFlag, { min: 1, max: 8760 });
     try {
       const res = await getSdk().org(org).invites.create({ email, role: role || "developer", inviteTtlHours });
@@ -654,15 +771,15 @@ async function runInvite(args) {
 
   if (inviteAction === "rm") {
     const a = normalizeArgv(rest);
-    assertKnownFlags(a, ["--principal", "--help", "-h"], ["--principal"]);
+    assertKnownFlags(a, ["--org", "--principal", "--help", "-h"], ["--org", "--principal"]);
     const principalFlag = flagValue(a, "--principal");
-    const count = principalFlag ? 1 : 2;
-    const pos = requirePositionalCount(a, ["--principal"], {
-      min: count, max: count, command: "run402 org invite rm <org_id> --principal <principal_id>",
-      missing: principalFlag ? "Missing <org_id>." : "Missing <org_id> and/or <principal_id> (use --principal).",
+    const count = principalFlag ? 0 : 1;
+    const { orgId: org, rest: pos } = await takeOrgPositional(a, ["--org", "--principal"], { cmd: "org" });
+    requireRest(pos, {
+      min: count, max: count, command: "run402 org invite rm [<org_id>] --principal <principal_id>",
+      missing: "Missing <principal_id> (use --principal).",
     });
-    const org = pos[0];
-    const principalId = principalFlag ?? pos[1];
+    const principalId = principalFlag ?? pos[0];
     try {
       console.log(JSON.stringify(await getSdk().org(org).invites.revoke(principalId), null, 2));
     } catch (err) {

package/lib/projects.mjs

@@ -319,7 +319,7 @@ async function provision(args) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--tier" && args[i + 1]) opts.tier = args[++i];
     // Use !== undefined so an empty-string value is captured (and rejected
-    // below) rather than silently dropped by the falsy-check pattern (GH-176).
+    // below) rather than silently dropped by the falsy-check pattern.
     if (args[i] === "--name" && args[i + 1] !== undefined) opts.name = args[++i];
     // --org targets an EXISTING org (v1.82); caller needs developer+ on it.
     // Omitted = cold-start. Tier is org-governed, so --tier is irrelevant here
@@ -345,7 +345,7 @@ async function provision(args) {
     });
   }
   // Validate --name when provided. Omitted --name lets the server pick a
-  // default. The same envelope should also be enforced server-side (GH-176).
+  // default. The same envelope should also be enforced server-side.
   if (opts.name !== undefined) {
     if (opts.name === "") {
       fail({