run402 4.63.1 → 4.64.0

package/gitvault-surface.json

@@ -1,5 +1,5 @@
 {
-  "surface_version": "4.63.1",
+  "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;
 
@@ -524,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 };
   };
 
   /**
@@ -569,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.
@@ -613,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
@@ -634,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
@@ -667,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.
@@ -700,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)`);

package/lib/repos.mjs

@@ -32,7 +32,13 @@ import { resolveOrgId, resolveOwningOrgId } from "./org-context.mjs";
 import { resolveGitvaultTarget } from "./gitvault-target.mjs";
 import { nextAction, claimOrgSlugAction, claimRepoNameAction } from "./next-actions.mjs";
 import { printKeystoreLocation } from "./gitvault.mjs";
-import { gitvaultRemoteUrlForRepo } from "#sdk";
+import {
+  GITVAULT_BYO_HEADLINE_STATEMENT,
+  GITVAULT_BYO_NO_PAYLOAD_COPY_STATEMENT,
+  GITVAULT_BYO_UNMIRRORED_REMEDY_STATEMENT,
+  GITVAULT_MIRROR_SETUP_HINT,
+  gitvaultRemoteUrlForRepo,
+} from "#sdk";
 import { sdkStats, printVerboseStats, isVerbose } from "./stats.mjs";
 import {
   normalizeArgv,
@@ -55,6 +61,7 @@ Usage:
 
 Common:
   run402 repos create [name]  [--org <org_id>] [--dir <path>] [--tier <tier>] [--project <id>]
+                              [--byo <s3://bucket/prefix>] [--profile <name> | --ambient] [--region <r>] [--endpoint <url>]
   run402 repos view           [--project <id>] [--repo <repo_id>] [--human]
   run402 repos list           [--org <org_id>] [--human]
 
@@ -99,7 +106,15 @@ Subcommands:
            nothing usable can be derived, this is a structured error naming
            exactly one next_action, never a guess. The response's next_action
            is the exact \`git push\` to run. Nothing is deployed, ever, unless
-           you separately choose to.
+           you separately choose to. \`--byo <s3://bucket/prefix>\` allocates a
+           BYO (bring-your-own-bucket) vault: source ciphertext is written
+           ONLY to your own bucket, never run402's — run402 holds the small
+           signed chain only. The destination is PROBED before anything is
+           allocated (create-only writes honored, versioning disabled, write
+           permitted) and refuses closed on any failed property. Fewer
+           copies than a managed vault by construction (the platform holds
+           no payload copy at all); \`run402 repos mirror <destination>\`
+           still works unchanged as your second customer-held location.
   view     Side-effect-free: what this machine and the control plane each
            believe about the repo — allocation, policy, whether this keystore
            can sign, the authenticated and materialized pins, the mirror
@@ -206,6 +221,14 @@ Subcommands:
            normal writing mode, so a budget-exceeded run resumes). \`--mirror\`
            additionally runs the keyless mirror integrity probe — it proves
            the mirror's VALIDITY, never its FRESHNESS, and says so.
+           For a BYO vault (\`repos create --byo\`), fsck ALSO adjudicates
+           the customer's own bucket against run402's signed chain —
+           automatic, no flag needed. No local BYO credentials on this
+           machine reports an explicit NOT CHECKED line, never a failure;
+           a confirmed absence FAILS fsck with GITVAULT_BYO_OBJECT_MISSING
+           naming exactly what's missing. Runs under \`--no-write\` too (a
+           pure HEAD-check read). See the result's \`byo_presence\` block
+           (also on \`--human\`); absent entirely for a managed vault.
            In write mode (not \`--no-write\`), when this keystore holds a
            local encryption identity, fsck ALSO submits its own
            chain-verified/decryptable generations as a proof-of-open receipt
@@ -557,6 +580,13 @@ async function formatRepoHuman(s, mirror) {
   const objectCount = storage?.objects ? Object.values(storage.objects).reduce((sum, n) => sum + Number(n), 0) : null;
   lines.push(storage ? `Storage: ${storage.source_bytes} byte(s)${objectCount != null ? ` across ${objectCount} object(s)` : ""}` : "Storage: unknown");
 
+  // gitvault-byo-primary-bucket task 3.5 — unconditional, independent of
+  // mirror status (D7).
+  if (s.vault.storage_profile === "byo") {
+    lines.push(`Storage profile: byo (${s.vault.byo_destination ?? "(unknown)"}) — ${GITVAULT_BYO_HEADLINE_STATEMENT}`);
+    lines.push(GITVAULT_BYO_NO_PAYLOAD_COPY_STATEMENT);
+  }
+
   const decryptPart = !s.keystore.holds_repo_key
     ? "CANNOT decrypt (no key in this machine's keystore)"
     : s.keystore.can_sign
@@ -564,7 +594,11 @@ async function formatRepoHuman(s, mirror) {
       : "can decrypt (read-only — no signing key)";
   lines.push(`This machine: ${decryptPart}. Policy: ${s.gitvault_policy ?? "(none)"}`);
 
-  if (mirror?.configured) {
+  // gitvault-mirror-default: the SDK-computed vault_unmirrored finding is
+  // echoed verbatim (never rephrased here) — informational, never blocking.
+  if (mirror?.finding) {
+    lines.push(`Mirror (${mirror.finding.kind}): ${mirror.finding.message} — ${mirror.finding.setup_command}`);
+  } else if (mirror?.configured) {
     const currency = mirror.is_current === true ? "current" : mirror.is_current === false ? "STALE" : "unknown";
     lines.push(`Mirror: ${mirror.destination} (${currency})`);
   }
@@ -665,7 +699,22 @@ async function inferRepoName(dir) {
 
 // ─── create ─────────────────────────────────────────────────────────────────
 
-const CREATE_VALUE_FLAGS = ["--org", "--dir", "--tier", "--idempotency-key", "--project"];
+const CREATE_VALUE_FLAGS = ["--org", "--dir", "--tier", "--idempotency-key", "--project", "--byo", "--profile", "--region", "--endpoint"];
+
+/** gitvault-byo-primary-bucket task 3.5 — `--byo <destination>` + the SAME credential/region/endpoint flags `repos mirror` already uses. `undefined` when `--byo` was not passed (byte-identical to today). */
+function resolveByoOption(a) {
+  const destinationUrl = flagValue(a, "--byo");
+  if (destinationUrl == null) return undefined;
+  const credential = resolveMirrorCredential(a);
+  const region = flagValue(a, "--region");
+  const endpoint = flagValue(a, "--endpoint");
+  return {
+    destination_url: destinationUrl,
+    ...(credential ? { credential } : {}),
+    ...(region != null ? { region } : {}),
+    ...(endpoint != null ? { endpoint } : {}),
+  };
+}
 
 async function printCreateResult({ sdk, projectId, vault, adopted, name, verboseArgv }) {
   let address = null;
@@ -689,7 +738,15 @@ 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 claimAction = address ? null : orgSlug ? claimRepoNameAction(projectId) : claimOrgSlugAction();
-  const nextActions = [pushAction, claimAction].filter(Boolean);
+  // 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
+  // the vault's own primary bucket already is one.
+  const isByo = vault.storage_profile === "byo";
+  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, mirrorAction, claimAction].filter(Boolean);
 
   // Secret-bearing (recovery_receipt): built fresh every call, printed once,
   // and never spilled into any cache path — see spillIfLarge's own doc
