run402 4.93.2 → 4.95.0

package/lib/repos.mjs

@@ -25,12 +25,12 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { withAutoApprove } from "./operator.mjs";
-import { allowanceAuthHeaders, isCoreApiTarget, readAllowance, resolveProjectId } from "./config.mjs";
+import { withAutoApprove } from "./sign-in.mjs";
+import { walletAuthHeaders, isCoreApiTarget, readWallet, resolveProjectId } from "./config.mjs";
 import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
 import { resolveOrgId, resolveOwningOrgId } from "./org-context.mjs";
 import { resolveGitvaultTarget } from "./gitvault-target.mjs";
-import { nextAction, claimOrgSlugAction, claimRepoNameAction } from "./next-actions.mjs";
+import { nextAction, setOrgSlugAction, setRepoNameAction } from "./next-actions.mjs";
 import { resolveHarnessLabels, resolveSessionKey, resolveTaskLabel, persistSessionKey } from "./harness-context.mjs";
 import { updateRoomState } from "./rooms-context.mjs";
 import { printKeystoreLocation } from "./gitvault.mjs";
@@ -63,9 +63,9 @@ Usage:
   run402 repos <verb> [options] — fifteen verbs, tiered by how often you reach for them:
 
 Common:
-  run402 repos create [name]  [--org <org_id>] [--dir <path>] [--nested] [--tier <tier>] [--project <id>]
+  run402 repos create [name]  [--org <org_id>] [--dir <path>] [--nested] [--tier <tier>] [--project <project_id>]
                               [--byo <s3://bucket/prefix>] [--profile <name> | --ambient] [--region <r>] [--endpoint <url>] [--no-init]
-  run402 repos view           [--project <id>] [--repo <repo_id>] [--human]
+  run402 repos view           [--project <project_id>] [--repo <repo_id>] [--human]
   run402 repos list           [--org <org_id>] [--human]
 
 Then plain git, forever:
@@ -73,38 +73,38 @@ Then plain git, forever:
   git clone run402::<org>/<repo>
 
 Handoff (pass a working tree to another agent):
-  run402 repos handoff [--project <id>] [--repo <repo_id>] [--ttl <seconds>] [--role <role>]
+  run402 repos handoff [--project <project_id>] [--repo <repo_id>] [--ttl <seconds>] [--role <role>]
                         [--include-sensitive <glob>]... [--note-file <path>] [--json] [--list] [--revoke <handoff_id>]
                         (the Handoff Note is JSON piped on stdin when not using --note-file)
   run402 repos resume  <kgh1_…|--key-stdin> [--to <dir>] [--no-init] [--json]
 
 Invite (bring a second agent into the SAME work, dirty tree included):
-  run402 repos invite  [--project <id>] [--repo <repo_id>] [--room <key>] [--ttl <seconds>] [--role <role>]
+  run402 repos invite  [--project <project_id>] [--repo <repo_id>] [--room <key>] [--ttl <seconds>] [--role <role>]
                         [--include-sensitive <glob>]... [--note-file <path>] [--json] [--list] [--revoke <invite_id>]
                         (the Invite Note is JSON piped on stdin when not using --note-file)
   run402 repos join    <kgi1_…|--key-stdin> [--to <dir>] [--no-init] [--json]
 
 Occasional:
-  run402 repos snapshot [--project <id>] [--repo <repo_id>] [--message <text>] [--checkpoint] [--dry-run] [--allow-dirty] [--manifest-out <path>]
-  run402 repos mirror   [<destination>] [--off] [--backfill] [--profile <name> | --ambient] [--region <r>] [--endpoint <url>] [--project <id>] [--repo <repo_id>]
+  run402 repos snapshot [--project <project_id>] [--repo <repo_id>] [--message <text>] [--checkpoint] [--dry-run] [--allow-dirty] [--manifest-out <path>]
+  run402 repos mirror   [<destination>] [--off] [--backfill] [--profile <name> | --ambient] [--region <r>] [--endpoint <url>] [--project <project_id>] [--repo <repo_id>]
   run402 repos recover  <source> --out <dir> [--repo <repo_id>] [--profile <name> | --ambient] [--region <r>] [--endpoint <url>]
                         [--bundle <file>] [--code <SRC1-…>] [--receipt <file>] [--rp-id <host>] [--human]
   run402 repos recovery-bundle [--out <file> | --out -]
 
 Lifecycle:
   run402 repos rename <new_name> [--repo <repo_id> | --project <project_id>]
-  run402 repos delete [--project <id>] [--repo <repo_id>] [--force]
+  run402 repos delete [--project <project_id>] [--repo <repo_id>] [--force]
 
 Maintenance:
-  run402 repos fsck   [--project <id>] [--repo <repo_id>] [--mirror] [--budget <n>] [--no-write] [--human]
-  run402 repos gc     [--project <id>] [--repo <repo_id>] [--force-headroom] [--submit --intent-core <path> --verifier-receipt <path> [--wait]]
+  run402 repos fsck   [--project <project_id>] [--repo <repo_id>] [--mirror] [--budget <n>] [--no-write] [--human]
+  run402 repos gc     [--project <project_id>] [--repo <repo_id>] [--force-headroom] [--submit --intent-core <path> --verifier-receipt <path> [--wait]]
   run402 repos daemon <status|stop>   The resident helper engine (gitvault-persistent-helper) — inspect or retire it; nothing requires either
-  run402 repos access [--project <id>] [--repo <repo_id>] [--human]
-  run402 repos access repair [--project <id>] [--repo <repo_id>] --recipient-state-version <n> --recipient-revocation-version <n>
-  run402 repos access revoke-key <principal_id> [--project <id>] [--repo <repo_id>]
-  run402 repos access declare-exposure [--project <id>] [--repo <repo_id>]
-  run402 repos access repin   [--project <id>] [--repo <repo_id>] --principal <principal_id> --fingerprint <ek_fingerprint>
-  run402 repos policy <required|grandfathered> [--project <id>] [--repo <repo_id>] [--reason <why>]
+  run402 repos access [--project <project_id>] [--repo <repo_id>] [--human]
+  run402 repos access repair [--project <project_id>] [--repo <repo_id>] --recipient-state-version <n> --recipient-revocation-version <n>
+  run402 repos access revoke-key <principal_id> [--project <project_id>] [--repo <repo_id>]
+  run402 repos access declare-exposure [--project <project_id>] [--repo <repo_id>]
+  run402 repos access repin   [--project <project_id>] [--repo <repo_id>] --principal <principal_id> --fingerprint <ek_fingerprint>
+  run402 repos policy <required|grandfathered> [--project <project_id>] [--repo <repo_id>] [--reason <why>]
   run402 repos policy auto-gc [<generations>|off]   (local, per-checkout — no --project/--repo)
 
 Every verb above also accepts -v/--verbose (a stderr summary line of request
@@ -115,7 +115,7 @@ Subcommands:
   create   Provision (or, with --project, ADOPT an existing project), ALLOCATE
            its vault (mints key material and, on first allocation, a one-shot
            recovery receipt), and scaffold the git remote — origin when free,
-           run402 when taken. \`--project <id>\` allocates for a project that already exists,
+           run402 when taken. \`--project <project_id>\` allocates for a project that already exists,
            nothing is provisioned. \`[name]\` is inferred from an existing git
            remote's basename or the directory name when unambiguous — NEVER a
            prompt; if the directory and an existing remote disagree, or
@@ -132,7 +132,7 @@ Subcommands:
            no payload copy at all); \`run402 repos mirror <destination>\`
            still works unchanged as your second customer-held location.
            On a machine with no wallet, or a wallet with no active tier, this folds the cold-start
-           chain (allowance -> faucet -> one x402 prototype payment,
+           chain (wallet -> faucet -> one x402 prototype payment,
            announced) before retrying once; \`--no-init\` opts out.
   view     Side-effect-free: what this machine and the control plane each
            believe about the repo — allocation, policy, whether this keystore
@@ -162,11 +162,11 @@ Subcommands:
            <handoff_id>\` read/revoke instead of minting.
   resume   Resume a Handoff Key on ANY machine: parses the key; on a wallet
            with no active tier first folds the same cold-start chain
-           \`create\` does (allowance → faucet → one x402 prototype payment,
+           \`create\` does (wallet → faucet → one x402 prototype payment,
            each step announced) so the resumed agent arrives as a paid-up
            run402 wallet of its own — \`--no-init\` opts out, and because the
-           claim itself needs no tier a chain failure is reported (never
-           blocks the resume); then claims the key with THIS machine's own
+           redemption itself needs no tier a chain failure is reported (never
+           blocks the resume); then redeems the key with THIS machine's own
            wallet, clones the vault at the base HEAD
            into \`--to <dir>\` (default: the vault's name), applies the
            stash-shaped checkpoint (staged/unstaged/deleted/untracked
@@ -188,10 +188,10 @@ Subcommands:
            whose key is not admitted is refused
            \`INVITE_MINT_REQUIRES_WRITER\` — have a live writer run
            \`run402 repos access sync\` (any push does it too), then retry.
-  join     Claim an Invite Key on ANY machine: the SAME cold-start fold
-           \`resume\` runs (allowance → faucet → one x402 prototype payment,
+  join     Redeem an Invite Key on ANY machine: the SAME cold-start fold
+           \`resume\` runs (wallet → faucet → one x402 prototype payment,
            announced — \`--no-init\` opts out; a chain failure never blocks
-           the claim), clones the vault at the base HEAD into \`--to <dir>\`
+           the redemption), clones the vault at the base HEAD into \`--to <dir>\`
            (default: the vault's name), restores the stash-shaped
            checkpoint exactly like \`resume\`, pins \`r402.room\` to the
            INVITE's own room, adds \`.run402/\` to \`.git/info/exclude\`,
@@ -275,8 +275,8 @@ Subcommands:
            cwd unless \`--out\` says otherwise (\`--out -\` prints only); the
            full JSON always goes to stdout. Principal-scoped, not
            repo-scoped (one bundle covers every vault you can read) — auth
-           is your control-plane session (\`run402 operator login
-           --loopback\` first; without one it answers for the active
+           is your sign-in session (\`run402 login\` first; without one
+           it answers for the active
            WALLET's agent principal, normally no wrappers, and says so).
            To make it travel WITH a mirror, copy it to
            member-recovery-bundles/<name>.json under the mirrored prefix —
@@ -376,7 +376,7 @@ Subcommands:
            \`off\` (or \`0\`) disables it. No value prints the current setting.
 
 Options:
-  --project <id>    Project whose repo to act on (defaults to the active project)
+  --project <project_id>    Project whose repo to act on (defaults to the active project)
   --repo <repo_id>  Address the repo directly by id, skipping project lookup
   --org <org_id>    create/list: the owning organization (create resolves it
                     the same way \`projects provision\` does when omitted)
@@ -655,7 +655,7 @@ async function formatRepoHuman(s, mirror) {
   lines.push(`Address: ${formatRepoAddress(s)}${remotePart}`);
 
   if (!s.vault) {
-    lines.push("Repo: not allocated yet for this project — run 'run402 repos create --project <id>' to allocate one.");
+    lines.push("Repo: not allocated yet for this project — run 'run402 repos create --project <project_id>' to allocate one.");
     if (s.warnings.length > 0) lines.push(`Warnings: ${s.warnings.map((w) => w.message).join(" ")}`);
     return lines.join("\n");
   }
@@ -851,7 +851,7 @@ async function printCreateResult({ sdk, projectId, vault, adopted, name, verbose
       }
     }
   } catch (err) {
-    if (name) console.error(`repo name not claimed (non-fatal): ${err?.message ?? String(err)}`);
+    if (name) console.error(`repo name not set (non-fatal): ${err?.message ?? String(err)}`);
   }
 
   // A `push_repo` action names a remote that EXISTS — only a scaffolded
@@ -863,7 +863,7 @@ async function printCreateResult({ sdk, projectId, vault, adopted, name, verbose
     ? nextAction("push_repo", { command: `git push -u ${vault.remote.name} HEAD`, why: "Publish the current branch to the encrypted Run402 remote." })
     : null;
   const remoteSkippedActions = vault.remote?.status === "skipped" ? (vault.remote.next_actions ?? []) : [];
-  const claimAction = address ? null : orgSlug ? claimRepoNameAction(projectId) : claimOrgSlugAction();
+  const nameAction = address ? null : orgSlug ? setRepoNameAction(projectId) : setOrgSlugAction();
   // gitvault-byo-primary-bucket task 3.5: a BYO vault's "add a copy" remedy
   // names a SECOND customer-held location (D7) — the plain mirror hint
   // frames the mirror as the FIRST custody-held copy, which is false once
@@ -872,7 +872,7 @@ async function printCreateResult({ sdk, projectId, vault, adopted, name, verbose
   const mirrorAction = isByo
     ? nextAction("configure_mirror", { command: "run402 repos mirror <destination>", why: GITVAULT_BYO_UNMIRRORED_REMEDY_STATEMENT })
     : nextAction("configure_mirror", { command: "run402 repos mirror <destination>", why: GITVAULT_MIRROR_SETUP_HINT });
-  const nextActions = [pushAction, ...remoteSkippedActions, mirrorAction, claimAction].filter(Boolean);
+  const nextActions = [pushAction, ...remoteSkippedActions, mirrorAction, nameAction].filter(Boolean);
 
   // Secret-bearing (recovery_receipt): built fresh every call, printed once,
   // and never spilled into any cache path — see spillIfLarge's own doc
@@ -897,8 +897,8 @@ async function printCreateResult({ sdk, projectId, vault, adopted, name, verbose
     (vault.deduplicated ? "already existed — nothing was re-allocated" : `allocated (genesis ${vault.genesis_sha256})`),
   );
   if (address) console.error(`address: ${address}`);
-  else if (!orgSlug) console.error("no named address yet — claim an org slug (run402 org slug <slug>) to get run402::<slug>/<name> addresses");
-  else console.error(`no address claimed — run 'run402 repos rename <name> --project ${projectId}' to claim one`);
+  else if (!orgSlug) console.error("no named address yet — set an org slug (run402 orgs slug <slug>) to get run402::<slug>/<name> addresses");
+  else console.error(`no address set — run 'run402 repos rename <name> --project ${projectId}' to set one`);
   if (remoteScaffolded) {
     console.error(`remote '${vault.remote.name}' -> ${vault.remote.url} (${vault.remote.reason})`);
     if (vault.remote.nested) console.error(`nested repository inside ${vault.remote.enclosing_toplevel}${vault.remote.excluded_in_enclosing ? " — excluded there via .git/info/exclude" : " — could not write its .git/info/exclude"}`);
@@ -918,7 +918,7 @@ async function printCreateResult({ sdk, projectId, vault, adopted, name, verbose
   console.error(vault.terminal_loss_statement);
   await printKeystoreLocation();
   console.error("");
-  console.error("nothing was deployed — this is a vault-only repo. Deploy later with `run402 deploy apply`, or never.");
+  console.error("nothing was deployed — this is a vault-only repo. Deploy later with `run402 deploy`, or never.");
   printVerboseStats(verboseArgv, sdk);
 }
 
@@ -955,13 +955,13 @@ async function createProvision(name, dir, a) {
   // with the old project id.
   const idempotencyKey = flagValue(a, "--idempotency-key") ?? `repos-create:${orgId ?? "org-of-one"}:${name}`;
 
-  // A genuinely bare machine has no allowance file at all, and the NO_ALLOWANCE
+  // A genuinely bare machine has no local wallet file at all, and the NO_WALLET
   // precheck below would refuse before the provision call could ever answer
   // NO_ACTIVE_TIER, so the cold-start fold would never reach the one case it
   // exists for. Fold first when there is no wallet; `--no-init` keeps the
   // bare refusal.
-  if (!isCoreApiTarget() && !loadLiveControlPlaneSession() && !readAllowance() && !a.includes("--no-init")) {
-    console.error("no wallet on this machine — folding the cold-start chain (allowance -> faucet -> prototype tier)");
+  if (!isCoreApiTarget() && !loadLiveControlPlaneSession() && !readWallet() && !a.includes("--no-init")) {
+    console.error("no wallet on this machine — folding the cold-start chain (wallet -> faucet -> prototype tier)");
     try {
       const { foldColdStartChain } = await import("./cold-start.mjs");
       await foldColdStartChain((line) => console.error(`  ${line}`));
@@ -970,7 +970,7 @@ async function createProvision(name, dir, a) {
       return;
     }
   }
-  if (!isCoreApiTarget() && !loadLiveControlPlaneSession()) allowanceAuthHeaders("/projects/v1");
+  if (!isCoreApiTarget() && !loadLiveControlPlaneSession()) walletAuthHeaders("/projects/v1");
 
   const provisionOnce = () =>
     withAutoApprove(() => sdk.projects.provision({ tier, name, ...(orgId ? { orgId } : {}), idempotencyKey }));
@@ -980,12 +980,12 @@ async function createProvision(name, dir, a) {
     provisioned = await provisionOnce();
   } catch (err) {
     // kygit-handoff design D5: `repos create` on a fresh wallet folds the
-    // cold-start chain ONCE — allowance → faucet → one x402 prototype
+    // cold-start chain ONCE — wallet → faucet → one x402 prototype
     // payment, announced — then retries exactly once. `--no-init` opts
     // out (the caller wants the bare NO_ACTIVE_TIER refusal).
     const code = err?.body?.code ?? err?.code;
     if (code === "NO_ACTIVE_TIER" && !a.includes("--no-init")) {
-      console.error("no active tier — folding the cold-start chain (allowance -> faucet -> prototype tier)");
+      console.error("no active tier — folding the cold-start chain (wallet -> faucet -> prototype tier)");
       try {
         const { foldColdStartChain } = await import("./cold-start.mjs");
         await foldColdStartChain((line) => console.error(`  ${line}`));
@@ -1040,7 +1040,7 @@ async function create(args) {
       fail({
         code: "BAD_USAGE",
         message: "a name positional and --project are mutually exclusive — --project adopts an EXISTING project.",
-        hint: "run402 repos create --project <id> to adopt, or run402 repos create <name> to provision a new one. Name it afterward with `run402 repos rename`.",
+        hint: "run402 repos create --project <project_id> to adopt, or run402 repos create <name> to provision a new one. Name it afterward with `run402 repos rename`.",
       });
     }
     if (flagValue(a, "--tier") != null || flagValue(a, "--idempotency-key") != null) {
@@ -1159,7 +1159,7 @@ async function list(args) {
   }
   printJson(sdk, { org_id: orgId, org_slug: orgSlug, repos });
   console.error(`${repos.length} vault-bearing project(s) in this organization${usedFallback ? " (per-project fallback read — the bulk vaults-by-org route is not live on this gateway yet)" : ""}`);
-  if (orgSlug) console.error(`org slug: ${orgSlug} — a repo with a claimed address-form name is reachable at run402::${orgSlug}/<name>`);
+  if (orgSlug) console.error(`org slug: ${orgSlug} — a repo with an address-form name set is reachable at run402::${orgSlug}/<name>`);
   printVerboseStats(a, sdk);
 }
 
@@ -1288,16 +1288,16 @@ async function rename(args) {
       const orgSlug = owningOrg ? (await sdk.org(owningOrg).get()).slug : null;
       if (orgSlug) address = gitvaultRemoteUrlForRepo(orgSlug, result.repo_name);
     } catch {
-      // The claim itself already succeeded — a failed address-preview lookup is never fatal.
+      // The name is already set — a failed address-preview lookup is never fatal.
     }
     printJson(sdk, { ...result, address });
     console.error(
       result.previous_repo_name && result.previous_repo_name !== result.repo_name
         ? `renamed from "${result.previous_repo_name}" to "${result.repo_name}"`
-        : `name "${result.repo_name}" claimed for ${projectId}`,
+        : `name "${result.repo_name}" set for ${projectId}`,
     );
     if (address) console.error(`address: ${address}`);
-    else console.error("this org has no slug yet — claim one with `run402 org slug <slug>` to get a full run402::<slug>/<name> address");
+    else console.error("this org has no slug yet — set one with `run402 orgs slug <slug>` to get a full run402::<slug>/<name> address");
     printVerboseStats(a, sdk);
   } catch (err) {
     reportSdkError(err);
@@ -1376,7 +1376,7 @@ async function del(args) {
   } else {
     ({ projectId, rest } = resolveProjectSelector(a, { rejectBareFirst: true }));
   }
-  requirePositionalCount(rest.filter((x) => x !== "--force"), [], { min: 0, max: 0, command: "run402 repos delete [--project <id>] [--repo <repo_id>] [--force]", missing: "" });
+  requirePositionalCount(rest.filter((x) => x !== "--force"), [], { min: 0, max: 0, command: "run402 repos delete [--project <project_id>] [--repo <repo_id>] [--force]", missing: "" });
   const force = a.includes("--force");
 
   let status;
@@ -1726,7 +1726,7 @@ async function readInviteNoteInput(a) {
   return parseInviteNoteJson(text, "stdin");
 }
 
-/** Shared body for `parseHandoffNoteJson`/`parseInviteNoteJson` — `schema`/`kindLabel` name the claim kind's own vocabulary. */
+/** Shared body for `parseHandoffNoteJson`/`parseInviteNoteJson` — `schema`/`kindLabel` name the redeem kind's own vocabulary. */
 function parseClaimNoteJson(text, source, schema, kindLabel, helpCommand) {
   let parsed;
   try {
@@ -1817,7 +1817,7 @@ async function handoff(args) {
     // gitvault-multi-writer (rev 47) task 6.4 — a handoff is now also a
     // WRITER admission, not just a checkout pass: the recipient signs its
     // own future pushes with a NEW key this vault's chain recognizes as a
-    // writer the moment `resume` claims it (design D4 — a grant minted here,
+    // writer the moment `resume` redeems it (design D4 — a grant minted here,
     // a two-signature acceptance the recipient's own resume completes).
     console.error(`the recipient becomes a WRITER on this vault the moment they resume — their own key signs future pushes, not yours.`);
     console.error(`recipient runs: kygit resume <key printed below>`);
@@ -1837,13 +1837,13 @@ async function handoff(args) {
 
 /**
  * Whether this wallet needs the cold-start chain before a resume: no
- * allowance file yet (a fresh machine — the viral case), or an allowance
+ * wallet file yet (a fresh machine — the viral case), or a wallet
  * whose org holds no active tier. An unreachable tier status reads as
- * "no" — the claim needs no tier, and a resume must never wait on a status
+ * "no" — the redemption needs no tier, and a resume must never wait on a status
  * read.
  */
 async function resumeNeedsColdStart(sdk) {
-  if (!readAllowance()) return true;
+  if (!readWallet()) return true;
   try {
     const status = await sdk.tier.status();
     return status?.active === false;
@@ -1856,11 +1856,11 @@ async function resumeNeedsColdStart(sdk) {
  * `resume`'s cold-start fold: the SAME chain `create` runs on
  * NO_ACTIVE_TIER (`cold-start.mjs`), announced step by step on stderr.
  * Never throws — a failure is returned as `{ error, next_action }` so the
- * caller carries it in the result and proceeds with the claim.
+ * caller carries it in the result and proceeds with the redemption.
  */
 async function foldColdStartForResume(sdk) {
   if (!(await resumeNeedsColdStart(sdk))) return { performed: false, skipped: "tier_active" };
-  console.error("no active tier — folding the cold-start chain (allowance -> faucet -> prototype tier) before the claim");
+  console.error("no active tier — folding the cold-start chain (wallet -> faucet -> prototype tier) before the redemption");
   try {
     const { foldColdStartChain } = await import("./cold-start.mjs");
     const chain = await foldColdStartChain((line) => console.error(`  ${line}`));
@@ -1868,16 +1868,16 @@ async function foldColdStartForResume(sdk) {
   } catch (err) {
     const code = err?.body?.code ?? err?.code ?? null;
     const message = err?.body?.message ?? err?.message ?? String(err);
-    console.error(`cold-start chain failed (${code ?? "error"}: ${message}) — continuing with the claim; run \`run402 tier set prototype\` afterwards`);
+    console.error(`cold-start chain failed (${code ?? "error"}: ${message}) — continuing with the redemption; run \`run402 tier set prototype\` afterwards`);
     return {
       performed: false,
       error: { code, message },
-      next_action: { type: "renew_tier", command: "run402 tier set prototype", why: "The resume proceeded without a tier of your own; the perpetual prototype tier is what lets this wallet create and deploy projects." },
+      next_action: { type: "renew_tier", command: "run402 tier set prototype", why: "The resume proceeded without a tier of your own; the free prototype tier is what lets this wallet create and deploy projects." },
     };
   }
 }
 
