run402 4.95.0 → 4.97.0

package/lib/grants.mjs

@@ -1,5 +1,5 @@
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError, parseFlagJson } from "./sdk-errors.mjs";
+import { reportSdkError, parseFlagJson, fail } from "./sdk-errors.mjs";
 import {
   normalizeArgv,
   assertKnownFlags,
@@ -9,114 +9,213 @@ import {
   failUnknownSubcommand,
 } from "./argparse.mjs";
 
-const HELP = `run402 grants — per-project capability grants (agent/CI principals)
+const HELP = `run402 grants — per-project capability grants and their grant keys
 
 Usage:
   run402 grants <subcommand> [args...]
 
 Subcommands:
-  create <wallet> --capability <cap> [--project <project_id>] [--policy <json>] [--expires <iso8601>]
-                                 Issue a capability grant (owner of the project's org)
+  create <wallet> --capability <cap> [--project <project_id>] [--policy <json>] [--expires-at <iso8601>]
+         [--key [--kind <kind>] [--scope <json>] [--spend-cap <json>]]
+                                 Issue a grant; with --key also mint its first
+                                 grant key (the token is printed ONCE)
+  list [--project <project_id>]  List grants with their keys nested (never tokens)
   revoke <grant_id> [--project <project_id>]
-                                 Revoke a capability grant
-
-Legacy (still supported):
-  run402 grants create <project_id> <wallet> <capability> [...]
-  run402 grants revoke <project_id> <grant_id>
+                                 Revoke a grant and every key minted against it
+  revoke-key <key_id> [--project <project_id>]
+                                 Revoke one grant key; the grant stays
+  rotate-key <key_id> [--project <project_id>]
+                                 Replace a lost key; the new token is printed ONCE
 
 Notes:
-  - Grants let a non-member wallet (an agent or CI principal) act on ONE project,
-    without making it a broad org member. Mutations require owner of the project's org.
+  - A grant is the permission row: this wallet may do this capability on this
+    project until this date. An agent with its own wallet needs only the grant.
+  - A grant key is a credential minted against exactly one grant: narrower than
+    it, spend-capped, expiring, revocable on its own, never an owner. Hand it to
+    an agent without a wallet: RUN402_GRANT_KEY=<token> run402 deploy ...
+  - Every subcommand requires owner of the project's org. Minting a key with a
+    sign-in session takes a fresh step-up.
+  - The key token is shown ONCE and cannot be read back. Store it immediately;
+    if you lose it, 'rotate-key' issues a new one.
   - capability examples: deploy, functions:write.
   - JSON in, JSON out.
 
 Examples:
   run402 grants create 0xf39Fd6...92266 --capability deploy --project prj_abc
-  run402 grants create 0xf39Fd6...92266 --capability functions:write --expires 2026-12-31T00:00:00Z
-  run402 grants revoke grt_xyz --project prj_abc
+  run402 grants create 0x90F3eB...F80a --capability deploy --key --project prj_abc
+  run402 grants list --project prj_abc
+  run402 grants revoke-key 5845f17b-... --project prj_abc
+  run402 grants revoke 1d86452e-... --project prj_abc
 `;
 
 const SUB_HELP = {
-  create: `run402 grants create — issue a per-project capability grant
+  create: `run402 grants create — issue a per-project capability grant, optionally with a grant key
 
 Usage:
-  run402 grants create <wallet> --capability <cap> [--project <project_id>] [--policy <json>] [--expires <iso8601>]
-
-Legacy (still supported):
-  run402 grants create <project_id> <wallet> <capability> [options]
+  run402 grants create <wallet> --capability <cap> [--project <project_id>] [--policy <json>] [--expires-at <iso8601>]
+                       [--key [--kind <kind>] [--scope <json>] [--spend-cap <json>]]
 
 Arguments:
-  <wallet>       EVM address or named wallet the grant is issued to
+  <wallet>              EVM address or named wallet the grant is issued to
 
 Options:
-  --project <project_id>      Project to grant access to (defaults to the active project)
-  --capability <cap>  e.g. deploy, functions:write (alternative to the legacy positional)
-  --policy <json>     Capability-scoping policy object (gateway-interpreted)
-  --expires <iso8601> Expiry timestamp; omit for a non-expiring grant
+  --project <project_id>  Project to grant access to (defaults to the active project)
+  --capability <cap>      e.g. deploy, functions:write
+  --policy <json>         Capability-scoping policy object (gateway-interpreted)
+  --expires-at <iso8601>  Expiry; omit for a non-expiring grant. With --key the
+                          key takes the same expiry.
+  --key                   Also mint the grant's first grant key in the same
+                          transaction. Its token is printed ONCE.
+  --kind <kind>           Key kind (with --key). Default run402_agent_key, the
+                          only kind that returns a bearer token.
+  --scope <json>          Key scope (with --key), e.g. {"v":1,"capabilities":["deploy"]}.
+                          Defaults to the grant's own capability; never wider.
+  --spend-cap <json>      Key spend cap (with --key), e.g.
+                          {"v":1,"currency":"usd_micros","per_period":5000000,"period":"month"}
 
 Requires you to be an owner of the project's org.
+`,
+  list: `run402 grants list — list a project's grants with their grant keys
+
+Usage:
+  run402 grants list [--project <project_id>]
+
+Each grant carries its keys under "keys" (kind, scope, spend cap, expiry,
+revocation). Never returns a token or secret material.
 `,
   revoke: `run402 grants revoke — revoke a per-project capability grant
 
 Usage:
   run402 grants revoke <grant_id> [--project <project_id>]
 
-Legacy (still supported):
-  run402 grants revoke <project_id> <grant_id>
+Revokes the grant and every grant key minted against it. Requires you to be an
+owner of the project's org.
+`,
+  "revoke-key": `run402 grants revoke-key — revoke one grant key
 
+Usage:
+  run402 grants revoke-key <key_id> [--project <project_id>]
+
+Takes effect for every subsequent request. The grant and its other keys stay.
 Requires you to be an owner of the project's org.
+`,
+  "rotate-key": `run402 grants rotate-key — replace a grant key
+
+Usage:
+  run402 grants rotate-key <key_id> [--project <project_id>]
+
+Revokes the key and mints a fresh one against the same grant with the same
+kind, scope, spend cap and expiry. The NEW token is printed once. Use this when
+a token is lost or possibly exposed.
 `,
 };
 
-const CREATE_VALUE_FLAGS = ["--project", "--capability", "--policy", "--expires"];
+const CREATE_VALUE_FLAGS = ["--project", "--capability", "--policy", "--expires-at", "--kind", "--scope", "--spend-cap"];
+const KEY_ONLY_FLAGS = ["--kind", "--scope", "--spend-cap"];
+
+function warnTokenOnce(key) {
+  if (!key?.token) return;
+  console.error("");
+  console.error("The grant key token above is shown ONCE and cannot be read back.");
+  console.error("Store it now, then use it as: RUN402_GRANT_KEY=<token>");
+}
 
 async function create(args) {
   const a = normalizeArgv(args);
-  assertKnownFlags(a, [...CREATE_VALUE_FLAGS, "--help", "-h"], CREATE_VALUE_FLAGS);
+  assertKnownFlags(a, [...CREATE_VALUE_FLAGS, "--key", "--help", "-h"], CREATE_VALUE_FLAGS);
   const policyRaw = flagValue(a, "--policy");
-  const expiresAt = flagValue(a, "--expires");
-  const capabilityFlag = flagValue(a, "--capability");
+  const expiresAt = flagValue(a, "--expires-at") || undefined;
+  const capability = flagValue(a, "--capability");
+  const wantsKey = a.includes("--key");
+  const kind = flagValue(a, "--kind") || undefined;
+  const scopeRaw = flagValue(a, "--scope");
+  const spendCapRaw = flagValue(a, "--spend-cap");
   const { projectId, rest } = resolveProjectSelector(a, { valueFlags: CREATE_VALUE_FLAGS });
-  const expected = capabilityFlag ? 1 : 2;
-  const pos = requirePositionalCount(rest, CREATE_VALUE_FLAGS, {
-    min: expected,
-    max: expected,
-    command: "run402 grants create <wallet> --capability <cap> [--project <project_id>] [--policy <json>] [--expires <iso8601>]",
-    missing: capabilityFlag ? "Missing <wallet>." : "Missing <wallet> and/or <capability>.",
+  const [wallet] = requirePositionalCount(rest, CREATE_VALUE_FLAGS, {
+    min: 1,
+    max: 1,
+    command: "run402 grants create <wallet> --capability <cap> [--project <project_id>] [--key]",
+    missing: "Missing <wallet>.",
   });
-  const wallet = pos[0];
-  const capability = capabilityFlag ?? pos[1];
+  if (!capability) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing --capability <cap>.",
+      hint: "run402 grants create <wallet> --capability deploy [--project <project_id>]",
+    });
+  }
+  if (!wantsKey) {
+    const stray = KEY_ONLY_FLAGS.filter((f) => a.includes(f));
+    if (stray.length > 0) {
+      fail({
+        code: "BAD_USAGE",
+        message: `${stray.join(", ")} describe a grant key; add --key to mint one.`,
+        hint: "run402 grants create <wallet> --capability <cap> --key [--kind <kind>] [--scope <json>] [--spend-cap <json>]",
+      });
+    }
+  }
   const policy = policyRaw != null ? parseFlagJson("--policy", policyRaw) : undefined;
+  let key;
+  if (wantsKey) {
+    key = {};
+    if (kind) key.kind = kind;
+    if (scopeRaw != null) key.scope = parseFlagJson("--scope", scopeRaw);
+    if (spendCapRaw != null) key.spendCap = parseFlagJson("--spend-cap", spendCapRaw);
+    if (expiresAt) key.expiresAt = expiresAt;
+  }
   try {
     const res = await getSdk().grants.create(projectId, {
       wallet,
       capability,
       policy,
-      expiresAt: expiresAt || undefined,
+      expiresAt,
+      key,
     });
     console.log(JSON.stringify(res, null, 2));
+    warnTokenOnce(res?.key);
   } catch (err) {
     reportSdkError(err);
   }
 }
 
