run402 4.95.0 → 4.96.0

package/lib/remote-helper-session.mjs

@@ -1,10 +1,10 @@
 /**
- * The HOST-AGNOSTIC remote-helper session (gitvault-persistent-helper D1).
+ * The HOST-AGNOSTIC remote-helper session (vault-persistent-helper D1).
  *
  * Extracted verbatim from `cli/git-remote-run402.mjs` so ONE implementation
  * serves two hosts: the in-process fallback (the thin bin imports this and
  * runs it with the real process's stdio) and the resident daemon
- * (`cli/lib/gitvault-daemon.mjs`, which forwards a client's session into it).
+ * (`cli/lib/vault-daemon.mjs`, which forwards a client's session into it).
  * Per-invocation state — wallet resolution, repository resolution, env-
  * derived config — is resolved fresh per `runHelperSession` call; the only
  * thing that persists across sessions in a daemon is warm code and warm
@@ -16,12 +16,12 @@
  * The original file-level doctrine follows, unchanged:
  *
 /**
- * `git-remote-run402` — the git remote helper for gitvault, so plain
+ * `git-remote-run402` — the git remote helper for vault, so plain
  * `git clone|fetch|push run402::<org_id>/<project_id>` speaks to a host-blind
  * encrypted vault with no run402-specific git ceremony.
  *
- * ARCHITECTURAL LAW (gitvault-client-surface, "All protocol logic lives in the
- * SDK"): this file is a THIN ADAPTER over `r.gitvault`. It translates git's
+ * ARCHITECTURAL LAW (vault-client-surface, "All protocol logic lives in the
+ * SDK"): this file is a THIN ADAPTER over `r.repos`. It translates git's
  * remote-helper wire protocol into SDK calls and back, and does nothing else.
  * No crypto, no HTTP, no ref-policy decisions, no pack building — those live
  * once in `@run402/sdk`. Even git itself is invoked only through the SDK's own
@@ -39,18 +39,18 @@
  * an unallocated vault reports as an empty ref set, exactly what a fresh
  * repository looks like — but `push` does: `git push origin main` against a
  * project whose vault does not exist yet runs the six-stage creation journal
- * inline (`r.gitvault.openOrCreate`, the SDK-owned primitive), prints the
+ * inline (`r.repos.openOrCreate`, the SDK-owned primitive), prints the
  * one-shot recovery receipt and the keystore path to stderr, and then
- * completes the push. One command, no prior `gitvault init`. `git ls-remote`
+ * completes the push. One command, no prior `vault init`. `git ls-remote`
  * / `fetch` stay pure reads and allocate nothing.
  *
  * NAMED ADDRESSING + PUSH-TO-CREATE (repo-first-onramp task 4, design D6).
  * `run402::<org>/<name>` admits TWO forms in the same slot — id-form
- * (`org_id`/`prj_...`, unchanged: resolved via `r.gitvault.openOrCreate`
+ * (`org_id`/`prj_...`, unchanged: resolved via `r.repos.openOrCreate`
  * above) and slug-form (`run402::<org-slug>/<name>`, e.g.
  * `run402::acme/my-notes`) — discriminated by
- * `gitvaultRemoteAddressForm`. A slug-form remote resolves through
- * `r.gitvault.resolveOrCreateAddress`, which ALSO drives push-to-create on a
+ * `vaultRemoteAddressForm`. A slug-form remote resolves through
+ * `r.repos.resolveOrCreateAddress`, which ALSO drives push-to-create on a
  * miss (`push` only; `list`/`fetch` pass `allow_create: false`, same "reads
  * never allocate" discipline as the id-form path) and PINS the resolved
  * `repo_id` in this checkout's local git config the first time it resolves
@@ -95,7 +95,7 @@
  *     helper points it at one of the branches THIS push is publishing — the
  *     local repository's own HEAD branch when it is among them, else the
  *     first branch in the batch — and prints a one-line stderr note saying
- *     which and why (see `chooseGitvaultHeadTargetForPush`). A HEALTHY HEAD
+ *     which and why (see `chooseVaultHeadTargetForPush`). A HEALTHY HEAD
  *     (one that already names a ref this push leaves present) is NEVER
  *     touched — push moving history never means push moving HEAD.
  *   - `option dry-run true` runs the REAL local
@@ -113,18 +113,18 @@
  *     `capabilities`, `option` and `list` work without one, which is exactly
  *     the set `git ls-remote <url>` outside a checkout needs.
  *
- * DEGRADED READ MODE (gitvault-byo-primary-bucket, design D4). `list` and
+ * DEGRADED READ MODE (vault-byo-primary-bucket, design D4). `list` and
  * `fetch` each wrap their own live gateway read in
- * `getSdk().gitvault.withDegradedRead` — on a NETWORK-CLASS failure (never a
+ * `getSdk().repos.withDegradedRead` — on a NETWORK-CLASS failure (never a
  * 401/403/404 or any other 4xx; one bounded retry runs first so a transient
  * blip does not flap between sources) with a mirror configured for this
  * vault, the read is served from it instead via the SAME `r402s-recover`
  * engine `run402 repos recover` uses — `git fetch`/`clone` keep working
  * while run402 is down. The result is marked `degraded: true` with source
  * provenance, and exactly one stderr line names the fallback and its source
- * (`gitvaultDegradedReadNote`). Local trust pins never advance past what the
+ * (`vaultDegradedReadNote`). Local trust pins never advance past what the
  * mirror copy itself chain-verifies (the fallback engine never touches the
- * live vault's own keystore pins at all — see `gitvault-degraded-read.ts`'s
+ * live vault's own keystore pins at all — see `vault-degraded-read.ts`'s
  * own doc comment). A vault with no mirror configured is BYTE-IDENTICAL to
  * today: the original gateway error surfaces unchanged. `push` is UNTOUCHED
  * by this — writes are never rerouted; admission always requires the
@@ -136,7 +136,7 @@ import { statSync } from "node:fs";
 
 // The heavy graphs load as ONE top-level await batch — in the in-process
 // host this races the thin bin's already-fired prewarm; in the daemon host
-// it happens once at daemon boot (gitvault-startup-amortization D1).
+// it happens once at daemon boot (vault-startup-amortization D1).
 const sdkModP = import("./sdk.mjs");
 const walletModP = import("./wallet-context.mjs");
 const isoModP = import("#sdk");
@@ -144,12 +144,12 @@ const nodeModP = import("#sdk/node");
 const configModP = import("./config.mjs");
 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 { vaultRemoteAddressForm, vaultSlugReleasedInfo, parseVaultRemoteUrl, vaultDegradedReadNote } = await isoModP;
+const { VAULT_R402_REF_NAMESPACE, hardenedGit, resolveGitInvocationRepo, readPinnedVaultRepo, pinVaultRepo, readVaultRestoreMarker, readVaultAutoGcThreshold, predialVaultObjectStore } = await nodeModP;
 const { walletFile, projectCredentialsFile, profileStateFile } = await configModP;
 
 /**
- * Per-session SDK construction cache (gitvault-first-op-premium task 2.2).
+ * Per-session SDK construction cache (vault-first-op-premium task 2.2).
  *
  * `getSdk()` builds a fresh Node SDK instance on every call — cheap for a
  * traditional one-process-per-invocation CLI, but this module is ALSO the
@@ -285,7 +285,7 @@ function describeError(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);
+  const released = vaultSlugReleasedInfo(err);
   const suffix = released?.successor_slug ? ` (renamed to "${released.successor_slug}" — update the remote and re-run)` : "";
   return oneLine(code ? `${code}: ${message}${suffix}` : message);
 }
@@ -307,7 +307,7 @@ function oneLine(value) {
 function resolveRemoteAddress(argv) {
   for (const raw of [argv[1], argv[0]]) {
     if (typeof raw !== "string" || raw.length === 0) continue;
-    const direct = parseGitvaultRemoteUrl(raw);
+    const direct = parseVaultRemoteUrl(raw);
     if (direct) return direct;
     // Re-add the prefix ONLY for a bare, colon-free address. Without this
     // guard `https://example.com/x` parses as org `https:` / project
@@ -315,7 +315,7 @@ function resolveRemoteAddress(argv) {
     // — a confidently wrong answer is worse than no answer here. The colon is
     // git's own URL punctuation, never part of a bare `<org_id>/<project_id>`.
     if (raw.includes(":")) continue;
-    const prefixed = parseGitvaultRemoteUrl(`run402::${raw}`);
+    const prefixed = parseVaultRemoteUrl(`run402::${raw}`);
     if (prefixed) return prefixed;
   }
   return null;
@@ -331,11 +331,11 @@ function parsePushSpec(spec) {
 }
 
 /** `R402_PROTECTED_REF_NAMESPACE`'s one-line reason, shared by the protocol `error` line and the stderr note. */
