run402 4.68.2 → 4.69.0

package/sdk/dist/node/gitvault-publication.js

@@ -39,10 +39,11 @@ import { join } from "node:path";
 import { LocalError, isRun402Error } from "../errors.js";
 import { fetchGitvaultObjectBytes } from "./gitvault-edge-fetch.js";
 import { openGitvaultDestinationBackend } from "./gitvault-mirror-backend.js";
-import { GITVAULT_FORMAT, GITVAULT_GENESIS_EPOCH, GITVAULT_GENESIS_GENERATION, GITVAULT_HEX16_RE, GITVAULT_OID40_RE, GITVAULT_SUITE, attemptKeyCommitment, bytesToHex, checkFreshEpochKeyAgainstPriorKeys, checkHPartition, computeRotationId, computeTargetPartitionDigest, deriveDigestKey, deriveObjectKey, ekFingerprint, epochRotationKeyCommitment, formatGitvaultTimestamp, fromBase64url, hexToBytes, jcs, keyEnvelopeLedgerId, keyedCommitment, newGitvaultId, newHex32, nextEpoch, objectsetContent, openBindingPreimage, openEpochRotationForRecipient, openFrame, parseGitvaultStrict, parseRotateEpochPayload, pinManifestLedgerId, randomBytes, sealFrame, sealKeyEnvelope, sha256Hex, signGitvaultObject, storedBytes, storedBytesSha256, toBase64url, verifyGitvaultObject, } from "../namespaces/gitvault.crypto.js";
+import { GITVAULT_FORMAT, GITVAULT_GENESIS_EPOCH, GITVAULT_GENESIS_GENERATION, GITVAULT_HEX16_RE, GITVAULT_OID40_RE, GITVAULT_SUITE, attemptKeyCommitment, bytesToHex, checkFreshEpochKeyAgainstPriorKeys, checkHPartition, computeRotationId, computeTargetPartitionDigest, deriveDigestKey, deriveObjectKey, ekFingerprint, vkFingerprint, GITVAULT_TERMINAL_LOSS_DOCTOR_TEXT, GITVAULT_TERMINAL_LOSS_STATEMENT, epochRotationKeyCommitment, formatGitvaultTimestamp, fromBase64url, hexToBytes, jcs, keyEnvelopeLedgerId, keyedCommitment, newGitvaultId, newHex32, nextEpoch, objectsetContent, openBindingPreimage, openEpochRotationForRecipient, openFrame, parseAddWriterKeyPayload, parseGitvaultStrict, parseRotateEpochPayload, pinManifestLedgerId, randomBytes, sealFrame, sealKeyEnvelope, sha256Hex, signGitvaultObject, storedBytes, storedBytesSha256, toBase64url, verifyGitvaultObject, } from "../namespaces/gitvault.crypto.js";
 import { GITVAULT_ZERO_SHA256_SENTINEL } from "../namespaces/gitvault.types.js";
 import { gitvaultCheckpointStaleness } from "../namespaces/gitvault.js";
 import { crossProfileGitvaultHint } from "./gitvault-profile-scan.js";
+import { applyAddWriterKey, applyWriterSetUpdate, buildAddWriterKeyActivationPayload, buildWriterDoorAddWriterKeyPayload, initialWriterState, resolveActiveWriter, validateAddWriterKeyPayload, validateWriterSetUpdate, writerKeyIdOf, } from "./gitvault-writer-state.js";
 import { GITVAULT_DEPLOY_REF, hardenedGit, hasObject, hasObjects, isAncestor } from "./gitvault-snapshot.js";
 // ─── Constants (constants.json) ──────────────────────────────────────────────
 export const GITVAULT_MAX_CANONICAL_REFS = 10_000;