-async function revoke(args) {
+async function list(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, ["--project", "--help", "-h"], ["--project"]);
   const { projectId, rest } = resolveProjectSelector(a, { valueFlags: ["--project"] });
-  const [grantId] = requirePositionalCount(rest, ["--project"], {
-    min: 1,
-    max: 1,
-    command: "run402 grants revoke <grant_id> [--project <project_id>]",
-    missing: "Missing <grant_id>.",
+  requirePositionalCount(rest, ["--project"], {
+    min: 0,
+    max: 0,
+    command: "run402 grants list [--project <project_id>]",
+    missing: "",
   });
   try {
-    console.log(JSON.stringify(await getSdk().grants.revoke(projectId, grantId), null, 2));
+    console.log(JSON.stringify(await getSdk().grants.list(projectId), null, 2));
   } catch (err) {
     reportSdkError(err);
   }
 }
 
+function oneIdCommand({ verb, idName, method }) {
+  return async (args) => {
+    const a = normalizeArgv(args);
+    assertKnownFlags(a, ["--project", "--help", "-h"], ["--project"]);
+    const { projectId, rest } = resolveProjectSelector(a, { valueFlags: ["--project"] });
+    const [id] = requirePositionalCount(rest, ["--project"], {
+      min: 1,
+      max: 1,
+      command: `run402 grants ${verb} <${idName}> [--project <project_id>]`,
+      missing: `Missing <${idName}>.`,
+    });
+    try {
+      const res = await getSdk().grants[method](projectId, id);
+      console.log(JSON.stringify(res, null, 2));
+      warnTokenOnce(res?.key);
+    } catch (err) {
+      reportSdkError(err);
+    }
+  };
+}
+
 export async function run(sub, args) {
   if (!sub || sub === "--help" || sub === "-h") {
     console.log(HELP);
@@ -128,7 +227,10 @@ export async function run(sub, args) {
   }
   switch (sub) {
     case "create": await create(args); break;
-    case "revoke": await revoke(args); break;
+    case "list": await list(args); break;
+    case "revoke": await oneIdCommand({ verb: "revoke", idName: "grant_id", method: "revoke" })(args); break;
+    case "revoke-key": await oneIdCommand({ verb: "revoke-key", idName: "key_id", method: "revokeKey" })(args); break;
+    case "rotate-key": await oneIdCommand({ verb: "rotate-key", idName: "key_id", method: "rotateKey" })(args); break;
     default:
       failUnknownSubcommand("grants", sub);
   }

package/lib/init.mjs

@@ -51,7 +51,7 @@ Options:
                   nothing; RUN402_AGENT_NAME=<name> sets or overrides it. Change
                   it any time with \`run402 whoami --set-name <name>\`.
   --git-remote    Also 'git init' the current directory when it is not a
-                  repository yet, so the gitvault remote can be added there.
+                  repository yet, so the vault remote can be added there.
                   Opt-in on purpose: init is often run outside a project
                   directory and must never create a repository somewhere you
                   did not ask it to. Inside an EXISTING repository the remote
@@ -62,11 +62,11 @@ Output:
   tier, projects_saved, active_project_id, next_step }. Progress lines
   (Config / Wallet / Balance / Tier / Next) go to stderr so a human
   re-running interactively sees what's happening while a script piping stdout
-  to jq stays clean. The summary also carries { gitvault } (the scaffolded
-  remote), or { gitvault: null, gitvault_skipped } naming why no remote was
-  added, or { gitvault: null, gitvault_error } when it could not be added.
+  to jq stays clean. The summary also carries { vault } (the scaffolded
+  remote), or { vault: null, vault_skipped } naming why no remote was
+  added, or { vault: null, vault_error } when it could not be added.
   \`projects_saved\` counts projects with LOCAL keys; \`active_project_id\` is the
-  project the gitvault scaffold acted on.
+  project the vault scaffold acted on.
 
   init scaffolds the git remote only. It does NOT allocate the vault — that is
   \`run402 repos create --project <project_id>\`, which mints key material and a
@@ -215,13 +215,13 @@ function errorMessage(err) {
 }
 
 /**
- * Which project the gitvault scaffold acts on — and why it may act on none.
+ * Which project the vault scaffold acts on — and why it may act on none.
  *
  * The CLI-wide resolution order (`RUN402_PROJECT_ID`, then the active
  * project), not `getActiveProjectId()` alone. Reading only the active project
  * meant an agent that had exported `RUN402_PROJECT_ID` — the normal way to
  * address a project without mutating machine state — got a silent no-op: no
- * remote, no allocation, and no `gitvault` key in the summary at all, with
+ * remote, no allocation, and no `vault` key in the summary at all, with
  * nothing anywhere saying `run402 projects use` was a prerequisite
  * (dogfood #1, finding A). A command that exits 0 having done nothing is worse
  * than an error, so the no-project case names itself.
@@ -375,7 +375,7 @@ export async function run(args = []) {
     ...(voucherCode ? { voucher: null } : {}),
     tier: null,
     projects_saved: 0,
-    /** The project init acted on — the input to the gitvault scaffold decision. */
+    /** The project init acted on — the input to the vault scaffold decision. */
     active_project_id: null,
     next_actions: [],
     next_step: null,
@@ -637,17 +637,17 @@ export async function run(args = []) {
   // local keys, so it is legitimately not counted here; `active_project_id`
   // below is the field that says which project init actually acted on, and
   // reading `projects_saved: 0` as "init did nothing" is what made the
-  // gitvault skip look silent (dogfood #1, finding A).
+  // vault skip look silent (dogfood #1, finding A).
   summary.projects_saved = Object.keys(store.projects).length;
   line("Projects", `${summary.projects_saved} saved`);
 
-  // 5b. gitvault git remote (gitvault-client-surface, task 5.7).
+  // 5b. vault git remote (vault-client-surface, task 5.7).
   //
   // Purely LOCAL git. No vault is allocated and no key material is written
   // here — the spec is explicit that neither exists until first capture, so the
   // cold-start path gains no prompt and no new failure mode. Allocation happens
-  // on the first `git push origin <branch>` or `run402 gitvault snapshot` (D2,
-  // repo-first-onramp) — NOT on deploy: `applyWithGitvault` only ever reads an
+  // on the first `git push origin <branch>` or `run402 repos capture` (D2,
+  // repo-first-onramp) — NOT on deploy: `applyWithVault` only ever reads an
   // EXISTING vault's policy (D3) and never allocates one that does not exist,
   // so a project with no vault deploys exactly as it always did.
   //
@@ -664,11 +664,11 @@ export async function run(args = []) {
   const { projectId: activeProjectId, skipped: noProjectSkip } = resolveScaffoldProject();
   summary.active_project_id = activeProjectId;
   if (noProjectSkip) {
-    summary.gitvault = null;
-    summary.gitvault_skipped = noProjectSkip;
-    line("Gitvault", "skipped — no project selected (run402 projects use <project_id>)");
+    summary.vault = null;
+    summary.vault_skipped = noProjectSkip;
+    line("Vault", "skipped — no project selected (run402 projects use <project_id>)");
   } else {
-    summary.gitvault = null;
+    summary.vault = null;
     try {
       // Dynamic import: the scaffold is the only thing here that needs the
       // Node SDK's hardened git runner, and a top-level import would drag it
@@ -681,43 +681,43 @@ export async function run(args = []) {
         insideRepo = false;
       }
       if (!insideRepo && !scaffoldGitRemote) {
-        summary.gitvault_skipped = "not a git repository — re-run with --git-remote to create one and add the remote";
-        line("Gitvault", "skipped — not a git repository (--git-remote creates one)");
+        summary.vault_skipped = "not a git repository — re-run with --git-remote to create one and add the remote";
+        line("Vault", "skipped — not a git repository (--git-remote creates one)");
       } else {
         const orgId = await resolveOwningOrgId(activeProjectId);
         if (!orgId) {
-          summary.gitvault_skipped = `could not resolve the owning org for ${activeProjectId} — the run402 remote was not added`;
-          line("Gitvault", "skipped — owning org unresolved");
+          summary.vault_skipped = `could not resolve the owning org for ${activeProjectId} — the run402 remote was not added`;
+          line("Vault", "skipped — owning org unresolved");
         } else {
-          const remote = await getSdk().gitvault.scaffoldRemote({
+          const remote = await getSdk().repos.scaffoldRemote({
             repo_dir: process.cwd(),
             org_id: orgId,
             project_id: activeProjectId,
           });
           // `allocated: false` is stated, not left to be inferred: this was
           // local git only, and no vault exists for the project yet.
-          summary.gitvault = { ...remote, allocated: false };
+          summary.vault = { ...remote, allocated: false };
           if (remote.already_present && remote.existing_url !== remote.url) {
             // Left exactly as it was. Name the URL that is actually in place
             // rather than implying the remote now points at this project.
-            line("Gitvault", `remote '${remote.name}' already points at ${remote.existing_url} — left unchanged (${remote.reason})`);
+            line("Vault", `remote '${remote.name}' already points at ${remote.existing_url} — left unchanged (${remote.reason})`);
           } else if (remote.already_present) {
-            line("Gitvault", `remote '${remote.name}' already set (${remote.url})`);
+            line("Vault", `remote '${remote.name}' already set (${remote.url})`);
           } else {
             // D1: `origin` when it was free, `run402` when it was already
             // taken by something else — `remote.reason` says which happened.
-            line("Gitvault", `${remote.created_repository ? "initialized a repository and added" : "added"} remote '${remote.name}' -> ${remote.url} (${remote.reason})`);
+            line("Vault", `${remote.created_repository ? "initialized a repository and added" : "added"} remote '${remote.name}' -> ${remote.url} (${remote.reason})`);
           }
         }
       }
     } catch (err) {
       const reason = errorMessage(err);
-      summary.gitvault = null;
-      summary.gitvault_error = {
-        code: err?.body?.code ?? err?.code ?? "GITVAULT_SCAFFOLD_FAILED",
+      summary.vault = null;
+      summary.vault_error = {
+        code: err?.body?.code ?? err?.code ?? "VAULT_SCAFFOLD_FAILED",
         message: reason,
       };
-      line("Gitvault", `remote not added: ${reason}`);
+      line("Vault", `remote not added: ${reason}`);
     }
   }
 

package/lib/logs.mjs

@@ -62,7 +62,7 @@ Output:
 
 Auth:
   The project's cached service_key when present; otherwise your wallet /
-  session / delegate, which the gateway authorizes with project.read — an org
+  session / grant key, which the gateway authorizes with project.read — an org
   member or teammate agent following an error fingerprint's drill-down needs
   no project key.
 

package/lib/next-actions.mjs

@@ -81,7 +81,7 @@ export function upDeployAction() {
 }
 
 /**
- * `repos create` (and `gitvault init`) on an org with no slug set: the
+ * `repos create` (and `vault init`) on an org with no slug set: the
  * response's `address: null` had no pointer to WHY, or to the named-addressing
  * feature at all. Owner-only. Wording deliberately
  * omits a price: the first slug per org is free, and renames/re-claims cost

package/lib/org-context.mjs

@@ -97,15 +97,15 @@ function orgFromRoomEnv(env) {
  * `r402.orgId` from `cwd`'s LOCAL git config (kygit-handoff design D10) —
  * best-effort, gracefully degrading like `findBindingKey`: no repository,
  * no pin, or a shape-invalid value all answer `null` rather than throwing,
- * so a bare directory or a checkout with no gitvault remote costs nothing.
+ * so a bare directory or a checkout with no vault remote costs nothing.
  * Checks a real vault checkout's pin first (gated on `r402.repoId`), then
  * falls back to the bare org/room pin a room-only `rooms join <key>` writes
  * in a directory with no vault at all (add-room-invite design D10).
  */
-async function readGitvaultPinnedOrgId(cwd) {
+async function readVaultPinnedOrgId(cwd) {
   try {
-    const { readPinnedGitvaultRepo, readPinnedRoomBinding } = await import("#sdk/node");
-    const pinned = await readPinnedGitvaultRepo(cwd);
+    const { readPinnedVaultRepo, readPinnedRoomBinding } = await import("#sdk/node");
+    const pinned = await readPinnedVaultRepo(cwd);
     const orgId = trimmed(pinned?.org_id);
     if (orgId && ORG_ID_RE.test(orgId)) return orgId;
     const bare = await readPinnedRoomBinding(cwd);
@@ -254,14 +254,14 @@ export async function resolveOrg(input = {}, opts = {}) {
   }
   if (bindingOrg) return { orgId: bindingOrg, source: "binding", sourceDetail: bindingHit.file };
 
-  // --- Class 3.5: gitvault local pin (kygit-handoff design D10) ------------
+  // --- Class 3.5: vault local pin (kygit-handoff design D10) ------------
   // `r402.orgId` in this checkout's LOCAL git config — written by every
-  // gitvault pin site (`repos create`, `resume`, address resolution), a
+  // vault pin site (`repos create`, `resume`, address resolution), a
   // rung below env/binding and above profile state: a checkout that IS a
   // resumed/pinned vault should resolve its own org with zero configuration,
   // but an explicit env var or a committed `.run402.json` binding still wins.
-  const pinnedOrg = await readGitvaultPinnedOrgId(cwd);
-  if (pinnedOrg) return { orgId: pinnedOrg, source: "gitvault_pin", sourceDetail: "r402.orgId (local git config)" };
+  const pinnedOrg = await readVaultPinnedOrgId(cwd);
+  if (pinnedOrg) return { orgId: pinnedOrg, source: "vault_pin", sourceDetail: "r402.orgId (local git config)" };
 
   // --- Class 4: profile state ----------------------------------------------
   const selected = trimmed(coreGetActiveOrgId());
@@ -434,7 +434,7 @@ export function orgProvenance(resolved) {
  * owns THIS project id", which is what a project-scoped scaffold needs and
  * where an `--org` override would be a mis-binding, not a convenience.
  *
- * WHY IT CACHES (task 5.12c): the gitvault scaffold is the one part of
+ * WHY IT CACHES (task 5.12c): the vault scaffold is the one part of
  * `run402 init` the client-surface spec says adds no network dependency to the
  * cold-start path, and resolving the org through `projects.list()` quietly made
  * that untrue. `org_id` is a non-secret routing identifier the control plane

package/lib/orgs.mjs

@@ -44,7 +44,7 @@ Usage:
   run402 orgs members add  [<org_id>] <wallet_address> [--role <role>]
   run402 orgs members role [<org_id>] --principal <principal_id> --role <role>
   run402 orgs members rm   [<org_id>] --principal <principal_id>
-  run402 orgs members 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 orgs members revoke-key [<org_id>] --principal <principal_id> [--reason <why>]   (owner + step-up; revokes the member's vault encryption key — its next vault operation enrolls afresh)
   run402 orgs invite list   [<org_id>]
   run402 orgs invite create [<org_id>] --email <email> [--role <role>] [--ttl-hours N]
   run402 orgs invite rm     [<org_id>] --principal <principal_id>
@@ -53,7 +53,7 @@ Usage:
 omit it and the org comes from --org, then RUN402_ORG, then the .run402.json
 binding, then 'run402 orgs use'. Inside a bound checkout two agents add each
 other with nothing to look up: run402 orgs members 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.
+A developer-or-above add REFUSES (VAULT_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 orgs members add <wallet_address>).
 
 Subcommands:
@@ -186,7 +186,7 @@ Usage:
   run402 orgs members add  [<org_id>] <wallet_address> [--role <role>]
   run402 orgs members role [<org_id>] --principal <principal_id> --role <role>
   run402 orgs members rm   [<org_id>] --principal <principal_id>
-  run402 orgs members 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 orgs members revoke-key [<org_id>] --principal <principal_id> [--reason <why>]   (owner + step-up; revokes the member's vault encryption key — its next vault 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.
@@ -202,7 +202,7 @@ Usage:
 omit it and the org comes from --org, then RUN402_ORG, then the .run402.json
 binding, then 'run402 orgs use'. Inside a bound checkout two agents add each
 other with nothing to look up: run402 orgs members 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.
+A developer-or-above add REFUSES (VAULT_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 orgs members add <wallet_address>).
 
 An invite is claimed at the recipient's first login. Mutations require an active owner
@@ -223,7 +223,7 @@ Requires an admin+ membership on the org. Newest-first. Page forward with --afte
 
 
 /**
- * gitvault-multi-writer (rev 47) task 6.3 / design D3 — decided 2026-09-03
+ * vault-multi-writer (rev 47) task 6.3 / design D3 — decided 2026-09-03
  * (Tal): `orgs members 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
@@ -237,11 +237,11 @@ Requires an admin+ membership on the org. Newest-first. Page forward with --afte
  * 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 listing = await sdk.repos.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 st = await sdk.repos.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;
@@ -250,7 +250,7 @@ async function assertCallerCanAdmitWritersEverywhere(sdk, orgId, effectiveRole)
   }
   if (blocked.length > 0) {
     fail({
-      code: "GITVAULT_WRITER_NOT_ADMITTED",
+      code: "VAULT_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: [
@@ -266,7 +266,7 @@ async function assertCallerCanAdmitWritersEverywhere(sdk, orgId, effectiveRole)
 }
 
 /**
- * `orgs members rm`'s inline epoch rotation (gitvault-multi-writer D6, the
+ * `orgs members rm`'s inline epoch rotation (vault-multi-writer D6, the
  * kygit-handoff member-removal decision): for every vault of the org where
  * this session's key is an admitted writer, drive
  * `rotateEpochForKeyRevocation(principalId)` — the one self-contained
@@ -275,7 +275,7 @@ async function assertCallerCanAdmitWritersEverywhere(sdk, orgId, effectiveRole)
  * no vault (nothing to rotate, nothing to report).
  */
 async function rotateOrgVaultsAfterRemoval(sdk, orgId, principalId) {
-  const listing = await sdk.gitvault.listByOrg(orgId);
+  const listing = await sdk.repos.listByOrg(orgId);
   const vaults = listing?.vaults ?? [];
   if (vaults.length === 0) return null;
   const rotated = [];
@@ -284,7 +284,7 @@ async function rotateOrgVaultsAfterRemoval(sdk, orgId, principalId) {
   for (const v of vaults) {
     let st;
     try {
-      st = await sdk.gitvault.status({ repo_id: v.repo_id, reconcile: "forbidden" });
+      st = await sdk.repos.status({ repo_id: v.repo_id, reconcile: "forbidden" });
     } catch (err) {
       errors.push({ repo_id: v.repo_id, code: err?.code ?? null, error: err?.message ?? String(err) });
       continue;
@@ -300,7 +300,7 @@ async function rotateOrgVaultsAfterRemoval(sdk, orgId, principalId) {
     try {
       // reason:"member_removed" — writer-capable (no owner step-up); the
       // removal itself advanced the counters this rotation is fenced on.
-      const r = await sdk.gitvault.rotateEpochForMemberRemoval({ repo_id: v.repo_id });
+      const r = await sdk.repos.rotateEpochForMemberRemoval({ repo_id: v.repo_id });
       rotated.push({ repo_id: v.repo_id, new_epoch: r.new_epoch, generation: r.generation, included: r.included.length, writers_removed: r.writers_removed?.length ?? 0, self_check: r.self_check });
     } catch (err) {
       errors.push({ repo_id: v.repo_id, code: err?.code ?? null, error: err?.message ?? String(err) });
@@ -717,7 +717,7 @@ async function runMember(args) {
         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
+      // vault-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
@@ -737,7 +737,7 @@ async function runMember(args) {
         const errors = [];
         for (const vaultId of syncTarget.vault_ids) {
           try {
-            const r = await sdk.gitvault.reconcile({ repo_id: vaultId });
+            const r = await sdk.repos.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) {
@@ -748,7 +748,7 @@ async function runMember(args) {
       }
       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.`);
+        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 vault operation admits them.`);
       }
       if (writerSync?.errors.length > 0) {
         for (const e of writerSync.errors) console.error(`writer sync: ${e.repo_id} — ${e.error}`);
@@ -760,10 +760,10 @@ async function runMember(args) {
   }
 
   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
+    // vault-agent-envelopes D3: owner + step-up revokes a member's current
+    // vault 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.
+    // VAULT_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");
@@ -818,7 +818,7 @@ async function runMember(args) {
     try {
       const sdk = getSdk();
       const res = await sdk.org(org).members.revoke(principalId);
-      // gitvault-multi-writer D6 — a removal rides `rotate_epoch`: the gateway
+      // vault-multi-writer D6 — a removal rides `rotate_epoch`: the gateway
       // has just blocked the principal's writer keys and flipped its desired
       // row to pending_removal, so every ordinary push on every vault of this
       // org now refuses EPOCH_ROTATION_REQUIRED until a surviving writer