-/** `kygit.handoff-note.v1` / `kygit.invite-note.v1` rendered as Markdown — shared body, `title` names the claim kind ("Handoff" or "Invite"). */
+/** `kygit.handoff-note.v1` / `kygit.invite-note.v1` rendered as Markdown — shared body, `title` names the redeem kind ("Handoff" or "Invite"). */
 function renderClaimNoteMarkdown(note, title) {
   if (!note) return null;
   const lines = [];
@@ -1939,12 +1939,12 @@ async function resume(args) {
   }
   // A resumed agent is a NEW run402 wallet, and the loop is the
   // point — so on a wallet with no active tier `resume` folds the same
-  // cold-start chain `create` does (allowance → faucet → one x402
-  // prototype payment, announced) BEFORE the claim. The claim itself needs
+  // cold-start chain `create` does (wallet → faucet → one x402
+  // prototype payment, announced) BEFORE the redemption. The redemption itself needs
   // no tier, so the chain is never allowed to block a resume: a faucet
   // throttle or payment failure is reported on stderr, carried in the
   // result as `cold_start.error` with a `renew_tier` next action, and the
-  // claim proceeds (the SDK still creates the bare wallet it needs).
+  // redemption proceeds (the SDK still creates the bare wallet it needs).
   // `--no-init` opts out entirely.
   const coldStart = a.includes("--no-init") ? { performed: false, skipped: "no_init" } : await foldColdStartForResume(sdk);
   try {
@@ -1956,7 +1956,7 @@ async function resume(args) {
       const { remoteHelperNextAction } = await import("./path-lookup.mjs");
       const helperAction = result.restored?.dir ? remoteHelperNextAction(result.restored.dir) : null;
       if (helperAction) result.next_actions = [...(result.next_actions ?? []), helperAction];
-    } catch { /* never fails a completed claim */ }
+    } catch { /* never fails a completed redemption */ }
     if (a.includes("--json")) {
       printJson(sdk, { ...result, cold_start: coldStart });
     } else {
@@ -1973,7 +1973,7 @@ async function resume(args) {
       if (result.writer_activation) {
         console.error(`writer: ${result.writer_activation.outcome} (generation ${result.writer_activation.generation})`);
       }
-      if (result.deduplicated) console.error("note: this key was already claimed by this same principal — the ORIGINAL envelope was reused (safe replay)");
+      if (result.deduplicated) console.error("note: this key was already redeemed by this same principal — the ORIGINAL envelope was reused (safe replay)");
       for (const na of result.next_actions ?? []) {
         if (na.command) console.error(`next: ${na.command}${na.why ? ` — ${na.why}` : ""}`);
       }
@@ -2067,15 +2067,15 @@ async function invite(args) {
     console.error(`invite minted: role ${result.minted_role}, expires ${result.expires_at}, room ${result.room?.room_key ?? "(unknown)"}`);
     console.error(`recipient runs: kygit join <key printed below>`);
     if (result.inviter_presence && result.inviter_presence.registered === false) {
-      console.error(`note: your own presence was not registered (${result.inviter_presence.error}) — the invite still mints and is claimable`);
+      console.error(`note: your own presence was not registered (${result.inviter_presence.error}) — the invite still mints and can be redeemed`);
     }
-    if (result.room_fact && result.room_fact.posted === false) {
-      console.error(`note: the room fact was not posted (${result.room_fact.reason}) — the invite still mints and remains claimable`);
+    if (result.room_message && result.room_message.posted === false) {
+      console.error(`note: the room message was not posted (${result.room_message.reason}) — the invite still mints and can still be redeemed`);
     }
-    // The inviter's own fact must not wake the inviter's next `messages wait`:
+    // The inviter's own message must not wake the inviter's next `messages wait`:
     // advance this checkout's stored cursor past it (best-effort).
-    if (result.room?.room_key && result.room_fact?.posted && typeof result.room_fact.cursor === "string") {
-      try { updateRoomState(result.room.organization_id, result.room.room_key, { cursor: result.room_fact.cursor }); } catch { /* never fails a mint */ }
+    if (result.room?.room_key && result.room_message?.posted && typeof result.room_message.cursor === "string") {
+      try { updateRoomState(result.room.organization_id, result.room.room_key, { cursor: result.room_message.cursor }); } catch { /* never fails a mint */ }
     }
     if (asJson) {
       printJson(sdk, result);
@@ -2093,7 +2093,7 @@ async function invite(args) {
 
 /**
  * `run402 repos join` — the full cold-start chain (SAME fold `resume`
- * uses), claim, restore exactly as `resume` does, pin `r402.room` to the
+ * uses), redeem, restore exactly as `resume` does, pin `r402.room` to the
  * invite's OWN room, register this session's presence, post ONE arrival
  * fact, and report the inviter by name and labels, live presences, the
  * catch-up cursor, and the last few messages (kygit-invite design D5).
@@ -2111,9 +2111,9 @@ async function joinInvite(args) {
     if (!key) fail({ code: "BAD_USAGE", message: "Missing the Invite Key on stdin.", hint: "Pipe the kgi1_… key, or pass it as a positional argument." });
   }
   // kygit-invite design D5: a joined agent is a NEW run402 wallet, so `join`
-  // folds the SAME cold-start chain `resume` does (allowance → faucet → one
-  // x402 prototype payment, announced) BEFORE the claim; the claim itself
-  // needs no tier, so the chain never blocks the claim. `--no-init` opts
+  // folds the SAME cold-start chain `resume` does (wallet → faucet → one
+  // x402 prototype payment, announced) BEFORE the redemption; the redemption itself
+  // needs no tier, so the chain never blocks the redemption. `--no-init` opts
   // out entirely.
   const coldStart = a.includes("--no-init") ? { performed: false, skipped: "no_init" } : await foldColdStartForResume(sdk);
   const { program, model } = resolveHarnessLabels();
@@ -2156,7 +2156,7 @@ async function joinInvite(args) {
       const { remoteHelperNextAction } = await import("./path-lookup.mjs");
       const helperAction = result.restored?.dir ? remoteHelperNextAction(result.restored.dir) : null;
       if (helperAction) result.next_actions = [...(result.next_actions ?? []), helperAction];
-    } catch { /* never fails a completed claim */ }
+    } catch { /* never fails a completed redemption */ }
     if (a.includes("--json")) {
       printJson(sdk, { ...result, cold_start: coldStart });
     } else {
@@ -2166,7 +2166,7 @@ async function joinInvite(args) {
       }
       console.error("");
       console.error(`joined into ${result.restored.dir} (branch ${result.restored.branch})`);
-      if (result.deduplicated) console.error("note: this key was already claimed by this same principal — the ORIGINAL envelope was reused (safe replay)");
+      if (result.deduplicated) console.error("note: this key was already redeemed by this same principal — the ORIGINAL envelope was reused (safe replay)");
       // gitvault-multi-writer (rev 47) / kygit-invite design D5 — this
       // checkout's own writer activation, printed in the SAME `writer: …`
       // shape `resume` uses. `pending` is D9's not-stranded path: the key is
@@ -2591,8 +2591,8 @@ async function fsck(args) {
 const GC_VALUE_FLAGS = [...COMMON_VALUE_FLAGS, "--intent-core", "--verifier-receipt"];
 
 /**
- * One line of headroom disclosure. Printed whether or not things fit: an
- * operator deciding when to compact wants the numbers in the passing case too
+ * One line of headroom disclosure. Printed whether or not things fit: a
+ * person deciding when to compact wants the numbers in the passing case too
  * (gitvault-compaction-headroom-preflight D4).
  */
 function printHeadroomNote(headroom) {
@@ -2767,7 +2767,7 @@ async function accessRead(args) {
     const cp = loadLiveControlPlaneSession();
     if (cp) {
       try {
-        const mine = await sdk.operator.session.sourceAccessWrappers({ token: cp.control_plane_session_token });
+        const mine = await sdk.session.sourceAccessWrappers({ token: cp.control_plane_session_token });
         result.member_custody = mine.encryption_key
           ? {
               available: true,
@@ -2782,7 +2782,7 @@ async function accessRead(args) {
         result.member_custody = { available: false, reason: e?.code ?? "read_failed", hint: "your own wrapper custody could not be read (older gateway, or the session lacks it)." };
       }
     } else {
-      result.member_custody = { available: false, reason: "no_control_plane_session", hint: "run 'run402 operator login --loopback' to include your own wrapper custody here." };
+      result.member_custody = { available: false, reason: "no_control_plane_session", hint: "run 'run402 login' to include your own wrapper custody here." };
     }
     if (human) {
       console.log(formatAccessHuman(result));
@@ -2935,7 +2935,7 @@ async function accessRevokeKey(args) {
  * eligible starting at the NEXT rotation.
  */
 /**
- * `repos access repin --principal <id> --fingerprint <ek_…>` — a KEY-HOLDER
+ * `repos access repin --principal <principal_id> --fingerprint <ek_…>` — a KEY-HOLDER
  * explicitly accepts a recipient's CHANGED key (gitvault-agent-envelopes D3).
  * The session-start reconcile refuses `pinned_key_mismatch` and never
  * bypasses it, not even after an owner's revoke — acceptance names the new
@@ -3172,7 +3172,7 @@ async function recover(args) {
  *
  * Principal-scoped, not repo-scoped (one bundle covers every vault you are
  * a recipient of) — which is why the auth is your control-plane (human)
- * session (`run402 operator login --loopback`), not the wallet. Without a
+ * session (`run402 login`), not the wallet. Without a
  * session the request falls back to the active WALLET's agent principal,
  * which normally holds no wrappers — truthful, with a stderr note saying so.
  * Enrollment/activation/revocation are browser ceremonies at
@@ -3182,7 +3182,7 @@ function sourceAccessTokenOpts(commandLabel) {
   const cp = loadLiveControlPlaneSession();
   if (!cp) {
     console.error(
-      `no control-plane (human) session — ${commandLabel} will answer for the active WALLET's agent principal, which normally holds no wrappers. Run 'run402 operator login --loopback' to act as yourself.`,
+      `no control-plane (human) session — ${commandLabel} will answer for the active WALLET's agent principal, which normally holds no wrappers. Run 'run402 login' to act as yourself.`,
     );
     return {};
   }
@@ -3196,7 +3196,7 @@ async function recoveryBundle(args) {
   const out = flagValue(a, "--out");
   const sdk = getSdk();
   try {
-    const bundle = await sdk.operator.session.sourceAccessRecoveryBundle(sourceAccessTokenOpts("recovery-bundle"));
+    const bundle = await sdk.session.sourceAccessRecoveryBundle(sourceAccessTokenOpts("recovery-bundle"));
     // Full JSON to stdout regardless — the pipe contract is sacred; the file
     // is the keep-a-copy convenience (0600 — the bundle is ciphertext the
     // platform cannot open, but it is still half of a recovery credential).