run402 4.68.3 → 4.69.0

package/cli.mjs

@@ -533,8 +533,8 @@ switch (cmd) {
     ]);
     const closest = typeof cmd === "string" ? closestWord(cmd, [...families]) : null;
     // `cmd` is the first bare positional — could be anything a script passes
-    // by mistake (kychee-com/run402-private#640 is the demonstrated risk for
-    // this shape of value), so it must not be echoed verbatim.
+    // by mistake, and a secret is a demonstrated risk for this shape of
+    // value, so it must not be echoed verbatim.
     const shownCmd = describeRejectedValue(cmd);
     fail({
       code: "UNKNOWN_COMMAND",

package/core-dist/allowance-auth.js

@@ -115,7 +115,7 @@ export function buildSIWxAuthHeaders(opts) {
  * @param path - API path (e.g. "/projects/v1") used to build the SIWE uri field.
  */
 export function getAllowanceAuthHeaders(path, allowancePath) {
-    // GH-194: readAllowance throws on a malformed-shape allowance file. The
+    // readAllowance throws on a malformed-shape allowance file. The
     // CLI's higher-level readAllowance wrapper surfaces this as a structured
     // BAD_ALLOWANCE_FILE envelope; here we preserve the public contract that
     // this helper returns SIWxAuthHeaders | null. Re-throw so callers above

package/core-dist/allowance.js

@@ -14,7 +14,7 @@ const PRIVATE_KEY_RE = /^0x[a-fA-F0-9]{64}$/;
  *   - the file exists but is not parseable JSON (preserve existing UX —
  *     consumers print "no_allowance" and tell the user to run init)
  *
- * Throws a structured `Error` (GH-194) when the file parses as JSON but the
+ * Throws a structured `Error` when the file parses as JSON but the
  * shape is wrong (missing/wrong-type/wrong-length fields). Without this guard
  * downstream callers crash with raw stack traces:
  *   - `cli/lib/status.mjs` reaches for `allowance.address.toLowerCase()`

package/core-dist/config.js

@@ -83,10 +83,10 @@ function assertSafeProfileName(name) {
         return;
     if (!isValidProfileName(name)) {
         // A value that failed this check is a value we know nothing about — the
-        // most likely mistake is a typo, but kychee-com/run402-private#640 was a
-        // Base-mainnet private key pasted into RUN402_WALLET (a NAME field), and
-        // the raw value used to be echoed straight into this message and
-        // wherever it propagated (terminal, logs, session transcripts).
+        // most likely mistake is a typo, but a Base-mainnet private key pasted
+        // into RUN402_WALLET (a NAME field) is a demonstrated case, and echoing
+        // the raw value propagates it into terminals, logs, and session
+        // transcripts.
         // describeRejectedValue() shows short/plain values in full (useful for
         // an actual typo) and redacts anything long or hex-shaped enough to be
         // a secret instead of a name.

package/core-dist/keystore.js

@@ -190,15 +190,15 @@ export function removeProject(projectId, path) {
  * bucket, not "unknown") and PERMANENTLY shadows every later wallet-scoped
  * activation for every caller that reads through this module: `resolveProjectId`
  * / `resolveProject` (cli/lib/config.mjs), `projects current`, and every
- * gitvault-verb target resolution. That is the root cause behind
- * kychee-com/run402#559(a) — `repos create` DID call `projects.provision`,
- * whose `creds.setActiveProject` correctly persisted the new project under
- * the real wallet's scoped bucket AND the flat fallback, but every CLI read
- * of "the active project" kept resolving the OLD "unknown"-bucket entry
- * first and never fell through to the freshly-updated flat value.
+ * gitvault-verb target resolution. The failure it causes: `repos create`
+ * calls `projects.provision`, whose `creds.setActiveProject` correctly
+ * persists the new project under the real wallet's scoped bucket AND the
+ * flat fallback, yet every CLI read of "the active project" resolves the
+ * stale "unknown"-bucket entry first and never falls through to the
+ * freshly-updated flat value.
  *
  * Best-effort: an unreadable/malformed allowance degrades to `null` (the
- * same "unknown" bucket callers already tolerated before this fix), never a
+ * "unknown" bucket callers tolerate), never a
  * throw — this is a read-scoping concern, not an allowance-validity one.
  */
 function currentPrincipal() {

package/core-dist/profiles.js

@@ -154,7 +154,7 @@ export function removeProfile(name) {
  */
 export function renameProfile(oldName, newName) {
     if (!isValidProfileName(newName)) {
-        // See describeRejectedValue()'s doc comment (kychee-com/run402-private#640):
+        // See describeRejectedValue()'s doc comment:
         // a rejected value may be a secret pasted into a name field, so it is
         // never safe to echo verbatim here.
         throw new Error(`Invalid wallet name ${JSON.stringify(describeRejectedValue(newName))}.`);

package/core-dist/redact.js

@@ -4,11 +4,10 @@
  * A value rejected by a format/existence check is a value we know nothing
  * about — the CLI has only established what it is NOT. The likeliest
  * failure is an ordinary typo, but the second likeliest, demonstrated in
- * practice, is a credential pasted into the wrong slot:
- * kychee-com/run402-private#640 — a Base-mainnet private key holding real
- * funds landed in `RUN402_WALLET` (which takes a wallet NAME, not a key),
- * failed the name check, and was printed verbatim to a terminal, a log, and
- * a session transcript.
+ * practice, is a credential pasted into the wrong slot: a Base-mainnet
+ * private key holding real funds lands in `RUN402_WALLET` (which takes a
+ * wallet NAME, not a key), fails the name check, and is printed verbatim to
+ * a terminal, a log, and a session transcript.
  *
  * `describeRejectedValue` is the one place that decides what a rejected
  * value is safe to show, so every call site — wallet names, org ids, room
@@ -35,11 +34,11 @@
 // canonical shape of an org id, and *itself* a public, harmless-to-echo
 // identifier even when it's the "wrong" one in a conflict, not a secret).
 // Secrets that land in the wrong slot (private keys, API tokens, JWTs) are
-// almost always well past it — the private key in #640 was 64-66 characters.
+// almost always well past it — a private key runs 64-66 characters.
 const MAX_SAFE_ECHO_LENGTH = 40;
 // A contiguous hex run (with or without a `0x` prefix) reads as key
 // material or a hash rather than a human-typed identifier, even when short
-// enough to pass the length check above — the exact shape of #640.
+// enough to pass the length check above.
 const HEX_RUN_RE = /^(0x)?[0-9a-fA-F]{16,}$/;
 function looksSecretShaped(str) {
     return str.length > MAX_SAFE_ECHO_LENGTH || HEX_RUN_RE.test(str);

package/git-remote-run402.mjs

@@ -20,8 +20,8 @@
  *     builtins + `./lib/daemon-path.mjs` only, pinned by a source-level
  *     gate test (design D7). The heavy graph loads only on fallback.
  *   - `RUN402_DAEMON=0` disables the daemon entirely (dev/CI toggle,
- *     approved 2026-08-30 — positively named, default on, only "0"
- *     disables); any other value behaves as unset.
+ *     positively named, default on, only "0" disables); any other value
+ *     behaves as unset.
  *
  * The remote-helper doctrine (fail-closed repository resolution, wallet
  * selection, protocol semantics) lives with the session implementation in

package/gitvault-surface.json

@@ -1,5 +1,5 @@
 {
-  "surface_version": "4.68.3",
+  "surface_version": "4.69.0",
   "verbs": [
     "repos create",
     "repos list",
@@ -17,6 +17,7 @@
     "repos access repair",
     "repos access revoke-key",
     "repos access declare-exposure",
+    "repos access sync",
     "repos recover",
     "repos recovery-bundle"
   ],

package/lib/agent.mjs

@@ -93,7 +93,7 @@ async function contact(args) {
   if (!name) {
     fail({ code: "BAD_USAGE", message: "Missing --name <name>" });
   }
-  // GH-192: validate webhook scheme locally BEFORE the allowance check so
+  // validate webhook scheme locally BEFORE the allowance check so
   // bad URLs fail fast even without an allowance configured. No-op when
   // --webhook is omitted (it's optional).
   validateWebhookUrl(webhook, "--webhook");

package/lib/allowance.mjs

@@ -92,10 +92,9 @@ async function status() {
         address: data.address,
         created: data.created,
         configured: data.configured,
-        // GH-109: `funded` used to leak an on-disk marker that only tracks
-        // faucet invocation, not actual pay-readiness. Renamed to `faucet_used`
-        // to match its real semantics. For a true "can this account pay right
-        // now" check, use `run402 allowance balance`.
+        // `faucet_used` is named for what it is: an on-disk marker that
+        // tracks faucet invocation, not pay-readiness. For a true "can this
+        // account pay right now" check, use `run402 allowance balance`.
         faucet_used: !!data.faucet_used,
         rail: w?.rail || "x402",
         path: data.path ?? allowanceFile(),

package/lib/argparse.mjs

@@ -141,9 +141,8 @@ export function validateEvmAddress(value, fieldName = "address") {
   }
 }
 
-// A rejected positional could be anything the caller typed or piped in — see
-// core-dist/redact.js's doc comment (kychee-com/run402-private#640) — so it
-// is never safe to echo verbatim.
+// A rejected positional could be anything the caller typed or piped in (see
+// core-dist/redact.js's doc comment), so it is never safe to echo verbatim.
 export function failBadProjectId(value) {
   fail({
     code: "BAD_PROJECT_ID",
@@ -156,7 +155,7 @@ export function failBadProjectId(value) {
 /**
  * Validate a webhook URL: parse it locally and reject non-https:// schemes.
  *
- * Scope (GH-192): scheme-only validation. Reject `javascript:`, `file:`,
+ * Scope: scheme-only validation. Reject `javascript:`, `file:`,
  * `http:`, `data:`, `ftp:`, etc. before the request leaves the CLI process.
  * Server-side SSRF defenses (private-IP filtering, DNS rebinding, IMDS
  * blocking) live on the gateway, not here — this helper is the cheap
@@ -198,9 +197,8 @@ export function validateWebhookUrl(url, fieldName = "--url") {
 
 /**
  * Validate that a CLI flag pointing at a filesystem path resolves to an
- * existing regular file. Replaces the GH-195 inline pattern that was
- * duplicated across `functions deploy`, `secrets set`, `projects sql`,
- * and `projects apply-expose` (GH-233).
+ * existing regular file. Shared by `functions deploy`, `secrets set`,
+ * `projects sql`, and `projects apply-expose`.
  *
  * Without this guard, `readFileSync` against a missing path leaks a raw
  * `node:fs` ENOENT/EISDIR stack to stderr (with the V8 source pointer),
@@ -439,8 +437,8 @@ export function failUnknownSubcommand(family, sub, { hint, label, extraSubcomman
   const known = [...new Set([...knownSubcommands(family), ...extraSubcommands])].sort();
   // closestWord() itself never echoes — it only ever returns one of the
   // known, safe `known` candidates — but `sub` is an arbitrary positional
-  // (could be anything piped or mistyped in; kychee-com/run402-private#640
-  // is the demonstrated risk), so the ECHO of `sub` below still needs
+  // (could be anything piped or mistyped in, a leaked secret included),
+  // so the ECHO of `sub` below still needs
   // redaction even though the matching runs on the raw value.
   const closest = typeof sub === "string" ? closestWord(sub, known) : null;
   const shownSub = describeRejectedValue(sub);

package/lib/billing.mjs

@@ -1,6 +1,7 @@
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
+import { takeOrgPositional, requireRest } from "./org-context.mjs";
 
 const HELP = `run402 billing — Email organizations and org checkouts
 
@@ -9,9 +10,9 @@ Usage:
 
 Subcommands:
   create-email <email>                     Create an email organization
-  link-wallet <org_id> <wallet_address>    Link a wallet to an email organization
+  link-wallet [<org_id>] <wallet_address>  Link a wallet to an email organization
   checkout <identifier> --product <p>      Create an org checkout
-  auto-recharge <org_id> <on|off> [--threshold <n>]
+  auto-recharge [<org_id>] <on|off> [--threshold <n>]
   balance <identifier>                     Balance by organization id (UUID), wallet (0x...), or email
   history <identifier> [--limit <n>]       Ledger history by organization id (UUID), wallet, or email
 
@@ -47,7 +48,7 @@ Examples:
   "auto-recharge": `run402 billing auto-recharge — Toggle email-pack auto-recharge
 
 Usage:
-  run402 billing auto-recharge <org_id> <on|off> [--threshold <n>]
+  run402 billing auto-recharge [<org_id>] <on|off> [--threshold <n>]
 
 Arguments:
   <org_id>        Organization ID
@@ -114,7 +115,7 @@ Examples:
   "link-wallet": `run402 billing link-wallet — Link a wallet to an email organization
 
 Usage:
-  run402 billing link-wallet <org_id> <wallet_address>
+  run402 billing link-wallet [<org_id>] <wallet_address>
 
 Arguments:
   <org_id>        Organization ID (e.g. org_abc123)
@@ -232,22 +233,16 @@ async function createEmail(args) {
 
 async function linkWallet(args) {
   const parsedArgs = normalizeArgv(args);
-  assertKnownFlags(parsedArgs, ["--wallet", "--help", "-h"], ["--wallet"]);
-  const walletFlag = flagValue(parsedArgs, "--wallet");
-  const positionals = positionalArgs(parsedArgs, ["--wallet"]);
-  const organizationId = positionals[0];
-  const wallet = walletFlag ?? positionals[1];
-  const max = walletFlag ? 1 : 2;
-  if (positionals.length > max) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing link-wallet: ${positionals[max]}` });
-  }
-  if (!organizationId || !wallet) {
-    fail({
-      code: "BAD_USAGE",
-      message: "Missing <org_id> and/or <wallet_address>.",
-      hint: "run402 billing link-wallet <org_id> --wallet <wallet_address>",
-    });
-  }
+  assertKnownFlags(parsedArgs, ["--org", "--address", "--help", "-h"], ["--org", "--address"]);
+  const walletFlag = flagValue(parsedArgs, "--address");
+  const { orgId: organizationId, rest } = await takeOrgPositional(parsedArgs, ["--org", "--address"], { cmd: "billing" });
+  const count = walletFlag ? 0 : 1;
+  requireRest(rest, {
+    min: count, max: count,
+    command: "run402 billing link-wallet [<org_id>] <wallet_address>",
+    missing: "Missing <wallet_address> (positional, or --address).",
+  });
+  const wallet = walletFlag ?? rest[0];
   try {
     const data = await getSdk().billing.linkWallet(organizationId, wallet);
     const output = {
@@ -264,27 +259,30 @@ async function linkWallet(args) {
 
 async function autoRecharge(args) {
   const parsedArgs = normalizeArgv(args);
-  const valueFlags = ["--threshold", "--state"];
+  const valueFlags = ["--org", "--threshold", "--state"];
   assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
   const stateFlag = flagValue(parsedArgs, "--state");
-  const positionals = positionalArgs(parsedArgs, valueFlags);
-  const organizationId = positionals[0];
-  const state = stateFlag ?? positionals[1];
-  const max = stateFlag ? 1 : 2;
-  if (positionals.length > max) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing auto-recharge: ${positionals[max]}` });
-  }
-  if (!organizationId || !state || !["on", "off"].includes(state)) {
-    fail({
-      code: "BAD_USAGE",
-      message: "Missing <org_id> and/or <on|off>.",
-      hint: "run402 billing auto-recharge <org_id> --state <on|off> [--threshold <n>]",
-    });
-  }
+  // Local validation FIRST — a malformed --threshold is refused before any org
+  // resolution (which may cost a network hop via --project).
   const thresholdStr = flagValue(parsedArgs, "--threshold");
   const threshold = parsedArgs.includes("--threshold")
     ? parseIntegerFlag("--threshold", thresholdStr, { min: 0 })
     : undefined;
+  const { orgId: organizationId, rest } = await takeOrgPositional(parsedArgs, valueFlags, { cmd: "billing" });
+  const count = stateFlag ? 0 : 1;
+  requireRest(rest, {
+    min: count, max: count,
+    command: "run402 billing auto-recharge [<org_id>] --state <on|off> [--threshold <n>]",
+    missing: "Missing <on|off> (positional, or --state).",
+  });
+  const state = stateFlag ?? rest[0];
+  if (!["on", "off"].includes(state)) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Expected on|off, got ${JSON.stringify(state)}.`,
+      hint: "run402 billing auto-recharge [<org_id>] --state <on|off> [--threshold <n>]",
+    });
+  }
   try {
     await getSdk().billing.setAutoRecharge({
       organizationId: organizationId,

package/lib/buzz-notifications.mjs

@@ -7,6 +7,7 @@
  */
 import { getSdk } from "./sdk.mjs";
 import { fail, reportSdkError } from "./sdk-errors.mjs";
+import { resolveOrgId } from "./org-context.mjs";
 import {
   normalizeArgv,
   hasHelp,
@@ -129,7 +130,7 @@ async function configure(args) {
   const eventTypes = flagValues(a, "--event-type");
   const eventClasses = flagValues(a, "--event-class");
   try {
-    const created = await getSdk().buzz.notifications.createRoute(requiredFlag(a, "--org"), {
+    const created = await getSdk().buzz.notifications.createRoute(await resolveOrgId(a, { cmd: "buzz" }), {
       installationId: requiredFlag(a, "--installation"),
       routeName: requiredFlag(a, "--name"),
       buzzChannelId: requiredFlag(a, "--channel"),
@@ -161,7 +162,7 @@ async function status(args) {
       out(await sdk.buzz.notifications.get(positionals[0]));
       return;
     }
-    const routes = await sdk.buzz.notifications.list(requiredFlag(a, "--org"));
+    const routes = await sdk.buzz.notifications.list(await resolveOrgId(a, { cmd: "buzz" }));
     out({ buzz_project_event_routes: routes });
   } catch (err) {
     reportSdkError(err);

package/lib/buzz.mjs

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { getSdk } from "./sdk.mjs";
 import { fail, reportSdkError } from "./sdk-errors.mjs";
+import { resolveOrgId } from "./org-context.mjs";
 import {
   assertKnownFlags,
   failUnknownSubcommand,
@@ -130,7 +131,8 @@ async function adopt(args) {
     const a = normalizeArgv(rest);
     assertKnownFlags(a, ["--org"], ["--org"]);
     requirePositionalCount(a, ["--org"], { min: 0, max: 0, command: "run402 buzz adopt list --org <org_id>" });
-    return invoke(() => getSdk().buzz.humanAdoptions.list(requiredFlag(a, "--org")));
+    const orgId = await resolveOrgId(a, { cmd: "buzz" });
+    return invoke(() => getSdk().buzz.humanAdoptions.list(orgId));
   }
   if (operation === "show") {
     const a = normalizeArgv(rest);
@@ -143,9 +145,10 @@ async function adopt(args) {
   const a = normalizeArgv(directArgs);
   const values = ["--org", "--identity-link", "--idempotency-key"];
   assertKnownFlags(a, values, values);
-  requirePositionalCount(a, values, { min: 0, max: 0, command: "run402 buzz adopt direct --org <org_id> --identity-link <idlnk_id>" });
+  requirePositionalCount(a, values, { min: 0, max: 0, command: "run402 buzz adopt direct [--org <org_id>] --identity-link <idlnk_id>" });
+  const organizationId = await resolveOrgId(a, { cmd: "buzz" });
   return invoke(() => getSdk({ authMode: "wallet" }).buzz.adopt({
-    organizationId: requiredFlag(a, "--org"),
+    organizationId,
     identityLinkId: requiredFlag(a, "--identity-link"),
     idempotencyKey: flagValue(a, "--idempotency-key") ?? undefined,
   }));
@@ -169,8 +172,9 @@ async function adoptionOffer(args) {
   const a = normalizeArgv(args);
   const values = ["--org", "--identity-link", "--deployment-context-file", "--idempotency-key"];
   assertKnownFlags(a, values, values);
-  requirePositionalCount(a, values, { min: 0, max: 0, command: "run402 buzz adopt offer --org <org_id> --identity-link <idlnk_id>" });
+  requirePositionalCount(a, values, { min: 0, max: 0, command: "run402 buzz adopt offer [--org <org_id>] --identity-link <idlnk_id>" });
   const deploymentPath = flagValue(a, "--deployment-context-file");
+  const organizationId = await resolveOrgId(a, { cmd: "buzz" });
   return invoke(async () => {
     const client = getSdk({ authMode: "wallet" });
     const status = await client.buzz.status();
@@ -183,7 +187,7 @@ async function adoptionOffer(args) {
       });
     }
     return client.buzz.offerAdoption({
-      organizationId: requiredFlag(a, "--org"),
+      organizationId,
       identityLinkId: requiredFlag(a, "--identity-link"),
       deploymentContext: deploymentPath ? readJsonFile(deploymentPath, "--deployment-context-file") : undefined,
       idempotencyKey: flagValue(a, "--idempotency-key") ?? undefined,
@@ -227,7 +231,8 @@ async function install(args) {
     const a = normalizeArgv(rest);
     assertKnownFlags(a, ["--org"], ["--org"]);
     requirePositionalCount(a, ["--org"], { min: 0, max: 0, command: "run402 buzz install list --org <org_id>" });
-    return invoke(() => getSdk().buzz.communityInstallations.list(requiredFlag(a, "--org")));
+    const orgId = await resolveOrgId(a, { cmd: "buzz" });
+    return invoke(() => getSdk().buzz.communityInstallations.list(orgId));
   }
   if (operation === "discover") {
     const a = normalizeArgv(rest);
@@ -247,10 +252,11 @@ async function install(args) {
   const a = normalizeArgv(args);
   const values = ["--org", "--community", "--authority", "--policy-file", "--idempotency-key"];
   assertKnownFlags(a, values, values);
-  requirePositionalCount(a, values, { min: 0, max: 0, command: "run402 buzz install --org <org_id> --community <subject> --authority <hex>" });
+  requirePositionalCount(a, values, { min: 0, max: 0, command: "run402 buzz install [--org <org_id>] --community <subject> --authority <hex>" });
   const policyFile = flagValue(a, "--policy-file");
+  const organizationId = await resolveOrgId(a, { cmd: "buzz" });
   return invoke(() => getSdk().buzz.install({
-    organizationId: requiredFlag(a, "--org"),
+    organizationId,
     buzzCommunitySubject: requiredFlag(a, "--community"),
     buzzCommunityAuthoritySubject: requiredFlag(a, "--authority"),
     enrollmentPolicy: policyFile ? readJsonFile(policyFile, "--policy-file") : undefined,

package/lib/buzz.test.mjs

@@ -92,7 +92,7 @@ describe("run402 buzz CLI", () => {
     try {
       await run("adopt", [
         "offer",
-        "--org", `org_${"2".repeat(32)}`,
+        "--org", "22222222-2222-4222-8222-222222222222",
         "--identity-link", `idlnk_${"3".repeat(32)}`,
         "--deployment-context-file", contextPath,
         "--idempotency-key", "offer-after-demo-1",

package/lib/command-manifest.mjs

@@ -15,6 +15,15 @@
  *   projectScoped          command operates on a project and accepts
  *                          `--project <id>` (precedence: --project > legacy
  *                          leading prj_ positional > active project)
+ *   orgScoped              command acts ON an organization and resolves it
+ *                          through the ONE shared chain (cli-org-context):
+ *                          an optional leading <org_id> positional, else
+ *                          --org, else RUN402_ORG, else the .run402.json
+ *                          binding, else `org use`. The gate drives every
+ *                          such entry through --org AND RUN402_ORG with no
+ *                          positional and fails on any "Missing <org_id>".
+ *                          Any entry with an `org_id` positional MUST be
+ *                          orgScoped and that positional MUST be optional.
  *   legacyPositionalProject  still accepts the legacy leading `prj_...`
  *                          positional project selector (compat, no warning)
  *   minimalArgs            args (beyond path) that satisfy LOCAL validation
@@ -40,6 +49,14 @@
 
 const p = (name, { required = true, variadic = false } = {}) => ({ name, required, variadic });
 
+/**
+ * The org id the gate uses for every orgScoped entry — a well-formed UUID so
+ * the shared resolver accepts it from any rung (positional, --org, RUN402_ORG).
+ * The behavioral org-scope gate strips it from minimalArgs and re-supplies the
+ * org through each rung in turn.
+ */
+export const GATE_ORG = "11111111-2222-3333-4444-555555555555";
+
 export const COMMAND_MANIFEST = [
   // ── external agent identity links ────────────────────────────────────────
   { path: ["identity", "link", "nostr", "begin"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--pubkey", "4f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa", "--visibility", "public"], skipBehavioral: "requires a live wallet and gateway challenge" },
@@ -50,16 +67,16 @@ export const COMMAND_MANIFEST = [
 
   // ── Buzz community ↔ Run402 control plane ───────────────────────────────
   { path: ["buzz", "status"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], skipBehavioral: "requires live principal authentication" },
-  { path: ["buzz", "adopt", "offer"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--org", "org_11111111111111111111111111111111", "--identity-link", "idlnk_11111111111111111111111111111111"], skipBehavioral: "requires eligible sole agent owner, live Buzz identity, and offer-capable gateway" },
-  { path: ["buzz", "adopt", "direct"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--org", "org_11111111111111111111111111111111", "--identity-link", "idlnk_11111111111111111111111111111111"], skipBehavioral: "advanced compatibility flow requiring eligible sole agent owner and live Buzz identity" },
-  { path: ["buzz", "install"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--org", "org_11111111111111111111111111111111", "--community", "buzz:community:relay.example", "--authority", "11".repeat(32)], skipBehavioral: "requires owner step-up and a compatible live Buzz relay" },
+  { path: ["buzz", "adopt", "offer"], positionals: [], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: ["--identity-link", "idlnk_11111111111111111111111111111111"], skipBehavioral: "requires eligible sole agent owner, live Buzz identity, and offer-capable gateway" },
+  { path: ["buzz", "adopt", "direct"], positionals: [], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: ["--identity-link", "idlnk_11111111111111111111111111111111"], skipBehavioral: "advanced compatibility flow requiring eligible sole agent owner and live Buzz identity" },
+  { path: ["buzz", "install"], positionals: [], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: ["--community", "buzz:community:relay.example", "--authority", "11".repeat(32)], skipBehavioral: "requires owner step-up and a compatible live Buzz relay" },
   { path: ["buzz", "enroll"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--installation", "buzzci_11111111111111111111111111111111", "--identity-link", "idlnk_11111111111111111111111111111111", "--grants-file", "__FIXTURE_FILE__", "--expires-at", "2026-08-01T00:00:00.000Z"], skipBehavioral: "requires live relay membership evidence and a grant fixture" },
   { path: ["buzz", "approve"], positionals: [p("buzz_agent_enrollment_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["buzzae_11111111111111111111111111111111", "--grants-file", "__FIXTURE_FILE__", "--descriptor-revision", "1", "--policy-revision", "1"], skipBehavioral: "requires owner step-up and a live pending enrollment" },
   { path: ["buzz", "deny"], positionals: [p("buzz_agent_enrollment_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["buzzae_11111111111111111111111111111111"], skipBehavioral: "requires owner step-up and a live pending enrollment" },
   { path: ["buzz", "revoke"], positionals: [p("buzz_agent_enrollment_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["buzzae_11111111111111111111111111111111"], skipBehavioral: "requires a live enrollment" },
   // Project-event routing into a Buzz channel (add-buzz-project-event-routing).
   // org ids on this surface are BARE dashed UUIDs, never org_-prefixed.
-  { path: ["buzz", "notifications", "configure"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--org", "11111111-1111-4111-8111-111111111111", "--installation", "buzzci_11111111111111111111111111111111", "--name", "deploys", "--channel", "22222222-2222-4222-8222-222222222222"], skipBehavioral: "requires live owner authentication and an active Buzz installation (and its repeatable --project scope flag is reserved by the gate)" },
+  { path: ["buzz", "notifications", "configure"], positionals: [], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: ["--installation", "buzzci_11111111111111111111111111111111", "--name", "deploys", "--channel", "22222222-2222-4222-8222-222222222222"], skipBehavioral: "requires live owner authentication and an active Buzz installation (and its repeatable --project scope flag is reserved by the gate)" },
   { path: ["buzz", "notifications", "status"], positionals: [p("buzz_project_event_route_id", { required: false })], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--org", "11111111-1111-4111-8111-111111111111"], skipBehavioral: "requires live owner authentication" },
   { path: ["buzz", "notifications", "test"], positionals: [p("buzz_project_event_route_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["buzzper_11111111111111111111111111111111"], skipBehavioral: "requires live owner authentication and a live route" },
   { path: ["buzz", "notifications", "deliveries"], positionals: [p("buzz_project_event_route_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["buzzper_11111111111111111111111111111111"], skipBehavioral: "requires live owner authentication and a live route" },
@@ -194,28 +211,28 @@ export const COMMAND_MANIFEST = [
   // ── org ──────────────────────────────────────────────────────────────────
   { path: ["org", "create"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["org", "list"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["org", "get"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1"] },
-  { path: ["org", "rename"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--name", "Gate"] },
-  { path: ["org", "payout-wallet"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--wallet", "0x1111111111111111111111111111111111111111"] },
+  { path: ["org", "get"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG] },
+  { path: ["org", "rename"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--name", "Gate"] },
+  { path: ["org", "payout-wallet"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "0x1111111111111111111111111111111111111111"] },
   // `--org` (not a positional org_id
   // like rename/payout-wallet above) goes through resolveOrg's SHAPE
   // validation (a real UUID) — "org_gate1" fails that locally, so this needs
   // the same UUID-shaped fixture `org use` below already established.
   { path: ["org", "slug"], positionals: [p("slug")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["acme", "--org", "11111111-2222-3333-4444-555555555555"] },
   { path: ["org", "whoami"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["org", "audit"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1"] },
+  { path: ["org", "audit"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG] },
   { path: ["org", "use"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["11111111-2222-3333-4444-555555555555"] },
   { path: ["org", "current"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["org", "clear"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["org", "bind"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--org", "11111111-2222-3333-4444-555555555555"] },
   { path: ["org", "unbind"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["org", "member", "list"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1"] },
-  { path: ["org", "member", "add"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--wallet", "0x1111111111111111111111111111111111111111"] },
-  { path: ["org", "member", "role"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--principal", "prn_gate1", "--role", "viewer"] },
-  { path: ["org", "member", "rm"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--principal", "prn_gate1"] },
-  { path: ["org", "invite", "list"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1"] },
-  { path: ["org", "invite", "create"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--email", "gate@example.com"] },
-  { path: ["org", "invite", "rm"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--principal", "prn_gate1"] },
+  { path: ["org", "member", "list"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG] },
+  { path: ["org", "member", "add"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "0x1111111111111111111111111111111111111111"] },
+  { path: ["org", "member", "role"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--principal", "prn_gate1", "--role", "viewer"] },
+  { path: ["org", "member", "rm"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--principal", "prn_gate1"] },
+  { path: ["org", "invite", "list"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG] },
+  { path: ["org", "invite", "create"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--email", "gate@example.com"] },
+  { path: ["org", "invite", "rm"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--principal", "prn_gate1"] },
 
   // ── grants ───────────────────────────────────────────────────────────────
   { path: ["grants", "create"], positionals: [p("wallet")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["0x1111111111111111111111111111111111111111", "--capability", "deploy"] },
@@ -285,13 +302,14 @@ export const COMMAND_MANIFEST = [
   { path: ["repos", "mirror"], positionals: [p("destination", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "reads/writes mirror destination config beside the keystore and may move real bytes into a customer-owned bucket" },
   { path: ["repos", "fsck"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "walks the live head chain and materializes the ref map against the keystore's local pins" },
   { path: ["repos", "gc"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "publishes a checkpoint under a maintenance lease and materializes the live vault head to enumerate retention roots" },
-  // `access repair`/`revoke-key`/`declare-exposure` are nested sub-verb
-  // literals — one manifest entry each, all dispatched through the ONE
-  // `run("access", ...)` case in repos.mjs.
+  // `access repair`/`revoke-key`/`declare-exposure`/`sync` are nested
+  // sub-verb literals — one manifest entry each, all dispatched through the
+  // ONE `run("access", ...)` case in repos.mjs.
   { path: ["repos", "access"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "reads the live org encryption-key directory + vault envelope recipients" },
   { path: ["repos", "access", "repair"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--recipient-state-version", "0", "--recipient-revocation-version", "0"], runStyle: "sub", skipBehavioral: "owner+step-up-gated epoch rotation (D193-D203, rev 42) — samples a fresh epoch key and re-seals a live vault's recipients" },
   { path: ["repos", "access", "revoke-key"], positionals: [p("principal_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["prin_00000000000000000000000000000000"], runStyle: "sub", skipBehavioral: "owner+step-up-gated: declares a recipient's key revoked (org-scoped watermark) and drives a real epoch rotation off it" },
   { path: ["repos", "access", "declare-exposure"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "owner+step-up-gated: declares this vault's epoch secret exposed, forcing every subsequent ordinary push to refuse until a rotation lands" },
+  { path: ["repos", "access", "sync"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "gitvault-multi-writer (rev 47): on-demand writer-admission reconcile — resolves pending candidates' signing keys via the live org encryption-key directory and publishes a real add_writer_key head per candidate" },
   { path: ["repos", "recover"], positionals: [p("source")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["s3://example-mirror-bucket", "--out", "__SCRATCH_DIR__/recover-out"], runStyle: "sub", skipBehavioral: "materializes a git repository from a mirror source, offline, with no server call" },
   // Principal-scoped (one bundle covers every vault you can read), so no
   // --project — deliberately unlike its eleven vault-scoped siblings.
@@ -424,9 +442,9 @@ export const COMMAND_MANIFEST = [
 
   // ── billing ──────────────────────────────────────────────────────────────
   { path: ["billing", "create-email"], positionals: [p("email")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["gate@example.com"] },
-  { path: ["billing", "link-wallet"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["00000000-0000-4000-8000-000000000001", "--wallet", "0x1111111111111111111111111111111111111111"] },
+  { path: ["billing", "link-wallet"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "0x1111111111111111111111111111111111111111"] },
   { path: ["billing", "checkout"], positionals: [p("identifier")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["00000000-0000-4000-8000-000000000001", "--product", "email-pack"] },
-  { path: ["billing", "auto-recharge"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["00000000-0000-4000-8000-000000000001", "--state", "on"] },
+  { path: ["billing", "auto-recharge"], positionals: [p("org_id", { required: false })], projectScoped: false, orgScoped: true, legacyPositionalProject: false, minimalArgs: [GATE_ORG, "--state", "on"] },
   { path: ["billing", "balance"], positionals: [p("identifier")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["gate@example.com"] },
   { path: ["billing", "history"], positionals: [p("identifier")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["gate@example.com"] },
 

package/lib/config.mjs

@@ -55,7 +55,7 @@ export const API = getApiBase();
 
 /**
  * Wraps core's `readAllowance()` and converts the malformed-shape throw
- * (GH-194) into the canonical CLI failure envelope. Without this guard, every
+ * into the canonical CLI failure envelope. Without this guard, every
  * CLI subcommand that touches the allowance leaks a Node stack trace and
  * source paths the moment a user has a malformed `allowance.json`.
  *