-export const R402_PROTECTED_REF_NAMESPACE_REASON = `R402_PROTECTED_REF_NAMESPACE: ${GITVAULT_R402_REF_NAMESPACE}* is client-local bookkeeping maintained by fetch, not push — push branches instead.`;
+export const R402_PROTECTED_REF_NAMESPACE_REASON = `R402_PROTECTED_REF_NAMESPACE: ${VAULT_R402_REF_NAMESPACE}* is client-local bookkeeping maintained by fetch, not push — push branches instead.`;
 
 /**
  * D4: `refs/r402/*` is client-local (design D1/D2's local ref bookkeeping) —
- * never advertised for push, never part of a `GitvaultRefTransaction`. Split
+ * never advertised for push, never part of a `VaultRefTransaction`. Split
  * one push batch into the specs this helper will actually publish and the
  * ones it refuses, PURE and pre-repository (a refname prefix check needs no
  * repo, no network, no wallet), so a batch made ENTIRELY of protected refs
@@ -349,7 +349,7 @@ export function partitionProtectedRefPushes(specs) {
   const refused = [];
   const allowed = [];
   for (const spec of specs) {
-    if (spec.dst.startsWith(GITVAULT_R402_REF_NAMESPACE)) refused.push(spec);
+    if (spec.dst.startsWith(VAULT_R402_REF_NAMESPACE)) refused.push(spec);
     else allowed.push(spec);
   }
   return { refused, allowed };
@@ -384,7 +384,7 @@ export function partitionProtectedRefPushes(specs) {
  * has no branch update to repair it WITH (a tags-only or deletion-only
  * batch cannot fix a dangling HEAD by itself).
  */
