run402 4.63.1 → 4.65.0

package/gitvault-surface.json

@@ -1,5 +1,5 @@
 {
-  "surface_version": "4.63.1",
+  "surface_version": "4.65.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/gitvault-daemon.mjs

@@ -53,9 +53,16 @@ export async function runDaemon() {
   // Load the heavy module ONCE — this is the entire point of residency.
   // Its top-level await pulls the SDK graph; the prewarm dials the API
   // origin so the first forwarded session rides a warm h2 connection.
-  const { prewarmGitvaultConnection, kickGitvaultConnection } = await import("../sdk/dist/node/gitvault-prewarm.js");
+  const { prewarmGitvaultConnection, kickGitvaultConnection, predialGitvaultObjectStore } = await import("../sdk/dist/node/gitvault-prewarm.js");
   prewarmGitvaultConnection();
   const { runHelperSession } = await import("./remote-helper-session.mjs");
+  // gitvault-object-host-predial task 2.2 — narrow, session-scoped imports
+  // (not the whole `#sdk/node` barrel) for the OFFLINE repo resolution the
+  // session-accept predial needs: a local git subprocess (`rev-parse
+  // --absolute-git-dir`) plus a local git-config read, never a network
+  // call (design D6).
+  const { resolveGitInvocationRepo } = await import("../sdk/dist/node/gitvault-snapshot.js");
+  const { readPinnedGitvaultRepo } = await import("../sdk/dist/node/gitvault-address.js");
 
   const socketPath = daemonSocketPath();
   if (process.platform !== "win32") {
@@ -184,6 +191,28 @@ export async function runDaemon() {
           // (never throws, never awaited, never delays a session).
           const acceptedAt = Date.now();
           kickGitvaultConnection();
+          // gitvault-object-host-predial task 2.2 — the addressed repo's
+          // persisted object-store origin(s), predialed on the SAME
+          // pre-connect timing as the API-origin kick above: resolved from
+          // THIS session's OWN `msg.cwd`/`msg.env` (not `process.cwd()`/
+          // `process.env`, which still name the daemon's PRIOR session
+          // until the swap below runs) via the same offline, no-network
+          // mechanism the session module itself uses once it takes over —
+          // `resolveGitInvocationRepo` (a local `git rev-parse
+          // --absolute-git-dir`) then `readPinnedGitvaultRepo` (a local
+          // `git config --local` read). Any resolution failure (no
+          // `GIT_DIR`, not a repository, no pin yet) predials nothing —
+          // never a network read to learn where to predial (design D6),
+          // and never allowed to delay or fail this session's accept.
+          void (async () => {
+            try {
+              const { repo_dir } = await resolveGitInvocationRepo(msg.env ?? {}, msg.cwd);
+              const pinned = await readPinnedGitvaultRepo(repo_dir);
+              if (pinned) predialGitvaultObjectStore(pinned.repo_id);
+            } catch {
+              /* best-effort: must never surface from session accept */
+            }
+          })();
           busy = true;
           sessionsServed += 1;
           const stdin = new PassThrough();

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,8 +144,8 @@ 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 { GITVAULT_R402_REF_NAMESPACE, hardenedGit, resolveGitInvocationRepo, readPinnedGitvaultRepo, pinGitvaultRepo, readGitvaultRestoreMarker, readGitvaultAutoGcThreshold } = await nodeModP;
+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;
 
 /**
@@ -461,7 +478,27 @@ async function main(argv, { onBackgroundWork } = {}) {
    */
   let resolvedRepo = null;
   async function requireRepo() {
-    if (!resolvedRepo) resolvedRepo = await resolveGitInvocationRepo(process.env, process.cwd());
+    if (!resolvedRepo) {
+      resolvedRepo = await resolveGitInvocationRepo(process.env, process.cwd());
+      // gitvault-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
+      // design D6) — fire-and-forget dial the addressed repo's persisted
+      // object-store origin(s), if the local keystore has learned any, so
+      // it overlaps the rest of this session's local work exactly like the
+      // API-origin prewarm that already raced module load above. A repo
+      // with no local pin (never opened here before) or nothing persisted
+      // 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);
+        } catch {
+          /* best-effort: must never surface from repository resolution */
+        }
+      })();
+    }
     return resolvedRepo.repo_dir;
   }
 
@@ -524,7 +561,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 };
   };
 
   /**
@@ -569,7 +606,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.
@@ -612,14 +652,46 @@ async function main(argv, { onBackgroundWork } = {}) {
         fetchMarker = null;
       }
     }
-    const materializeOpts = fetchMarker ? { deltaSince: fetchMarker.generation } : {};
-    let vault;
-    let state;
+    // gitvault-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
+    // `fetch` below via `sharedListSession` (never a second round trip). A
+    // repo-free `list` (bare `git ls-remote`) has no target to restore into
+    // at all, so neither `since` nor `restore` is sent — same gate as today.
+    const materializeOpts = fetchMarker ? { deltaSince: fetchMarker.generation } : repoDir ? { restore: true } : {};
+    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
@@ -634,30 +706,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
@@ -667,7 +763,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.
@@ -700,15 +795,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)`);