run402 4.93.2 → 4.94.0

package/lib/redeem.mjs

@@ -2,14 +2,13 @@ import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, normalizeArgv, positionalArgs } from "./argparse.mjs";
 
-const HELP = `run402 redeem — Redeem a promo code for run402 credit
+const HELP = `run402 redeem — Redeem a promo code into your organization's allowance
 
 Usage:
   run402 redeem <code> [--json]
 
-A promo code credits your organization with run402 prepaid credit. That credit
-spends like any other prepaid balance — a tier purchase settles from it with no
-on-chain payment.
+A promo code adds to your organization's allowance, which spends like any
+other allowance — a tier purchase settles from it with no on-chain payment.
 
 Notes:
   - Order does not matter. This works as your very first authenticated call
@@ -17,7 +16,7 @@ Notes:
   - Codes are forgiving: case-insensitive and hyphens are optional, so
     'R402-K8F3-Q2W9' and 'r402k8f3q2w9' are the same code.
   - Retrying is safe. A repeat by the same organization returns the original
-    result with "already_redeemed": true and never credits twice.
+    result with "already_redeemed": true and never adds the amount twice.
   - Being in a grace state does not block you. Redeeming is how an owner funds
     a renewal, so it is never gated.
   - One gift per organization, per issuer: past the lifetime ceiling for a