-export function chooseGitvaultHeadTargetForPush({ baseHeadTarget, baseRefs, updates, localHeadRef }) {
+export function chooseVaultHeadTargetForPush({ baseHeadTarget, baseRefs, updates, localHeadRef }) {
   const postPushRefs = { ...(baseRefs ?? {}) };
   for (const u of updates) {
     if (u.new_oid === null) delete postPushRefs[u.ref];
@@ -412,13 +412,13 @@ export function chooseGitvaultHeadTargetForPush({ baseHeadTarget, baseRefs, upda
 }
 
 /**
- * gitvault-checkpoint-cadence design D1 — the pure post-push auto-gc
+ * vault-checkpoint-cadence design D1 — the pure post-push auto-gc
  * threshold decision, exported standalone so the threshold matrix (below /
  * at / disabled) is directly unit-testable without the session's heavier
  * closures (network, git, daemon plumbing). `0` (or anything not a
  * positive finite number — a corrupt local config value) means disabled;
  * `generationsSinceCheckpoint >= threshold` is the trigger (matches
- * `gitvaultCheckpointStaleness`'s own `since >= THRESHOLD` shape).
+ * `vaultCheckpointStaleness`'s own `since >= THRESHOLD` shape).
  */
 export function shouldRunAutoGc(threshold, generationsSinceCheckpoint) {
   return Number.isFinite(threshold) && threshold > 0 && Number.isFinite(generationsSinceCheckpoint) && generationsSinceCheckpoint >= threshold;
@@ -427,12 +427,12 @@ export function shouldRunAutoGc(threshold, generationsSinceCheckpoint) {
 /**
  * The auto-gc cycle's `compact()`/`prune()` target — exported standalone,
  * same reasoning as `shouldRunAutoGc` above, because the merge itself was
- * the bug: `GitvaultVaultHandleOptions.repo_dir` defaults to
+ * the bug: `VaultHandleOptions.repo_dir` defaults to
  * `process.cwd()` only in CALLER convention, never inside the SDK's own
  * `open()` (which sets it ONLY when `options.repo_dir !== undefined`).
  * Building the auto-gc target from `{ ...target }` alone — omitting
  * `repo_dir` — makes every real post-push auto-gc cycle fail closed with
- * `GITVAULT_REPO_DIR_REQUIRED`, silently degrading to the advisory on
+ * `VAULT_REPO_DIR_REQUIRED`, silently degrading to the advisory on
  * EVERY push. `repos gc`'s CLI wrapper passes repo_dir explicitly, so it
  * never exercises this path.
  */
@@ -441,8 +441,8 @@ export function buildAutoGcCompactionTarget(target, repoDir) {
 }
 
 async function main(argv, { onBackgroundWork } = {}) {
-  // gitvault-connection-amortization (bench P5) note: the prewarm now fires
-  // at the module TOP, before the SDK graph loads (gitvault-startup-
+  // vault-connection-amortization (bench P5) note: the prewarm now fires
+  // at the module TOP, before the SDK graph loads (vault-startup-
   // amortization D1) — connection dial and signer warmup both race module
   // evaluation instead of starting here.
   const address = resolveRemoteAddress(argv);
@@ -457,7 +457,7 @@ async function main(argv, { onBackgroundWork } = {}) {
   // no separate lookup. Only meaningful for an ID-FORM address; a slug-form
   // one resolves through `resolveOrCreateAddress` instead (below), which
   // needs no separate org_id at all — the gateway resolves the slug itself.
-  const addressForm = gitvaultRemoteAddressForm(address);
+  const addressForm = vaultRemoteAddressForm(address);
   const target = { project_id: address.project_id, org_id: address.org_id };
   let verbosity = 1;
   // `option dry-run true` is a REAL dry run — see `handleOption`'s
@@ -476,7 +476,7 @@ async function main(argv, { onBackgroundWork } = {}) {
   async function requireRepo() {
     if (!resolvedRepo) {
       resolvedRepo = await resolveGitInvocationRepo(process.env, process.cwd());
-      // gitvault-object-host-predial task 2.1 (trigger (a), the in-process
+      // vault-object-host-predial task 2.1 (trigger (a), the in-process
       // fallback path — this module IS that fallback; a daemon-forwarded
       // session reaches the same code and gets the same predial for free).
       // The repository is now known OFFLINE (no network read, matching
@@ -488,8 +488,8 @@ async function main(argv, { onBackgroundWork } = {}) {
       // yet predials nothing — never a source of a new failure mode.
       void (async () => {
         try {
-          const pinned = await readPinnedGitvaultRepo(resolvedRepo.repo_dir);
-          if (pinned) predialGitvaultObjectStore(pinned.repo_id);
+          const pinned = await readPinnedVaultRepo(resolvedRepo.repo_dir);
+          if (pinned) predialVaultObjectStore(pinned.repo_id);
         } catch {
           /* best-effort: must never surface from repository resolution */
         }
@@ -499,7 +499,7 @@ async function main(argv, { onBackgroundWork } = {}) {
   }
 
   /**
-   * One materialize per push session (gitvault-client-round-trips design
+   * One materialize per push session (vault-client-round-trips design
    * D1). Git guarantees `list` precedes `push` in the same helper process,
    * so a `list` that resolves an EXISTING vault against a real repository
    * stashes its vault instance + materialized base here; `runPush` reuses
@@ -547,8 +547,8 @@ async function main(argv, { onBackgroundWork } = {}) {
    * Open the vault lazily — `capabilities` and `option` must never touch the
    * network. Both address forms resolve (and, on the first successful
    * resolution, PIN `repo_id` in local git state — task 4.5 for slug-form,
-   * gitvault-client-round-trips design D4 widening the same mechanism to
-   * id-form) through `gitvault.resolveOrCreateAddress` with
+   * vault-client-round-trips design D4 widening the same mechanism to
+   * id-form) through `repos.resolveOrCreateAddress` with
    * `allow_create: false` — a read never allocates, and `allow_create` is
    * meaningless for id-form's own dispatch anyway (it never creates,
    * pinned or not). A repo-free call (`repoDir` undefined — `list` outside
@@ -556,7 +556,7 @@ async function main(argv, { onBackgroundWork } = {}) {
    * pin.
    */
   const openVault = async (repoDir) => {
-    const result = await getCachedSdk().gitvault.resolveOrCreateAddress({ address, allow_create: false, ...(repoDir ? { repo_dir: repoDir } : {}) });
+    const result = await getCachedSdk().repos.resolveOrCreateAddress({ address, allow_create: false, ...(repoDir ? { repo_dir: repoDir } : {}) });
     return { vault: result.handle.vault, keystore: result.handle.keystore, repo_id: result.handle.repo_id, resolution: result.resolution };
   };
 
@@ -567,12 +567,12 @@ async function main(argv, { onBackgroundWork } = {}) {
    * `list`/`fetch` stay pure reads and never create anything (see
    * `runList`'s own not-found handling below).
    *
-   * Id-form (gitvault-client-round-trips design D4): a PINNED repo_id means
+   * Id-form (vault-client-round-trips design D4): a PINNED repo_id means
    * this checkout has already resolved (or pushed to) this vault before, so
    * there is nothing left to allocate — the read-only, pin-aware
    * `resolveOrCreateAddress` path (same one `openVault` uses) is enough,
    * and cheaper than re-running the allocation-capable flow on every push.
-   * With NO pin yet, this is unchanged: `gitvault.openOrCreate` runs its
+   * With NO pin yet, this is unchanged: `repos.openOrCreate` runs its
    * six-stage creation journal when the vault does not exist, exactly as
    * before — and, on success, PINS the resolved id for every later push on
    * this checkout (this is the "first successful resolution" the pin exists
@@ -586,27 +586,27 @@ async function main(argv, { onBackgroundWork } = {}) {
    */
   async function openOrCreateVault(repoDir) {
     if (addressForm === "id" && repoDir) {
-      const pinned = await readPinnedGitvaultRepo(repoDir);
+      const pinned = await readPinnedVaultRepo(repoDir);
       if (pinned) {
-        const result = await getCachedSdk().gitvault.resolveOrCreateAddress({ address, repo_dir: repoDir, allow_create: false });
+        const result = await getCachedSdk().repos.resolveOrCreateAddress({ address, repo_dir: repoDir, allow_create: false });
         return result.handle.vault;
       }
     }
     const result =
       addressForm === "id"
-        ? await getCachedSdk().gitvault.openOrCreate({ ...target, repo_dir: repoDir })
-        : await getCachedSdk().gitvault.resolveOrCreateAddress({ address, repo_dir: repoDir, allow_create: true });
-    if (addressForm === "id" && repoDir) await pinGitvaultRepo(repoDir, result.handle.repo_id, undefined, { project_id: target.project_id, org_id: target.org_id });
+        ? await getCachedSdk().repos.openOrCreate({ ...target, repo_dir: repoDir })
+        : await getCachedSdk().repos.resolveOrCreateAddress({ address, repo_dir: repoDir, allow_create: true });
+    if (addressForm === "id" && repoDir) await pinVaultRepo(repoDir, result.handle.repo_id, undefined, { project_id: target.project_id, org_id: target.org_id });
     if (!result.found && result.created) {
       note("");
       note(`vault ${result.handle.repo_id} allocated (genesis ${result.created.genesis_sha256}) — one-shot recovery receipt, keep many copies:`);
       note(JSON.stringify(result.created.recovery_receipt));
       try {
-        const { getGitvaultKeystoreRoot, GITVAULT_MIRROR_SETUP_HINT } = await import("#sdk/node");
-        // gitvault-mirror-default: every allocation teaches the mirror door
+        const { getVaultKeystoreRoot, VAULT_MIRROR_SETUP_HINT } = await import("#sdk/node");
+        // vault-mirror-default: every allocation teaches the mirror door
         // beside the recovery receipt, lazy push-to-create included.
-        note(GITVAULT_MIRROR_SETUP_HINT);
-        note(`keystore: ${getGitvaultKeystoreRoot()} — back this up; whole-machine or whole-keystore loss is terminal for vault history until human envelopes ship`);
+        note(VAULT_MIRROR_SETUP_HINT);
+        note(`keystore: ${getVaultKeystoreRoot()} — back this up; whole-machine or whole-keystore loss is terminal for vault history until human envelopes ship`);
       } catch {
         // Never let a diagnostic line fail a push that already allocated successfully.
       }
@@ -633,7 +633,7 @@ async function main(argv, { onBackgroundWork } = {}) {
       // checkout) — `list` still works, and there is nothing for `push` to
       // share later in that case.
     }
-    // gitvault-session-state-reuse design D2: read the restore MARKER —
+    // vault-session-state-reuse design D2: read the restore MARKER —
     // NEVER the chain-trust pin (see `tryStateFastPath`'s own doc comment on
     // why the pin is the wrong `since` for a standing clone that is
     // generations behind) — once, here, and thread it to the materialize
@@ -643,12 +643,12 @@ async function main(argv, { onBackgroundWork } = {}) {
     let fetchMarker = null;
     if (repoDir) {
       try {
-        fetchMarker = await readGitvaultRestoreMarker(repoDir);
+        fetchMarker = await readVaultRestoreMarker(repoDir);
       } catch {
         fetchMarker = null;
       }
     }
-    // gitvault-restore-recipe design D2/D6: a marker-absent fetch target is,
+    // vault-restore-recipe design D2/D6: a marker-absent fetch target is,
     // by construction, the WHOLESALE restore shape (a fresh `git clone`, or
     // a target that never completed a restore) — declare restore intent
     // here so a capable gateway's plan rides THIS state read, reused by
@@ -673,18 +673,18 @@ async function main(argv, { onBackgroundWork } = {}) {
         endBlock();
         return;
       }
-      // gitvault-byo-primary-bucket (design D4): the OPEN itself needed the
+      // vault-byo-primary-bucket (design D4): the OPEN itself needed the
       // gateway. On a network-class failure, with this checkout already
       // knowing the vault and holding a local copy source (its BYO destination
       // or a mirror), the listing is served from that copy — `null` means the
       // fallback cannot help and the original error surfaces unchanged.
-      const fallback = repoDir ? await getCachedSdk().gitvault.degradedOpenFallback?.({ address, repo_dir: repoDir, error: err }).catch(() => null) : null;
+      const fallback = repoDir ? await getCachedSdk().repos.degradedOpenFallback?.({ address, repo_dir: repoDir, error: err }).catch(() => null) : null;
       if (!fallback) throw err;
       outcome = fallback;
     }
     let vault = opened?.vault;
 
-    // gitvault-byo-primary-bucket (design D4, task 3.4 — mirror half): the
+    // vault-byo-primary-bucket (design D4, task 3.4 — mirror half): the
     // live materialize (with its own stale-pin retry, unchanged from before
     // this change) is the "attemptLive" `withDegradedRead` wraps — on a
     // NETWORK-CLASS failure (never 4xx) with a mirror configured for this
@@ -705,7 +705,7 @@ async function main(argv, { onBackgroundWork } = {}) {
         // always runs `list` first in a helper session, so this one site
         // heals the pin for the `fetch`/`push` that follows it.
         const recovered = repoDir && opened.resolution?.offline
-          ? await getCachedSdk().gitvault.recoverStalePin({ address, repo_dir: repoDir, resolution: opened.resolution, error: err })
+          ? await getCachedSdk().repos.recoverStalePin({ address, repo_dir: repoDir, resolution: opened.resolution, error: err })
           : null;
         if (!recovered) throw err;
         note(`pinned vault ${opened.resolution.repo_id} no longer resolves — re-resolved to ${recovered.resolution.repo_id}, retrying`);
@@ -717,7 +717,7 @@ async function main(argv, { onBackgroundWork } = {}) {
 
     if (!outcome) {
     try {
-      outcome = await getCachedSdk().gitvault.withDegradedRead({ attemptLive, keystore: opened.keystore, repo_id: opened.repo_id, out_dir: repoDir });
+      outcome = await getCachedSdk().repos.withDegradedRead({ attemptLive, keystore: opened.keystore, repo_id: opened.repo_id, out_dir: repoDir });
     } catch (err) {
       // Same "an unallocated vault is not an error" reasoning as above — a
       // 404 discovered only once materialize actually runs takes this same
@@ -738,7 +738,7 @@ async function main(argv, { onBackgroundWork } = {}) {
       // Exactly ONE stderr line naming the degraded read and its source
       // (design D4) — the validity-not-freshness limit rides inside the
       // canonical statement this composes, verbatim.
-      note(gitvaultDegradedReadNote(outcome.result.source));
+      note(vaultDegradedReadNote(outcome.result.source));
       refs = outcome.result.refs ?? {};
       head = outcome.result.head_target;
       // No live vault instance materialized this pass — nothing safe to
@@ -749,7 +749,7 @@ async function main(argv, { onBackgroundWork } = {}) {
       const state = outcome.live;
       refs = state.refs ?? {};
       head = state.head_target;
-      // gitvault-session-state-reuse design D1: `fetchState`/`fetchMarker`
+      // vault-session-state-reuse design D1: `fetchState`/`fetchMarker`
       // extend the SAME session-scoped handoff `push` already reuses (`base`)
       // — the `fetch` phase of THIS session reuses this response instead of
       // issuing its own state read. Session-scoped only: dropped the moment a
@@ -793,7 +793,7 @@ async function main(argv, { onBackgroundWork } = {}) {
     // wherever clone was run FROM, unrelated to the target repository).
     applyWalletForDir(repoDir);
     if (verbosity >= 1) note(`restoring the vault object database for ${batch.length} ref(s) into ${repoDir}`);
-    // gitvault-session-state-reuse design D1/D4: reuse THIS session's `list`
+    // vault-session-state-reuse design D1/D4: reuse THIS session's `list`
     // phase state — same resolved repository AND wallet, exactly the same
     // matching rule `push`'s own reuse uses above — instead of a second
     // network state read. Any mismatch (no prior `list`, a failed list, a
@@ -801,9 +801,9 @@ async function main(argv, { onBackgroundWork } = {}) {
     // same session — see `runPush`'s reset) falls back to the vault's own
     // read, unchanged.
     //
-    // gitvault-byo-primary-bucket (design D4, task 3.4 — mirror half):
+    // vault-byo-primary-bucket (design D4, task 3.4 — mirror half):
     // either path's actual chain/payload read is the "attemptLive" that
-    // `withDegradedRead` wraps — `gitvault.restore(...)` is exactly `open()`
+    // `withDegradedRead` wraps — `repos.restore(...)` is exactly `open()`
     // followed by `handle.vault.restoreObjectsInto(target_dir)` (see that
     // method's own one-line body), decomposed here so the SECOND half can be
     // wrapped, with byte-identical resolution to today on the live-success
@@ -824,11 +824,11 @@ async function main(argv, { onBackgroundWork } = {}) {
     } else {
       let handle = null;
       try {
-        handle = await getCachedSdk().gitvault.open({ ...target, repo_dir: repoDir });
+        handle = await getCachedSdk().repos.open({ ...target, repo_dir: repoDir });
       } catch (err) {
-        // gitvault-byo-primary-bucket (design D4): the open needed the
+        // vault-byo-primary-bucket (design D4): the open needed the
         // gateway — see runList's identical fallback.
-        const fallback = await getCachedSdk().gitvault.degradedOpenFallback?.({ address, repo_dir: repoDir, error: err }).catch(() => null);
+        const fallback = await getCachedSdk().repos.degradedOpenFallback?.({ address, repo_dir: repoDir, error: err }).catch(() => null);
         if (!fallback) throw err;
         outcome = fallback;
       }
@@ -839,7 +839,7 @@ async function main(argv, { onBackgroundWork } = {}) {
       }
     }
     if (!outcome) {
-      outcome = await getCachedSdk().gitvault.withDegradedRead({
+      outcome = await getCachedSdk().repos.withDegradedRead({
         attemptLive,
         keystore: degradedKeystore,
         repo_id: degradedRepoId,
@@ -853,7 +853,7 @@ async function main(argv, { onBackgroundWork } = {}) {
       // canonical statement this composes, verbatim. A later `git push`
       // still requires the gateway unchanged — this function only ever
       // serves reads; `runPush` below is untouched by this change.
-      note(gitvaultDegradedReadNote(outcome.result.source));
+      note(vaultDegradedReadNote(outcome.result.source));
       restored = { generation: outcome.result.generation, retained_refs: outcome.result.retained_refs };
     } else {
       restored = { generation: outcome.live.generation, retained_refs: outcome.live.retained_refs };
@@ -872,7 +872,7 @@ async function main(argv, { onBackgroundWork } = {}) {
   }
 
   /**
-   * gitvault-checkpoint-cadence (design D1/D2) — the post-push auto-gc
+   * vault-checkpoint-cadence (design D1/D2) — the post-push auto-gc
    * cadence, `git gc --auto`'s shape: a cheap local threshold check after
    * every successful push, maintenance only past it.
    *
@@ -884,7 +884,7 @@ async function main(argv, { onBackgroundWork } = {}) {
    * it.
    *
    * Threshold: `repoDir`'s local `auto_gc_generations` (default 32, `0`
-   * disables — `readGitvaultAutoGcThreshold`, design D1's "rides the
+   * disables — `readVaultAutoGcThreshold`, design D1's "rides the
    * existing vault policy surface" as a per-checkout `repos policy` knob).
    *
    * Dispatch: with a daemon-supplied `onBackgroundWork`, the compaction is
@@ -894,9 +894,9 @@ async function main(argv, { onBackgroundWork } = {}) {
    * one (the in-process fallback), the SAME cycle is awaited right here,
    * with one stderr advisory line naming the wait.
    *
-   * `compact()` (namespace, `sdk/src/namespaces/gitvault.ts`) already owns
+   * `compact()` (namespace, `sdk/src/namespaces/repos.ts`) already owns
    * the compaction headroom grant's open/close and single-flight refusal
-   * (`GITVAULT_COMPACTION_IN_PROGRESS`) — this function only decides WHETHER
+   * (`VAULT_COMPACTION_IN_PROGRESS`) — this function only decides WHETHER
    * and HOW to run the cycle, never re-implements those. `--force-headroom`
    * is NEVER passed on this path (design D5) — an insufficient-headroom
    * refusal, a conflicting in-flight compaction, or any other failure all
@@ -906,23 +906,23 @@ async function main(argv, { onBackgroundWork } = {}) {
   async function maybeRunAutoGc({ repoDir, generationsSinceCheckpoint }) {
     let threshold;
     try {
-      threshold = await readGitvaultAutoGcThreshold(repoDir);
+      threshold = await readVaultAutoGcThreshold(repoDir);
     } catch {
       return; // never let a local-config read failure touch the push it follows
     }
     if (!shouldRunAutoGc(threshold, generationsSinceCheckpoint)) return;
 
     // `compact()`/`prune()` never default repo_dir to process.cwd() —
-    // GitvaultVaultHandleOptions's own doc comment describes CALLER
+    // VaultHandleOptions's own doc comment describes CALLER
     // convention, not an SDK fallback (`open()` only sets repo_dir when
     // `options.repo_dir !== undefined`). Omitting it here made every real
-    // post-push auto-gc cycle fail closed with GITVAULT_REPO_DIR_REQUIRED,
+    // post-push auto-gc cycle fail closed with VAULT_REPO_DIR_REQUIRED,
     // silently degrading to the advisory on every push.
     const compactionTarget = buildAutoGcCompactionTarget(target, repoDir);
     const runCycle = async () => {
       const sdk = getCachedSdk();
-      const checkpoint = await sdk.gitvault.compact({ ...compactionTarget });
-      const prune = await sdk.gitvault.prune(compactionTarget); // PLAN only — never `submit`; see compact()'s own grant-close doc comment for why prune needs no headroom of its own
+      const checkpoint = await sdk.repos.compact({ ...compactionTarget });
+      const prune = await sdk.repos.prune(compactionTarget); // PLAN only — never `submit`; see compact()'s own grant-close doc comment for why prune needs no headroom of its own
       return { checkpoint, prune };
     };
 
@@ -938,17 +938,17 @@ async function main(argv, { onBackgroundWork } = {}) {
     }
 
     // In-process fallback: the extra wall time is real, so name it.
-    note(`gitvault: compacting (${generationsSinceCheckpoint} generations since checkpoint)…`);
+    note(`vault: compacting (${generationsSinceCheckpoint} generations since checkpoint)…`);
     try {
       await runCycle();
     } catch (err) {
-      note(`gitvault: auto-compaction stopped short — ${describeError(err)} — run \`run402 repos gc\` to finish it by hand.`);
+      note(`vault: auto-compaction stopped short — ${describeError(err)} — run \`run402 repos gc\` to finish it by hand.`);
     }
   }
 
   async function runPush(batch) {
     const specs = batch.map(parsePushSpec);
-    // gitvault-checkpoint-cadence: set ONLY after a successful admission
+    // vault-checkpoint-cadence: set ONLY after a successful admission
     // (never in the catch block) — `null` means "auto-gc has nothing to
     // do", which is also the correct value for every early-return path
     // above (nothing pushed, nothing refused-only, dry-run).
@@ -1052,10 +1052,10 @@ async function main(argv, { onBackgroundWork } = {}) {
         });
       }
       // Repair a DANGLING HEAD from this batch's own branches — see
-      // `chooseGitvaultHeadTargetForPush`'s own doc comment for the exact
+      // `chooseVaultHeadTargetForPush`'s own doc comment for the exact
       // rule. `localHeadRef` is read from THIS repository (never cwd, same
       // fail-closed resolution as everything else in this function).
-      const headFix = chooseGitvaultHeadTargetForPush({
+      const headFix = chooseVaultHeadTargetForPush({
         baseHeadTarget: base.head_target,
         baseRefs: base.refs,
         updates,
@@ -1072,7 +1072,7 @@ async function main(argv, { onBackgroundWork } = {}) {
         base,
         ...(headFix.head_target ? { head_target: headFix.head_target } : {}),
       });
-      // gitvault-session-state-reuse design D4: this admission just advanced
+      // vault-session-state-reuse design D4: this admission just advanced
       // the vault, so the `list` phase's handoff (if any) is now stale —
       // drop it. A `fetch` later in this SAME session (an unusual ordering
       // git's own protocol does not normally produce) reads fresh rather
@@ -1083,12 +1083,12 @@ async function main(argv, { onBackgroundWork } = {}) {
       // opt-in mirror dual-push and a BYO vault's signed-chain copy into the
       // customer bucket. Best-effort: never alters the push above, one
       // stderr line per outcome worth knowing.
-      const copies = await getCachedSdk().gitvault.postPublishCopies?.({ repo_id: vault.repoId, keystore: vault.keystore }).catch(() => null);
+      const copies = await getCachedSdk().repos.postPublishCopies?.({ repo_id: vault.repoId, keystore: vault.keystore }).catch(() => null);
       if (copies?.mirror_push?.outcome === "pushed") note(`mirror: pushed generation ${published.generation} (${copies.mirror_push.summary?.objects_copied ?? 0} object(s) copied)`);
-      else if (copies?.mirror_push?.outcome === "failed") note(`mirror: dual-push FAILED (the push is unaffected) — ${copies.mirror_push.error ?? "see run402 repos fsck --mirror"}`);
+      else if (copies?.mirror_push?.outcome === "failed") note(`mirror: mirroring this capture FAILED (the push is unaffected) — ${copies.mirror_push.error ?? "see run402 repos fsck --mirror"}`);
       if (copies?.byo_chain_copy?.outcome === "pushed") note(`byo: signed-chain copy written to your bucket (${copies.byo_chain_copy.summary?.objects_copied ?? 0} object(s))`);
       else if (copies?.byo_chain_copy?.outcome === "failed") note(`byo: signed-chain copy FAILED (the push is unaffected) — ${copies.byo_chain_copy.error ?? copies.byo_chain_copy.summary?.errors?.[0]?.error ?? "see run402 repos fsck"}`);
-      // gitvault-clone-scaling (P3): advisory only — informational, always
+      // vault-clone-scaling (P3): advisory only — informational, always
       // fires at 25 generations regardless of the SEPARATE auto-gc
       // threshold below (design D1's `auto_gc_generations`, default 32) —
       // the two are deliberately different numbers for different purposes.
@@ -1096,7 +1096,7 @@ async function main(argv, { onBackgroundWork } = {}) {
         note(`${published.checkpoint_staleness.generations_since_checkpoint} generations since the last checkpoint — cold clones re-verify each one; run402 repos gc compacts them`);
       }
       for (const spec of allowed) out(`ok ${spec.dst}`);
-      // gitvault-checkpoint-cadence: captured here (never in the catch
+      // vault-checkpoint-cadence: captured here (never in the catch
       // block below — auto-gc must never fire on a failed push) and acted
       // on AFTER this function's own `endBlock()`, so the auto-gc check
       // itself can never delay, alter, or reorder the push's own report.
@@ -1105,7 +1105,7 @@ async function main(argv, { onBackgroundWork } = {}) {
       // The transaction is atomic, so a failure failed every ref in it. Report
       // it against each one rather than letting some look like they landed.
       if (err?.code === "GIT_INVOCATION_REPO_UNRESOLVED") repoRefusalNote(err);
-      // Force-spelling truth (gitvault-force-spelling-and-pin-fold): render
+      // Force-spelling truth (vault-force-spelling-and-pin-fold): render
       // the SDK's own `git push --force` next_action beside git's per-ref
       // rejection — humans read stderr, agents read the structured error.
       const forceHint = Array.isArray(err?.body?.next_actions) ? err.body.next_actions.find((a) => a?.action === "git push --force") : null;
@@ -1114,7 +1114,7 @@ async function main(argv, { onBackgroundWork } = {}) {
       for (const spec of allowed) out(`error ${spec.dst} ${reason}`);
     }
     endBlock();
-    // gitvault-checkpoint-cadence design D1/D2: strictly AFTER the push's
+    // vault-checkpoint-cadence design D1/D2: strictly AFTER the push's
     // own report — `null` (a failed push, a refused-only batch, dry-run)
     // is a silent no-op. `maybeRunAutoGc` itself never throws.
     if (autoGcCandidate) await maybeRunAutoGc(autoGcCandidate);
@@ -1221,7 +1221,7 @@ async function main(argv, { onBackgroundWork } = {}) {
 }
 
 /**
- * Run one remote-helper session to completion (gitvault-persistent-helper
+ * Run one remote-helper session to completion (vault-persistent-helper
  * D1). `argv` is git's argv slice (`[remote, address]`); `stdin` is the
  * session's input stream (defaults to the real process stdin for the
  * in-process host). Per-session module state is reset here so a daemon
@@ -1229,8 +1229,8 @@ async function main(argv, { onBackgroundWork } = {}) {
  * the next (D2). Never throws — the error path is the same
  * note-and-exit-1 the standalone binary always had.
  *
- * `onBackgroundWork` (gitvault-checkpoint-cadence design D2): when supplied
- * (the DAEMON host only — see `gitvault-daemon.mjs`), a successful push's
+ * `onBackgroundWork` (vault-checkpoint-cadence design D2): when supplied
+ * (the DAEMON host only — see `vault-daemon.mjs`), a successful push's
  * auto-gc cycle is handed to it as an ALREADY-STARTED promise instead of
  * being awaited inline, so this call resolves (and the client-visible
  * session ends) at push speed. The caller is responsible for keeping