@@ -533,14 +534,20 @@ export function checkChainLink(input) {
  * rotation is ACTIVATED") — `checkChainLink`'s own D194 epoch-continuity
  * check already validates its structural admissibility, and
  * {@link parseRotateEpochPayload} / the caller's own envelope-open step
- * (`GitvaultVault.verifyToNewest`) handle it fully. The other three kinds
- * (`add_envelope`, `add_writer_key`, `transfer_binding`) remain genuinely
- * unactivated and stay fail-closed exactly as before.
+ * (`GitvaultVault.verifyToNewest`) handle it fully. `add_writer_key` is
+ * EXEMPT as of rev 47 (gitvault-multi-writer) the same way — {@link
+ * parseAddWriterKeyPayload} + `validateAddWriterKeyPayload`
+ * (`gitvault-writer-state.js`) handle it fully, INSIDE `verifyToNewest`'s
+ * own loop, BEFORE this function ever runs on that head (so a transition
+ * that fails writer validation never reaches here at all — this function
+ * only ever sees ones that already passed). The other two kinds
+ * (`add_envelope`, `transfer_binding`) remain genuinely unactivated and stay
+ * fail-closed exactly as before.
  */
 export function assertNoTransition(head) {
     if (head.transition === null)
         return;
-    if (head.transition.kind === "rotate_epoch")
+    if (head.transition.kind === "rotate_epoch" || head.transition.kind === "add_writer_key")
         return;
     const kinds = ["add_envelope", "rotate_epoch", "add_writer_key", "transfer_binding"];
     if (!kinds.includes(head.transition.kind))
@@ -791,12 +798,9 @@ export function createGitvaultHttpTransport(client, options = {}) {
             if (isRun402Error(e) && e.code === "RESOURCE_NOT_FOUND")
                 return null;
             // The gateway accepts `{object_kind: "recipient_pin_manifest",
-            // pin_manifest_version}` reads (fixed 2026-08-28; before that its
-            // null-idScalar validation was hardcoded to key_envelope's
-            // `{epoch, recipient_fingerprint}` shape and 400'd every such read
-            // with "epoch must be 16 hex"). A VALIDATION_FAILED here therefore
+            // pin_manifest_version}` reads. A VALIDATION_FAILED here therefore
             // indicates a genuinely malformed request and propagates as-is —
-            // EXCEPT the pre-fix epoch-shape complaint, which a fixed gateway can
+            // EXCEPT the epoch-shape complaint, which a current gateway can
             // never emit for this kind: that signature can only mean an unfixed
             // (older/staging) gateway behind RUN402_API_BASE, so name it rather
             // than letting it read as a client validation bug.
@@ -1339,7 +1343,7 @@ export function createGitvaultHttpTransport(client, options = {}) {
                 parsed = null;
             }
             if (!r.ok) {
-                // kychee-com/run402#578 fix 1: the gateway's error envelope is FLAT
+                // The gateway's error envelope is FLAT
                 // (docs/style.md §Errors — `buildErrorEnvelope` in the gateway) —
                 // `code`, `message`, `details`, `trace_id`, and `next_actions` all
                 // ride at the TOP level, never nested under an `error` object (that
@@ -1593,6 +1597,7 @@ export class GitvaultVault {
     stateRestorePlan = null;
     retries;
     servicePublicKey;
+    allowUnauthenticatedSalvage;
     genesisCache = null;
     /**
      * gitvault-byo-primary-bucket task 3.2 — this vault's resolved BYO write
@@ -1613,6 +1618,7 @@ export class GitvaultVault {
         this.budget = options.verification_budget ?? GITVAULT_VERIFICATION_BUDGET_HEADS;
         this.retries = options.conflict_retries ?? GITVAULT_PUSH_CONFLICT_RETRIES;
         this.servicePublicKey = options.service_public_key ?? null;
+        this.allowUnauthenticatedSalvage = options.allow_unauthenticated_salvage ?? false;
     }
     static open(options) {
         const v = new GitvaultVault(options);
@@ -1620,7 +1626,7 @@ export class GitvaultVault {
         return v;
     }
     repoFile() {
-        // Cross-profile hint (kychee-com/run402#564): a keystore-miss on the
+        // Cross-profile hint: a keystore-miss on the
         // ACTIVE profile is enriched, when the scan finds one, with which OTHER
         // local wallet profile holds this repo's key — a purely local
         // directory/filename read, appended after the existing remedy rather
@@ -1638,6 +1644,137 @@ export class GitvaultVault {
         }
         return repo;
     }
+    /**
+     * gitvault-agent-envelopes D4 — the COLD OPEN. A keystore that holds an
+     * identity but no repo file for this vault (a member joining from a fresh
+     * machine, or a creator whose repo file was lost) restores `K_repo` from
+     * its OWN `key_envelope` instead of dying `GITVAULT_REPO_STATE_MISSING`:
+     *
+     *   1. genesis (the writer-key source) is fetched and signature-verified;
+     *   2. its creator fingerprints are compared against the control plane's
+     *      SIGNED allocation record — `platform_attested`, never `receipt`
+     *      (the platform serves both sides of that comparison; a substituted
+     *      genesis needs a substituted allocation, which the org's owners can
+     *      see — TOFU + audit, human-envelopes D4's tier);
+     *   3. the envelope-recipients read says whether THIS fingerprint is
+     *      covered — if not, `GITVAULT_ENVELOPE_PENDING` names the key-holders
+     *      who can fulfil and the exact next actions (never a terminal error:
+     *      the desired state already records this member; any key-holder's
+     *      next gitvault operation wraps);
+     *   4. the base envelope is fetched, opened, and the repo file written
+     *      `restored_from_envelope` with the genesis hash PINNED (a later open
+     *      seeing a different genesis for this repo_id refuses
+     *      `VAULT_CREATION_CONFLICT`).
+     *
+     * Rotation epochs are NOT opened here — `verifyToNewest` walks them and
+     * opens each rotation-scoped envelope this identity is included in, exactly
+     * as it does for every other reader (`openEpochRotationForRecipient`).
+     *
+     * Returns `null` when the repo file already existed (nothing restored).
+     */
+    async ensureRepoState() {
+        if (this.keystore.readRepo(this.repoId))
+            return null;
+        const identity = this.keystore.readIdentity();
+        if (!identity) {
+            fail("KEYSTORE_MISSING", "no gitvault identity in the keystore", "opening gitvault vault", undefined, [
+                { action: "restore ~/.config/run402/gitvault from backup or accept vault loss" },
+                ...crossProfileGitvaultHint(this.repoId),
+            ]);
+        }
+        const ownKeypair = this.keystore.encryptionKeypair(identity);
+        if (!ownKeypair) {
+            fail("VAULT_UNRECOVERABLE", GITVAULT_TERMINAL_LOSS_DOCTOR_TEXT, "opening gitvault vault", { statement: GITVAULT_TERMINAL_LOSS_STATEMENT, repo_id: this.repoId });
+        }
+        const ownFingerprint = identity.encryption_fingerprint;
+        const genesisBytes = await this.transport.getGenesis({ repo_id: this.repoId });
+        if (!genesisBytes)
+            fail("CHAIN_BROKEN", "the vault has no admitted genesis", "opening gitvault vault", { repo_id: this.repoId });
+        const genesis = parseGitvaultStrict(new TextDecoder().decode(genesisBytes));
+        if (genesis.epoch !== GITVAULT_GENESIS_EPOCH) {
+            fail("VAULT_CREATION_CONFLICT", `the served genesis declares epoch ${genesis.epoch}, not the genesis epoch`, "opening gitvault vault", { repo_id: this.repoId, epoch: genesis.epoch });
+        }
+        if (genesis.repo_id !== this.repoId) {
+            fail("VAULT_CREATION_CONFLICT", `the served genesis names repo ${genesis.repo_id}, not ${this.repoId}`, "opening gitvault vault", { repo_id: this.repoId, served: genesis.repo_id });
+        }
+        // Platform-attested creator anchor. The allocation is optional on the
+        // wire (older gateways) — absent means the restore is unauthenticated
+        // salvage, and the result says so.
+        let allocationAttested = false;
+        const record = await this.transport.getVaultRecord({ repo_id: this.repoId });
+        const allocation = record.allocation ?? null;
+        if (!allocation && !this.allowUnauthenticatedSalvage) {
+            // Consult round 2 §5: an absent allocation on an ordinary open is not a
+            // downgrade to salvage — it is a refusal. A malicious or broken serving
+            // path that cannot forge the SIGNED allocation must not get a vault
+            // opened by simply omitting it.
+            fail("GITVAULT_ALLOCATION_UNATTESTED", "the control plane returned no signed allocation record for this vault — refusing an unattested cold restore (recovery flows may opt into explicit unauthenticated salvage)", "opening gitvault vault", { repo_id: this.repoId });
+        }
+        if (allocation) {
+            const genesisEk = ekFingerprint(fromBase64url(genesis.creator_encryption_pubkey, "genesis.creator_encryption_pubkey"));
+            const genesisVk = vkFingerprint(fromBase64url(genesis.creator_signing_pubkey, "genesis.creator_signing_pubkey"));
+            if (genesisEk !== allocation.creator_encryption_fingerprint || genesisVk !== allocation.creator_signing_fingerprint) {
+                fail("VAULT_CREATION_CONFLICT", "the served genesis's creator keys do not match the control plane's signed allocation record for this vault — refusing a substituted genesis", "opening gitvault vault", { repo_id: this.repoId, genesis_creator_encryption_fingerprint: genesisEk, allocation_creator_encryption_fingerprint: allocation.creator_encryption_fingerprint, genesis_creator_signing_fingerprint: genesisVk, allocation_creator_signing_fingerprint: allocation.creator_signing_fingerprint });
+            }
+            allocationAttested = true;
+        }
+        const coverage = await this.transport.listEnvelopeRecipients({ repo_id: this.repoId });
+        if (!coverage.recipient_fingerprints.includes(ownFingerprint)) {
+            // Who can fulfil: every current directory recipient that IS covered
+            // (they hold K_repo), named by principal id — best-effort, the read may
+            // 403 for a caller whose membership is still propagating.
+            let keyHolders = [];
+            try {
+                const directory = await this.transport.listOrgEncryptionKeys({ org_id: genesis.org_id });
+                keyHolders = directory.keys
+                    .filter((k) => coverage.recipient_fingerprints.includes(k.ek_fingerprint))
+                    .map((k) => ({ principal_id: k.principal_id, display_name: k.display_name ?? null, ek_fingerprint: k.ek_fingerprint }));
+            }
+            catch {
+                // best-effort — the refusal is complete without the roster
+            }
+            const desired = coverage.desired?.find((d) => d.ek_fingerprint === ownFingerprint) ?? null;
+            fail("GITVAULT_ENVELOPE_PENDING", `this keystore (fingerprint ${ownFingerprint}) is not yet a recipient on vault ${this.repoId} — no key_envelope has been wrapped for it; a key-holder's next gitvault operation fulfils the org's desired state`, "opening gitvault vault", {
+                repo_id: this.repoId,
+                org_id: genesis.org_id,
+                own_fingerprint: ownFingerprint,
+                desired_state: desired ? desired.status : (coverage.desired ? "not_desired" : "unknown"),
+                key_holders: keyHolders,
+                covering_recipient_count: coverage.recipient_fingerprints.length,
+            }, [
+                { action: "run402 repos access", why: "poll — this_keystore.covered_on_this_vault flips true once a key-holder has wrapped this vault to your key" },
+                { action: "ask a key-holder to run any gitvault operation (run402 repos view / git push)", why: "a key-holding client wraps every pending desired recipient on its next operation; nothing else is required of them" },
+            ]);
+        }
+        const envelopeBytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.envelope(genesis.epoch, ownFingerprint) });
+        if (!envelopeBytes) {
+            fail("GITVAULT_EPOCH_NOT_OPENABLE", `the envelope-recipients read lists this keystore (fingerprint ${ownFingerprint}) as covered, but its base key_envelope could not be retrieved — a server-side or network problem, not a problem with your key; retry`, "opening gitvault vault", { repo_id: this.repoId, epoch: genesis.epoch, recipient_fingerprint: ownFingerprint, reason: "envelope_fetch_failed" });
+        }
+        const envelope = parseGitvaultStrict(new TextDecoder().decode(envelopeBytes));
+        if (envelope.repo_id !== this.repoId || envelope.epoch !== genesis.epoch || envelope.recipient_fingerprint !== ownFingerprint) {
+            fail("GITVAULT_ENVELOPE_ALTERED", "the retrieved base key_envelope does not address this vault, epoch, and recipient — refusing to open it", "opening gitvault vault", { repo_id: this.repoId, epoch: genesis.epoch, recipient_fingerprint: ownFingerprint, envelope: { repo_id: envelope.repo_id, epoch: envelope.epoch, recipient_fingerprint: envelope.recipient_fingerprint } });
+        }
+        const restored = await this.keystore.restoreRepoFromEnvelope({ genesis, envelope, allocation_attested: allocationAttested });
+        this.keystore.writeCachedGenesis(this.repoId, restored.repo.genesis_sha256, genesisBytes);
+        this.genesisCache = { genesis, sha256: restored.repo.genesis_sha256 };
+        return {
+            repo_id: this.repoId,
+            org_id: genesis.org_id,
+            provenance: "restored_from_envelope",
+            trust: restored.trust,
+            continuity: restored.continuity,
+            independently_verified: restored.independently_verified,
+            epoch: envelope.epoch,
+            recipient_fingerprint: ownFingerprint,
+        };
+    }
+    /** {@link open}, but a missing repo file triggers {@link ensureRepoState} first. */
+    static async openOrRestore(options) {
+        const v = new GitvaultVault(options);
+        const restored = await v.ensureRepoState();
+        v.repoFile();
+        return { vault: v, restored };
+    }
     kRepo() { return hexToBytes(this.repoFile().k_repo_hex); }
     epoch() { return this.repoFile().epoch; }
     /**
@@ -1946,10 +2083,44 @@ export class GitvaultVault {
         const decryptValidate = options.decryptValidate ?? false;
         const strict = options.strict ?? true;
         const { genesis, sha256: genesisSha } = await this.genesis();
+        // gitvault-multi-writer rev 47: `writerKey`/`writerKeyId` (kept for the
+        // rotation-envelope open below, which is signed by whoever DROVE that
+        // specific rotation — resolved per-rotation from `writerState`, not this
+        // fallback) name just the genesis creator, retained as the seed for
+        // `writerState` and as the fallback signer for methods that do not
+        // resolve a per-rotation writer.
         const writerKey = genesis.creator_signing_pubkey;
         const writerKeyId = genesis.writer_key_id;
         const repo = this.repoFile();
         let pin = repo.verified_prefix ?? repo.head_pin ?? { generation: GITVAULT_GENESIS_GENERATION, head_sha256: genesisSha, pinned_at: formatGitvaultTimestamp(this.now()) };
+        // gitvault-multi-writer rev 47 (task 5.1): the writer set as chain state.
+        // Trusted as the starting point at `pin`'s generation exactly the same
+        // way `pin` itself is trusted as the starting point for the head chain —
+        // `writer_set_pin` advances in LOCKSTEP with `head_pin`/`verified_prefix`
+        // (see `GitvaultRepoFile.writer_set_pin`'s own doc comment), so a repeat
+        // call never re-walks the writer set from genesis. `initialWriterState`
+        // covers the true first-ever call (no persisted pin yet).
+        //
+        // `burnedWriterKeyIds`/`consumedHandoffIds` are NOT persisted and reset
+        // to empty on every resume — deliberately, not an oversight. This is safe
+        // for THIS function's own job (verifying an ALREADY-ADMITTED chain):
+        // the gateway is the sole admission authority, so a burned key or a
+        // consumed handoff_id can never appear in a real `add_writer_key`
+        // transition on the actual chain — the gateway already refused it before
+        // it could be admitted. These two sets only matter as a CLIENT-SIDE
+        // pre-check before PROPOSING a new transition (tasks 5.4/5.5), where an
+        // incomplete local set costs at most a wasted round trip — the gateway's
+        // own fence-time re-check (which DOES hold the complete history) is the
+        // real backstop either way. If a future caller ever needs these complete
+        // across a resume, persist them on `writer_set_pin` too; not needed yet.
+        let writerState = repo.writer_set_pin
+            ? { version: repo.writer_set_pin.version, writers: repo.writer_set_pin.writers, sha256: repo.writer_set_pin.sha256, burnedWriterKeyIds: new Set(), consumedHandoffIds: new Set() }
+            : initialWriterState(this.repoId, genesis);
+        const persistWriterSetPin = () => {
+            if (!persist)
+                return;
+            this.keystore.updateRepo(this.repoId, { writer_set_pin: { version: writerState.version, sha256: writerState.sha256, writers: [...writerState.writers], pinned_at: formatGitvaultTimestamp(this.now()) } });
+        };
         // gitvault-composite-state-read design D1: try the pin-current fast path
         // FIRST — see {@link tryStateFastPath}'s own doc comment. `null` means
         // ineligible (genuinely more than one generation behind, or the pin's
@@ -2033,7 +2204,11 @@ export class GitvaultVault {
                         payload: rot.payload,
                         own_fingerprint: ownFingerprint,
                         own_encryption_keypair: ownKeypair,
-                        writer_signing_public_key: writerKey,
+                        // gitvault-multi-writer rev 47: the writer who actually drove
+                        // THIS rotation (resolved by the forward walk when it collected
+                        // `rot` — see `GitvaultEncounteredRotation.signing_pubkey`'s own
+                        // doc comment for the one narrower gap this falls back for).
+                        writer_signing_public_key: rot.signing_pubkey ?? writerKey,
                         get_envelope_bytes: (path) => this.transport.getObject({ repo_id: this.repoId, path }),
                         envelope_path: (epoch, fp, rotationId) => gitvaultPaths.envelope(epoch, fp, rotationId),
                     });
@@ -2050,7 +2225,12 @@ export class GitvaultVault {
                 // Design D2: ref_state + retention_roots both ride `head`, so one
                 // batched presign (or a cache hit) serves both instead of two
                 // independent presign-then-GET round trips.
-                const { refState, roots } = await this.openMaterializeCarriers(head.ref_state, gitvaultPaths.refState(head.ref_state.object_id), head.retention_roots, gitvaultPaths.retentionRoots(head.retention_roots.object_id), writerKey, { epoch: head.epoch, k_repo: kRepo });
+                // gitvault-multi-writer rev 47: `head`'s OWN signer, resolved from
+                // the writer state — by the time this runs, `writerState` already
+                // reflects `head`'s own transition (if any), so this correctly finds
+                // a just-self-admitted handoff writer too, not only a pre-existing one.
+                const headSigner = resolveActiveWriter(writerState, head.writer_key_id)?.signing_pubkey ?? writerKey;
+                const { refState, roots } = await this.openMaterializeCarriers(head.ref_state, gitvaultPaths.refState(head.ref_state.object_id), head.retention_roots, gitvaultPaths.retentionRoots(head.retention_roots.object_id), headSigner, { epoch: head.epoch, k_repo: kRepo });
                 if (refState.generation !== head.generation || roots.generation !== head.generation)
                     fail("CHAIN_UNUSABLE", "carrier generation does not match the head", "materializing gitvault head");
                 decryptedRefState = refState;
@@ -2157,6 +2337,7 @@ export class GitvaultVault {
                 if (verified >= this.budget) {
                     if (persist)
                         this.keystore.updateRepo(this.repoId, { verified_prefix: pin });
+                    persistWriterSetPin();
                     persistMaterializedIfAny();
                     fail("VERIFICATION_BUDGET_EXCEEDED", persist
                         ? `${verified} heads verified this call; the verified prefix (generation ${pin.generation}) is persisted — call again to continue`
@@ -2166,7 +2347,53 @@ export class GitvaultVault {
                 if (!bytes)
                     fail("CHAIN_BROKEN", `listed head ${entry.generation} is absent from storage`, "verifying gitvault chain", { generation: entry.generation });
                 const head = parseGitvaultStrict(new TextDecoder().decode(bytes));
-                checkChainLink({ head, stored_bytes: bytes, listed_sha256: entry.stored_bytes_sha256, expected_generation: nextGeneration(pin.generation), prev_sha256: pin.head_sha256, repo_id: this.repoId, writer_public_key: writerKey, writer_key_id: writerKeyId, prev_epoch: prevEpoch });
+                // gitvault-multi-writer rev 47 (task 5.1): resolve WHO must have
+                // signed this specific head from the writer state as of the
+                // PREDECESSOR generation (`writerState`, not yet advanced past this
+                // head) — never the single fixed genesis key. A head carrying an
+                // admitted `add_writer_key` transition is the one case the signer
+                // might NOT already be in `writerState`: the "handoff" door is
+                // self-signed by the key being added, which is only proven legitimate
+                // by `validateAddWriterKeyPayload` succeeding on THIS SAME payload —
+                // so that validation runs BEFORE signature verification, not after,
+                // and its own success is what licenses trusting `added_writer.signing_pubkey`
+                // as the correct verification key.
+                const failClosedTransition = (code, detail) => {
+                    if (persist)
+                        this.keystore.updateRepo(this.repoId, { head_pin: pin, verified_prefix: null });
+                    persistWriterSetPin();
+                    persistMaterializedIfAny();
+                    fail(code, `head ${head.generation}: ${detail}`, "verifying gitvault chain", { generation: head.generation });
+                };
+                const isWriterAdd = head.transition !== null && head.transition.kind === "add_writer_key";
+                let addWriterKeyPayload = null;
+                let resolvedWriterPubkey = writerKey;
+                let resolvedWriterKeyId = writerKeyId;
+                if (isWriterAdd) {
+                    addWriterKeyPayload = parseAddWriterKeyPayload(head); // throws CHAIN_BROKEN on any wire-shape defect
+                    const v = validateAddWriterKeyPayload(this.repoId, writerState, addWriterKeyPayload, head.writer_key_id);
+                    if (!v.ok)
+                        failClosedTransition(v.code, v.detail);
+                    if (addWriterKeyPayload.authorization.kind === "writer") {
+                        // The head's own signer is an EXISTING writer — same resolution as the ordinary case below.
+                        const signer = resolveActiveWriter(writerState, head.writer_key_id); // non-null: v.ok already proved it
+                        resolvedWriterPubkey = signer.signing_pubkey;
+                        resolvedWriterKeyId = signer.writer_key_id;
+                    }
+                    else {
+                        // "handoff" door: self-signed by the key being admitted — validated above, not yet in writerState.
+                        resolvedWriterPubkey = addWriterKeyPayload.added_writer.signing_pubkey;
+                        resolvedWriterKeyId = addWriterKeyPayload.added_writer.writer_key_id;
+                    }
+                }
+                else {
+                    const signer = resolveActiveWriter(writerState, head.writer_key_id);
+                    if (!signer)
+                        failClosedTransition("GITVAULT_WRITER_NOT_ADMITTED", `writer_key_id ${head.writer_key_id} is not a currently admitted writer`);
+                    resolvedWriterPubkey = signer.signing_pubkey;
+                    resolvedWriterKeyId = signer.writer_key_id;
+                }
+                checkChainLink({ head, stored_bytes: bytes, listed_sha256: entry.stored_bytes_sha256, expected_generation: nextGeneration(pin.generation), prev_sha256: pin.head_sha256, repo_id: this.repoId, writer_public_key: resolvedWriterPubkey, writer_key_id: resolvedWriterKeyId, prev_epoch: prevEpoch });
                 try {
                     assertNoTransition(head);
                 }
@@ -2174,6 +2401,7 @@ export class GitvaultVault {
                     // fail closed: pin stays BELOW the transition head; the verified prefix is cleared (this is the final state, not a budget pause)
                     if (persist)
                         this.keystore.updateRepo(this.repoId, { head_pin: pin, verified_prefix: null });
+                    persistWriterSetPin();
                     persistMaterializedIfAny();
                     throw e;
                 }
@@ -2186,7 +2414,33 @@ export class GitvaultVault {
                     // later `materialize()` call over an already-chain-verified prefix
                     // can still resolve the epoch keys it needs.
                     rotationPayload = parseRotateEpochPayload(head);
-                    rotations.push({ generation: head.generation, epoch: head.epoch, payload: rotationPayload });
+                    rotations.push({ generation: head.generation, epoch: head.epoch, payload: rotationPayload, signing_pubkey: resolvedWriterPubkey });
+                    // gitvault-multi-writer rev 47 (D227): writer REMOVAL rides
+                    // rotate_epoch as an additive `writer_set_update` field. The
+                    // "blocked set" gate inside `validateWriterSetUpdate` is a
+                    // gateway-only, live-state fact this reader cannot independently
+                    // re-derive (the module's own header doc names this boundary) —
+                    // trusting the update's OWN declared `removed[]` as the "blocked
+                    // set" input makes that ONE check a structural no-op while every
+                    // OTHER invariant (base/next commitments, the writers-array
+                    // arithmetic, the signer-survives-or-explicit-terminal rule) is
+                    // still independently re-verified in full. Honest: this reader
+                    // trusts the GATEWAY already answered "were these the right keys
+                    // to remove" at admission time, same as it already trusts every
+                    // other admission decision it did not itself make.
+                    if (rotationPayload.writer_set_update) {
+                        const wsu = rotationPayload.writer_set_update;
+                        const declaredBlocked = new Set(wsu.removed.map((r) => r.writer_key_id));
+                        const allowEmpty = wsu.writers.length === 0;
+                        const wv = validateWriterSetUpdate(this.repoId, writerState, wsu, head.writer_key_id, declaredBlocked, allowEmpty);
+                        if (!wv.ok)
+                            failClosedTransition(wv.code, wv.detail);
+                        writerState = applyWriterSetUpdate(this.repoId, writerState, wsu.removed.map((r) => r.writer_key_id));
+                    }
+                }
+                if (isWriterAdd && addWriterKeyPayload) {
+                    const consumedHandoffId = addWriterKeyPayload.authorization.kind === "handoff" ? addWriterKeyPayload.authorization.grant.handoff_id ?? null : null;
+                    writerState = applyAddWriterKey(this.repoId, writerState, { writer_key_id: addWriterKeyPayload.added_writer.writer_key_id, signing_pubkey: addWriterKeyPayload.added_writer.signing_pubkey }, consumedHandoffId);
                 }
                 prevEpoch = head.epoch;
                 pin = { generation: head.generation, head_sha256: entry.stored_bytes_sha256, pinned_at: formatGitvaultTimestamp(this.now()) };
@@ -2205,6 +2459,7 @@ export class GitvaultVault {
             // verified prefix persists per page (resumable) — skipped entirely in no-write mode
             if (persist)
                 this.keystore.updateRepo(this.repoId, { verified_prefix: pin });
+            persistWriterSetPin();
             persistMaterializedIfAny();
             const next = nextListingRequest(request, page);
             if (!next)
@@ -2240,9 +2495,16 @@ export class GitvaultVault {
             while (cur && !epochKeys[cur.epoch]) {
                 if (cur.transition !== null && cur.transition.kind === "rotate_epoch") {
                     const payload = parseRotateEpochPayload(cur);
-                    backwardRotations.unshift({ generation: cur.generation, epoch: cur.epoch, payload });
+                    // gitvault-multi-writer rev 47: best-effort resolution against the
+                    // FINAL (post-forward-walk) writer state — correct unless `cur`'s
+                    // own signer was removed by a LATER rotation between `cur` and
+                    // `lastHead`, the one documented residual gap (falls back to the
+                    // genesis-creator key at the `openEpochRotationForRecipient`
+                    // call site when this resolves to `undefined`).
+                    const curSigner = resolveActiveWriter(writerState, cur.writer_key_id)?.signing_pubkey;
+                    backwardRotations.unshift({ generation: cur.generation, epoch: cur.epoch, payload, signing_pubkey: curSigner });
                     if (!rotations.some((r) => r.generation === cur.generation))
-                        rotations.push({ generation: cur.generation, epoch: cur.epoch, payload });
+                        rotations.push({ generation: cur.generation, epoch: cur.epoch, payload, signing_pubkey: curSigner });
                 }
                 if (cur.generation === "0000000000000001") {
                     cur = null;
@@ -2277,6 +2539,7 @@ export class GitvaultVault {
         }
         if (persist)
             this.keystore.updateRepo(this.repoId, { head_pin: pin, verified_prefix: null });
+        persistWriterSetPin();
         persistMaterializedIfAny();
         // `strict` (materialize()'s ordinary, fail-closed read path) is enforced
         // HERE, once, after the full keyless chain walk has already run to
@@ -2498,10 +2761,9 @@ export class GitvaultVault {
      * **This is task 1.1's residual WORKAROUND, not the design D5 ideal.** D5
      * describes a recipient-set change as an epoch rotation — "history epochs
      * stay wrapped as they were; a new member reads from their first covered
-     * epoch forward" — which needs a protocol revision (task 1, BLOCKED as of
-     * 2026-08-26: V0 pins `epoch` to the single constant
-     * `GITVAULT_GENESIS_EPOCH` on every head, so there is no "forward" to
-     * speak of yet). What this method actually does, legally, without any
+     * epoch forward" — which needs a protocol revision: V0 pins `epoch` to
+     * the single constant `GITVAULT_GENESIS_EPOCH` on every head, so there
+     * is no "forward" to speak of. What this method actually does, legally, without any
      * protocol change: `key_envelope` objects are never head-referenced (not
      * even genesis's own envelope is), so uploading an ADDITIONAL one at
      * `envelopes/<current epoch>/<recipient fingerprint>` for a missing
@@ -2524,7 +2786,7 @@ export class GitvaultVault {
      * this SDK does not make unattended.
      *
      * **The gateway directory route carries `public_key` on every row**
-     * (`GET /orgs/v1/:org_id/encryption-keys`, deployed 2026-08-26 — see the
+     * (`GET /orgs/v1/:org_id/encryption-keys` — see the
      * doc comment on {@link GitvaultOrgEncryptionKeyEntry}), so against a
      * current gateway entries actually wrap. A directory entry that arrives
      * WITHOUT the field (an older/rolling-deploy gateway) is still tolerated
@@ -2613,6 +2875,33 @@ export class GitvaultVault {
                 // recipient is now genuinely covered. Treat exactly that code as a
                 // benign race, not a failure; anything else propagates.
                 if (isRun402Error(e) && e.code === "GITVAULT_OBJECT_EXISTS_DIFFERENT") {
+                    // gitvault-agent-envelopes (consult 7.6): a benign race is only
+                    // benign once the WINNING envelope has been read back and verified
+                    // — same repo, same epoch, this recipient, signed by the vault's
+                    // registered writer. Anything else is recorded as skipped, never as
+                    // coverage, and never pinned.
+                    const winnerPath = gitvaultPaths.envelope(epoch, sealed.receipt.recipient_fingerprint);
+                    const winnerBytes = await this.transport.getObject({ repo_id: this.repoId, path: winnerPath }).catch(() => null);
+                    let winnerOk = false;
+                    if (winnerBytes) {
+                        try {
+                            const winner = parseGitvaultStrict(new TextDecoder().decode(winnerBytes));
+                            const g = (await this.genesis()).genesis;
+                            winnerOk = winner.repo_id === this.repoId && winner.epoch === epoch && winner.recipient_fingerprint === entry.ek_fingerprint
+                                && winner.created_by === g.writer_key_id
+                                && verifyGitvaultObject(winner, g.creator_signing_pubkey);
+                        }
+                        catch {
+                            winnerOk = false;
+                        }
+                    }
+                    if (!winnerOk) {
+                        // Consult round 2 §7: a conflicting IMMUTABLE object whose stored
+                        // winner does not verify is evidence of tampering, equivocation,
+                        // or broken object identity — categorically different from a
+                        // stale recipient. FATAL, never an ordinary skip.
+                        fail("GITVAULT_ENVELOPE_ALTERED", `a conflicting key_envelope already stored at ${winnerPath} does not verify as this vault's writer-signed envelope for this recipient — refusing to treat the conflict as a benign race`, "reconciling gitvault envelope recipients", { repo_id: this.repoId, path: winnerPath, epoch, recipient_fingerprint: entry.ek_fingerprint });
+                    }
                     alreadyCovered.push(entry.ek_fingerprint);
                 }
                 else {
@@ -2657,6 +2946,49 @@ export class GitvaultVault {
         return kp.seed;
     }
     writerKeyId() { return this.keystore.ensureIdentity().signing_fingerprint; }
+    /**
+     * gitvault-multi-writer (task 5.8) — the push pre-check: before signing an
+     * ORDINARY head (any operation that expects this session to already be an
+     * active writer), refuse EARLY and LOCALLY when this session's own key is
+     * not (or is no longer) an active writer, rather than let real
+     * crypto/upload work run only to be refused by the gateway with a less
+     * specific message once the head finally reaches it. Reads the FRESHLY-
+     * pinned `writer_set_pin`; every call site below calls this immediately
+     * after its own `materialize()`/`verifyToNewest()` (same generation the
+     * caller is about to build against), so this performs no verification of
+     * its own — it only reads what the caller already froze.
+     *
+     * `removedMidRace` (design D8/D10) distinguishes the two shapes this
+     * refusal takes: `false` (the default) is the ORDINARY pre-check — this
+     * session was never (or is not currently) an admitted writer, thrown as
+     * `GITVAULT_WRITER_NOT_ADMITTED`. `true` is the CAS-LOSER path
+     * specifically: a retry, after re-materializing from the winner, that
+     * discovers THIS session's own key was removed by whatever won the race —
+     * "stop if removed" in D8's loser-rule sequence (fetch winner → verify →
+     * apply writer transition → stop if removed → rebase → rebuild → bounded
+     * backoff) — thrown as the more specific, client-local
+     * `GITVAULT_WRITER_REMOVED` (D10) instead: a real prior attempt just lost
+     * to a removal, not a caller who was never eligible.
+     *
+     * Deliberately NOT called for a "handoff"-door `add_writer_key` head
+     * ({@link submitWriterActivationHead}): there the signer is BY DESIGN not
+     * yet a writer — becoming one is what that exact head does.
+     */
+    assertCallerIsWriter(context, removedMidRace = false) {
+        const pin = this.repoFile().writer_set_pin;
+        const myKey = this.writerKeyId();
+        if (pin && pin.writers.some((w) => w.writer_key_id === myKey))
+            return;
+        const code = removedMidRace ? "GITVAULT_WRITER_REMOVED" : "GITVAULT_WRITER_NOT_ADMITTED";
+        fail(code, removedMidRace
+            ? `this session's writer key (${myKey}) was removed while a conflicting head was admitted first`
+            : `this session's writer key (${myKey}) is not an active writer on this vault`, context, {}, [
+            {
+                type: "request_writer_sync",
+                why: "This session's key is not (yet, or no longer) an admitted writer on this vault. If you were just added as an org member, any current writer's next gitvault operation (push, deploy, or r.gitvault.reconcile()) admits pending writers automatically.",
+            },
+        ]);
+    }
     /** The owner's full signing keypair, or `GITVAULT_READ_ONLY` — same refusal path as {@link signer}, which returns only the seed; {@link sealKeyEnvelope} needs both halves. */
     signingKeypair() {
         const identity = this.keystore.ensureIdentity();
@@ -2872,7 +3204,17 @@ export class GitvaultVault {
         if (!block)
             fail("CHECKPOINT_INCOMPLETE", `head ${head.generation} carries no checkpoint to verify`, "verifying a stored checkpoint", { generation: head.generation });
         const { genesis } = await this.genesis();
-        const writerKey = genesis.creator_signing_pubkey;
+        // gitvault-multi-writer rev 47: `head` may have been signed by any
+        // CURRENTLY-KNOWN writer, not just the genesis creator — resolved from
+        // the keystore's persisted `writer_set_pin` (the same substrate
+        // `verifyToNewest` maintains), falling back to the genesis-creator key
+        // for a pre-rev-47 keystore or one that hasn't run `verifyToNewest` yet
+        // (byte-identical to this method's own pre-rev-47 behavior in that case).
+        // A writer removed SINCE this checkpoint's own head was admitted is the
+        // same documented residual as the backward-catch-up decrypt path above —
+        // `writer_set_pin` only remembers currently-active writers, not burned ones.
+        const pinnedWriters = this.repoFile().writer_set_pin?.writers ?? [];
+        const writerKey = pinnedWriters.find((w) => w.writer_key_id === head.writer_key_id)?.signing_pubkey ?? genesis.creator_signing_pubkey;
         const claimBytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.claimSet(block.claim_set.object_id), expected_sha256: block.claim_set.stored_bytes_sha256 });
         if (!claimBytes || sha256Hex(claimBytes) !== block.claim_set.stored_bytes_sha256) {
             fail("CHECKPOINT_INCOMPLETE", `checkpoint claim set ${block.claim_set.object_id} is absent or does not match the head's receipt`, "verifying a stored checkpoint", { object_id: block.claim_set.object_id });
@@ -2945,11 +3287,17 @@ export class GitvaultVault {
         const generations = [...chain.keys()].sort();
         const out = [];
         const { genesis } = await this.genesis();
+        // gitvault-multi-writer rev 47: `verifyToNewest()` above already
+        // persisted the current `writer_set_pin` — same per-head resolution as
+        // `verifyStoredCheckpoint`, same documented residual (a writer removed
+        // since falls back to the genesis-creator key).
+        const pinnedWriters = this.repoFile().writer_set_pin?.writers ?? [];
         for (const gen of generations) {
             const entry = chain.get(gen);
             let claimSet = null;
             const block = entry.head.checkpoint;
             if (block) {
+                const writerKey = pinnedWriters.find((w) => w.writer_key_id === entry.head.writer_key_id)?.signing_pubkey ?? genesis.creator_signing_pubkey;
                 // Plaintext-structured and stored-bytes-receipted: no decryption, but
                 // the hash and the owner signature are still checked before a single
                 // pack receipt inside it is believed.
@@ -2958,7 +3306,7 @@ export class GitvaultVault {
                     fail("CHECKPOINT_INCOMPLETE", `checkpoint claim set ${block.claim_set.object_id} (generation ${gen}) is absent or altered`, "walking the gitvault chain", { generation: gen, object_id: block.claim_set.object_id });
                 }
                 claimSet = parseGitvaultStrict(new TextDecoder().decode(bytes));
-                if (!verifyGitvaultObject(claimSet, genesis.creator_signing_pubkey)) {
+                if (!verifyGitvaultObject(claimSet, writerKey)) {
                     fail("CHECKPOINT_INCOMPLETE", `checkpoint claim set ${claimSet.object_id} signature fails`, "walking the gitvault chain", { generation: gen });
                 }
             }
@@ -3041,7 +3389,7 @@ export class GitvaultVault {
                 rawPackBytes += pack.length;
             }
         }
-        // kychee-com/run402#565: everything above this point is REAL local work —
+        // everything above this point is REAL local work —
         // real signing, real pack building, real encryption. Stopping HERE is what
         // makes the dry run honest: nothing below this line has run yet, so
         // nothing was uploaded and no generation was admitted.
@@ -3055,7 +3403,13 @@ export class GitvaultVault {
             ref_state: { object_id: refState.object.object_id, object_kind: "ref_state", ciphertext_sha256: refState.upload.sha256, size_bytes: refState.upload.size_bytes },
             retention_roots: { object_id: rootsObj.object.object_id, object_kind: "retention_roots", ciphertext_sha256: rootsObj.upload.sha256, size_bytes: rootsObj.upload.size_bytes },
             checkpoint, checkpoint_purpose: checkpoint ? "ordinary_push" : null, capture_binding: binding, repair: null,
-        });
+        }, 
+        // gitvault-multi-writer (task 5.6) — an `add_writer_key` activation
+        // head rides THIS same content-neutral machinery: `input.transition`
+        // is undefined for every pre-existing caller (push/publishCheckpoint),
+        // so their heads are byte-for-byte unchanged; `submitWriterActivationHead`
+        // below is the one caller that passes it.
+        input.transition !== undefined ? { transition: input.transition } : undefined);
         const admitted = await this.admit(head);
         if (admitted.outcome === "conflict")
             return { outcome: "conflict", generation, winner: admitted.winner };
@@ -3073,6 +3427,14 @@ export class GitvaultVault {
         let conflicts = 0;
         let base = options.base ?? (await this.materialize());
         for (;;) {
+            // gitvault-multi-writer (task 5.8) — checked fresh on EVERY attempt
+            // (including a CAS-loser retry, design D8's "stop if removed"): a
+            // concurrent rotation could remove this session's own writer key
+            // between one attempt and the next. `conflicts > 0` is exactly the
+            // CAS-loser path (this iteration only runs after losing a race and
+            // re-materializing from the winner) — GITVAULT_WRITER_REMOVED there,
+            // the ordinary GITVAULT_WRITER_NOT_ADMITTED on the first attempt.
+            this.assertCallerIsWriter("publishing gitvault head", conflicts > 0);
             const evaluation = await evaluateRefTransaction(base.refs, options.transaction, { isAncestor: (a, d) => isAncestor(this.git(), a, d), protocol_refs: options.protocol_refs });
             const published = await this.publishGeneration({
                 base, refs: evaluation.refs, dropped: evaluation.dropped, head_target: options.head_target ?? base.head_target,
@@ -3094,7 +3456,7 @@ export class GitvaultVault {
         }
     }
     /**
-     * A REAL preview of what {@link push} would publish (kychee-com/run402#565)
+     * A REAL preview of what {@link push} would publish
      * — runs the SAME local pipeline `push` runs (materialize → evaluate →
      * evolve retention roots → build refState/retentionRoots → build packs or a
      * checkpoint set → seal/encrypt) and stops BEFORE the two network
@@ -3302,9 +3664,9 @@ export class GitvaultVault {
      * `POST …/object-reads` rejected every `recipient_pin_manifest` read
      * (its null-`idScalar` validation was hardcoded to `key_envelope`'s
      * `{epoch, recipient_fingerprint}` shape, never generalized when D197
-     * shipped the second path-addressed kind), so the network fallback below
-     * always 400'd. That gateway bug is fixed (deployed and live-verified
-     * 2026-08-28): the network path works for any keystore, including
+     * shipped the second path-addressed kind), which 400'd the network
+     * fallback below. That gateway bug is fixed: the network path works for
+     * any keystore, including
      * §4.11's fresh-client "SEEDS its local pin file from it" onboarding.
      * The cache stays purely as the round-trip saver described above.
      */
@@ -3319,7 +3681,11 @@ export class GitvaultVault {
         }
         const manifest = parseGitvaultStrict(new TextDecoder().decode(bytes));
         const { genesis } = await this.genesis();
-        if (!verifyGitvaultObject(manifest, genesis.creator_signing_pubkey)) {
+        // gitvault-multi-writer rev 47: resolve the manifest's OWN declared
+        // signer against the persisted writer set (same pattern + same
+        // documented residual as `verifyStoredCheckpoint`/`chainEntries` above).
+        const manifestSigner = this.repoFile().writer_set_pin?.writers.find((w) => w.writer_key_id === manifest.writer_key_id)?.signing_pubkey ?? genesis.creator_signing_pubkey;
+        if (!verifyGitvaultObject(manifest, manifestSigner)) {
             fail("GITVAULT_SIGNATURE_INVALID", `recipient_pin_manifest ${receipt.pin_manifest_version} signature does not verify`, "resolving the effective recipient pin manifest", { pin_manifest_version: receipt.pin_manifest_version });
         }
         const pinnedFingerprintOf = new Map(manifest.pins.map((p) => [p.principal_id, p.ek_fingerprint]));
@@ -3392,6 +3758,7 @@ export class GitvaultVault {
         let conflicts = 0;
         for (;;) {
             const base = await this.materialize();
+            this.assertCallerIsWriter("publishing a recipient_pin_manifest update", conflicts > 0); // gitvault-multi-writer task 5.8
             const prior = await this.loadEffectivePinManifest(base.generation);
             const { nextVersion, manifestSha, upload: manifestUpload, pins } = this.buildPinManifestUpdate(prior, [input]);
             await this.uploadAll([manifestUpload]);
@@ -3459,10 +3826,10 @@ export class GitvaultVault {
      * `publishPinManifestUpdate` is an ORDINARY admission (`transition:
      * null`) and is therefore itself refused `EPOCH_ROTATION_REQUIRED` while
      * this vault has an urgent/migration condition outstanding — the exact
-     * state a `rotateEpoch` call is being made to clear. Reproduced live in
-     * production 2026-08-27 (a vault's first `epoch_secret_exposed` rekey:
-     * `/confirm` minted a receipt server-side, but the ordinary push that
-     * would publish it never admitted). Pass the pending receipted updates
+     * state a `rotateEpoch` call is being made to clear. On an
+     * `epoch_secret_exposed` rekey `/confirm` mints a receipt server-side,
+     * but the ordinary push that would publish it never admits. Pass the
+     * pending receipted updates
      * here instead — they ride the SAME head as this rotation's `transition`,
      * which IS `EPOCH_ROTATION_REQUIRED`'s own escape valve, so the publish
      * is no longer blocked. **This does NOT include these principals in
@@ -3490,6 +3857,7 @@ export class GitvaultVault {
         let conflicts = 0;
         for (;;) {
             const base = await this.materialize();
+            this.assertCallerIsWriter("driving an epoch rotation", conflicts > 0); // gitvault-multi-writer task 5.8
             const repo = this.repoFile();
             const currentEpoch = base.head?.epoch ?? this.epoch();
             const newEpoch = nextEpoch(currentEpoch);
@@ -3579,6 +3947,65 @@ export class GitvaultVault {
                 excluded_keyless_principal_ids: excludedKeyless,
                 excluded_unconfirmed_principal_ids: excludedUnconfirmed,
             });
+            // gitvault-multi-writer (task 5.9, D6/D227) — fold in a writer_set_update
+            // whenever the gateway's own blocked set (`ineligible_members`, read
+            // fresh) is non-empty. This is what closes D6's "ordinary
+            // admissions... refuse EPOCH_ROTATION_REQUIRED... until a rotate_epoch
+            // carries writer_set_update" deadlock, automatically, on EVERY
+            // rotation regardless of `options.reason` — the SAME "self-healing"
+            // shape `pending_confirmations` already gives the recipient side.
+            //
+            // Deliberately NO caller-supplied "also remove this OTHER writer key"
+            // option: the gateway's own admission rule requires `removed[]` to
+            // equal the gateway-computed blocked set EXACTLY (D6's own words,
+            // confirmed against `validateWriterSetUpdate`'s identical
+            // RECIPIENT_SET_MISMATCH check) — a client-named superset would be
+            // refused, not honored. A genuinely NEW, deliberate writer-key
+            // revocation (the "repos access revoke-key" aspiration this task's
+            // own text names) needs a gateway-side "declare this writer key
+            // revoked" mutation FIRST (the writer-dimension analog of
+            // `declareRecipientKeyRevoked`) to populate `ineligible_members` in
+            // the first place — confirmed absent from every gateway route as of
+            // this task (`grep -rn "declareWriterKeyRevoked|revoke-key"
+            // packages/gateway/src/routes/` — zero hits). That server-side
+            // mutation is real, new, owner+step-up-gated authorization logic, not
+            // a client-side gap this task can close — filed as a residual rather
+            // than half-built against a route that doesn't exist. Once it ships,
+            // this SAME automatic fold-in picks up whatever it gateway-blocks
+            // with zero client changes — the fold-in doesn't care WHY a key
+            // is blocked, only THAT it is.
+            const writerPin = this.repoFile().writer_set_pin;
+            const vaultRecord = await this.transport.getVaultRecord({ repo_id: this.repoId });
+            const ineligible = vaultRecord.ineligible_members ?? [];
+            let writerSetUpdate = null;
+            if (ineligible.length > 0) {
+                if (!writerPin) {
+                    fail("GITVAULT_WRITER_STATE_UNAVAILABLE", "no locally verified writer_set_pin for this vault — the chain must be verified (materialize/verifyToNewest) before a writer_set_update can be built against a known base writer set", "computing the writer_set_update");
+                }
+                const predecessorState = { version: writerPin.version, writers: writerPin.writers, sha256: writerPin.sha256, burnedWriterKeyIds: new Set(), consumedHandoffIds: new Set() };
+                // A rotation's own top-level `reason:"epoch_secret_exposed"` is the
+                // one unambiguous signal worth carrying down to each removed entry
+                // (a genuinely distinct, meaningful narrative); everything else —
+                // including the gateway's own finer-grained `ineligible_members[].
+                // reason` taxonomy (membership_revoked/role_below_developer/
+                // encryption_key_revoked/gateway_blocked_pending_removal), which
+                // has no clean mapping onto this field's narrower 3-value wire
+                // vocabulary — collapses to the safe, generic "member_removed".
+                const perEntryReason = options.reason === "epoch_secret_exposed" ? "epoch_secret_exposed" : "member_removed";
+                const removed = ineligible.map((m) => ({ writer_key_id: m.writer_key_id, principal_id: m.principal_id, reason: perEntryReason }));
+                const removedIds = removed.map((r) => r.writer_key_id);
+                const nextState = applyWriterSetUpdate(this.repoId, predecessorState, removedIds);
+                const update = {
+                    base_version: writerPin.version, base_sha256: writerPin.sha256,
+                    next_version: nextState.version, next_sha256: nextState.sha256,
+                    removed, writers: nextState.writers,
+                };
+                const wsuCheck = validateWriterSetUpdate(this.repoId, predecessorState, update, this.writerKeyId(), new Set(removedIds), options.force_empty_writer_set === true);
+                if (!wsuCheck.ok) {
+                    fail(wsuCheck.code, `internal: the writer_set_update this producer built is not valid (${wsuCheck.detail}) — refusing to submit a rotation the gateway would refuse`, "computing the writer_set_update", { removed: removedIds });
+                }
+                writerSetUpdate = { base_version: update.base_version, base_sha256: update.base_sha256, next_version: update.next_version, next_sha256: update.next_sha256, removed, writers: [...update.writers] };
+            }
             // D195: build + sign the rotation_attempt_descriptor, derive rotation_id, submit the create-only CAS BEFORE any envelope upload.
             const clientIdempotencyKey = options.client_idempotency_key ?? newHex32();
             const descriptorFields = {
@@ -3587,6 +4014,8 @@ export class GitvaultVault {
                 recipient_state_version: options.recipient_state_version, recipient_revocation_version: options.recipient_revocation_version,
                 pin_manifest_sha256: pinManifest.pinManifestSha256, target_partition_digest: targetPartitionDigest,
                 client_idempotency_key: clientIdempotencyKey, writer_key_id: this.writerKeyId(),
+                // D227 (rev 47): present together IFF this rotation carries a writer_set_update — frozen at THIS attempt's own admission fence, mirroring recipient_state_version/recipient_revocation_version's existing discipline.
+                ...(writerSetUpdate ? { writer_revocation_version: vaultRecord.writer_revocation_version ?? "0", writer_set_base_sha256: writerSetUpdate.base_sha256, writer_set_next_sha256: writerSetUpdate.next_sha256 } : {}),
             };
             const attemptCommitment = attemptKeyCommitment(kE, this.repoId, newEpoch, descriptorFields);
             const signedDescriptor = signGitvaultObject({ ...descriptorFields, attempt_key_commitment: attemptCommitment }, this.signer());
@@ -3614,6 +4043,8 @@ export class GitvaultVault {
                 pin_manifest_sha256: pinManifest.pinManifestSha256, target_partition_digest: targetPartitionDigest,
                 epoch_key_commitment: epochKeyCommitmentValue, excluded_keyless_principal_ids: excludedKeyless, excluded_unconfirmed_principal_ids: excludedUnconfirmed,
                 recipient_authority_attestation: null, envelopes: sealedReceipts,
+                // gitvault-multi-writer (task 5.9, D227): present IFF this rotation ALSO removes one or more writers.
+                ...(writerSetUpdate ? { writer_set_update: writerSetUpdate } : {}),
             };
             // D209 (rev 44) — round-trip THIS principal's own new-epoch
             // key_envelope through the REAL reader entry point
@@ -3623,11 +4054,10 @@ export class GitvaultVault {
             // EPOCH_ROTATION_SELF_OPEN_UNPROVEN on any rotate_epoch admission
             // that omits this or whose claim disagrees with its own
             // server-computed writer-in-envelopes biconditional — this call site
-            // is the fix for the exact gap the 2026-08-28 drill found (production
-            // clients could not READ a rotated vault because the reader had never
-            // implemented rotation traversal, while the write side was green on
-            // its own tests). This SUPERSEDES the old post-commit self-check
-            // below (which called openKeyEnvelope directly, bypassing the
+            // closes the gap where a client can WRITE a rotated vault it cannot
+            // READ, because the reader never implements rotation traversal while
+            // the write side stays green on its own tests. It replaces a bare
+            // post-commit self-check (calling openKeyEnvelope directly, bypassing the
             // membership lookup, the envelope_path callback derivation, and the
             // reader's own error framing) — moving the round-trip BEFORE
             // admission means a genuine failure aborts this call before anything
@@ -3737,12 +4167,20 @@ export class GitvaultVault {
             if (pinManifestFold) {
                 this.keystore.updateRepo(this.repoId, { known_pin_manifest: { pin_manifest_version: pinManifestFold.nextVersion, stored_bytes_sha256: pinManifestFold.manifestSha, pins: pinManifestFold.pins } });
             }
+            // gitvault-multi-writer (task 5.9) — the SAME local-pin advance
+            // #publishAddWriterKeyTransition performs on ITS success path: this
+            // head just admitted a writer_set_update, so the locally-pinned
+            // writer set is now stale until refreshed here.
+            if (writerSetUpdate) {
+                this.keystore.updateRepo(this.repoId, { writer_set_pin: { version: writerSetUpdate.next_version, sha256: writerSetUpdate.next_sha256, writers: [...writerSetUpdate.writers], pinned_at: formatGitvaultTimestamp(this.now()) } });
+            }
             return {
                 outcome: "admitted", generation, head_sha256: admitted.head_sha256, new_epoch: newEpoch, rotation_id: rotationId, reason: options.reason,
                 included: included.map((p) => ({ principal_id: p.principal_id, ek_fingerprint: p.ek_fingerprint })),
                 excluded_keyless_principal_ids: excludedKeyless, excluded_unconfirmed_principal_ids: excludedUnconfirmed,
                 admission_record_sha256: admitted.admission_record_sha256, capture_receipt: admitted.capture_receipt, self_check: selfCheck,
                 pin_manifest_published: pinManifestFold ? { pin_manifest_version: pinManifestFold.nextVersion, stored_bytes_sha256: pinManifestFold.manifestSha, principal_ids: pendingConfirmations.map((p) => p.principal_id) } : null,
+                writers_removed: writerSetUpdate ? writerSetUpdate.removed.map((r) => ({ writer_key_id: r.writer_key_id, principal_id: r.principal_id, reason: r.reason })) : [],
             };
         }
     }
@@ -3756,6 +4194,183 @@ export class GitvaultVault {
         const counters = await this.transport.declareRecipientKeyRevoked({ repo_id: this.repoId, principal_id: principalId });
         return this.rotateEpoch({ reason: "recipient_key_revoked", recipient_state_version: counters.recipient_state_version, recipient_revocation_version: counters.recipient_revocation_version, client_idempotency_key: options.client_idempotency_key });
     }
+    // ── writer activation (gitvault-multi-writer task 5.6, design D4/D5) ──────
+    /**
+     * Submit a REF-NEUTRAL `add_writer_key{authorization.kind:"handoff"}`
+     * activation head — no ref/checkpoint/repair changes ride it (protocol
+     * §4.17's own "ref-neutral head shape... for the activation head" rule),
+     * built by `publishGeneration` the SAME way every ordinary no-op push
+     * would be (`refs`/`head_target` carried forward from `base` UNCHANGED),
+     * just with `transition` set. Retries `HEAD_CAS_CONFLICT` like every
+     * other publish path here. The caller (`resume()`) has already built and
+     * locally sanity-checked the grant + acceptance; this method only reads
+     * the FRESHLY-verified `writer_set_pin` (set by the `materialize()` this
+     * same call performs, mirroring `push()`'s own base-then-retry shape) to
+     * compute `base_writer_set`/`next_writer_set`, signs the head under
+     * `this.signer()` (the ADDED key itself — protocol §4.17's "head signed
+     * by the added key" — since `signer()` reads straight from THIS
+     * keystore's identity, and `resume()` mints/loads that identity before
+     * ever reaching this call), and advances the local `writer_set_pin` on
+     * success so a subsequent read reflects the new writer without a second
+     * chain walk.
+     *
+     * Crash-resumable (task 5.6): the chain burns `handoff_id` single-use, so
+     * a naive resubmission after a crash between a prior attempt's successful
+     * admission and this checkout learning about it would be refused
+     * VALIDATION_FAILED. Returns `{outcome:"already_admitted", generation}`
+     * instead of submitting anything whenever the freshly-verified writer set
+     * ALREADY contains `input.addedWriterKeyId` — the caller treats both
+     * outcomes as success (the writer IS active either way) and proceeds.
+     */
+    async submitWriterActivationHead(input) {
+        return this.#publishAddWriterKeyTransition(input.addedWriterKeyId, (pin) => buildAddWriterKeyActivationPayload(this.repoId, pin, { writer_key_id: input.addedWriterKeyId, signing_pubkey: input.addedSigningPubkeyB64u, principal_id: input.addedPrincipalId }, input.handoffId, input.grant, input.acceptance), "submitting a writer activation head", 
+        // gitvault-multi-writer task 5.8: the handoff door is signed by the
+        // ADDED key itself, which is by design NOT YET a writer — the pre-
+        // check must be SKIPPED here, or this call could never succeed.
+        false);
+    }
+    /**
+     * gitvault-multi-writer (task 5.7) — the "writer"-door twin of {@link
+     * submitWriterActivationHead}: an ALREADY-ACTIVE writer (this vault
+     * session's own key) admits `input`, an eligible org member with a
+     * published signing key but no writer standing yet, via a fresh
+     * `add_writer_key{"writer"}` head. No grant/acceptance — the carrying
+     * head's own signer being an active writer at the predecessor generation
+     * IS the authorization (`validateAddWriterKeyPayload`'s `"writer"`
+     * branch), re-verified admission-side by `checkTransitionAdmissible`.
+     * Task 5.8 adds the SAME local pre-check every other head-signing path
+     * gets: if THIS session's own key is not (or is no longer) an active
+     * writer, refuse EARLY and LOCALLY (`GITVAULT_WRITER_NOT_ADMITTED` /
+     * `GITVAULT_WRITER_REMOVED`) rather than let the head reach the gateway
+     * only to be refused there — redundant with `reconcileWriterAdmissions`'s
+     * own upfront gate for that caller, but this method is public and a
+     * direct caller should get the same fast, specific refusal.
+     */
+    async admitPendingWriter(input) {
+        return this.#publishAddWriterKeyTransition(input.addedWriterKeyId, (pin) => buildWriterDoorAddWriterKeyPayload(this.repoId, pin, { writer_key_id: input.addedWriterKeyId, signing_pubkey: input.addedSigningPubkeyB64u, principal_id: input.addedPrincipalId }), "admitting a pending writer", true);
+    }
+    /**
+     * Shared publish+retry+pin-update tail for BOTH doors of `add_writer_key`
+     * ({@link submitWriterActivationHead}'s handoff door, task 5.6; {@link
+     * admitPendingWriter}'s writer door, task 5.7). `buildPayload` constructs
+     * a fresh {@link AddWriterKeyPayload} against whatever `writer_set_pin`
+     * the CURRENT attempt's freshly-materialized base carries, so a
+     * conflict-retry rebuilds against the winner's own pin, never a stale
+     * one. Crash/race-resumable the same way for both doors: if
+     * `addedWriterKeyId` is ALREADY in the freshly-verified writer set before
+     * anything is built, returns `{outcome:"already_admitted"}` instead of
+     * attempting a resubmission the chain would refuse.
+     *
+     * `requireCallerIsWriter` (task 5.8) gates {@link assertCallerIsWriter} —
+     * `false` for the handoff door (the signer is deliberately not yet a
+     * writer), `true` for the writer door (the signer must already be one).
+     */
+    async #publishAddWriterKeyTransition(addedWriterKeyId, buildPayload, errorContext, requireCallerIsWriter) {
+        let conflicts = 0;
+        for (;;) {
+            const base = await this.materialize();
+            if (requireCallerIsWriter)
+                this.assertCallerIsWriter(errorContext, conflicts > 0);
+            const pin = this.repoFile().writer_set_pin;
+            if (!pin) {
+                fail("GITVAULT_WRITER_STATE_UNAVAILABLE", "no locally verified writer_set_pin for this vault — the chain must be verified (materialize/verifyToNewest) before an activation head can be built against a known base writer set", errorContext);
+            }
+            if (pin.writers.some((w) => w.writer_key_id === addedWriterKeyId)) {
+                return { outcome: "already_admitted", generation: base.generation };
+            }
+            const payload = buildPayload(pin);
+            const nextState = payload.next_writer_set;
+            const payloadBytes = jcs(payload);
+            const transition = { kind: "add_writer_key", payload_format: "base64url-jcs", payload: toBase64url(payloadBytes), payload_sha256: sha256Hex(payloadBytes) };
+            const published = await this.publishGeneration({
+                base, refs: base.refs, dropped: [], head_target: base.head_target,
+                force_checkpoint: false, cutoff: null, transition,
+            });
+            if (published.outcome === "conflict") {
+                conflicts += 1;
+                if (conflicts > this.retries)
+                    fail("HEAD_CAS_CONFLICT", `the writer activation lost ${conflicts} races at generation ${published.generation}; giving up`, errorContext, { generation: published.generation, winner: published.winner });
+                continue;
+            }
+            if (published.outcome === "dry_run")
+                fail("GIT_COMMAND_FAILED", "internal: #publishAddWriterKeyTransition() received a dry-run result it never requested", errorContext);
+            this.keystore.updateRepo(this.repoId, { writer_set_pin: { version: nextState.version, sha256: nextState.sha256, writers: [...nextState.writers], pinned_at: formatGitvaultTimestamp(this.now()) } });
+            return {
+                outcome: "activated",
+                result: { generation: published.generation, head_sha256: published.head_sha256, head: published.head, admission_record_sha256: published.admission_record_sha256, capture_receipt: published.capture_receipt, form: published.form, conflicts_retried: conflicts, refs: published.refs, checkpoint_staleness: this.checkpointStalenessNow(published.generation) },
+            };
+        }
+    }
+    /**
+     * gitvault-multi-writer (task 5.7) — the vault's OWN writer-admission
+     * reconcile: reads `pending_writers[]` off the vault record (eligible org
+     * members with no writer standing yet), resolves each candidate's
+     * published signing key off the org's encryption-key directory (the SAME
+     * `/orgs/v1/:org_id/encryption-keys` row {@link
+     * reconcileEnvelopeRecipients} reads, widened D9 to also carry the
+     * signing half), and admits each via {@link admitPendingWriter} — one
+     * `add_writer_key{"writer"}` head per candidate, sequentially: each
+     * admission materializes fresh against the PRIOR one's own updated writer
+     * set, so there is no batched/parallel form.
+     *
+     * Requires THIS session's own key to already be an active writer (the
+     * chain's own authorization rule for the "writer" door) — checked ONCE,
+     * upfront, off the locally-pinned `writer_set_pin` (no network call),
+     * rather than discovered N times over from N identical gateway refusals:
+     * a session that reached this call already pushed successfully as an
+     * active writer in every wired call site (push/snapshot/deploy) OR is a
+     * member that simply is not one yet (session-start/read) — the SAME
+     * "not yet admitted" case {@link Gitvault.push}'s own pre-push check
+     * (task 5.8) names, not a new refusal shape. Returns `{eligible: false}`
+     * with every other field empty (never throws) for that case: every OTHER
+     * `pending_writers[]` entry would fail identically, so there is nothing
+     * this call can usefully do, and "I am not a writer" is not this vault's
+     * fault — but it is distinguishable from "there was nothing pending"
+     * (`eligible: true`, still all empty), which matters to a caller trying
+     * to explain an all-empty result to a human.
+     */
+    async reconcileWriterAdmissions() {
+        const repo = this.repoFile();
+        const admitted = [];
+        const alreadyCovered = [];
+        const skipped = [];
+        const assembleResult = (eligible) => ({ repo_id: this.repoId, org_id: repo.org_id, eligible, admitted, already_covered: alreadyCovered, skipped });
+        const myWriterKeyId = this.writerKeyId();
+        const startingPin = repo.writer_set_pin;
+        if (!startingPin || !startingPin.writers.some((w) => w.writer_key_id === myWriterKeyId))
+            return assembleResult(false);
+        const record = await this.transport.getVaultRecord({ repo_id: this.repoId });
+        const pending = record.pending_writers ?? [];
+        if (pending.length === 0)
+            return assembleResult(true);
+        const directory = await this.transport.listOrgEncryptionKeys({ org_id: repo.org_id });
+        const byPrincipal = new Map(directory.keys.map((k) => [k.principal_id, k]));
+        for (const candidate of pending) {
+            const currentPin = this.repoFile().writer_set_pin;
+            if (currentPin?.writers.some((w) => w.writer_key_id === candidate.writer_key_id)) {
+                alreadyCovered.push(candidate.writer_key_id);
+                continue;
+            }
+            const entry = byPrincipal.get(candidate.principal_id);
+            const signingPubkey = entry?.signing_pubkey;
+            if (typeof signingPubkey !== "string" || signingPubkey.length === 0) {
+                skipped.push({ principal_id: candidate.principal_id, writer_key_id: candidate.writer_key_id, reason: "missing_signing_pubkey" });
+                continue;
+            }
+            if (writerKeyIdOf(signingPubkey) !== candidate.writer_key_id) {
+                skipped.push({ principal_id: candidate.principal_id, writer_key_id: candidate.writer_key_id, reason: "invalid_signing_pubkey" });
+                continue;
+            }
+            const outcome = await this.admitPendingWriter({ addedWriterKeyId: candidate.writer_key_id, addedSigningPubkeyB64u: signingPubkey, addedPrincipalId: candidate.principal_id });
+            if (outcome.outcome === "already_admitted") {
+                alreadyCovered.push(candidate.writer_key_id);
+            }
+            else {
+                admitted.push({ principal_id: candidate.principal_id, writer_key_id: candidate.writer_key_id, generation: outcome.result.generation });
+            }
+        }
+        return assembleResult(true);
+    }
     // ── repair (owner-only; mandatory fresh checkpoint; repair resource lane server-side) ──
     /**
      * Publish a repair head over `base_generation` (§4.3): superseded tips that
@@ -3766,6 +4381,14 @@ export class GitvaultVault {
      */
     async repair(input) {
         const newest = await this.verifyToNewest();
+        // gitvault-multi-writer task 5.8 — repair requires OWNER+step-up
+        // server-side (`authority.repair`), but that is layered ON TOP of the
+        // baseline writer requirement every head needs (`authority.writer`,
+        // confirmed against the gateway's own admission fixture: an owner who
+        // is not also a chain-recognized writer is refused just the same). No
+        // retry loop here (a losing repair is a hard failure below, not a
+        // rebuild-and-retry), so there is no CAS-loser variant to distinguish.
+        this.assertCallerIsWriter("preparing repair");
         const baseGen = generationToBigInt(input.base_generation);
         const newestGen = generationToBigInt(newest.generation);
         if (baseGen >= newestGen)