@run402/sdk 4.39.1 → 4.41.0

package/dist/namespaces/gitvault.js

@@ -29,7 +29,7 @@
  * never persisted into an agent-surface result store, and never logged.
  */
 import { LocalError } from "../errors.js";
-import { GITVAULT_TERMINAL_LOSS_DOCTOR_TEXT, GITVAULT_TERMINAL_LOSS_STATEMENT } from "./gitvault.crypto.js";
+import { GITVAULT_MIRROR_KEYSTORE_STILL_REQUIRED_STATEMENT, GITVAULT_MIRROR_VALIDITY_NOT_FRESHNESS_STATEMENT, GITVAULT_TERMINAL_LOSS_DOCTOR_TEXT, GITVAULT_TERMINAL_LOSS_STATEMENT, } from "./gitvault.crypto.js";
 /** A keystore path, or `null` when there is no id to derive it from (or it is malformed). */
 function safePath(derive, repoId) {
     if (!repoId)
@@ -49,6 +49,34 @@ async function nodeOnly(load, verb) {
         throw new LocalError(`\`r.gitvault.${verb}\` needs the Node runtime (keystore + git); import it from a Node process, or use the read-only vault methods in a browser.`, `running gitvault ${verb}`, { code: "GITVAULT_NODE_ONLY", details: { cause: e instanceof Error ? e.message : String(e) } });
     }
 }