@@ -703,6 +760,8 @@ async function printCreateResult({ sdk, projectId, vault, adopted, name, verbose
     genesis_sha256: vault.genesis_sha256,
     recovery_receipt: vault.recovery_receipt,
     terminal_loss_statement: vault.terminal_loss_statement,
+    storage_profile: vault.storage_profile,
+    byo_destination: vault.byo_destination,
     deployed: false,
     next_actions: nextActions,
   };
@@ -716,6 +775,13 @@ async function printCreateResult({ sdk, projectId, vault, adopted, name, verbose
   else console.error(`no address claimed — run 'run402 repos rename <name> --project ${projectId}' to claim one`);
   if (vault.remote) console.error(`remote '${vault.remote.name}' -> ${vault.remote.url} (${vault.remote.reason})`);
   if (pushAction) console.error(`next: ${pushAction.command}`);
+  if (isByo) {
+    console.error(`storage: byo (${vault.byo_destination}) — ${GITVAULT_BYO_HEADLINE_STATEMENT}`);
+    console.error(GITVAULT_BYO_NO_PAYLOAD_COPY_STATEMENT);
+    console.error(GITVAULT_BYO_UNMIRRORED_REMEDY_STATEMENT);
+  } else {
+    console.error(GITVAULT_MIRROR_SETUP_HINT);
+  }
   console.error("");
   console.error(vault.terminal_loss_statement);
   await printKeystoreLocation();
@@ -736,7 +802,8 @@ async function createAdopt(projectId, dir, a) {
     });
   }
   try {
-    const vault = await sdk.gitvault.init({ org_id: orgId, project_id: projectId, repo_dir: dir });
+    const byo = resolveByoOption(a);
+    const vault = await sdk.gitvault.init({ org_id: orgId, project_id: projectId, repo_dir: dir, ...(byo ? { byo } : {}) });
     await printCreateResult({ sdk, projectId, vault, adopted: true, name: null, verboseArgv: a });
   } catch (err) {
     reportSdkError(err);
@@ -775,7 +842,8 @@ async function createProvision(name, dir, a) {
   }
 
   try {
-    const vault = await sdk.gitvault.init({ org_id: effectiveOrgId, project_id: provisioned.project_id, repo_dir: dir });
+    const byo = resolveByoOption(a);
+    const vault = await sdk.gitvault.init({ org_id: effectiveOrgId, project_id: provisioned.project_id, repo_dir: dir, ...(byo ? { byo } : {}) });
     await printCreateResult({ sdk, projectId: provisioned.project_id, vault, adopted: false, name, verboseArgv: a });
   } catch (err) {
     reportSdkError(err);
@@ -784,7 +852,7 @@ async function createProvision(name, dir, a) {
 
 async function create(args) {
   const a = normalizeArgv(args);
-  assertKnownFlags(a, [...CREATE_VALUE_FLAGS, "--help", "-h", "-v", "--verbose"], CREATE_VALUE_FLAGS);
+  assertKnownFlags(a, [...CREATE_VALUE_FLAGS, "--ambient", "--help", "-h", "-v", "--verbose"], CREATE_VALUE_FLAGS);
   const positionals = requirePositionalCount(a, CREATE_VALUE_FLAGS, {
     min: 0, max: 1, command: "run402 repos create [name]", missing: "",
   });
@@ -936,10 +1004,11 @@ async function view(args) {
     // Design D3: `view` NEVER passes `refs: true` — it is side-effect-free
     // by construction, not by convention. Materialization belongs to `fsck`.
     const s = await sdk.gitvault.status(target);
+    const isByo = s.vault?.storage_profile === "byo";
     let mirror = null;
     if (s.repo_id) {
       try {
-        mirror = await sdk.gitvault.mirrorStatus({ ...target, repo_id: s.repo_id });
+        mirror = await sdk.gitvault.mirrorStatus({ ...target, repo_id: s.repo_id, is_byo: isByo });
       } catch {
         // best-effort — a mirror read failure never fails `view`
       }
@@ -969,10 +1038,22 @@ async function view(args) {
     if (s.pinned) {
       console.error(`pinned: repo_id ${s.pinned.repo_id}` + (s.pinned.resolved_from ? ` (resolved from run402::${s.pinned.resolved_from.org_slug}/${s.pinned.resolved_from.repo_name})` : ""));
     }
+    // gitvault-byo-primary-bucket task 3.5: the no-payload-copy disclosure —
+    // unconditional and independent of mirror status (D7), never folded
+    // into the mirror finding below (that's a SEPARATE fact: "is there a
+    // second copy", not "is there any platform-held copy at all").
+    if (isByo) {
+      console.error(`storage: byo (${s.vault?.byo_destination ?? "(unknown)"}) — ${GITVAULT_BYO_HEADLINE_STATEMENT}`);
+      console.error(GITVAULT_BYO_NO_PAYLOAD_COPY_STATEMENT);
+    }
     if (mirror?.configured) {
       const currency = mirror.is_current === true ? "current" : mirror.is_current === false ? `STALE — ${mirror.closing_command}` : "unknown (mirror unreachable or vault unread)";
       console.error(`mirror ${mirror.destination}: mirrored generation ${mirror.mirrored_generation ?? "(none)"}, vault newest ${mirror.newest_generation ?? "(none)"} — ${currency}`);
     }
+    // gitvault-mirror-default: echoed verbatim from the SDK, exactly like the
+    // vault warnings below — informational, never blocking, and it clears on
+    // the first successful mirror write or sync.
+    if (mirror?.finding) console.error(`finding (${mirror.finding.kind}): ${mirror.finding.message} — ${mirror.finding.setup_command}`);
     for (const w of s.warnings) console.error(`warning (${w.kind}): ${w.message}`);
     for (const n of combinedNextActions) console.error(`next: ${n.why ?? n.action ?? n.type}${n.command ? ` — ${n.command}` : ""}`);
     printVerboseStats(a, sdk);
@@ -1292,6 +1373,9 @@ async function snapshot(args) {
       console.error("");
       console.error(`repo allocated (genesis ${created.genesis_sha256}) — one-shot recovery receipt, keep many copies:`);
       console.error(JSON.stringify(created.recovery_receipt));
+      // gitvault-mirror-default: lazy allocation is a birth too — the mirror
+      // one-liner rides beside the recovery receipt here as well.
+      console.error(GITVAULT_MIRROR_SETUP_HINT);
       await printKeystoreLocation();
       console.error("");
     },
@@ -1597,6 +1681,25 @@ function formatOpenProofLine(openProof) {
   return `proof-of-open: not submitted — ${openProof.error.code}: ${openProof.error.message}`;
 }
 
+/**
+ * gitvault-byo-primary-bucket task 3.3: one line reporting `fsck`'s BYO
+ * presence check — always present for a BYO vault (never blank), absent for
+ * a managed one (`result.byo_presence` is `undefined` there, so this
+ * returns `null` and no line prints — zero output change for managed
+ * vaults). A MISSING-object verdict never reaches here: it throws
+ * `GITVAULT_BYO_OBJECT_MISSING` before `fsck` returns a result at all, so
+ * this line only ever reports the two non-failure outcomes — checked-clean
+ * or explicitly not-checked. Shared by `--human` and the default JSON-mode
+ * stderr summary, same convention as `formatOpenProofLine` above.
+ */
+function formatByoPresenceLine(byoPresence) {
+  if (!byoPresence) return null;
+  if (!byoPresence.verified) {
+    return `BYO storage: NOT CHECKED — ${byoPresence.not_checked_reason}`;
+  }
+  return `BYO storage: verified ${byoPresence.checked_count} object(s) present at ${byoPresence.destination}.`;
+}
+
 /** `repos fsck --human`: the same verdict the stderr lines already carry, condensed into one block. */
 function formatFsckHuman(result, mirrorRequested) {
   const lines = [`Repo: ${result.repo_id}`];
@@ -1633,6 +1736,8 @@ function formatFsckHuman(result, mirrorRequested) {
   }
   const openProofLine = formatOpenProofLine(result.open_proof);
   if (openProofLine) lines.push(openProofLine);
+  const byoPresenceLine = formatByoPresenceLine(result.byo_presence);
+  if (byoPresenceLine) lines.push(byoPresenceLine);
   return lines.join("\n");
 }
 
@@ -1690,6 +1795,14 @@ async function fsck(args) {
     // status as a mirror probe's failure would be).
     const openProofLine = formatOpenProofLine(result.open_proof);
     if (openProofLine) console.error(openProofLine);
+    // gitvault-byo-primary-bucket task 3.3: absent (formats to `null`) for a
+    // managed vault — `result.byo_presence` is `undefined` there, so this
+    // line never prints and JSON-mode output for a managed vault is
+    // unchanged. A missing-object verdict never reaches this line at all —
+    // it throws `GITVAULT_BYO_OBJECT_MISSING` before `fsck` returns, caught
+    // by this function's own `reportSdkError(err)` below.
+    const byoPresenceLine = formatByoPresenceLine(result.byo_presence);
+    if (byoPresenceLine) console.error(byoPresenceLine);
     if (mirrorRequested && result.mirror) {
       console.error(`mirror: recoverable generation ${result.mirror.recovered_generation}${result.mirror.chain_break ? ` (chain break at ${result.mirror.chain_break.generation}: ${result.mirror.chain_break.reason})` : ""}.`);
       if (result.mirror.data_loss_detected) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.63.1",
+  "version": "4.64.0",
   "description": "CLI for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.",
   "type": "module",
   "bin": {