run402 4.63.0 → 4.64.0

package/gitvault-surface.json

@@ -1,5 +1,5 @@
 {
-  "surface_version": "4.63.0",
+  "surface_version": "4.64.0",
   "verbs": [
     "repos create",
     "repos list",
@@ -68,6 +68,7 @@
     "revocation_live": true,
     "human_envelope_add_live": true,
     "mirror_live": true,
+    "byo_live": true,
     "recover_live": true,
     "allocation": "create_immediate",
     "snapshot_dirty_default": "refuse"

package/lib/doctor.mjs

@@ -12,6 +12,7 @@
  */
 
 import { existsSync, statSync } from "node:fs";
+import { GITVAULT_BYO_NO_PAYLOAD_COPY_STATEMENT } from "#sdk";
 import { configDir, readAllowance, loadKeyStore } from "./config.mjs";
 import { resolveGitvaultTarget } from "./gitvault-target.mjs";
 import { getSdk } from "./sdk.mjs";
@@ -665,6 +666,10 @@ export async function run(sub, args = []) {
           project_id: gv.project_id ?? projectId,
           repo_id: gv.repo_id,
           vault: gv.vault === null ? null : "allocated",
+          // gitvault-byo-primary-bucket task 3.5 — absent-or-"managed" is
+          // byte-identical to before this fold for every non-BYO vault.
+          storage_profile: gv.vault?.storage_profile ?? null,
+          byo_destination: gv.vault?.byo_destination ?? null,
           gitvault_policy: gv.gitvault_policy,
           keystore_root: gv.keystore.root,
           can_sign: gv.keystore.can_sign,
@@ -704,30 +709,34 @@ export async function run(sub, args = []) {
         // doctor-persistent `grandfathered` advisory it owns.
         for (const w of gv.warnings ?? []) gaps.push(`${w.kind}: ${w.message}`);
 
-        // gitvault-mirror-and-recover task 4.3: mirror currency, reported
-        // ALONGSIDE (never in place of) the deploy-related gaps above, and
-        // never blocking `run402 deploy`'s own gate — the vault lane's
-        // outcome is unaffected regardless of mirror state (design D6).
-        // `mirror_currency` mirrors `mirror status`'s own tri-state:
-        // `current` / `stale` / `unknown` (mirror unreachable or vault
-        // unread) only STALE is actionable enough to become a warning; NO
-        // mirror configured is a purely informational, ungated advisory —
-        // most vaults have never opted in, and that is a normal shape.
+        // gitvault-mirror-and-recover task 4.3 + gitvault-mirror-default:
+        // mirror currency, reported ALONGSIDE (never in place of) the
+        // deploy-related gaps above, and never blocking `run402 deploy`'s
+        // own gate — the vault lane's outcome is unaffected regardless of
+        // mirror state (design D6). `mirror_currency` mirrors `mirror
+        // status`'s own tri-state: `current` / `stale` / `unknown` (mirror
+        // unreachable or vault unread). Only STALE is actionable enough to
+        // become a warning gap; a vault with no successful mirror copy yet
+        // carries the SDK-computed `vault_unmirrored` finding — named and
+        // standing (gitvault-mirror-default supersedes the old anonymous
+        // `advisory` string), echoed verbatim, and deliberately NOT pushed
+        // into `gaps`: informational, never blocking, computed client-side
+        // only, cleared by the first successful mirror write or sync.
         if (gv.vault !== null && value.repo_id) {
           try {
-            const mirrorStatus = await getSdk().gitvault.mirrorStatus({ repo_id: value.repo_id });
+            const mirrorStatus = await getSdk().gitvault.mirrorStatus({ repo_id: value.repo_id, is_byo: value.storage_profile === "byo" });
             value.gitvault_mirror = {
               configured: mirrorStatus.configured,
               destination: mirrorStatus.destination,
               mirrored_generation: mirrorStatus.mirrored_generation,
               newest_generation: mirrorStatus.newest_generation,
               is_current: mirrorStatus.is_current,
+              last_success_at: mirrorStatus.last_success_at,
+              finding: mirrorStatus.finding,
               validity_not_freshness: mirrorStatus.validity_not_freshness,
               keystore_still_required: mirrorStatus.keystore_still_required,
             };
-            if (!mirrorStatus.configured) {
-              value.gitvault_mirror.advisory = "no ciphertext mirror is configured for this vault — the exit ramp is opt-in; 'run402 repos mirror <destination>' to configure one.";
-            } else if (mirrorStatus.is_current === false) {
+            if (mirrorStatus.is_current === false) {
               gaps.push(`the ciphertext mirror at ${mirrorStatus.destination} is STALE (mirrored generation ${mirrorStatus.mirrored_generation ?? "(none)"}, vault newest ${mirrorStatus.newest_generation ?? "(none)"}) — ${mirrorStatus.closing_command}`);
             }
           } catch {
@@ -736,15 +745,19 @@ export async function run(sub, args = []) {
           }
         }
 
+        // gitvault-byo-primary-bucket task 3.5 — unconditional, independent
+        // of mirror status (D7); imported from the canonical constants, never
+        // paraphrased.
+        const byoDisclosure = value.storage_profile === "byo" ? ` Storage: byo (${value.byo_destination ?? "(unknown)"}) — ${GITVAULT_BYO_NO_PAYLOAD_COPY_STATEMENT}` : "";
         checks.push({
           name: "gitvault",
           status: gaps.length > 0 ? "warning" : "ok",
           value: gaps.length > 0 ? { ...value, gaps } : value,
-          hint: gv.vault === null
+          hint: (gv.vault === null
             ? `No vault for this project (that is a normal shape). Allocate one with 'run402 repos create --project <id>'. Keystore: ${gv.keystore.root}`
             : gv.durability_statement
               ? `Back up ${gv.keystore.root} anyway — ${gv.durability_statement} (covering_recipients: ${gv.covering_recipients})`
-              : `Back up ${gv.keystore.root} — whole-machine or whole-keystore loss is terminal for vault history.`,
+              : `Back up ${gv.keystore.root} — whole-machine or whole-keystore loss is terminal for vault history.`) + byoDisclosure,
         });
       } catch (err) {
         // A gateway without gitvault, an unreachable API, or a project this

package/lib/gitvault-capabilities.mjs

@@ -28,6 +28,14 @@ export const GITVAULT_CAPABILITIES = {
   // `repos mirror` reads/writes a mirror destination beside the keystore and
   // moves real bytes into a customer-owned bucket.
   mirror_live: true,
+  // `repos create --byo <s3://bucket/prefix>` allocates a
+  // `storage_profile: "byo"` vault whose payload ciphertext is written by
+  // the client straight to the customer's own bucket (create-only probe
+  // fail-closed before allocation; chain-copy dual-write; attested finalize
+  // with `storage_verification: "client_attested"`; degraded reads from the
+  // destination; fsck absence check) — shipped end to end in the same
+  // change that flips this flag (gitvault-byo-primary-bucket, Phase 3).
+  byo_live: true,
   // `repos recover` materializes a git repository from a mirror source,
   // offline, with no server call.
   recover_live: true,

package/lib/remote-helper-session.mjs

@@ -112,6 +112,23 @@
  *     is refused rather than silently pointed at the current directory. Only
  *     `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
+ * `fetch` each wrap their own live gateway read in
+ * `getSdk().gitvault.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
+ * 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
+ * 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
+ * gateway.
  */
 
 import { createInterface } from "node:readline";
@@ -127,7 +144,7 @@ const nodeModP = import("#sdk/node");
 const configModP = import("./config.mjs");
 const { getSdk } = await sdkModP;
 const { resolveWalletCore, enforceWalletExistsCore, WalletSelectionError } = await walletModP;
-const { gitvaultRemoteAddressForm, gitvaultSlugReleasedInfo, parseGitvaultRemoteUrl } = await isoModP;
+const { gitvaultRemoteAddressForm, gitvaultSlugReleasedInfo, parseGitvaultRemoteUrl, gitvaultDegradedReadNote } = await isoModP;
 const { GITVAULT_R402_REF_NAMESPACE, hardenedGit, resolveGitInvocationRepo, readPinnedGitvaultRepo, pinGitvaultRepo, readGitvaultRestoreMarker, readGitvaultAutoGcThreshold } = await nodeModP;
 const { allowanceFile, projectCredentialsFile, profileStateFile } = await configModP;
 
@@ -408,6 +425,23 @@ export function shouldRunAutoGc(threshold, generationsSinceCheckpoint) {
   return Number.isFinite(threshold) && threshold > 0 && Number.isFinite(generationsSinceCheckpoint) && generationsSinceCheckpoint >= threshold;
 }
 
+/**
+ * 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
+ * `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` — made every real post-push auto-gc cycle fail closed with
+ * `GITVAULT_REPO_DIR_REQUIRED`, silently degrading to the advisory on
+ * EVERY push, live in production shape, until a push-latency guard bench
+ * finally drove the real trigger path (found 2026-08-31; `repos gc`'s CLI
+ * wrapper passes repo_dir explicitly and never hit this).
+ */
+export function buildAutoGcCompactionTarget(target, repoDir) {
+  return { ...target, repo_dir: 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-
@@ -507,7 +541,7 @@ async function main(argv, { onBackgroundWork } = {}) {
    */
   const openVault = async (repoDir) => {
     const result = await getCachedSdk().gitvault.resolveOrCreateAddress({ address, allow_create: false, ...(repoDir ? { repo_dir: repoDir } : {}) });
-    return { vault: result.handle.vault, resolution: result.resolution };
+    return { vault: result.handle.vault, keystore: result.handle.keystore, repo_id: result.handle.repo_id, resolution: result.resolution };
   };
 
   /**
@@ -552,7 +586,10 @@ async function main(argv, { onBackgroundWork } = {}) {
       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 } = await import("#sdk/node");
+        const { getGitvaultKeystoreRoot, GITVAULT_MIRROR_SETUP_HINT } = await import("#sdk/node");
+        // gitvault-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`);
       } catch {
         // Never let a diagnostic line fail a push that already allocated successfully.
@@ -596,13 +633,38 @@ async function main(argv, { onBackgroundWork } = {}) {
       }
     }
     const materializeOpts = fetchMarker ? { deltaSince: fetchMarker.generation } : {};
-    let vault;
-    let state;
+    let opened;
     try {
-      const opened = await openVault(repoDir ?? undefined);
-      vault = opened.vault;
+      opened = await openVault(repoDir ?? undefined);
+    } catch (err) {
+      // An unallocated vault is not an error here: `list` is the read half of
+      // the protocol dance and must never create anything on its own (D2
+      // scopes lazy creation to `push`). Reporting it as an EMPTY ref set is
+      // exactly what a fresh repository looks like to git, and `push` still
+      // runs `list` first either way — this is what lets a first push land in
+      // one command instead of `list` failing the whole exchange before
+      // `push` ever gets a turn. Nothing to share with `push` either
+      // (design D7): an unallocated vault has no base to reuse.
+      if (isVaultNotFound(err)) {
+        endBlock();
+        return;
+      }
+      throw err;
+    }
+    let vault = opened.vault;
+
+    // gitvault-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
+    // vault, it falls back to `r402s-recover`'s engine against it instead of
+    // failing the whole `list`/`clone`. `repoDir` is required for the
+    // fallback to materialize into (`out_dir`); a repo-free `list` (bare
+    // `git ls-remote`) simply has none, so the fallback never runs and the
+    // original error surfaces exactly as it always did.
+    const attemptLive = async () => {
       try {
-        state = await vault.materialize(materializeOpts);
+        return await vault.materialize(materializeOpts);
       } catch (err) {
         // An OFFLINE (id-carrying pin) resolution discovers a stale pin on
         // its FIRST repo-scoped read (client-surface spec, id-pinning
@@ -617,30 +679,54 @@ async function main(argv, { onBackgroundWork } = {}) {
         if (!recovered) throw err;
         note(`pinned vault ${opened.resolution.repo_id} no longer resolves — re-resolved to ${recovered.resolution.repo_id}, retrying`);
         vault = recovered.handle.vault;
-        state = await vault.materialize(materializeOpts);
+        opened = { ...opened, vault: recovered.handle.vault, keystore: recovered.handle.keystore, repo_id: recovered.handle.repo_id, resolution: recovered.resolution };
+        return await vault.materialize(materializeOpts);
       }
+    };
+
+    let outcome;
+    try {
+      outcome = await getCachedSdk().gitvault.withDegradedRead({ attemptLive, keystore: opened.keystore, repo_id: opened.repo_id, out_dir: repoDir });
     } catch (err) {
-      // An unallocated vault is not an error here: `list` is the read half of
-      // the protocol dance and must never create anything on its own (D2
-      // scopes lazy creation to `push`). Reporting it as an EMPTY ref set is
-      // exactly what a fresh repository looks like to git, and `push` still
-      // runs `list` first either way — this is what lets a first push land in
-      // one command instead of `list` failing the whole exchange before
-      // `push` ever gets a turn. Nothing to share with `push` either
-      // (design D7): an unallocated vault has no base to reuse.
+      // Same "an unallocated vault is not an error" reasoning as above — a
+      // 404 discovered only once materialize actually runs takes this same
+      // empty-ref-set path (network-class errors never reach here at all:
+      // `withDegradedRead` only rethrows them after exhausting its own
+      // fallback, and a 404 is never network-class).
       if (isVaultNotFound(err)) {
         endBlock();
         return;
       }
       throw err;
     }
-    // gitvault-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
-    // push admits in this same session (see `runPush`'s reset below).
-    if (repoDir) sharedListSession = { repoDir, walletName: resolvedWallet?.name ?? null, vault, base: state, fetchMarker, fetchState: state };
-    const refs = state.refs ?? {};
+
+    let refs;
+    let head;
+    if (outcome.degraded) {
+      // 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));
+      refs = outcome.result.refs ?? {};
+      head = outcome.result.head_target;
+      // No live vault instance materialized this pass — nothing safe to
+      // share with a following `push` (design D7's own "unallocated vault"
+      // reasoning applies equally to a degraded one: writes are never
+      // rerouted, so `push` must resolve and materialize live on its own).
+    } else {
+      const state = outcome.live;
+      refs = state.refs ?? {};
+      head = state.head_target;
+      // gitvault-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
+      // push admits in this same session (see `runPush`'s reset below).
+      // `keystore`/`repo_id` ride along so `fetch`'s own degraded-read wrap
+      // can fall back without re-resolving.
+      if (repoDir) sharedListSession = { repoDir, walletName: resolvedWallet?.name ?? null, vault, keystore: opened.keystore, repo_id: opened.repo_id, base: state, fetchMarker, fetchState: state };
+    }
+
     for (const ref of Object.keys(refs).sort()) out(`${refs[ref]} ${ref}`);
     // A snapshot-only vault holds protocol refs but no branch heads, so a
     // plain `git clone` prints "cloned an empty repository" with no hint the
@@ -650,7 +736,6 @@ async function main(argv, { onBackgroundWork } = {}) {
       note(`this vault has no branch heads yet — its history lives on ${refNames.sort()[0]}`);
       note(`fetch it with: git fetch <remote> '+${refNames.sort()[0]}:${refNames.sort()[0]}' && git checkout -b restored ${refNames.sort()[0]}`);
     }
-    const head = state.head_target;
     // A symref is only advertised when its target is actually present:
     // pointing HEAD at a ref that does not exist is what an empty repository
     // looks like, and git reads the empty list correctly on its own.
@@ -683,15 +768,55 @@ async function main(argv, { onBackgroundWork } = {}) {
     // different repository/wallet, or a push that already admitted in this
     // 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):
+    // either path's actual chain/payload read is the "attemptLive" that
+    // `withDegradedRead` wraps — `gitvault.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
+    // path. On a NETWORK-CLASS failure (never 4xx) with a mirror configured
+    // for this vault, the fetch is served from it instead of failing the
+    // whole clone; the destination it materialized into is the SAME
+    // `repoDir` git already prepared, so `git fetch`/`clone` completes
+    // exactly as if the live path had run.
     const shared = sharedListSession && sharedListSession.repoDir === repoDir && sharedListSession.walletName === (resolvedWallet?.name ?? null) ? sharedListSession : null;
-    const restored = shared
-      ? await shared.vault.restoreObjectsInto(repoDir, { marker: shared.fetchMarker, state: shared.fetchState })
-      : await getCachedSdk().gitvault.restore({ ...target, repo_dir: repoDir, target_dir: repoDir });
+    let attemptLive;
+    let degradedKeystore;
+    let degradedRepoId;
+    if (shared) {
+      attemptLive = () => shared.vault.restoreObjectsInto(repoDir, { marker: shared.fetchMarker, state: shared.fetchState });
+      degradedKeystore = shared.keystore;
+      degradedRepoId = shared.repo_id;
+    } else {
+      const handle = await getCachedSdk().gitvault.open({ ...target, repo_dir: repoDir });
+      attemptLive = () => handle.vault.restoreObjectsInto(repoDir);
+      degradedKeystore = handle.keystore;
+      degradedRepoId = handle.repo_id;
+    }
+    const outcome = await getCachedSdk().gitvault.withDegradedRead({
+      attemptLive,
+      keystore: degradedKeystore,
+      repo_id: degradedRepoId,
+      out_dir: repoDir,
+    });
+    let restored;
+    if (outcome.degraded) {
+      // 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. 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));
+      restored = { generation: outcome.result.generation, retained_refs: outcome.result.retained_refs };
+    } else {
+      restored = { generation: outcome.live.generation, retained_refs: outcome.live.retained_refs };
+    }
     if (verbosity >= 1) note(`restored generation ${restored.generation}`);
     // clone-installs-retained-refs D3: a bookkeeping failure here degrades to
     // exactly today's (pre-change) behavior — one stderr note, fetch still
-    // completes. `restored.retained_refs` is never absent (the SDK always
-    // returns a result, never throws for this step).
+    // completes. `restored.retained_refs` is never absent (both the live and
+    // the degraded path always return a result, never throw for this step).
     if (restored.retained_refs?.warning) note(restored.retained_refs.warning);
     else if (verbosity >= 1 && (restored.retained_refs?.written.length > 0 || restored.retained_refs?.deleted.length > 0)) {
       note(`refs/r402/retain: +${restored.retained_refs.written.length} -${restored.retained_refs.deleted.length} (${restored.retained_refs.retained_count} retained tip(s) total)`);
@@ -741,10 +866,19 @@ async function main(argv, { onBackgroundWork } = {}) {
     }
     if (!shouldRunAutoGc(threshold, generationsSinceCheckpoint)) return;
 
+    // `compact()`/`prune()` never default repo_dir to process.cwd() —
+    // GitvaultVaultHandleOptions'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,
+    // silently degrading to the advisory on every push (found live,
+    // 2026-08-31, via a push-latency guard bench that finally drove the
+    // ACTUAL trigger path instead of a synthetic `repos gc` invocation).
+    const compactionTarget = buildAutoGcCompactionTarget(target, repoDir);
     const runCycle = async () => {
       const sdk = getCachedSdk();
-      const checkpoint = await sdk.gitvault.compact({ ...target });
-      const prune = await sdk.gitvault.prune(target); // 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.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
       return { checkpoint, prune };
     };