@@ -64,10 +63,10 @@ export async function run(args = []) {
     // in a field a human skims past.
     console.error("");
     console.error(
-      `  Voucher    ${usd(data.amount_usd_micros)} credited` +
-        `${data.already_redeemed ? " (already redeemed " + data.redeemed_at + " — no second credit)" : ""}`,
+      `  Voucher    ${usd(data.amount_usd_micros)} added` +
+        `${data.already_redeemed ? " (already redeemed " + data.redeemed_at + " — not added twice)" : ""}`,
     );
-    console.error(`  Balance    ${usd(data.balance_usd_micros)} available`);
+    console.error(`  Allowance  ${usd(data.balance_usd_micros)}`);
     const next = Array.isArray(data.next_actions) ? data.next_actions.find((a) => a?.cli) : null;
     if (next?.cli) console.error(`\n  Next: ${next.cli}`);
     console.error("");

package/lib/remote-helper-session.mjs

@@ -146,7 +146,7 @@ const { getSdk } = await sdkModP;
 const { resolveWalletCore, enforceWalletExistsCore, WalletSelectionError } = await walletModP;
 const { gitvaultRemoteAddressForm, gitvaultSlugReleasedInfo, parseGitvaultRemoteUrl, gitvaultDegradedReadNote } = await isoModP;
 const { GITVAULT_R402_REF_NAMESPACE, hardenedGit, resolveGitInvocationRepo, readPinnedGitvaultRepo, pinGitvaultRepo, readGitvaultRestoreMarker, readGitvaultAutoGcThreshold, predialGitvaultObjectStore } = await nodeModP;
-const { allowanceFile, projectCredentialsFile, profileStateFile } = await configModP;
+const { walletFile, projectCredentialsFile, profileStateFile } = await configModP;
 
 /**
  * Per-session SDK construction cache (gitvault-first-op-premium task 2.2).
@@ -167,10 +167,10 @@ const { allowanceFile, projectCredentialsFile, profileStateFile } = await config
  * doc comment calls out as reasons a fresh instance mattered for tests that
  * mutate them between calls in one process) and INVALIDATED on the mtime of
  * the three files whose bytes actually determine signer/credential material
- * (allowance, project-credentials keystore, profile state) — a wallet
+ * (wallet, project-credentials keystore, profile state) — a wallet
  * rotation, `run402 init`, or any other on-disk change is picked up on the
  * very next call, no daemon restart required. A file that does not exist
- * yet (fresh wallet, no allowance) signs into the key as `null`, so its
+ * yet (fresh wallet, no local wallet) signs into the key as `null`, so its
  * LATER appearance also busts the cache. The in-process fallback host calls
  * this at most once per process anyway, so it degrades to exactly today's
  * behavior there — this only changes anything for the daemon.
@@ -189,7 +189,7 @@ function sdkCacheKey() {
   const wallet = process.env.RUN402_WALLET ?? "";
   const configDir = process.env.RUN402_CONFIG_DIR ?? "";
   const apiBase = process.env.RUN402_API_BASE ?? "";
-  const files = [mtimeOf(allowanceFile()), mtimeOf(projectCredentialsFile()), mtimeOf(profileStateFile())];
+  const files = [mtimeOf(walletFile()), mtimeOf(projectCredentialsFile()), mtimeOf(profileStateFile())];
   return `${wallet} ${configDir} ${apiBase} ${files.join(",")}`;
 }
 
@@ -214,7 +214,7 @@ const note = (line) => process.stderr.write(`git-remote-run402: ${line}\n`);
  * selection at all — a `.run402.json` binding, and even the global
  * `wallets use` default, would silently never reach it; only the
  * `RUN402_WALLET` env layer would work, so a bound checkout's `git push
- * run402 main` would use the WRONG wallet's (usually empty) allowance.
+ * run402 main` would use the WRONG (usually empty) wallet.
  *
  * Shares `resolveWalletCore`/`enforceWalletExistsCore` with the CLI
  * (`cli/lib/wallet-context.mjs`) — ONE implementation, minus the CLI's
@@ -253,19 +253,19 @@ function walletSourceLabel(resolved) {
 }
 
 /**
- * The allowance-missing/malformed family (`core/src/allowance.ts`'s own
+ * The wallet-missing/malformed family (`core/src/wallet.ts`'s own
  * throws) all end with "Back up the file and run 'run402 init' to recreate
  * it." — a remedy that assumes the resolved wallet is the one you meant.
  * That is only true when NOTHING selected a wallet (the bare default); when
  * an env var or a binding DID name one, the remedy is actively harmful —
- * `run402 init` recreates the DEFAULT wallet's allowance, a DIFFERENT
- * wallet than the one that was actually resolved and whose allowance is
+ * `run402 init` recreates the DEFAULT wallet's key file, a DIFFERENT
+ * wallet than the one that was actually resolved and whose key file is
  * actually missing/broken. Replace
  * it with the resolved wallet's name and how selection works, so the fix is
  * "correct the selection" rather than "recreate the wrong wallet".
  */
-function enrichAllowanceError(message) {
-  if (!resolvedWallet || !/allowance\.json/.test(message)) return message;
+function enrichWalletError(message) {
+  if (!resolvedWallet || !/wallet\.json/.test(message)) return message;
   const source = walletSourceLabel(resolvedWallet);
   const stripped = message.replace(/\s*Back up the file and run 'run402 init' to recreate it\.?/, "").trim();
   if (!source) {
@@ -276,13 +276,13 @@ function enrichAllowanceError(message) {
   return (
     `${stripped} Resolved wallet '${resolvedWallet.name}' via ${source} ` +
     "(order: RUN402_WALLET env > .run402.json binding > 'wallets use' default > default). " +
-    `Wrong wallet? Fix selection instead. Right wallet, just no allowance yet? 'run402 wallets new ${resolvedWallet.name}'.`
+    `Wrong wallet? Fix selection instead. Right wallet, just not created yet? 'run402 wallets new ${resolvedWallet.name}'.`
   );
 }
 
 function describeError(err) {
   const code = err?.code ?? err?.body?.code ?? null;
-  const message = enrichAllowanceError(err?.message ?? err?.body?.message ?? String(err));
+  const message = enrichWalletError(err?.message ?? err?.body?.message ?? String(err));
   // SLUG_RELEASED is never auto-followed — but the successor slug (design D6)
   // is exactly the fact a human/agent reading stderr needs to act on it.
   const released = gitvaultSlugReleasedInfo(err);

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";
@@ -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 —
@@ -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 org 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}`));
@@ -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 org slug <slug>` to get a full run402::<slug>/<name> address");
     printVerboseStats(a, sdk);
   } catch (err) {
     reportSdkError(err);
@@ -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));
@@ -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).