run402 4.40.0 → 4.42.0

package/sdk/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_MIRROR_KEYSTORE_STILL_REQUIRED_STATEMENT, GITVAULT_MIRROR_VALIDITY_NOT_FRESHNESS_STATEMENT, GITVAULT_TERMINAL_LOSS_DOCTOR_TEXT, GITVAULT_TERMINAL_LOSS_STATEMENT, } from "./gitvault.crypto.js";
+import { GITVAULT_DURABILITY_STATEMENT, 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)
@@ -97,8 +97,33 @@ export class Gitvault {
         return this.#client.request(`/gitvault/v1/vaults?project_id=${encodeURIComponent(projectId)}`, { context: "resolving the project's gitvault" });
     }
     /**
-     * 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>`.
+     * Every vault the organization owns, one round trip — `repos list`'s bulk
+     * read. 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` —
+     * `GET /gitvault/v1/vaults?repo=<org-slug>/<name>`.
      * `RESOURCE_NOT_FOUND` for no such org OR no such name (deliberately
      * collapsed — see the design's slug-namespace-probing note);
      * `SLUG_RELEASED` (read it with {@link gitvaultSlugReleasedInfo}) while the
@@ -110,7 +135,7 @@ export class Gitvault {
     }
     /**
      * Resolve a parsed remote address (`parseGitvaultRemoteUrl`'s output),
-     * dispatching on its form (design D6): id-form resolves exactly like
+     * dispatching on its form: id-form resolves exactly like
      * {@link forProject}; slug-form resolves via {@link forRepo}. A pure read —
      * no pinning, no creation. Node-only callers wanting BOTH should use
      * {@link resolveOrCreateAddress} instead, which also drives the local pin
@@ -275,9 +300,9 @@ export class Gitvault {
     }
     /**
      * Resolve a parsed remote address to an OPEN handle, pinning `repo_id` in
-     * local git state on the first successful slug-form resolution (design D6,
-     * task 4.5), and — when `allow_create` is set and resolution misses —
-     * push-to-create it (task 4.4/4.5). This is what the remote helper and
+     * local git state on the first successful slug-form resolution, and —
+     * when `allow_create` is set and resolution misses —
+     * push-to-create it. This is what the remote helper and
      * `gitvault snapshot` drive for a `run402::<org-slug>/<name>` remote; an
      * id-form remote resolves through here too (no pin, since it needs none)
      * so a caller need not branch on the address's form itself.
@@ -519,6 +544,26 @@ export class Gitvault {
                 pending = [];
             }
         }
+        // Best-effort covering-recipient count (dogfood item 2): the same
+        // envelope-recipients read `access()` uses. Decides whether the V0-A
+        // single-principal terminal-loss statement is still honest to print for
+        // THIS vault, or whether this client has locally proven a second covering
+        // recipient. Only attempted when a vault record is already in hand
+        // (`record` non-null means the credentials that fetched it already work)
+        // — a session-less or offline caller never pays for a second failing
+        // request, and any failure here falls back to exactly today's
+        // single-principal behavior, never a new failure mode for `status`.
+        let coveringRecipients = null;
+        if (repoId && record) {
+            try {
+                const coverage = await this.#client.request(`/gitvault/v1/vaults/${encodeURIComponent(repoId)}/envelope-recipients`, { context: "reading the gitvault envelope recipients" });
+                coveringRecipients = coverage.recipient_fingerprints.length;
+            }
+            catch {
+                coveringRecipients = null;
+            }
+        }
+        const isMultiPrincipal = coveringRecipients !== null && coveringRecipients >= 2;
         const warnings = [...(record?.warnings ?? [])];
         if (keystorePresent && !canSign) {
             warnings.push({ kind: "read_only", message: "the signing key is missing from identity.json — this principal can decrypt and verify but cannot publish a new head" });
@@ -529,18 +574,28 @@ export class Gitvault {
         // D7 (repo-first-onramp task 2.7): a vault that has accrued enough value
         // at risk gets a STANDING warning instead of the one-time genesis note.
         // `record` is `null` for an unallocated project, which is the ordinary
-        // "nothing to warn about" shape, not a gap in this check.
+        // "nothing to warn about" shape, not a gap in this check. Once this
+        // client has locally proven >= 2 covering recipients, the SAME threshold
+        // still fires — real value at risk still deserves a standing reminder —
+        // but the copy downgrades to `keystore_backup_reminder`, which never
+        // claims terminal loss (dogfood item 2: the single-principal premise
+        // behind `terminal_loss_risk` is provably false for this vault).
         if (record) {
             const trip = gitvaultLossWarningTrip(record);
             if (gitvaultLossWarningTripped(trip)) {
-                warnings.push({ kind: "terminal_loss_risk", message: gitvaultLossWarningMessage(trip) });
+                if (isMultiPrincipal) {
+                    warnings.push({ kind: "keystore_backup_reminder", message: gitvaultKeystoreBackupReminderMessage(trip, coveringRecipients) });
+                }
+                else {
+                    warnings.push({ kind: "terminal_loss_risk", message: gitvaultLossWarningMessage(trip) });
+                }
             }
         }
-        // The local id-pin, when there is a repository to read it from (design
-        // D6, task 4.5) — a pure read, same discipline as `remote` below. Read
+        // The local id-pin, when there is a repository to read it from — a pure
+        // read, same discipline as `remote` below. Read
         // BEFORE `remote` so a slug-form remote's `matches` comparison can use
         // it: the pin is the only LOCAL ground truth a slug-form address's own
-        // URL text does not carry (kychee-com/run402#562).
+        // URL text does not carry.
         let pinned = null;
         if (options.repo_dir) {
             const { readPinnedGitvaultRepo } = await this.#address();
@@ -551,13 +606,10 @@ export class Gitvault {
         // pure read: `status` must never write git configuration.
         //
         // Checks BOTH conventional names, `run402` first then `origin` —
-        // matching `scaffoldRemote`'s own naming (design D1: it claims `origin`
+        // matching `scaffoldRemote`'s own naming: it claims `origin`
         // additively when the repository has none yet, falling back to `run402`
-        // only when `origin` is already taken by something else). The common
-        // case is therefore an `origin` remote, not a `run402` one — checking
-        // only "run402" (the pre-fix behavior) reported `remote: null` for most
-        // repositories even though a run402-form remote was sitting right there
-        // under `origin` (kychee-com/run402#559c). A name whose URL exists but
+        // only when `origin` is already taken by something else. The common
+        // case is therefore an `origin` remote, not a `run402` one. A name whose URL exists but
         // does not parse as a run402 address (someone's own unrelated remote
         // happening to be named "run402") is skipped rather than reported, so
         // the other conventional name still gets a chance.
@@ -585,8 +637,8 @@ export class Gitvault {
                 }
                 else {
                     // Slug-form: the URL's second half is a repo NAME, not a project
-                    // id — comparing it against `project` always mismatched, even for
-                    // a perfectly-configured remote (kychee-com/run402#562). The only
+                    // id — comparing it against `project` would always mismatch, even for
+                    // a perfectly-configured remote. The only
                     // LOCAL ground truth for a slug-form remote's real identity is the
                     // id-pin; without one there is nothing to compare against, and
                     // that absence is NOT evidence of a mismatch.
@@ -620,11 +672,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,
@@ -654,8 +706,10 @@ export class Gitvault {
             pins: { highest_authenticated: authenticated, highest_materialized: materialized },
             gitvault_policy: record?.gitvault_policy ?? null,
             pending_overrides: pending.length,
-            terminal_loss_statement: GITVAULT_TERMINAL_LOSS_STATEMENT,
-            terminal_loss_detail: GITVAULT_TERMINAL_LOSS_DOCTOR_TEXT,
+            covering_recipients: coveringRecipients,
+            terminal_loss_statement: isMultiPrincipal ? null : GITVAULT_TERMINAL_LOSS_STATEMENT,
+            terminal_loss_detail: isMultiPrincipal ? null : GITVAULT_TERMINAL_LOSS_DOCTOR_TEXT,
+            durability_statement: isMultiPrincipal ? GITVAULT_DURABILITY_STATEMENT : null,
             warnings,
             next_actions: nextActions,
         };
@@ -713,13 +767,12 @@ export class Gitvault {
             ...(options.checkpoint ? { checkpoint: true } : {}),
         };
         const result = await handle.vault.push(push);
-        // Capture-time dual-push hook (design D6/task 2.4): fires only when a
+        // Capture-time dual-push hook: 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,
+        // Deploy-time reconcile hook: 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.
@@ -952,7 +1005,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 });
@@ -1075,7 +1128,55 @@ 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
@@ -1086,19 +1187,133 @@ export class Gitvault {
      * gateway `public_key` gap, and why this is a workaround rather than the
      * eventual epoch-rotation design).
      *
-     * `run402 gitvault reconcile [--repo <id>]` is the explicit standalone
-     * CLI surface (design D5's "session start" hook). `deploy()` runs this
-     * itself, 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.
+     * `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);
+        // `desired` is OPTIONAL on the wire (see GitvaultEnvelopeRecipientsResponse):
+        // absent means an older gateway that predates this field — genuinely
+        // unknown, not "no desired recipients." Distinguish "absent" from
+        // "present and empty" via the array itself, not a boolean flag, so a
+        // null/undefined check is the single source of truth for both this
+        // method and any future caller of the same wire type.
+        const desiredList = coverage.desired ?? null;
+        const envelopeStateAvailable = desiredList !== null;
+        const desiredByPrincipal = new Map(desiredList?.map((d) => [d.principal_id, d]) ?? []);
+        // Node-only, best-effort: THIS machine's own local TOFU pins, and this
+        // keystore's own encryption-key fingerprint (used below to keep the
+        // vault creator's own machine out of `unmatched_covered_fingerprints` —
+        // the org directory only lists human-enrolled keys, so a wallet-principal
+        // creator's fingerprint is legitimately absent from it, not orphaned).
+        // Never fails the whole read — a browser/worker caller, or a machine that
+        // has never wrapped anyone, simply reports every `tofu_pin` as `null` and
+        // `this_keystore` as `null`.
+        let pins = {};
+        let ownFingerprint = null;
+        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 ?? {};
+            ownFingerprint = keystore.readIdentity()?.encryption_fingerprint ?? null;
+        }
+        catch {
+            // Not Node, or no local keystore for this repo — pins/ownFingerprint stay empty/null.
+        }
+        const recipients = directory.keys.map((k) => {
+            const pinned = pins[k.principal_id];
+            const desired = desiredByPrincipal.get(k.principal_id) ?? null;
+            const envelopeState = desired == null ? null : desired.status === "pending_removal" ? "pending_removal" : covered.has(k.ek_fingerprint) ? "converged" : "pending";
+            return {
+                principal_id: k.principal_id,
+                display_name: k.display_name,
+                fingerprint: k.ek_fingerprint,
+                covered: covered.has(k.ek_fingerprint),
+                envelope_state: envelopeState,
+                tofu_pin: pinned !== undefined ? { fingerprint: pinned, matches_directory: pinned === k.ek_fingerprint } : null,
+            };
+        });
+        const directoryFingerprints = new Set(directory.keys.map((k) => k.ek_fingerprint));
+        // Removed members (desired status pending_removal) whose fingerprint is
+        // STILL covered: real, continuing access that membership removal did not
+        // revoke, because gitvault v0 has no epoch-rotation mechanism yet. See
+        // GitvaultAccessResult's doc comment.
+        const staleAccess = (desiredList ?? [])
+            .filter((d) => d.status === "pending_removal" && d.ek_fingerprint != null && covered.has(d.ek_fingerprint))
+            .map((d) => ({ principal_id: d.principal_id, display_name: d.display_name, fingerprint: d.ek_fingerprint }));
+        const staleAccessFingerprints = new Set(staleAccess.map((s) => s.fingerprint));
+        // Genuinely unexplained: covering fingerprints that match neither a
+        // current directory entry NOR a desired-state row (already broken out
+        // above as stale_access) — orphaned, externally revoked, or a recipient
+        // outside this org's membership model entirely. THIS keystore's own
+        // fingerprint is a separate, locally-provable case: the org directory
+        // only lists human-enrolled keys, so the vault creator's own
+        // wallet-principal keystore legitimately never appears there — that is
+        // not orphaned/external, it is provably this machine, so it is broken
+        // out into `this_keystore` instead of left to read as a misconfiguration.
+        const unmatchedRaw = coverage.recipient_fingerprints.filter((fp) => !directoryFingerprints.has(fp) && !staleAccessFingerprints.has(fp));
+        const thisKeystore = ownFingerprint !== null && unmatchedRaw.includes(ownFingerprint) ? { fingerprint: ownFingerprint, covered: true } : null;
+        const unmatched = thisKeystore ? unmatchedRaw.filter((fp) => fp !== thisKeystore.fingerprint) : unmatchedRaw;
+        const gap = envelopeStateAvailable
+            ? "history_scope (which epochs each recipient can read) is not available: gitvault protocol v0 pins a single fixed epoch for a " +
+                "vault's entire lifetime, so there is no per-epoch scope to report — that lands with the epoch-rotation protocol revision " +
+                "gitvault-human-envelopes is mid-fold on, under adversarial review. envelope_state per recipient IS available today, from the " +
+                `gateway's desired-recipient-state substrate (desired_state_version ${String(coverage.desired_state_version ?? "unknown")}): ` +
+                "\"converged\" means desired and covered, \"pending\" means desired but not yet wrapped, \"pending_removal\" means membership " +
+                "removed them but this vault has not been re-keyed away from them. pending_removal does NOT mean revoked — with covered:true " +
+                "they still decrypt this vault's entire history, past and future, until epoch rotation ships; see stale_access for exactly who."
+            : "the gateway did not report desired-recipient state (desired[]) for this vault_id — likely an older gateway than this SDK " +
+                "expects, so per-recipient envelope_state and stale_access are unavailable. history_scope is unavailable regardless: gitvault " +
+                "protocol v0 pins a single fixed epoch, so there is no per-epoch scope to report. 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.";
+        return {
+            repo_id: repoId,
+            org_id: orgId,
+            recipients,
+            unmatched_covered_fingerprints: unmatched,
+            this_keystore: thisKeystore,
+            stale_access: staleAccess,
+            envelope_state_available: envelopeStateAvailable,
+            history_scope_available: false,
+            gap,
+        };
+    }
     /**
      * The push-gated deploy: both lanes under one fresh `capture_id`, resolving
      * to exactly one of five outcomes — `DEPLOYED_AND_VAULTED`,
@@ -1216,7 +1431,7 @@ export class Gitvault {
         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 gitvault mirror sync" : null,
+            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. */
@@ -1226,7 +1441,7 @@ export class Gitvault {
         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 gitvault mirror verify`). */
+    /** 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(),
@@ -1235,7 +1450,7 @@ export class Gitvault {
         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 gitvault mirror set <destination>" }] });
+            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 });
     }
@@ -1336,10 +1551,16 @@ export const GITVAULT_LOSS_WARNING_THRESHOLDS = {
  * strings (protocol convention for values that could exceed safe-integer
  * precision in principle; comfortably within it here).
  *
- * There is deliberately no companion "is this resolved" function: V0-A
- * cannot detect a second principal or human envelope able to open the vault
- * (design D7's stricter-than-drafted resolution), so once tripped this has
- * nothing further to compute — a caller does not un-trip it, ever, in V0.
+ * There is deliberately no companion "is this resolved" function on the
+ * TRIP computation itself: whether the generations/bytes/days thresholds
+ * crossed is independent of how many principals cover the vault, and this
+ * function stays a pure threshold check forever — a caller does not un-trip
+ * it, ever, in V0. What DOES now exist, one call site up in `status()`, is a
+ * way to downgrade the COPY once tripped: a locally-provable read of the
+ * vault's covering-recipient count (the same envelope-recipients read
+ * `Gitvault.access` uses) can show this is no longer the single-principal
+ * case the message below describes. See
+ * {@link gitvaultKeystoreBackupReminderMessage} for that downgraded form.
  */
 export function gitvaultLossWarningTrip(record, now = new Date()) {
     const generations = Number(record.admitted_generations ?? "0");
@@ -1356,12 +1577,8 @@ export function gitvaultLossWarningTrip(record, now = new Date()) {
 export function gitvaultLossWarningTripped(trip) {
     return trip.generations || trip.source_bytes || trip.days_since_genesis;
 }
-/**
- * The standing warning text (design D7): names what tripped, states the
- * resolution honestly (a second principal or human envelope — nothing this
- * client can verify yet), and never claims an attestation would clear it.
- */
-export function gitvaultLossWarningMessage(trip) {
+/** Shared by both D7 message forms below — which threshold(s) tripped, in prose. */
+function gitvaultLossWarningReasons(trip) {
     const reasons = [];
     if (trip.generations)
         reasons.push(`≥${GITVAULT_LOSS_WARNING_THRESHOLDS.generations} generations`);
@@ -1369,10 +1586,41 @@ export function gitvaultLossWarningMessage(trip) {
         reasons.push(`≥${Math.round(GITVAULT_LOSS_WARNING_THRESHOLDS.source_bytes / (1024 * 1024))} MB of source`);
     if (trip.days_since_genesis)
         reasons.push(`≥${GITVAULT_LOSS_WARNING_THRESHOLDS.days_since_genesis} days since genesis`);
+    return reasons;
+}
+/**
+ * The standing warning text (design D7): names what tripped, states the
+ * resolution honestly (a second principal or human envelope — nothing this
+ * client can verify yet), and never claims an attestation would clear it.
+ *
+ * This is the SINGLE-PRINCIPAL form — use it only when the vault's
+ * covering-recipient count is unknown or <= 1. Once a caller has locally
+ * proven >= 2 covering recipients, its premise ("only one principal can open
+ * it") is false; use {@link gitvaultKeystoreBackupReminderMessage} instead.
+ */
+export function gitvaultLossWarningMessage(trip) {
+    const reasons = gitvaultLossWarningReasons(trip);
     return (`this vault has accrued real value at risk (${reasons.join(", ")}) while only one principal can open it. ` +
         "Only a second principal — another keystore, or later a human envelope — demonstrably able to open the vault clears this warning; " +
         "this client cannot verify that yet, so it stands until you add one. No attestation or flag clears it.");
 }
+/**
+ * D7's downgraded form (dogfood item 2): once `status()` has locally proven
+ * this vault carries >= 2 covering recipients (via the same envelope-recipients
+ * read `Gitvault.access` uses), the single-principal premise behind
+ * {@link gitvaultLossWarningMessage} is false for THIS vault — printing it
+ * anyway would be a false terminal-loss claim. The composite threshold still
+ * fires the SAME way (this function does not touch `gitvaultLossWarningTrip`/
+ * `gitvaultLossWarningTripped` at all — a real value-at-risk signal is still
+ * worth a reminder), but the copy switches to the protocol's own
+ * keystore-qualified durability sentence instead of asserting single-principal
+ * risk, and never claims terminal loss.
+ */
+export function gitvaultKeystoreBackupReminderMessage(trip, coveringRecipients) {
+    const reasons = gitvaultLossWarningReasons(trip);
+    return (`this vault has accrued real value at risk (${reasons.join(", ")}), but it is covered by ${coveringRecipients} recipients today — not the single-principal case. ` +
+        `${GITVAULT_DURABILITY_STATEMENT} Back up this machine's keystore anyway: losing it does not lose the vault, but it does lose YOUR access to it.`);
+}
 /** `run402::<org_id>/<project_id>` — what `git-remote-run402` resolves. */
 export function gitvaultRemoteUrl(orgId, projectId) {
     return `run402::${orgId}/${projectId}`;