+/**
+ * {@link Gitvault.deploy}'s post-push glue: attach the best-effort
+ * mirror/reconcile hooks to a deploy result, gated on whether this deploy
+ * actually landed a new generation in the vault. Extracted as a standalone
+ * function (rather than inlined in `deploy()`) purely so the gating can be
+ * unit-tested with fake thunks — the real hooks (`#tryMirrorPush` /
+ * `#tryReconcileEnvelopeRecipients`) are private class methods that already
+ * catch everything and never reject, so this function does not need its own
+ * try/catch: it only decides WHETHER to call them and how to merge what they
+ * resolve to.
+ *
+ * `DEPLOYED_AND_VAULTED` and `DEPLOY_FAILED_VAULTED` are the only two
+ * outcomes that carry a `generation` — a vault push actually landed. The
+ * other three (`DEPLOY_BLOCKED_PUSH_FAILED`, `DEPLOY_FAILED_UNVAULTED`,
+ * `DEPLOYED_UNVAULTED_OVERRIDE`) published nothing new, so `mirror_push` /
+ * `reconcile_recipients` are OMITTED rather than a faked `skipped_*` value —
+ * there is nothing this deploy did that either hook could report on.
+ */
+export async function attachGitvaultDeployHooks(result, mirror, reconcile) {
+    if (result.outcome !== "DEPLOYED_AND_VAULTED" && result.outcome !== "DEPLOY_FAILED_VAULTED")
+        return result;
+    // Sequential, not Promise.all — same ordering push() uses, so a reconcile
+    // failure can never be misread as a mirror failure in a log line that
+    // assumed ordering.
+    const mirrorPush = await mirror();
+    const reconcileRecipients = await reconcile();
+    return { ...result, mirror_push: mirrorPush, reconcile_recipients: reconcileRecipients };
+}
 // ─── The namespace ───────────────────────────────────────────────────────────
 export class Gitvault {
     #client;
@@ -68,6 +96,31 @@ export class Gitvault {
     async forProject(projectId) {
         return this.#client.request(`/gitvault/v1/vaults?project_id=${encodeURIComponent(projectId)}`, { context: "resolving the project's gitvault" });
     }
+    /**
+     * Every vault the organization owns, one round trip — `repos list`'s bulk
+     * read (repo-surface-consolidation task 2.4). See {@link
+     * GitvaultOrgVaultsListing}'s doc comment for the FROZEN response shape and
+     * the 404-until-shipped fallback contract.
+     */
+    async listByOrg(orgId) {
+        // The gateway keyset-paginates (has_more/next_cursor, opaque store-and-
+        // echo). This method's contract is "the org's vaults", so it follows the
+        // cursor and aggregates — a silently-truncated page one would be the
+        // Faithful breach agent-response-design.md names. The page bound is a
+        // runaway guard, far above any real org; hitting it surfaces has_more:
+        // true honestly instead of looping forever on a misbehaving cursor.
+        const all = [];
+        let cursor;
+        for (let page = 0; page < 100; page++) {
+            const url = `/gitvault/v1/vaults?org_id=${encodeURIComponent(orgId)}` + (cursor ? `&cursor=${encodeURIComponent(cursor)}` : "");
+            const res = await this.#client.request(url, { context: "listing the organization's vaults" });
+            all.push(...res.vaults);
+            if (!res.has_more || !res.next_cursor)
+                return { vaults: all, has_more: false, next_cursor: null };
+            cursor = res.next_cursor;
+        }
+        return { vaults: all, has_more: true, next_cursor: cursor ?? null };
+    }
     /**
      * Resolve a vault by its address-form `org-slug/name` (repo-first-onramp
      * task 4.3, design D6) — `GET /gitvault/v1/vaults?repo=<org-slug>/<name>`.
@@ -592,11 +645,11 @@ export class Gitvault {
         // nothing; pointing at it here sent users to a command that silently did
         // not do what this line promised (dogfood #1, finding A).
         if (!record)
-            nextActions.push({ action: "allocate the project's vault", command: "run402 gitvault init" });
+            nextActions.push({ action: "allocate the project's vault", command: "run402 repos create --project <id>" });
         else if (pending.length > 0)
-            nextActions.push({ action: `complete ${pending.length} unvaulted-override journal(s)`, command: "run402 gitvault snapshot" });
+            nextActions.push({ action: `complete ${pending.length} unvaulted-override journal(s)`, command: "run402 repos snapshot" });
         else if (record && !holdsRepoKey)
-            nextActions.push({ action: "this machine holds no key for the vault — allocate resolves to the existing vault and is idempotent", command: "run402 gitvault init" });
+            nextActions.push({ action: "this machine holds no key for the vault — allocate resolves to the existing vault and is idempotent", command: "run402 repos create --project <id>" });
         return {
             repo_id: repoId,
             project_id: options.project_id ?? record?.project_id ?? null,
@@ -685,7 +738,38 @@ export class Gitvault {
             ...(options.checkpoint ? { checkpoint: true } : {}),
         };
         const result = await handle.vault.push(push);
-        return { ...result, snapshot, gitvault_commit: snapshot.oid, gitvault_commit_line: line };
+        // Capture-time dual-push hook (design D6/task 2.4): fires only when a
+        // mirror is configured; NEVER throws, NEVER alters the vault outcome
+        // above (already returned/committed) — a mirror failure is a named
+        // pending finding reported BESIDE the vault result, on its own field.
+        const mirrorPush = await this.#tryMirrorPush(handle.repo_id, handle.keystore);
+        // Deploy-time reconcile hook (design D5's "deploy time" cadence,
+        // gitvault-human-envelopes task 4.1): fires on every successful push,
+        // best-effort — a reconcile failure (including a read-only principal
+        // with no signing key) is reported BESIDE the vault result, never a
+        // `push()` throw, same non-blocking contract as the mirror hook above.
+        const reconcileRecipients = await this.#tryReconcileEnvelopeRecipients(handle.vault);
+        return { ...result, snapshot, gitvault_commit: snapshot.oid, gitvault_commit_line: line, mirror_push: mirrorPush, reconcile_recipients: reconcileRecipients };
+    }
+    /** Best-effort dual-push: catches EVERYTHING, including the lazy module import itself, so a mirror problem can never surface as a `push()` throw. */
+    async #tryMirrorPush(repoId, keystore) {
+        try {
+            const { mirrorPushForGeneration } = await this.#mirror();
+            return await mirrorPushForGeneration(this.#client, repoId, { keystore });
+        }
+        catch (e) {
+            return { attempted: false, outcome: "skipped_no_mirror", error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    /** Best-effort envelope-recipient reconcile: catches EVERYTHING so a reconcile problem can never surface as a `push()` throw (mirrors {@link #tryMirrorPush}'s contract exactly). */
+    async #tryReconcileEnvelopeRecipients(vault) {
+        try {
+            const result = await vault.reconcileEnvelopeRecipients();
+            return { attempted: true, outcome: "reconciled", result };
+        }
+        catch (e) {
+            return { attempted: false, outcome: "skipped_error", error: e instanceof Error ? e.message : String(e) };
+        }
     }
     /**
      * A REAL preview of what {@link push} would publish (kychee-com/run402#565)
@@ -893,7 +977,7 @@ export class Gitvault {
                 submitted: false,
                 intent: null,
                 confirmation: null,
-                note: "run `run402 gitvault compact` to publish a checkpoint bound to a fresh retention_cutoff ticket, then plan the prune again.",
+                note: "run `run402 repos gc` to publish a checkpoint bound to a fresh retention_cutoff ticket, then plan the prune again.",
             };
         }
         const record = await handle.vault.transport.getVaultRecord({ repo_id: handle.repo_id });
@@ -1016,7 +1100,142 @@ export class Gitvault {
      */
     async verify(options = {}) {
         const handle = await this.open(options);
-        return handle.vault.verifyToNewest();
+        return handle.vault.verifyToNewest({ persist: options.persist ?? true });
+    }
+    /**
+     * `repos fsck` (repo-surface-consolidation D2/D3): walk the head chain
+     * (what `verify()` did) AND materialize the ref map (what `status({refs:
+     * true})` used to do before `--refs` was removed from `view`), reporting
+     * BOTH local trust pins — authenticated and materialized — before and
+     * after, with an explicit `local_state_changed` flag. This is the one
+     * place chain materialization and pin advance live now; `view` never
+     * calls it.
+     *
+     * `options.write` (default `true`) is the inverse of the CLI's
+     * `--no-write`: `false` still walks and decrypts everything (the returned
+     * `refs`/`verified_to_generation` are real, computed answers, not
+     * estimates) but persists neither pin — a genuine audit mode, not a
+     * simulation. `options.mirror` additionally runs the keyless mirror
+     * verification ({@link mirrorVerify}) and folds its report in; that half
+     * proves the mirror's validity, never its freshness (its own honesty
+     * statements ride the result unchanged).
+     */
+    async fsck(options = {}) {
+        const before = await this.status(options);
+        const repoId = before.repo_id;
+        if (!repoId) {
+            throw new LocalError(options.repo_id || options.project_id
+                ? "no vault is allocated for this project yet — nothing to fsck"
+                : "pass repo_id, or project_id to resolve it from the control plane", "running gitvault fsck", { code: "GITVAULT_VAULT_UNRESOLVED", details: { project_id: options.project_id ?? null } });
+        }
+        const write = options.write ?? true;
+        const handle = await this.open({ ...options, repo_id: repoId });
+        const state = await handle.vault.materialize({ persist: write });
+        const mirror = options.mirror ? await this.mirrorVerify({ ...options, repo_id: repoId }) : null;
+        const pinBefore = { highest_authenticated: before.pins.highest_authenticated, highest_materialized: before.pins.highest_materialized };
+        const pinAfter = write
+            ? { highest_authenticated: state.generation, highest_materialized: state.generation }
+            : pinBefore;
+        const localStateChanged = write && (pinBefore.highest_authenticated !== pinAfter.highest_authenticated || pinBefore.highest_materialized !== pinAfter.highest_materialized);
+        return {
+            repo_id: repoId,
+            write,
+            verified_from_generation: pinBefore.highest_authenticated,
+            verified_to_generation: state.generation,
+            local_state_changed: localStateChanged,
+            pin_before: pinBefore,
+            pin_after: pinAfter,
+            refs: { ...state.refs },
+            head_target: state.head_target,
+            mirror,
+        };
+    }
+    /**
+     * Wrap this vault's current epoch key to every org member who has
+     * published an encryption key but has no `key_envelope` on this vault yet
+     * — gitvault-human-envelopes task 4.1's ADD-path workaround. See {@link
+     * import("../node/gitvault-publication.js").GitvaultVault.
+     * reconcileEnvelopeRecipients} for the full design (TOFU pinning, the
+     * gateway `public_key` gap, and why this is a workaround rather than the
+     * eventual epoch-rotation design).
+     *
+     * `run402 gitvault reconcile` was this method's explicit standalone CLI
+     * surface (design D5's "session start" hook); repo-surface-consolidation
+     * D5/D7/D10 REMOVED it (no `repos` equivalent — `reconcile` is a
+     * workaround, not a permanent verb) and it now answers `COMMAND_REMOVED`
+     * pointing at `repos access` for inspection. This method itself is
+     * unchanged and un-retired: `deploy()` still runs it, best-effort,
+     * whenever a deploy lands a new generation in the vault — design D5's
+     * "deploy time" hook, "the same 'one command every agent runs' argument
+     * that decided deploy-implies-capture." `push()` (capture-and-publish
+     * outside a deploy) runs the identical hook after every successful
+     * publish, for the vault-only-project cadence. See
+     * `#tryReconcileEnvelopeRecipients` below for both call sites, and
+     * {@link Gitvault.access} for the READ half repo-surface-consolidation
+     * ships in its place.
+     */
+    async reconcileEnvelopeRecipients(options = {}) {
+        const handle = await this.open(options);
+        return handle.vault.reconcileEnvelopeRecipients();
+    }
+    /**
+     * `repos access` (repo-surface-consolidation D5/D10) — a READ-ONLY report
+     * of who can open this vault, composed from whatever the live gateway
+     * surface exposes today. Never wraps, never mutates a `key_envelope` —
+     * that mutating half stays {@link reconcileEnvelopeRecipients}, reachable
+     * only through the deploy/push best-effort hooks until `access repair`
+     * ships (gated on `gitvault-human-envelopes`' epoch-rotation work). See
+     * {@link GitvaultAccessResult}'s doc comment for the honest gap this
+     * reports rather than invents.
+     */
+    async access(options = {}) {
+        const repoId = await this.#resolveRepoId(options);
+        const record = await this.get(repoId).catch(() => null);
+        const orgId = record?.org_id ?? null;
+        const [directory, coverage] = await Promise.all([
+            orgId
+                ? this.#client.request(`/orgs/v1/${encodeURIComponent(orgId)}/encryption-keys`, { context: "reading the org encryption-key directory" })
+                : Promise.resolve({ org_id: "", keys: [] }),
+            this.#client.request(`/gitvault/v1/vaults/${encodeURIComponent(repoId)}/envelope-recipients`, { context: "reading the gitvault envelope recipients" }),
+        ]);
+        const covered = new Set(coverage.recipient_fingerprints);
+        // Node-only, best-effort: THIS machine's own local TOFU pins. Never
+        // fails the whole read — a browser/worker caller, or a machine that has
+        // never wrapped anyone, simply reports every `tofu_pin` as `null`.
+        let pins = {};
+        try {
+            const { GitvaultKeystore } = await this.#keystore();
+            const keystore = new GitvaultKeystore(options.keystore_root !== undefined ? { rootDir: options.keystore_root } : {});
+            pins = keystore.readRepo(repoId)?.envelope_recipient_pins ?? {};
+        }
+        catch {
+            // Not Node, or no local keystore for this repo — pins stay empty.
+        }
+        const recipients = directory.keys.map((k) => {
+            const pinned = pins[k.principal_id];
+            return {
+                principal_id: k.principal_id,
+                display_name: k.display_name,
+                fingerprint: k.ek_fingerprint,
+                covered: covered.has(k.ek_fingerprint),
+                tofu_pin: pinned !== undefined ? { fingerprint: pinned, matches_directory: pinned === k.ek_fingerprint } : null,
+            };
+        });
+        const directoryFingerprints = new Set(directory.keys.map((k) => k.ek_fingerprint));
+        const unmatched = coverage.recipient_fingerprints.filter((fp) => !directoryFingerprints.has(fp));
+        return {
+            repo_id: repoId,
+            org_id: orgId,
+            recipients,
+            unmatched_covered_fingerprints: unmatched,
+            envelope_state_available: false,
+            history_scope_available: false,
+            gap: "the gateway does not yet expose per-recipient envelope_state (converged/pending) or history_scope — " +
+                "that is server-authoritative desired-recipient-state work owned by gitvault-human-envelopes and has not shipped. " +
+                "This reports what the read surface has today: the org's directory of encryption-key-holding members, which of " +
+                "the vault's current envelope-recipient fingerprints match a directory entry (covered), and this machine's own " +
+                "local TOFU pin per principal when it has ever wrapped one (tofu_pin) — never a server-side fact.",
+        };
     }
     /**
      * The push-gated deploy: both lanes under one fresh `capture_id`, resolving
@@ -1027,11 +1246,33 @@ export class Gitvault {
      * The push is never gated on deploy success, and a build that fails before a
      * canonical apply plan exists still captures (with a null plan digest, so no
      * activation token can be minted from it).
+     *
+     * `run402 deploy` is design D5's PRIMARY envelope-recipient reconcile hook
+     * ("the same 'one command every agent runs' argument that decided
+     * deploy-implies-capture") and design D6's primary dual-push mirror trigger
+     * — both fire HERE, not inside {@link runGitvaultDeploy} itself, mirroring
+     * {@link push}'s exact non-blocking contract: best-effort, NEVER throw,
+     * NEVER alter the deploy outcome already resolved above, reported BESIDE it
+     * on `mirror_push` / `reconcile_recipients`. They fire only when this
+     * deploy actually landed a new generation in the vault
+     * (`DEPLOYED_AND_VAULTED` / `DEPLOY_FAILED_VAULTED` — the outcomes carrying
+     * a `generation`); the other three outcomes published nothing new, so
+     * there is nothing to mirror or reconcile against ({@link
+     * import("../node/gitvault-mirror.js").mirrorPushForGeneration}'s own
+     * contract: "fires after an ordinary vault push/deploy produces a new
+     * generation"). Both fields are therefore OMITTED — never a faked
+     * `skipped_*` outcome — when no generation landed.
      */
     async deploy(options) {
         const { runGitvaultDeploy } = await this.#deploy();
         const handle = await this.open(options);
-        return runGitvaultDeploy({ ...options, vault: handle.vault, repo_dir: options.repo_dir ?? process.cwd() });
+        const result = await runGitvaultDeploy({ ...options, vault: handle.vault, repo_dir: options.repo_dir ?? process.cwd() });
+        // Same ordering push() uses (mirror, then reconcile) — sequential, not
+        // Promise.all, so a reconcile failure can never be misread as a mirror
+        // failure in a log line that assumed ordering. Extracted to a standalone
+        // function so the outcome-gating is unit-testable with fake thunks,
+        // without standing up a live vault — see gitvault-deploy-hooks.test.ts.
+        return attachGitvaultDeployHooks(result, () => this.#tryMirrorPush(handle.repo_id, handle.keystore), () => this.#tryReconcileEnvelopeRecipients(handle.vault));
     }
     /**
      * Drain every unvaulted-override journal on this machine: push the exact
@@ -1053,6 +1294,114 @@ export class Gitvault {
         const out = await handle.vault.restoreObjectsInto(options.target_dir);
         return { refs: out.refs, generation: out.generation };
     }
+    // ── mirror (gitvault-mirror-and-recover, design D1/D2/D7) ─────────────────
+    /**
+     * Configure (or replace) the customer-owned mirror destination for one
+     * vault. Client-side ONLY — the destination + credential NAME are written
+     * beside the keystore (design D2); run402 never sees or stores a raw
+     * secret value. `s3://<bucket>/<prefix>` needs `credential`; a plain
+     * filesystem path needs none.
+     */
+    async mirrorSet(options) {
+        const [{ GitvaultKeystore }, { parseMirrorDestinationUrl, saveMirrorConfig }] = await Promise.all([this.#keystore(), this.#mirrorConfig()]);
+        const repoId = await this.#resolveRepoId(options);
+        const keystore = new GitvaultKeystore(options.keystore_root !== undefined ? { rootDir: options.keystore_root } : {});
+        const destination = parseMirrorDestinationUrl(options.destination_url, { region: options.region, endpoint: options.endpoint });
+        return saveMirrorConfig(keystore, { repo_id: repoId, destination, ...(options.credential ? { credential: options.credential } : {}) });
+    }
+    /** Remove the mirror config for one vault. Never touches the mirror's own bytes (design: config removal ≠ data deletion). */
+    async mirrorRemove(options = {}) {
+        const [{ GitvaultKeystore }, { removeMirrorConfig }] = await Promise.all([this.#keystore(), this.#mirrorConfig()]);
+        const repoId = await this.#resolveRepoId(options);
+        const keystore = new GitvaultKeystore(options.keystore_root !== undefined ? { rootDir: options.keystore_root } : {});
+        return { repo_id: repoId, ...removeMirrorConfig(keystore, repoId) };
+    }
+    /**
+     * What this machine and the mirror each believe: whether a mirror is
+     * configured, the newest generation the MIRROR holds and can chain-verify
+     * (keyless — never touches keys), the LIVE vault's newest generation (one
+     * read of the vault record), and — when they disagree — the closing
+     * command. Both honesty statements (design D8) ride every response.
+     */
+    async mirrorStatus(options = {}) {
+        const [{ GitvaultKeystore }, { readMirrorConfig, formatMirrorDestination }, { openGitvaultMirrorBackend }, { verifyGitvaultMirror }] = await Promise.all([
+            this.#keystore(), this.#mirrorConfig(), this.#mirrorBackend(), this.#recovery(),
+        ]);
+        const repoId = await this.#resolveRepoId(options);
+        const keystore = new GitvaultKeystore(options.keystore_root !== undefined ? { rootDir: options.keystore_root } : {});
+        const config = readMirrorConfig(keystore, repoId);
+        const base = { repo_id: repoId, validity_not_freshness: GITVAULT_MIRROR_VALIDITY_NOT_FRESHNESS_STATEMENT, keystore_still_required: GITVAULT_MIRROR_KEYSTORE_STILL_REQUIRED_STATEMENT };
+        if (!config) {
+            return { ...base, configured: false, destination: null, credential_kind: null, mirrored_generation: null, newest_generation: null, is_current: null, closing_command: null };
+        }
+        let mirroredGeneration = null;
+        try {
+            const backend = openGitvaultMirrorBackend(config.destination, repoId, config.credential);
+            const report = await verifyGitvaultMirror(backend, { keystore });
+            mirroredGeneration = report.recovered_generation;
+        }
+        catch {
+            // A configured-but-unreachable/empty mirror is still `configured: true` — the honest report is "unknown", not a thrown status call.
+        }
+        let newestGeneration = null;
+        try {
+            newestGeneration = (await this.get(repoId)).newest_generation;
+        }
+        catch {
+            /* the live vault read is best-effort here; the mirror half of status still answers */
+        }
+        const isCurrent = mirroredGeneration !== null && newestGeneration !== null ? mirroredGeneration === newestGeneration : null;
+        return {
+            ...base, configured: true, destination: formatMirrorDestination(config.destination), credential_kind: config.credential?.kind ?? null,
+            mirrored_generation: mirroredGeneration, newest_generation: newestGeneration, is_current: isCurrent,
+            closing_command: isCurrent === false ? "run402 repos mirror --backfill" : null,
+        };
+    }
+    /** List the vault's stored objects, diff against the mirror, fetch + hash-verify + write what's missing, in admission order. Resumable and idempotent. */
+    async mirrorSync(options = {}) {
+        const [{ GitvaultKeystore }, { mirrorSync }] = await Promise.all([this.#keystore(), this.#mirror()]);
+        const repoId = await this.#resolveRepoId(options);
+        const keystore = new GitvaultKeystore(options.keystore_root !== undefined ? { rootDir: options.keystore_root } : {});
+        return mirrorSync(this.#client, repoId, { keystore });
+    }
+    /** Keyless integrity probe against the CONFIGURED mirror: discovery + chain verification + closure/absence adjudication, never decryption (`run402 repos fsck --mirror`). */
+    async mirrorVerify(options = {}) {
+        const [{ GitvaultKeystore }, { readMirrorConfig }, { openGitvaultMirrorBackend }, { verifyGitvaultMirror }] = await Promise.all([
+            this.#keystore(), this.#mirrorConfig(), this.#mirrorBackend(), this.#recovery(),
+        ]);
+        const repoId = await this.#resolveRepoId(options);
+        const keystore = new GitvaultKeystore(options.keystore_root !== undefined ? { rootDir: options.keystore_root } : {});
+        const config = readMirrorConfig(keystore, repoId);
+        if (!config)
+            throw new LocalError(`no mirror is configured for ${repoId}`, "verifying gitvault mirror", { code: "GITVAULT_MIRROR_NOT_CONFIGURED", details: { repo_id: repoId }, next_actions: [{ action: "run402 repos mirror <destination>" }] });
+        const backend = openGitvaultMirrorBackend(config.destination, repoId, config.credential);
+        return verifyGitvaultMirror(backend, { keystore });
+    }
+    /**
+     * `r402s-recover` (design D4): rebuild a working git repository straight
+     * from a mirrored `source/<repo_id>/` prefix — NO SERVER INVOLVED. `source`
+     * is `s3://<bucket>[/<prefix>]` or a local directory; when it names more
+     * than one mirrored vault, pass `repo_id` explicitly. Recovery proves
+     * validity, never freshness (both honesty statements ride every result).
+     */
+    async recover(options) {
+        const [{ GitvaultKeystore }, { parseMirrorDestinationUrl }, { openGitvaultMirrorBackend, discoverMirroredRepoIds }, { recoverGitvaultMirror }] = await Promise.all([
+            this.#keystore(), this.#mirrorConfig(), this.#mirrorBackend(), this.#recovery(),
+        ]);
+        const keystore = new GitvaultKeystore(options.keystore_root !== undefined ? { rootDir: options.keystore_root } : {});
+        const destination = parseMirrorDestinationUrl(options.source, { region: options.region, endpoint: options.endpoint });
+        let repoId = options.repo_id;
+        if (!repoId) {
+            const found = await discoverMirroredRepoIds(destination, options.credential);
+            if (found.length === 0)
+                throw new LocalError(`${options.source} holds no mirrored vault (no source/<repo_id>/ prefix found)`, "recovering gitvault vault", { code: "GITVAULT_MIRROR_EMPTY", details: { source: options.source } });
+            if (found.length > 1)
+                throw new LocalError(`${options.source} holds ${found.length} mirrored vaults; pass repo_id to pick one`, "recovering gitvault vault", { code: "GITVAULT_MIRROR_AMBIGUOUS", details: { source: options.source, repo_ids: found }, next_actions: found.map((id) => ({ action: `recover --repo ${id}` })) });
+            repoId = found[0];
+        }
+        const backend = openGitvaultMirrorBackend(destination, repoId, options.credential);
+        return recoverGitvaultMirror({ backend, out_dir: options.out_dir, keystore, ...(options.recovery_receipt ? { recovery_receipt: options.recovery_receipt } : {}) });
+    }
     // ── internals ─────────────────────────────────────────────────────────────
     async #resolveRepoId(options) {
         if (options.repo_id)
@@ -1085,6 +1434,18 @@ export class Gitvault {
     #address() {
         return nodeOnly(() => import("../node/gitvault-address.js"), "resolveOrCreateAddress");
     }
+    #mirror() {
+        return nodeOnly(() => import("../node/gitvault-mirror.js"), "mirrorSync");
+    }
+    #mirrorConfig() {
+        return nodeOnly(() => import("../node/gitvault-mirror-config.js"), "mirrorSet");
+    }
+    #mirrorBackend() {
+        return nodeOnly(() => import("../node/gitvault-mirror-backend.js"), "mirrorSet");
+    }
+    #recovery() {
+        return nodeOnly(() => import("../node/gitvault-recover.js"), "recover");
+    }
 }
 // ─── D7 — progressive terminal-loss warning (repo-first-onramp task 2.7) ────
 //