run402 4.41.0 → 4.43.0

package/sdk/dist/namespaces/gitvault.js

@@ -28,8 +28,8 @@
  * docs/agent-response-design.md a secret-bearing response is never cached,
  * 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 { LocalError, isRun402Error } from "../errors.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)
@@ -98,7 +98,7 @@ export class Gitvault {
     }
     /**
      * Every vault the organization owns, one round trip — `repos list`'s bulk
-     * read (repo-surface-consolidation task 2.4). See {@link
+     * read. See {@link
      * GitvaultOrgVaultsListing}'s doc comment for the FROZEN response shape and
      * the 404-until-shipped fallback contract.
      */
@@ -122,8 +122,8 @@ export class Gitvault {
         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>`.
+     * 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
@@ -135,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
@@ -212,6 +212,56 @@ export class Gitvault {
      * instrument for heartbeat/release. Never log it, never cache it, never place
      * it in an agent-surface result store.
      */
+    // ── epoch rotation ceremonies + declarations (D193-D203, rev 42) ──────────
+    //
+    // Five isomorphic, no-local-key-material API calls (owner + step-up,
+    // `gitvault.rotate`) — same "direct #client.request" shape as `setPolicy`/
+    // `completeOverride` above. The actual ROTATION (sampling K_e, sealing
+    // envelopes, submitting the head) needs the Node-only keystore + crypto
+    // core and lives on `GitvaultVault` (`sdk/src/node/gitvault-publication.ts`);
+    // see {@link rotateEpoch} / {@link rotateEpochForKeyRevocation} below.
+    /** `POST …/recipients/:principal_id/confirm` (D197) — first-seen pin confirmation. */
+    async confirmRecipient(repoId, principalId, newFingerprint) {
+        return this.#client.request(`/gitvault/v1/vaults/${encodeURIComponent(repoId)}/recipients/${encodeURIComponent(principalId)}/confirm`, {
+            method: "POST", body: { new_fingerprint: newFingerprint }, context: "confirming a gitvault recipient's first pin",
+        });
+    }
+    /** `POST …/recipients/:principal_id/repin` (D197) — re-pin ceremony. */
+    async repinRecipient(repoId, principalId, input) {
+        return this.#client.request(`/gitvault/v1/vaults/${encodeURIComponent(repoId)}/recipients/${encodeURIComponent(principalId)}/repin`, {
+            method: "POST", body: input, context: "re-pinning a gitvault recipient",
+        });
+    }
+    /**
+     * `POST …/recipients/:principal_id/key-revocation` (D199) — declares
+     * `reason:"recipient_key_revoked"` admissible for the NEXT rotation this
+     * org's vaults submit; org-scoped, advances the same watermark a member
+     * removal does. Returns the D194 counters — the ONE client-visible read of
+     * them, which is why {@link rotateEpochForKeyRevocation} exists as the
+     * fully self-contained entry point.
+     */
+    async declareRecipientKeyRevoked(repoId, principalId) {
+        return this.#client.request(`/gitvault/v1/vaults/${encodeURIComponent(repoId)}/recipients/${encodeURIComponent(principalId)}/key-revocation`, {
+            method: "POST", body: {}, context: "declaring a gitvault recipient key revoked",
+        });
+    }
+    /**
+     * `POST …/epoch-secret-exposure` (D199) — declares `reason:"epoch_secret_exposed"`
+     * admissible for THIS vault (deliberately vault-scoped, not org-wide — one
+     * vault's leaked `K_repo`/`K_e` is not evidence any sibling vault is
+     * compromised). This is the rekey remedy for a leaked/exposed vault key:
+     * declare exposure here, then drive a `rotate_epoch` with
+     * `reason:"epoch_secret_exposed"` (the required counters must be supplied
+     * from a source other than this call — see {@link rotateEpoch}'s doc
+     * comment on the confirmed gap in what the gateway exposes today).
+     */
+    async declareEpochSecretExposed(repoId) {
+        return this.#client.request(`/gitvault/v1/vaults/${encodeURIComponent(repoId)}/epoch-secret-exposure`, { method: "POST", body: {}, context: "declaring a gitvault epoch secret exposed" });
+    }
+    /** `POST …/writer-authority/declare-unavailable` (D202) — an explicit, audited fact that the writer signing key is gone. */
+    async declareWriterAuthorityUnavailable(repoId) {
+        return this.#client.request(`/gitvault/v1/vaults/${encodeURIComponent(repoId)}/writer-authority/declare-unavailable`, { method: "POST", body: {}, context: "declaring gitvault writer authority unavailable" });
+    }
     async acquireMaintenanceLease(request) {
         const { repo_id, ...body } = request;
         return this.#client.request(`/gitvault/v1/vaults/${encodeURIComponent(repo_id)}/maintenance-leases`, {
@@ -300,9 +350,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.
@@ -544,6 +594,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" });
@@ -554,18 +624,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();
@@ -576,13 +656,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.
@@ -610,8 +687,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.
@@ -679,8 +756,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,
         };
@@ -737,14 +816,13 @@ export class Gitvault {
             protocol_refs: "allow",
             ...(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
+        const result = await handle.vault.push(push).catch((e) => { throw this.#enrichEpochRotationRequired(e, handle.repo_id); });
+        // 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.
@@ -752,6 +830,43 @@ export class Gitvault {
         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. */
+    /**
+     * `EPOCH_ROTATION_REQUIRED` (D193) is left THROWN — never swallowed into a
+     * silent auto-rotation — because this call site cannot legally decide the
+     * two D194 counters (`recipient_state_version`/`recipient_revocation_version`)
+     * a rotation attempt must be fenced against: no shipped gateway route
+     * exposes them for `reason:"member_removed"`/`"elective_rekey"`/
+     * `"epoch_secret_exposed"` (verified against the live gateway route
+     * source — see `GitvaultVault.rotateEpoch`'s own doc comment). Submitting
+     * a GUESSED pair would either fail loudly (`RECIPIENT_SET_MISMATCH`, the
+     * honest outcome) or — worse — never be reachable at all for a fresh
+     * counter row. Rather than let a caller decode `details.migration_required`/
+     * `revocation_outstanding`/`exposure_outstanding` themselves, this
+     * decorates the SAME thrown error with the exact next command for each
+     * cause (`repos access repair` / `repos access revoke-key` / `repos
+     * access declare-exposure`) so "the next push" surfaces its own remedy
+     * instead of an opaque 409 — "wire into the natural path" without
+     * pretending a blind retry could ever succeed.
+     */
+    #enrichEpochRotationRequired(e, repoId) {
+        if (!isRun402Error(e) || e.code !== "EPOCH_ROTATION_REQUIRED")
+            return e;
+        // Mirrors `epochRotationRequiredNextActions` in
+        // `../node/gitvault-deploy.ts` byte-for-byte (same three causes, same
+        // three commands) — kept as a small standalone copy rather than a
+        // shared import so this namespace-level module (isomorphic — Deno/Bun/V8
+        // isolates, no Node-only imports) never has to pull in the Node-only
+        // deploy module just to decode three booleans. Update BOTH on drift.
+        const details = e.details ?? {};
+        const nextActions = [];
+        if (details.migration_required)
+            nextActions.push({ action: "run402 repos access repair", why: "this vault predates rev-42 epoch rotation and must complete one first-ever rotation (owner + step-up)" });
+        if (details.revocation_outstanding)
+            nextActions.push({ action: "run402 repos access revoke-key <principal_id>", why: "an org membership removal or key revocation is outstanding for this vault (owner + step-up)" });
+        if (details.exposure_outstanding)
+            nextActions.push({ action: "run402 repos access declare-exposure", why: "this vault's own epoch secret has been declared exposed (owner + step-up)" });
+        return new LocalError(`this vault requires a rotate_epoch admission before an ordinary push is admissible (repo_id ${repoId})`, "pushing to gitvault", { code: "EPOCH_ROTATION_REQUIRED", details, next_actions: nextActions.length > 0 ? nextActions : undefined, cause: e });
+    }
     async #tryMirrorPush(repoId, keystore) {
         try {
             const { mirrorPushForGeneration } = await this.#mirror();
@@ -1178,6 +1293,78 @@ export class Gitvault {
         const handle = await this.open(options);
         return handle.vault.reconcileEnvelopeRecipients();
     }
+    /**
+     * Drive one epoch rotation (D193-D203, rev 42) — the client half of
+     * epoch rotation: sample a fresh `K_e`, compute the H-partition from live
+     * desired-recipient state + the effective pin manifest, seal one
+     * `key_envelope` per included recipient, submit the create-only
+     * `rotation_attempt_descriptor`, submit the `rotate_epoch` head, verify
+     * this principal's own envelope opens to the committed key (when it is
+     * itself a recipient), and advance the local keystore's epoch pointer.
+     * See {@link import("../node/gitvault-publication.js").GitvaultVault.
+     * rotateEpoch}'s own doc comment for the full obligations and — load-
+     * bearing — the confirmed gap in what the gateway exposes for
+     * `recipient_state_version`/`recipient_revocation_version` outside the
+     * `recipient_key_revoked` reason, and (also load-bearing) `options.
+     * pending_confirmations` for folding a receipted `/confirm`/`/repin`
+     * result into THIS rotation's head instead of a separately-gated
+     * `publishPinManifestUpdate` call.
+     */
+    async rotateEpoch(options) {
+        const handle = await this.open(options);
+        return handle.vault.rotateEpoch(options);
+    }
+    /**
+     * The ONE fully self-contained rotation entry point: declares
+     * `reason:"recipient_key_revoked"` for `principalId` (owner + step-up)
+     * and drives the rotation from that call's OWN returned counters — no
+     * external counter source needed. The rekey remedy for the exact witness
+     * task 5.0 records: a specific member's key is compromised/should no
+     * longer be trusted.
+     */
+    async rotateEpochForKeyRevocation(principalId, options = {}) {
+        const handle = await this.open(options);
+        return handle.vault.rotateEpochForKeyRevocation(principalId, options);
+    }
+    /**
+     * Publish a receipted `recipient_pin_manifest` update (D197) — the
+     * publication half of the `/confirm`/`/repin` ceremonies above. Call
+     * after {@link confirmRecipient}/{@link repinRecipient} returns a receipt;
+     * this is `gitvault.writer`-sufficient (the owner-gated half already
+     * happened at the ceremony route).
+     *
+     * **This publish is an ORDINARY admission** and is therefore itself
+     * refused `EPOCH_ROTATION_REQUIRED` while this vault has a migration/
+     * revocation/exposure condition outstanding (D193) — reproduced live in
+     * production 2026-08-27. `#enrichEpochRotationRequiredForPinManifest`
+     * below decorates that refusal with the remedy: fold the SAME receipt
+     * into `rotateEpoch({..., pending_confirmations: [...]})` instead, which
+     * durably publishes it on a `rotate_epoch` admission (the gate's own
+     * escape valve) rather than a separately-gated ordinary one.
+     */
+    async publishPinManifestUpdate(input) {
+        const handle = await this.open(input);
+        return handle.vault
+            .publishPinManifestUpdate({ principal_id: input.principal_id, ek_fingerprint: input.ek_fingerprint, confirmed_by: "operator_confirmation", receipt: input.receipt })
+            .catch((e) => { throw this.#enrichEpochRotationRequiredForPinManifest(e, handle.repo_id); });
+    }
+    /**
+     * `EPOCH_ROTATION_REQUIRED` from a `publishPinManifestUpdate` call names
+     * the SAME three causes {@link #enrichEpochRotationRequired} decodes for
+     * `push()`, but the remedy is different: a manifest-only publish should
+     * fold into the NEXT `rotateEpoch` call via `pending_confirmations`
+     * rather than run a separate migration/revocation/exposure rotation
+     * first and publish again afterward — one admission instead of two, and
+     * the only path that works at all while EVERY predecessor-confirmed
+     * principal is already exhausted (see `GitvaultVault.rotateEpoch`'s own
+     * doc comment for the honest residual: this does not rescue a vault with
+     * zero ever-confirmed principals, which needs an operator-side fix).
+     */
+    #enrichEpochRotationRequiredForPinManifest(e, repoId) {
+        if (!isRun402Error(e) || e.code !== "EPOCH_ROTATION_REQUIRED")
+            return e;
+        return new LocalError(`this vault requires a rotate_epoch admission before an ordinary pin-manifest publish is admissible (repo_id ${repoId}) — fold this SAME receipt into rotateEpoch({..., pending_confirmations: [{principal_id, ek_fingerprint, receipt}]}) instead of retrying this call`, "publishing a recipient_pin_manifest update", { code: "EPOCH_ROTATION_REQUIRED", details: e.details, next_actions: [{ action: "r.gitvault.rotateEpoch({..., pending_confirmations: [{principal_id, ek_fingerprint, receipt}]})", why: "the manifest publish rides the SAME head as the required rotation, which is EPOCH_ROTATION_REQUIRED's own escape valve — a standalone publish never is" }], cause: e });
+    }
     /**
      * `repos access` (repo-surface-consolidation D5/D10) — a READ-ONLY report
      * of who can open this vault, composed from whatever the live gateway
@@ -1199,42 +1386,100 @@ export class Gitvault {
             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`.
+        // `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 stay empty.
+            // 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));
-        const unmatched = coverage.recipient_fingerprints.filter((fp) => !directoryFingerprints.has(fp));
+        // 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: this read has no per-epoch view, only the vault's " +
+                "CURRENT coverage — a recipient covered here may still be excluded from a PAST epoch's key (forward revocation is exactly what " +
+                "an epoch rotation buys). 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 yet completed a rotation away from them. pending_removal does NOT mean revoked — with " +
+                "covered:true they still decrypt this vault until an owner runs `repos access repair` (or, for a targeted key, `repos access " +
+                "revoke-key`); see stale_access for exactly who, and next_actions for the exact command."
+            : "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,
-            envelope_state_available: false,
+            this_keystore: thisKeystore,
+            stale_access: staleAccess,
+            envelope_state_available: envelopeStateAvailable,
             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.",
+            gap,
+            ...(staleAccess.length > 0
+                ? {
+                    next_actions: [
+                        { action: "run402 repos access repair", why: "re-key this vault's current epoch away from every principal in stale_access at once (owner + step-up)" },
+                        { action: "run402 repos access revoke-key <principal_id>", why: "target exactly one stale_access principal for revocation-triggered rotation (owner + step-up)" },
+                    ],
+                }
+                : {}),
         };
     }
     /**
@@ -1474,10 +1719,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");
@@ -1494,12 +1745,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`);
@@ -1507,10 +1754,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}`;