run402 4.53.0 → 4.54.1

package/cli.mjs

@@ -85,6 +85,7 @@ PLATFORM — everything else, and the things still finding a home
   cloud       Cloud portability archive export (archives create/download/status)
   archives    Inspect and verify portable project archives locally
   gitvault    RETIRED — moved to repos (repo-surface-consolidation); every spelling answers COMMAND_MOVED/COMMAND_REMOVED
+  source-access RETIRED — moved into repos (recovery-bundle + access); every spelling answers COMMAND_MOVED
   buzz        Buzz human/community/agent control-plane workflows
   apps        Browse and manage the app marketplace
   ai          AI translation and moderation tools
@@ -438,6 +439,11 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "source-access": {
+    const { run } = await import("./lib/source-access.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "auth": {
     const { run } = await import("./lib/auth.mjs");
     await run(sub, rest);

package/gitvault-surface.json

@@ -1,5 +1,5 @@
 {
-  "surface_version": "4.53.0",
+  "surface_version": "4.54.1",
   "verbs": [
     "repos create",
     "repos list",
@@ -15,7 +15,8 @@
     "repos access repair",
     "repos access revoke-key",
     "repos access declare-exposure",
-    "repos recover"
+    "repos recover",
+    "repos recovery-bundle"
   ],
   "retired_spellings": [
     {

package/lib/command-manifest.mjs

@@ -261,7 +261,7 @@ export const COMMAND_MANIFEST = [
   // COMMAND_REMOVED) redirect that dispatches nothing — see
   // RESERVED_SUBCOMMANDS below, and "gitvault" in SKIPPED_FAMILIES.
 
-  // ── repos (the consolidated 12-verb family) ─
+  // ── repos (the consolidated 13-verb family) ─
   // Every verb needs a real principal keystore and, for most, an allocated
   // repo and a local git working tree, so the gate runs structural checks
   // only — an in-process behavioral run would either no-op against the
@@ -288,6 +288,9 @@ export const COMMAND_MANIFEST = [
   { path: ["repos", "access", "revoke-key"], positionals: [p("principal_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["prin_00000000000000000000000000000000"], runStyle: "sub", skipBehavioral: "owner+step-up-gated: declares a recipient's key revoked (org-scoped watermark) and drives a real epoch rotation off it" },
   { path: ["repos", "access", "declare-exposure"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "owner+step-up-gated: declares this vault's epoch secret exposed, forcing every subsequent ordinary push to refuse until a rotation lands" },
   { path: ["repos", "recover"], positionals: [p("source")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["s3://example-mirror-bucket", "--out", "__SCRATCH_DIR__/recover-out"], runStyle: "sub", skipBehavioral: "materializes a git repository from a mirror source, offline, with no server call" },
+  // Principal-scoped (one bundle covers every vault you can read), so no
+  // --project — deliberately unlike its eleven vault-scoped siblings.
+  { path: ["repos", "recovery-bundle"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--out", "-"], runStyle: "sub", skipBehavioral: "exports the caller's live member recovery bundle (stamps recovery-posture export evidence server-side)" },
   { path: ["errors"], positionals: [p("fingerprint_id", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "merged" },
 
   // ── jobs ─────────────────────────────────────────────────────────────────
@@ -468,6 +471,11 @@ export const SKIPPED_FAMILIES = {
   // of UNKNOWN_COMMAND) but has zero manifest entries, since a redirect
   // dispatches nothing.
   "gitvault": "retired; every subcommand answers COMMAND_MOVED/COMMAND_REMOVED naming its `repos`/git successor",
+  // Shipped in exactly one release (v4.54.0, live for hours) before the
+  // one-noun review caught it: a gateway route namespace is not a CLI noun.
+  // Both verbs answer COMMAND_MOVED into the repos family for one release,
+  // then the spelling is reserved and answers nothing.
+  "source-access": "retired same-day; `export` -> `repos recovery-bundle`, `status` -> `repos access` (member_custody block)",
   // `repo` singular resolves identically to `repos` — same
   // module, same case block in cli.mjs, so it needs no manifest of its own.
   "repo": "alias for `repos`, resolves identically (design D1)",
@@ -486,6 +494,8 @@ export const SKIPPED_FAMILIES = {
  * which the family list cannot express.
  */
 export const RESERVED_SUBCOMMANDS = {
+  "source-access:export": "moved to `repos recovery-bundle` — the artifact `repos recover --bundle` consumes belongs to the repos family",
+  "source-access:status": "moved to `repos access` — your own wrapper custody rides its member_custody block; the org advisory is `doctor --only recovery_posture`",
   "rooms:who": "renamed to `rooms join` — an interrogative must not name a write",
   "rooms:send": "moved to `messages send` — the verb acts on a message",
   // The routes and SDK methods for room list/get exist (agent-room-lifecycle);

package/lib/doctor.mjs

@@ -51,6 +51,7 @@ const DOCTOR_CHECK_NAMES = [
   "tier",
   "operator_health",
   "runtime_staleness",
+  "recovery_posture",
   "gitvault",
   "source_scan",
 ];
@@ -132,6 +133,12 @@ Checks performed:
   - Function runtime staleness: deployed functions running an older platform
     runtime than the current gateway build (refresh with 'run402 functions
     rebuild --all'; re-bundles from your stored source, no source change)
+  - Recovery posture: per vault-owning org, whether a human owner has a
+    working control-plane login and whether any member holds a working
+    source-access key (wrapper custody), plus a legacy-custody warning —
+    the org's disaster backstops if the agent machine dies. Evidence
+    levels: "configured" is what the platform verified, never proof an
+    off-platform passkey or saved code still exists.
   - gitvault: the active project's vault — activation policy, whether THIS
     machine can produce the capture a 'required' policy demands, open
     unvaulted-override journals, and where the keystore lives (back it up:
@@ -406,12 +413,13 @@ export async function run(sub, args = []) {
   }
 
   // 6. Operator health snapshot (v1.55 + v1.56 verification attempt detail).
-  // Both checks below ride the SAME operator-status read (runtime_staleness
-  // reuses the response operator_health already pulled), so the whole block
-  // is gated on wanting EITHER — --only runtime_staleness alone still needs
-  // this read, but --only-ing neither skips it entirely, same "don't do the work of a
-  // check nobody asked for" discipline the rest of --only follows.
-  if (wanted("operator_health") || wanted("runtime_staleness")) try {
+  // The checks below all ride the SAME operator-status read (runtime_staleness
+  // and recovery_posture reuse the response operator_health already pulled),
+  // so the whole block is gated on wanting ANY — --only runtime_staleness
+  // alone still needs this read, but --only-ing none skips it entirely, same
+  // "don't do the work of a check nobody asked for" discipline the rest of
+  // --only follows.
+  if (wanted("operator_health") || wanted("runtime_staleness") || wanted("recovery_posture")) try {
     const sdk = getSdk();
     const status = await sdk.admin.getOperatorStatus();
     const gaps = [];
@@ -502,6 +510,53 @@ export async function run(sub, args = []) {
         });
       }
     }
+
+    // 6c. Org recovery posture (gitvault-recovery-custody). One entry per
+    // vault-owning org the caller can see; rides the same operator-status
+    // read. Evidence levels, not guarantees: "configured" names what the
+    // platform VERIFIED — it can never observe whether an off-platform
+    // passkey or saved code still exists. The two headline facts mirror the
+    // feed events org_recovery_posture_degraded/_recovered; each gap line
+    // carries its remedy (Anticipatory), same shape as the reachability gaps
+    // above.
+    if (wanted("recovery_posture")) {
+      const posture = status.recovery_posture;
+      if (!Array.isArray(posture)) {
+        // Gateway older than gitvault-recovery-custody doesn't surface it.
+        checks.push({
+          name: "recovery_posture",
+          status: "skipped",
+          ...(verbose && { hint: "operator status has no 'recovery_posture' block; requires a gitvault-recovery-custody gateway." }),
+        });
+      } else if (posture.length === 0) {
+        // No vault-owning org in the caller's view — nothing to lose, nothing to advise.
+        checks.push({ name: "recovery_posture", status: "ok", value: { orgs: [] } });
+      } else {
+        const gaps = [];
+        for (const org of posture) {
+          const label = `org ${org.org_id} (${org.vault_count} vault${org.vault_count === 1 ? "" : "s"})`;
+          if (org.control_plane_configured === false) {
+            gaps.push(`${label}: no human owner with a working control-plane login — if this org's agent machine dies, nobody can sign in to recover it. Invite a backup human (run402 org invite create ${org.org_id} --email <their-email> --role owner) and have them complete login at console.run402.com.`);
+          }
+          if (org.source_backup_configured === false) {
+            gaps.push(`${label}: no human member holds a working source-access key — vault history has no member-side decryption backup. Have a member complete source enrollment at console.run402.com/account → Source access.`);
+          }
+          if (org.custody_legacy_present === true) {
+            gaps.push(`${label}: a member key is still on single-credential legacy custody (one passkey, no recovery code — losing that one credential loses source access). Re-enroll at console.run402.com/account to move to wrapper custody with a recovery code.`);
+          }
+        }
+        checks.push(
+          gaps.length > 0
+            ? {
+                name: "recovery_posture",
+                status: "warning",
+                value: { orgs: posture, gaps },
+                hint: "These are the org's disaster-recovery backstops — the same facts arrive as org_recovery_posture_degraded/_recovered feed events. After enrolling, export the recovery bundle (run402 repos recovery-bundle) and store it separately from the code.",
+              }
+            : { name: "recovery_posture", status: "ok", value: { orgs: posture } },
+        );
+      }
+    }
   } catch (err) {
     // Operator status endpoint may not be reachable if the operator-binding
     // substrate isn't deployed yet on the target API. Don't fail the whole
@@ -518,6 +573,11 @@ export async function run(sub, args = []) {
       status: "skipped",
       message: describeCheckFailure("operator status check", err),
     });
+    if (wanted("recovery_posture")) checks.push({
+      name: "recovery_posture",
+      status: "skipped",
+      message: describeCheckFailure("operator status check", err),
+    });
   }
 
   // 6c. gitvault (add-gitvault). Doctor was completely silent about the vault

package/lib/repos.mjs

@@ -1,6 +1,6 @@
 /**
  * `run402 repos` — the consolidated encrypted-repository family. One noun,
- * twelve verbs, each one either a `gh repo` verb, a `git` verb meaning what
+ * thirteen verbs, each one either a `gh repo` verb, a `git` verb meaning what
  * it means in git, or a plain-English verb for an operation with no analog.
  * `repo` singular resolves identically (`cli.mjs` dispatches both spellings
  * here).
@@ -51,7 +51,7 @@ const COMMON_VALUE_FLAGS = ["--project", "--repo"];
 export const HELP = `run402 repos — your source, encrypted before it leaves the machine
 
 Usage:
-  run402 repos <verb> [options] — twelve verbs, tiered by how often you reach for them:
+  run402 repos <verb> [options] — thirteen verbs, tiered by how often you reach for them:
 
 Common:
   run402 repos create [name]  [--org <org_id>] [--dir <path>] [--tier <tier>] [--project <id>]
@@ -65,7 +65,9 @@ Then plain git, forever:
 Occasional:
   run402 repos snapshot [--project <id>] [--repo <repo_id>] [--message <text>] [--checkpoint] [--dry-run] [--allow-dirty] [--manifest-out <path>]
   run402 repos mirror   [<destination>] [--off] [--backfill] [--profile <name> | --ambient] [--region <r>] [--endpoint <url>] [--project <id>] [--repo <repo_id>]
-  run402 repos recover  <source> --out <dir> [--repo <repo_id>] [--profile <name> | --ambient] [--region <r>] [--endpoint <url>] [--human]
+  run402 repos recover  <source> --out <dir> [--repo <repo_id>] [--profile <name> | --ambient] [--region <r>] [--endpoint <url>]
+                        [--bundle <file>] [--code <SRC1-…>] [--receipt <file>] [--rp-id <host>] [--human]
+  run402 repos recovery-bundle [--out <file> | --out -]
 
 Lifecycle:
   run402 repos rename <new_name> [--repo <repo_id> | --project <project_id>]
@@ -164,6 +166,34 @@ Subcommands:
            mirror's validity, never freshness — read both honesty statements
            before relying on the result. \`--human\` renders a short summary
            instead of JSON.
+           A human member under wrapper custody (no keystore) recovers with
+           their exported recovery bundle + source recovery code:
+           \`--bundle <file>\` (omit to use the mirror's own
+           member-recovery-bundles/ sidecar) + \`--code\` (prompted, hidden,
+           when omitted) + \`--receipt <pin.json>\` (the vault's one-shot
+           recovery receipt — key material never substitutes for the trust
+           anchor). A raw WebAuthn PRF output is NOT a supported input; a
+           code with no exported bundle refuses by name (a server-side
+           wrapper row that was never exported is not offline backup).
+  recovery-bundle
+           Export YOUR member recovery bundle
+           (r402s-member-recovery-bundle/v1): key identity + every ACTIVE
+           wrapper ciphertext — the file \`recover --bundle\` opens with the
+           source recovery code, kept SEPARATELY. A server-side wrapper row
+           alone is NOT offline backup; this export is. Writes
+           run402-source-recovery-bundle-<fingerprint>.json (0600) in the
+           cwd unless \`--out\` says otherwise (\`--out -\` prints only); the
+           full JSON always goes to stdout. Principal-scoped, not
+           repo-scoped (one bundle covers every vault you can read) — auth
+           is your control-plane session (\`run402 operator login
+           --loopback\` first; without one it answers for the active
+           WALLET's agent principal, normally no wrappers, and says so).
+           To make it travel WITH a mirror, copy it to
+           member-recovery-bundles/<name>.json under the mirrored prefix —
+           \`recover\` finds it there automatically. Enrollment/activation/
+           revocation are browser ceremonies: console.run402.com/account.
+           Your own wrapper custody also renders in \`repos access\` (its
+           member_custody block) when a control-plane session is cached.
   fsck     Walks the head chain AND materializes
            the ref map, advancing BOTH
            local trust pins — reported EXPLICITLY as local_state_changed +
@@ -291,6 +321,19 @@ Options:
   --region <r>      mirror / recover: AWS region for an s3:// destination
   --endpoint <url>  mirror / recover: an S3-compatible endpoint override
   --out <dir>       recover: where to materialize the recovered repository
+  --bundle <file>   recover: an exported r402s-member-recovery-bundle/v1 (from
+                    \`run402 repos recovery-bundle\` or the console's download).
+                    Omit to use the mirror's member-recovery-bundles/ sidecar.
+  --code <SRC1-…>   recover: the source recovery code that opens the bundle.
+                    Prefer omitting it — with --bundle set it is prompted with
+                    hidden input, so it never lands in shell history.
+  --receipt <file>  recover: the vault's recovery-receipt pin as JSON (the
+                    one-shot receipt from repo creation). Required for trusted
+                    recovery when no keystore holds it — without any pin the
+                    result is labeled unauthenticated_salvage.
+  --rp-id <host>    recover: the seal-time ceremony host bound into the
+                    wrapper context (default: the bundle's own rp_id, then
+                    console.run402.com — where every wrapper is sealed today)
   --budget <n>      fsck: heads walked in this call (write mode persists the
                     verified prefix, so a budget-exceeded run resumes; a
                     --no-write run does not, since nothing was persisted)
@@ -340,6 +383,8 @@ Examples:
   run402 repos gc
   run402 repos access --human
   run402 repos recover s3://acme-vault-mirror --out ./restored --human
+  run402 repos recovery-bundle --out ./bundle.json
+  run402 repos recover ./mirror-copy --out ./restored --receipt ./recovery-receipt.json --bundle ./bundle.json
   run402 repos delete --project prj_xyz --force
 `;
 
@@ -1556,6 +1601,19 @@ async function fsck(args) {
       if (result.mirror.data_loss_detected) {
         console.error(`DATA LOSS DETECTED: ${result.mirror.absences.filter((x) => x.adjudication === "unexplained_absence").length} object(s) are unexplained absences.`);
       }
+      // gitvault-recovery-custody: member recovery-bundle sidecars, reported
+      // as UNVERIFIED availability hints — nothing about them is chain-
+      // authenticated; they only say bundle + source recovery code can
+      // recover this mirror with no server.
+      if (Array.isArray(result.mirror.member_recovery_bundles) && result.mirror.member_recovery_bundles.length > 0) {
+        for (const b of result.mirror.member_recovery_bundles) {
+          console.error(
+            b.parse_error
+              ? `member recovery bundle (unverified hint): ${b.key} — does not parse (${b.parse_error})`
+              : `member recovery bundle (unverified hint): ${b.key} — ${b.ek_fingerprint} [${b.wrapper_kinds.join(", ")}]; recover with \`run402 repos recover <source> --receipt <pin.json>\` + the source recovery code`,
+          );
+        }
+      }
       printMirrorHonesty(result.mirror);
     }
     printVerboseStats(a, sdk);
@@ -1676,6 +1734,28 @@ function formatAccessHuman(result) {
   return lines.join("\n");
 }
 
+/** One stderr line for the access read's "you" block — your own wrapper custody, or the honest reason it is absent. */
+function printMemberCustodySummary(mc) {
+  if (!mc) return;
+  if (!mc.available) {
+    console.error(`you: (not included — ${mc.reason}) ${mc.hint}`);
+    return;
+  }
+  if (!mc.encryption_key_id) {
+    console.error(`you: ${mc.hint}`);
+    return;
+  }
+  const active = mc.wrappers.filter((w) => w.state === "active");
+  const pending = mc.wrappers.filter((w) => w.state === "pending");
+  console.error(
+    `you: ${mc.ek_fingerprint} (${mc.custody_scheme}, ${mc.state}) — ${active.length} active wrapper(s) [${active.map((w) => w.kind).join(", ") || "none"}]` +
+      (pending.length > 0 ? `, ${pending.length} pending (unfinished enrollment — finish or it expires)` : "") + ".",
+  );
+  if (active.length > 0 && !active.some((w) => w.kind === "recovery_code")) {
+    console.error("you: no recovery_code wrapper — a passkey-only key has no offline/no-server recovery path; add one at console.run402.com/account.");
+  }
+}
+
 async function accessRead(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, [...COMMON_VALUE_FLAGS, "--human", "-v", "--verbose", "--help", "-h"], COMMON_VALUE_FLAGS);
@@ -1688,14 +1768,42 @@ async function accessRead(args) {
   const target = await vaultTarget(a);
   try {
     const result = await sdk.gitvault.access(target);
+    // gitvault-recovery-custody — the "you" block: YOUR OWN wrapper custody
+    // (kind/state per wrapper, custody scheme), rendered inside the family's
+    // custody roster read. Principal-scoped, so it needs your control-plane
+    // (human) session; without one it is honestly absent-with-reason rather
+    // than silently missing or misleadingly answered as the agent principal.
+    // Best-effort: an older gateway or a failed read never breaks `access`.
+    const cp = loadLiveControlPlaneSession();
+    if (cp) {
+      try {
+        const mine = await sdk.operator.session.sourceAccessWrappers({ token: cp.control_plane_session_token });
+        result.member_custody = mine.encryption_key
+          ? {
+              available: true,
+              encryption_key_id: mine.encryption_key.encryption_key_id,
+              ek_fingerprint: mine.encryption_key.ek_fingerprint,
+              custody_scheme: mine.encryption_key.custody_scheme,
+              state: mine.encryption_key.state,
+              wrappers: mine.wrappers.map((w) => ({ wrapper_id: w.wrapper_id, kind: w.kind, state: w.state, created_at: w.created_at, activated_at: w.activated_at })),
+            }
+          : { available: true, encryption_key_id: null, hint: "no source-access key enrolled — enroll at console.run402.com/account → Source access." };
+      } catch (e) {
+        result.member_custody = { available: false, reason: e?.code ?? "read_failed", hint: "your own wrapper custody could not be read (older gateway, or the session lacks it)." };
+      }
+    } else {
+      result.member_custody = { available: false, reason: "no_control_plane_session", hint: "run 'run402 operator login --loopback' to include your own wrapper custody here." };
+    }
     if (human) {
       console.log(formatAccessHuman(result));
+      printMemberCustodySummary(result.member_custody);
       printVerboseStats(a, sdk);
       return;
     }
     printJson(sdk, result);
     await spillIfLarge(result.repo_id, "access", result);
     console.error(`${result.recipients.length} directory recipient(s), ${result.recipients.filter((r) => r.covered).length} covered on this repo.`);
+    printMemberCustodySummary(result.member_custody);
     if (result.this_keystore) {
       console.error(`1 covering fingerprint is this machine's own keystore (the vault's writing principal, not in the org directory): ${result.this_keystore.fingerprint}`);
     }
@@ -1876,6 +1984,9 @@ function formatRecoverHuman(result, outDir) {
   if (result.data_loss_detected) {
     lines.push(`DATA LOSS DETECTED: ${result.absences.filter((x) => x.adjudication === "unexplained_absence").length} object(s) are unexplained absences.`);
   }
+  if (result.member_recovery) {
+    lines.push(`Decrypted via member recovery bundle${result.member_recovery.bundle_key ? ` ${result.member_recovery.bundle_key}` : ""} + source recovery code (no keystore).`);
+  }
   lines.push(`Layout: ${result.layout}` + (result.layout === "bare" ? " (no working files — not a failed recovery)" : ""));
   if (result.retained_refs?.warning) {
     lines.push(`refs/r402/retain: ${result.retained_refs.warning}`);
@@ -1885,9 +1996,40 @@ function formatRecoverHuman(result, outDir) {
   return lines.join("\n");
 }
 
+/**
+ * Read the source recovery code without echoing it (TTY) — a recovery code
+ * is long-lived key material; it must never land in shell history (prefer
+ * the prompt over `--code <value>`) and never echo into a scrollback.
+ * Non-TTY stdin (piped) reads one line verbatim.
+ */
+async function promptSourceRecoveryCode() {
+  const { stdin, stderr } = process;
+  if (!stdin.isTTY) {
+    const chunks = [];
+    for await (const c of stdin) {
+      chunks.push(c);
+      const s = Buffer.concat(chunks).toString("utf8");
+      if (s.includes("\n")) return s.slice(0, s.indexOf("\n")).trim();
+    }
+    return Buffer.concat(chunks).toString("utf8").trim();
+  }
+  const { createInterface } = await import("node:readline");
+  stderr.write("Source recovery code (SRC1-…, input hidden): ");
+  return await new Promise((resolve) => {
+    const rl = createInterface({ input: stdin, terminal: true });
+    // Mute the echo: readline in terminal mode writes through _writeToOutput.
+    rl._writeToOutput = () => {};
+    rl.question("", (answer) => {
+      rl.close();
+      stderr.write("\n");
+      resolve(answer.trim());
+    });
+  });
+}
+
 async function recover(args) {
   const a = normalizeArgv(args);
-  const valueFlags = ["--out", "--repo", "--profile", "--region", "--endpoint"];
+  const valueFlags = ["--out", "--repo", "--profile", "--region", "--endpoint", "--bundle", "--code", "--receipt", "--rp-id"];
   assertKnownFlags(a, [...valueFlags, "--ambient", "--human", "-v", "--verbose", "--help", "-h"], valueFlags);
   const [source] = requirePositionalCount(a, valueFlags, {
     min: 1, max: 1, command: "run402 repos recover <source> --out <dir>",
@@ -1906,6 +2048,18 @@ async function recover(args) {
   const repoId = flagValue(a, "--repo");
   const region = flagValue(a, "--region");
   const endpoint = flagValue(a, "--endpoint");
+  // gitvault-recovery-custody — the human-member path: --bundle (the exported
+  // r402s-member-recovery-bundle/v1; omit to use the mirror's own
+  // member-recovery-bundles/ sidecar) + the source recovery code. --receipt
+  // supplies the recovery-receipt pin when no keystore holds one (a member
+  // has no keystore); --rp-id overrides the seal-time ceremony host.
+  const bundlePath = flagValue(a, "--bundle");
+  const receiptPath = flagValue(a, "--receipt");
+  const rpId = flagValue(a, "--rp-id");
+  let code = flagValue(a, "--code");
+  const memberBundle = bundlePath != null ? readJsonFile("--bundle", bundlePath) : undefined;
+  const recoveryReceipt = receiptPath != null ? readJsonFile("--receipt", receiptPath) : undefined;
+  if (memberBundle !== undefined && code == null) code = await promptSourceRecoveryCode();
   try {
     const result = await sdk.gitvault.recover({
       source, out_dir: outDir,
@@ -1913,6 +2067,10 @@ async function recover(args) {
       ...(credential ? { credential } : {}),
       ...(region != null ? { region } : {}),
       ...(endpoint != null ? { endpoint } : {}),
+      ...(memberBundle !== undefined ? { member_bundle: memberBundle } : {}),
+      ...(code != null ? { source_recovery_code: code } : {}),
+      ...(recoveryReceipt !== undefined ? { recovery_receipt: recoveryReceipt } : {}),
+      ...(rpId != null ? { rp_id: rpId } : {}),
     });
     if (human) {
       console.log(formatRecoverHuman(result, outDir));
@@ -1924,6 +2082,9 @@ async function recover(args) {
     printJson(sdk, result);
     await spillIfLarge(result.repo_id, "recover", result);
     console.error(`recovered generation ${result.recovered_generation} for ${result.repo_id} into ${outDir}` + (result.chain_break ? ` (chain break at ${result.chain_break.generation} — fell back to the newest fully-verified generation)` : "") + ".");
+    if (result.member_recovery) {
+      console.error(`decrypted via member recovery bundle${result.member_recovery.bundle_key ? ` ${result.member_recovery.bundle_key}` : ""} (wrapper ${result.member_recovery.wrapper_id}, ${result.member_recovery.ek_fingerprint}) + source recovery code — no keystore involved.`);
+    }
     if (result.data_loss_detected) {
       console.error(`DATA LOSS DETECTED: ${result.absences.filter((x) => x.adjudication === "unexplained_absence").length} object(s) are unexplained absences — see "absences" in the result above.`);
     }
@@ -1946,6 +2107,59 @@ async function recover(args) {
   }
 }
 
+// ─── recovery-bundle (gitvault-recovery-custody — the export half of `recover`) ─
+
+/**
+ * `run402 repos recovery-bundle` — export YOUR member recovery bundle
+ * (`r402s-member-recovery-bundle/v1`): key identity + every ACTIVE wrapper
+ * ciphertext. Together with the source recovery code — kept SEPARATELY —
+ * it is what `repos recover --bundle` opens with no run402 server; a
+ * server-side wrapper row alone is NOT offline backup, this export is.
+ *
+ * Principal-scoped, not repo-scoped (one bundle covers every vault you are
+ * a recipient of) — which is why the auth is your control-plane (human)
+ * session (`run402 operator login --loopback`), not the wallet. Without a
+ * session the request falls back to the active WALLET's agent principal,
+ * which normally holds no wrappers — truthful, with a stderr note saying so.
+ * Enrollment/activation/revocation are browser ceremonies at
+ * console.run402.com/account → Source access; this verb is read-only.
+ */
+function sourceAccessTokenOpts(commandLabel) {
+  const cp = loadLiveControlPlaneSession();
+  if (!cp) {
+    console.error(
+      `no control-plane (human) session — ${commandLabel} will answer for the active WALLET's agent principal, which normally holds no wrappers. Run 'run402 operator login --loopback' to act as yourself.`,
+    );
+    return {};
+  }
+  return { token: cp.control_plane_session_token };
+}
+
+async function recoveryBundle(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, ["--out", "--json", "--help", "-h", "-v", "--verbose"], ["--out"]);
+  requirePositionalCount(a, ["--out"], { min: 0, max: 0, command: "run402 repos recovery-bundle", missing: "" });
+  const out = flagValue(a, "--out");
+  const sdk = getSdk();
+  try {
+    const bundle = await sdk.operator.session.sourceAccessRecoveryBundle(sourceAccessTokenOpts("recovery-bundle"));
+    // Full JSON to stdout regardless — the pipe contract is sacred; the file
+    // is the keep-a-copy convenience (0600 — the bundle is ciphertext the
+    // platform cannot open, but it is still half of a recovery credential).
+    console.log(JSON.stringify({ ...bundle, stats: sdkStats(sdk) }, null, 2));
+    if (out !== "-") {
+      const path = out ?? `run402-source-recovery-bundle-${(bundle.ek_fingerprint || "key").slice(0, 11)}.json`;
+      writeFileSync(path, JSON.stringify(bundle, null, 2) + "\n", { mode: 0o600 });
+      console.error(`bundle written to ${path} (0600).`);
+    }
+    console.error("keep this bundle SEPARATELY from your source recovery code — together they are equivalent to your member private key.");
+    console.error("to make it travel with a vault mirror: copy it to member-recovery-bundles/<name>.json under the mirrored prefix; `run402 repos recover` finds it there.");
+    printVerboseStats(a, sdk);
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
 // ─── dispatch ───────────────────────────────────────────────────────────────
 
 export async function run(sub, args) {
@@ -2003,6 +2217,10 @@ export async function run(sub, args) {
       await recover(argv);
       break;
     }
+    case "recovery-bundle": {
+      await recoveryBundle(argv);
+      break;
+    }
     default:
       failUnknownSubcommand("repos", sub, {
         hint: "Run `run402 repos --help` for usage.",

package/lib/source-access.mjs

@@ -0,0 +1,70 @@
+/**
+ * `run402 source-access` — RETIRED after exactly one release (v4.54.0, live
+ * for hours), moved into the `repos` family the same day it shipped.
+ *
+ * The family violated the one-noun consolidation the CLI just fought for
+ * (repo-surface-consolidation: 19 commands → one noun, twelve verbs): it
+ * pattern-matched the gateway's `/agent/v1/source-access/*` route namespace
+ * into a CLI noun, and the wire is organized by resource while the CLI is
+ * organized by user nouns. Both verbs live where a user actually looks:
+ *
+ *   source-access export  ->  repos recovery-bundle   (the artifact
+ *                             `repos recover --bundle` consumes; custody
+ *                             machinery of the repos family)
+ *   source-access status  ->  repos access            (its "you" block —
+ *                             your own wrapper custody, rendered inside the
+ *                             family's existing custody roster read)
+ *
+ * Same contract as the gitvault retirement (`cli/lib/gitvault.mjs`): every
+ * spelling answers a structured COMMAND_MOVED for exactly one release —
+ * typed next_actions, non-zero exit, EMPTY stdout — then the spelling is
+ * reserved and answers nothing at all. Never re-pointed at new behavior.
+ */
+import { fail } from "./sdk-errors.mjs";
+import { hasHelp } from "./argparse.mjs";
+
+export const HELP = `run402 source-access — RETIRED (moved into the repos family)
+
+Usage:
+  run402 source-access <anything> — answers a structured error naming its repos successor; see below.
+
+Moved:
+  source-access export -> repos recovery-bundle   (export your member recovery bundle)
+  source-access status -> repos access            (your own wrapper custody rides its "you" block)
+
+Run \`run402 repos --help\` for the current surface.
+`;
+
+const MOVED = {
+  export: {
+    command: "run402 repos recovery-bundle",
+    why: "The bundle's whole life is in the repos family — it is the artifact `repos recover --bundle` consumes and the sidecar a `repos mirror` carries.",
+  },
+  status: {
+    command: "run402 repos access",
+    why: "Your own wrapper custody now renders inside the family's existing custody roster read (its member_custody block); the org-level advisory is `run402 doctor --only recovery_posture`.",
+  },
+};
+
+export async function run(sub, args) {
+  const argv = Array.isArray(args) ? args : [];
+  if (!sub || hasHelp([sub, ...argv])) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  const m = MOVED[sub];
+  if (m) {
+    fail({
+      code: "COMMAND_MOVED",
+      message: `run402 source-access ${sub} moved to ${m.command}.`,
+      hint: m.why,
+      details: { was: `source-access ${sub}`, now: m.command },
+      next_actions: [{ type: "use_moved_command", command: m.command, why: m.why }],
+    });
+  }
+  fail({
+    code: "UNKNOWN_SUBCOMMAND",
+    message: `run402 source-access ${sub}: unknown, and source-access itself is retired.`,
+    hint: "Run `run402 repos --help` for the current surface.",
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.53.0",
+  "version": "4.54.1",
   "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": {

package/sdk/dist/namespaces/gitvault.crypto.d.ts

@@ -562,5 +562,46 @@ export declare function checkPinManifestConservation(prior: readonly {
 /** The synthetic ledger id a path-addressed `key_envelope` gets — mirrors the gateway's `keyEnvelopeLedgerId` exactly (drift here breaks receipt pairing at upload finalize). */
 export declare function keyEnvelopeLedgerId(epoch: string, fingerprint: string, rotationId: string | null): string;
 export declare function pinManifestLedgerId(pinManifestVersion: string): string;
+export declare const SOURCE_WRAP_BLOB_PREFIX = "swrap2_";
+export declare const SOURCE_RC_DISPLAY_PREFIX = "SRC1";
+export type SourceWrapperKind = "webauthn_prf" | "recovery_code";
+export interface SourceWrapperContextFields {
+    /** The seal-time ceremony host (`location.hostname` of the sealing page — `console.run402.com` for every wrapper sealed today). */
+    rp_id: string;
+    principal_id: string;
+    encryption_key_id: string;
+    wrapper_id: string;
+    kind: SourceWrapperKind;
+    /** WebAuthn `public_subject` for `webauthn_prf` wrappers; always null in the JCS for `recovery_code`. */
+    credential_subject: string | null;
+    /** The raw 32-byte member public key — the context binds its FULL SHA-256, never the truncated `ek_` fingerprint. */
+    member_public_key: Uint8Array;
+}
+/** The pinned canonical context for one wrapper — BOTH the KEK HKDF-info suffix AND the AEAD AAD. */
+export declare function buildSourceWrapperContext(fields: SourceWrapperContextFields): Uint8Array;
+/**
+ * Open a `swrap2_...` wrapper blob back into the 32-byte member scalar.
+ * `ikm` is the UTF-8 bytes of the normalized code CORE (`recovery_code`) or
+ * the raw PRF output (`webauthn_prf` — only ever exercised by browser
+ * surfaces; offline recovery refuses raw PRF as an input by policy, at the
+ * recover layer). A failed AEAD is `WRAPPER_DID_NOT_OPEN` — the truthful
+ * cause-neutral error: wrong code, corrupt blob, and wrong context (rp_id
+ * included) are indistinguishable here. The caller MUST compare the derived
+ * FULL public key against the published one before trusting the scalar.
+ */
+export declare function openSourceWrapper(input: {
+    kind: SourceWrapperKind;
+    ikm: Uint8Array;
+    blob: string;
+    context: Uint8Array;
+}): Uint8Array;
+/**
+ * Pinned normalization (ONE canonical accepted form): uppercase; strip every
+ * char outside [0-9A-Z]; map I→1, L→1, O→0; drop a leading "SRC1" when the
+ * result is 37 chars; require exactly 33 chars; validate the check character
+ * (`RECOVERY_CODE_CHECKSUM_INVALID` — a local typo, caught before any KEK
+ * derivation or wrapper read). Returns the 32-char CORE (the KEK ikm).
+ */
+export declare function normalizeSourceRecoveryCode(input: string): string;
 export { bytesToHex, hexToBytes };
 //# sourceMappingURL=gitvault.crypto.d.ts.map