run402 4.68.3 → 4.69.1

package/sdk/dist/namespaces/gitvault.js

@@ -28,8 +28,31 @@
  * 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, isRun402Error } from "../errors.js";
-import { GITVAULT_BYO_UNMIRRORED_REMEDY_STATEMENT, GITVAULT_DEGRADED_READ_STATEMENT, GITVAULT_DURABILITY_STATEMENT, GITVAULT_MIRROR_KEYSTORE_STILL_REQUIRED_STATEMENT, GITVAULT_MIRROR_VALIDITY_NOT_FRESHNESS_STATEMENT, GITVAULT_TERMINAL_LOSS_DOCTOR_TEXT, GITVAULT_TERMINAL_LOSS_STATEMENT, GITVAULT_UNMIRRORED_FINDING_STATEMENT, bytesToHex, hexToBytes, parseGitvaultStrict, randomBytes, sha256Hex, verifyGitvaultObject, toBase64url, } from "./gitvault.crypto.js";
+import { LocalError, isRun402Error, isNetworkError } from "../errors.js";
+import { GITVAULT_BYO_UNMIRRORED_REMEDY_STATEMENT, GITVAULT_DEGRADED_READ_STATEMENT, GITVAULT_DURABILITY_STATEMENT, GITVAULT_MIRROR_KEYSTORE_STILL_REQUIRED_STATEMENT, GITVAULT_MIRROR_VALIDITY_NOT_FRESHNESS_STATEMENT, GITVAULT_TERMINAL_LOSS_DOCTOR_TEXT, GITVAULT_TERMINAL_LOSS_STATEMENT, GITVAULT_UNMIRRORED_FINDING_STATEMENT, bytesToHex, computeKeystorePossessionProof, computeSigningKeyPossessionSignature, ed25519PublicKey, fromBase64url, hexToBytes, jcs, parseGitvaultStrict, randomBytes, sha256Hex, verifyGitvaultObject, toBase64url, } from "./gitvault.crypto.js";
+/**
+ * gitvault-agent-envelopes — per-process memo for the session-start
+ * fulfilment (`<keystore root>|<repo_id>`) and the enroll-if-absent step
+ * (`<keystore root>`), so a process that opens the same vault many times
+ * (a `git push` runs several verbs) reconciles and enrolls once.
+ */
+const SESSION_RECONCILED = new Set();
+/**
+ * Round 3 blocker 2: integrity verdicts must PROPAGATE through every
+ * best-effort reconcile boundary — converting tampering evidence into
+ * `skipped_error` at the outer catch is exactly the swallow the inner
+ * verifier exists to prevent. Availability and local-policy failures stay
+ * best-effort.
+ */
+const RECONCILE_FATAL_CODES = new Set([
+    "GITVAULT_ENVELOPE_ALTERED",
+    "GITVAULT_SIGNATURE_INVALID",
+    "VAULT_CREATION_CONFLICT",
+]);
+function rethrowFatalReconcile(e) {
+    if (isRun402Error(e) && RECONCILE_FATAL_CODES.has(String(e.code)))
+        throw e;
+}
 /** A keystore path, or `null` when there is no id to derive it from (or it is malformed). */
 function safePath(derive, repoId) {
     if (!repoId)
@@ -419,6 +442,47 @@ export class Gitvault {
             method: "POST", body: input, context: "re-pinning a gitvault recipient",
         });
     }
+    /**
+     * gitvault-agent-envelopes D3 — a KEY-HOLDER explicitly accepts a recipient's
+     * CHANGED key. The session-start reconcile refuses to wrap under a
+     * fingerprint that differs from this keystore's TOFU pin
+     * (`pinned_key_mismatch`) — that refusal is the substitution defence and
+     * is never bypassed automatically, not even after an owner's revoke: from
+     * this machine's view an owner-driven re-key and a platform substitution
+     * look identical, and the audit event is not proof against the platform.
+     * Acceptance is a deliberate act naming the new fingerprint (the
+     * out-of-band verification point — read it back with the recipient over any
+     * channel; it is public data): this records the D197 re-pin receipt with the
+     * gateway AND moves the local pin, so the next reconcile wraps. Refuses when
+     * `new_fingerprint` is not what the org directory currently serves for the
+     * principal (a stale or mistyped fingerprint never pins).
+     */
+    async acceptRecipientKeyChange(options) {
+        const repoId = await this.#resolveRepoId(options);
+        const { GitvaultKeystore } = await this.#keystore();
+        const keystore = new GitvaultKeystore(options.keystore_root !== undefined ? { rootDir: options.keystore_root } : {});
+        const repo = keystore.readRepo(repoId);
+        if (!repo)
+            throw new LocalError("this keystore holds no repo state for the vault — only a key-holder can accept a recipient's key change", "accepting a recipient key change", { code: "GITVAULT_REPO_STATE_MISSING", details: { repo_id: repoId } });
+        const record = await this.get(repoId);
+        const directory = await this.#client.request(`/orgs/v1/${encodeURIComponent(record.org_id)}/encryption-keys`, { context: "reading the org encryption-key directory" });
+        const served = directory.keys.find((k) => k.principal_id === options.principal_id)?.ek_fingerprint ?? null;
+        if (served !== options.new_fingerprint) {
+            throw new LocalError(`the org directory currently serves ${served ?? "no key"} for principal ${options.principal_id}, not ${options.new_fingerprint} — refusing to pin a fingerprint the directory does not vouch for`, "accepting a recipient key change", { code: "PIN_CHANGE_UNCONFIRMED", details: { repo_id: repoId, principal_id: options.principal_id, directory_fingerprint: served, requested_fingerprint: options.new_fingerprint } });
+        }
+        const pins = { ...(repo.envelope_recipient_pins ?? {}) };
+        const old = pins[options.principal_id] ?? null;
+        let receipt = null;
+        if (old && old !== options.new_fingerprint) {
+            receipt = await this.repinRecipient(repoId, options.principal_id, { old_ek_fingerprint: old, new_fingerprint: options.new_fingerprint }).catch(() => null);
+        }
+        else if (!old) {
+            receipt = await this.confirmRecipient(repoId, options.principal_id, options.new_fingerprint).catch(() => null);
+        }
+        pins[options.principal_id] = options.new_fingerprint;
+        keystore.updateRepo(repoId, { envelope_recipient_pins: pins });
+        return { repo_id: repoId, principal_id: options.principal_id, old_fingerprint: old, new_fingerprint: options.new_fingerprint, receipt };
+    }
     /**
      * `POST …/recipients/:principal_id/key-revocation` (D199) — declares
      * `reason:"recipient_key_revoked"` admissible for the NEXT rotation this
@@ -504,6 +568,10 @@ export class Gitvault {
         const transport = createGitvaultHttpTransport(this.#client, {
             onObjectStoreOriginObserved: (rid, origins) => keystore.recordObjectStoreOrigins(rid, origins),
         });
+        // gitvault-agent-envelopes D3: enroll the keystore's key if this principal
+        // has none (publish + possession proof, one round trip each); a differing
+        // current key REFUSES here — rotation is never automatic.
+        const enrollment = await this.#ensureEnrolled(keystore);
         const vault = new GitvaultVault({
             keystore,
             transport,
@@ -512,7 +580,245 @@ export class Gitvault {
             ...(options.verification_budget !== undefined ? { verification_budget: options.verification_budget } : {}),
             ...(options.service_public_key !== undefined ? { service_public_key: options.service_public_key } : {}),
         });
-        return { repo_id: repoId, keystore, transport, vault };
+        // D4: a cold keystore restores from its own envelope (or fails
+        // GITVAULT_ENVELOPE_PENDING with the exact next actions). The lazy
+        // fallback is an ALLOWLIST of typed transport/absence states, not a
+        // denylist of known verdicts (consult round 2 §5): a network fault, an
+        // older gateway missing the route (404/501), or a vault with no admitted
+        // genesis yet (CHAIN_BROKEN — not born, nothing to restore or disclose)
+        // leave the handle lazy so the verb fails exactly where it always did
+        // (`GITVAULT_REPO_STATE_MISSING` at first use). EVERYTHING else —
+        // integrity failures, parse failures, programming errors — propagates.
+        // A keystore with NO identity has nothing to restore and nothing that
+        // could be disclosed — stay lazy and let the verb hit the ordinary
+        // KEYSTORE_MISSING wall (with its cross-profile hint) exactly where it
+        // always did, AFTER the caller's own address-pin writes.
+        let restored = null;
+        try {
+            restored = keystore.readIdentity() ? await vault.ensureRepoState() : null;
+        }
+        catch (e) {
+            const code = isRun402Error(e) ? e.code : undefined;
+            const status = isRun402Error(e) ? (e.status ?? null) : null;
+            const transportAbsence = isNetworkError(e) || status === 404 || status === 501;
+            if (code === "CHAIN_BROKEN" || transportAbsence) {
+                restored = null;
+            }
+            else {
+                throw e;
+            }
+        }
+        // D5: a key-holder fulfils pending recipients once per process per vault.
+        // A just-restored keystore holds K_repo too, but it just LEARNED it from
+        // someone else's wrap — it is not the party that owes fulfilment on this
+        // open, and wrapping from a first-contact restore before verifying the
+        // chain would be premature; the next open in this process does it.
+        const policy = options.reconcile ?? "auto";
+        // Consult round 2 §4: reconcile WRAPS K_repo — a disclosure — so it runs
+        // only when this open VERIFIED custody continuity against the gateway
+        // (whoami answered and the current key is this keystore's). A transport
+        // fault or unresolved principal is never fail-open into a wrap.
+        // `signing_republished` (rev 47) belongs in this allowlist too: it is
+        // reached only when the ENCRYPTION half was already active (continuity
+        // already held) and a fresh, gateway-verified Ed25519 possession
+        // signature was just proven for the signing half — strictly MORE
+        // evidence of custody than `already_active` alone, not less.
+        const custodyVerified = enrollment.outcome === "already_active" || enrollment.outcome === "enrolled" || enrollment.outcome === "activated_pending" || enrollment.outcome === "signing_republished";
+        // Scoped to what was actually verified: keystore + vault + the exact
+        // fingerprint whose continuity this open proved. Marked ONLY after a
+        // successful reconcile — a transient failure stays retryable, and a
+        // `deferred` policy never consumes the marker.
+        const sessionKey = `${keystore.rootDir}|${repoId}|${enrollment.ek_fingerprint ?? "none"}`;
+        let reconcileRecipients = null;
+        if (policy === "forbidden") {
+            reconcileRecipients = { attempted: false, outcome: "forbidden" };
+        }
+        else if (!restored && !custodyVerified) {
+            reconcileRecipients = { attempted: false, outcome: "custody_unverified", ...(enrollment.error !== undefined ? { error: enrollment.error } : {}) };
+        }
+        else if (!restored && !SESSION_RECONCILED.has(sessionKey)) {
+            if (policy === "deferred") {
+                let pendingCount = null;
+                try {
+                    const coverage = await transport.listEnvelopeRecipients({ repo_id: repoId });
+                    const covered = new Set(coverage.recipient_fingerprints);
+                    pendingCount = coverage.desired ? coverage.desired.filter((d) => d.status === "active" && d.ek_fingerprint && !covered.has(d.ek_fingerprint)).length : null;
+                }
+                catch {
+                    pendingCount = null;
+                }
+                reconcileRecipients = { attempted: false, outcome: "deferred_by_local_policy", pending_count: pendingCount };
+            }
+            else {
+                try {
+                    const result = await vault.reconcileEnvelopeRecipients();
+                    reconcileRecipients = { attempted: true, outcome: "reconciled", result };
+                    SESSION_RECONCILED.add(sessionKey);
+                }
+                catch (e) {
+                    rethrowFatalReconcile(e);
+                    reconcileRecipients = { attempted: true, outcome: "skipped_error", error: e instanceof Error ? e.message : String(e) };
+                }
+            }
+        }
+        // gitvault-multi-writer (task 5.7) — the SAME "session-start"/"read"
+        // wiring point as the envelope reconcile above, but a genuinely simpler
+        // policy: no disclosure risk, so only `forbidden` is honored — no
+        // custody gate, no `deferred`/memoization branch.
+        const writerReconcile = policy === "forbidden" ? { attempted: false, outcome: "forbidden" } : await this.#tryReconcileWriterAdmissions(vault);
+        return { repo_id: repoId, keystore, transport, vault, restored, reconcile_recipients: reconcileRecipients, writer_reconcile: writerReconcile, enrollment };
+    }
+    /**
+     * gitvault-agent-envelopes D3 — enroll-if-absent, checked FRESH on every
+     * open (consult round 2 §4: memoizing this decision let a long-lived
+     * process keep trusting a key an owner had since revoked). Reads
+     * `GET /agent/v1/whoami` (the gateway folds the principal's current key
+     * metadata in), then:
+     *   - no current key → publish the keystore's X25519 key as
+     *     `custody_scheme: keystore_v1`, answer the ECDH possession challenge,
+     *     activate;
+     *   - current key = this keystore's key, still `pending` → finish the
+     *     activation (a crashed earlier enrollment);
+     *   - current key = this keystore's key, `active` → no-op;
+     *   - current key ≠ this keystore's key → `GITVAULT_KEY_ROTATION_REQUIRED`.
+     *     Never published as a rotation: a stolen wallet key must not silently
+     *     replace a member's decryption identity. The remedies are the
+     *     gateway's — restore the keystore backup; an org owner revokes the
+     *     stale key; or, for a sole-member principal, `replace_current`.
+     * A credential that resolves to no enrolling principal (a service key)
+     * skips enrollment — reads keep working; nothing pretends to be enrolled.
+     */
+    async #ensureEnrolled(keystore) {
+        let identity = keystore.readIdentity();
+        let whoami;
+        try {
+            whoami = await this.#client.request("/agent/v1/whoami", { context: "resolving the enrolling principal" });
+        }
+        catch (e) {
+            // An older gateway, a credential whoami refuses, or a transport fault:
+            // enrollment is best-effort on the way IN — the verb itself still runs
+            // (and a cold open will say `GITVAULT_ENVELOPE_PENDING` honestly if it
+            // needed an envelope this principal never enrolled for). A keystore
+            // with no identity reaches the ordinary KEYSTORE_MISSING wall unchanged.
+            return { outcome: identity ? "skipped_error" : "skipped_no_identity", ek_fingerprint: identity?.encryption_fingerprint ?? null, signing_fingerprint: identity?.signing_fingerprint ?? null, error: e instanceof Error ? e.message : String(e) };
+        }
+        if (!whoami.principal) {
+            return { outcome: "skipped_no_principal", ek_fingerprint: identity?.encryption_fingerprint ?? null, signing_fingerprint: identity?.signing_fingerprint ?? null };
+        }
+        if (whoami.principal.type !== "human" && whoami.principal.type !== "agent") {
+            // Only custody-eligible principal types enroll (consult round 2 §4):
+            // the gateway would refuse the publish anyway, but by then an orphan
+            // identity would already exist on disk.
+            return { outcome: "skipped_not_enrollable", ek_fingerprint: identity?.encryption_fingerprint ?? null, signing_fingerprint: identity?.signing_fingerprint ?? null };
+        }
+        if (identity?.enrolled_principal_id && identity.enrolled_principal_id !== whoami.principal.id) {
+            throw new LocalError(`this keystore identity enrolled as principal ${identity.enrolled_principal_id}, but the active credential resolves to ${whoami.principal.id} — refusing cross-profile reuse of a custody identity`, "enrolling the keystore encryption key", { code: "GITVAULT_IDENTITY_PROFILE_MISMATCH", details: { enrolled_principal_id: identity.enrolled_principal_id, principal_id: whoami.principal.id, keystore_root: keystore.rootDir } });
+        }
+        const current = whoami.encryption_key ?? null;
+        // A member joining from a FRESH machine has no keystore identity yet.
+        // Mint one only now — a real gateway confirmed an enrollable principal
+        // with no published key, so this identity is about to become that
+        // principal's key. (Vault creation mints its own via the six-stage
+        // journal; nothing else ever mints.) A principal that already HAS a
+        // published key but no local identity lost its keystore — that is the
+        // rotation case below, never a fresh mint.
+        if (!identity && !current)
+            identity = keystore.ensureIdentity();
+        if (!identity) {
+            throw new LocalError(`this principal has a published encryption key (${current.ek_fingerprint}) but this keystore holds no identity — the keystore that enrolled it is not this one; rotation is never automatic`, "enrolling the keystore encryption key", {
+                code: "GITVAULT_KEY_ROTATION_REQUIRED",
+                details: { current_ek_fingerprint: current.ek_fingerprint, current_state: current.state, local_ek_fingerprint: null, keystore_root: keystore.rootDir },
+                next_actions: [
+                    { type: "edit_request", why: "restore the keystore backup that holds the current key (~/.config/run402/gitvault or the wallet profile's gitvault dir)" },
+                    { type: "edit_request", why: "have an org owner revoke the stale key: DELETE /orgs/v1/:org_id/members/:principal_id/encryption-key (owner + step-up); your next gitvault operation then enrolls a fresh key" },
+                    { type: "edit_request", why: "if this principal is the sole custody-eligible member of every org it belongs to: POST /agent/v1/whoami/encryption-key with replace_current: true" },
+                ],
+            });
+        }
+        if (current && current.ek_fingerprint !== identity.encryption_fingerprint) {
+            throw new LocalError(`this principal's published encryption key (${current.ek_fingerprint}) is not this keystore's key (${identity.encryption_fingerprint}); rotation is never automatic`, "enrolling the keystore encryption key", {
+                code: "GITVAULT_KEY_ROTATION_REQUIRED",
+                details: { current_ek_fingerprint: current.ek_fingerprint, current_state: current.state, local_ek_fingerprint: identity.encryption_fingerprint, keystore_root: keystore.rootDir },
+                next_actions: [
+                    { type: "edit_request", why: "restore the keystore backup that holds the current key (~/.config/run402/gitvault or the wallet profile's gitvault dir)" },
+                    { type: "edit_request", why: "have an org owner revoke the stale key: DELETE /orgs/v1/:org_id/members/:principal_id/encryption-key (owner + step-up); your next gitvault operation then enrolls this key" },
+                    { type: "edit_request", why: "if this principal is the sole custody-eligible member of every org it belongs to: POST /agent/v1/whoami/encryption-key with replace_current: true" },
+                ],
+            });
+        }
+        // gitvault-multi-writer rev 47 (task 5.3, design D9) — the signing half's
+        // OWN continuity check, parallel to the encryption half's: does the
+        // directory's currently-published signing_fingerprint already equal
+        // this keystore's? UNLIKE the encryption half this is never a rotation
+        // refusal (D9: the signing half is always freely republishable) — a
+        // mismatch just means the publish call below is still needed, even
+        // when the encryption half is already fully active.
+        const needsSigningPublish = identity.signing_fingerprint !== (current?.signing_fingerprint ?? null);
+        if (current && current.state === "active" && !needsSigningPublish) {
+            keystore.bindIdentityPrincipal(whoami.principal.id);
+            return { outcome: "already_active", ek_fingerprint: current.ek_fingerprint, signing_fingerprint: identity.signing_fingerprint };
+        }
+        const keypair = keystore.encryptionKeypair(identity);
+        if (!keypair) {
+            throw new LocalError("the keystore identity has no X25519 private key — it cannot enroll or open envelopes", "enrolling the keystore encryption key", { code: "VAULT_UNRECOVERABLE", details: { statement: GITVAULT_TERMINAL_LOSS_STATEMENT } });
+        }
+        // The signing half rides the SAME publish call as the encryption half
+        // (task 4.1's gateway contract: one round trip, both halves, all-or-
+        // none). `keystore.signingKeypair` is `null` only for a read-only
+        // recovery identity that lost its signing seed — that keystore can
+        // still enroll its encryption half (existing behavior, unchanged); it
+        // simply cannot become a vault writer until the seed is recovered.
+        const signingKeypair = keystore.signingKeypair(identity);
+        const signingFields = signingKeypair
+            ? {
+                signing_pubkey: identity.signing_pubkey,
+                signing_fingerprint: identity.signing_fingerprint,
+                possession_signature: computeSigningKeyPossessionSignature({
+                    signing_seed: signingKeypair.seed,
+                    principal_id: whoami.principal.id,
+                    signing_pubkey: identity.signing_pubkey,
+                    encryption_pubkey: identity.encryption_pubkey,
+                }),
+            }
+            : {};
+        try {
+            const published = await this.#client.request("/agent/v1/whoami/encryption-key", { method: "POST", body: { public_key: identity.encryption_pubkey, ek_fingerprint: identity.encryption_fingerprint, custody_scheme: "keystore_v1", ...signingFields }, context: "publishing the keystore encryption key" });
+            if (published.state !== "active") {
+                if (!published.activation) {
+                    throw new LocalError("the gateway published the key as pending without an activation challenge", "enrolling the keystore encryption key", { code: "KEY_NOT_PENDING", details: { state: published.state } });
+                }
+                const proof = computeKeystorePossessionProof({
+                    private_key: keypair.private_key,
+                    epk_b64u: published.activation.epk,
+                    challenge_id: published.activation.challenge_id,
+                    encryption_key_id: published.encryption_key_id,
+                    public_key_b64u: identity.encryption_pubkey,
+                });
+                await this.#client.request("/agent/v1/whoami/encryption-key/activate", {
+                    method: "POST",
+                    body: { challenge_id: published.activation.challenge_id, proof },
+                    context: "proving possession of the keystore encryption key",
+                });
+            }
+        }
+        catch (e) {
+            // The ONE refusal that must surface is a rotation (the gateway saw a
+            // different current key than whoami just reported — a race with a
+            // concurrent publish); everything else stays best-effort.
+            if (isRun402Error(e) && e.code === "KEY_ROTATION_REQUIRED")
+                throw e;
+            return { outcome: "skipped_error", ek_fingerprint: identity.encryption_fingerprint, signing_fingerprint: identity.signing_fingerprint ?? null, error: e instanceof Error ? e.message : String(e) };
+        }
+        keystore.bindIdentityPrincipal(whoami.principal.id);
+        // The early `already_active` return above only fires when NEITHER half
+        // needs work, so reaching here with `current.state === "active"` means
+        // specifically that the ENCRYPTION half was already fine and only the
+        // signing half triggered this publish — `signing_republished`, not
+        // `activated_pending` (which would wrongly imply an ECDH activation
+        // challenge was just completed; none was, `published.state` was
+        // already `"active"` and the activation branch above never ran).
+        const outcome = !current ? "enrolled" : current.state === "active" ? "signing_republished" : "activated_pending";
+        return { outcome, ek_fingerprint: identity.encryption_fingerprint, signing_fingerprint: identity.signing_fingerprint ?? null };
     }
     /**
      * Open a vault, allocating it first when it does not exist yet (D2 — lazy
@@ -1013,6 +1319,23 @@ export class Gitvault {
         else if (options.refs === true && !holdsRepoKey) {
             warnings.push({ kind: "refs_unavailable", message: "this machine does not hold K_repo for the vault, so its ref map cannot be decrypted here" });
         }
+        // gitvault-agent-envelopes D3/D5: a KEY-HOLDER's ordinary read is a
+        // session start — enroll this keystore's key if absent and fulfil every
+        // pending desired recipient once per process (best-effort, reported,
+        // never folded into the observation above). `status` on a machine that
+        // holds no K_repo has nothing to fulfil and stays a pure read.
+        let reconcileRecipients = null;
+        let enrollment = null;
+        if (repoId && holdsRepoKey && options.reconcile !== "forbidden") {
+            try {
+                const handle = await this.open({ ...options, repo_id: repoId });
+                reconcileRecipients = handle.reconcile_recipients;
+                enrollment = handle.enrollment;
+            }
+            catch (e) {
+                warnings.push({ kind: "reconcile_unavailable", message: `the session-start envelope fulfilment could not run: ${e instanceof Error ? e.message : String(e)}` });
+            }
+        }
         const nextActions = [];
         // `run402 init` scaffolds the git remote and deliberately allocates
         // nothing; pointing at it here sent users to a command that silently did
@@ -1027,6 +1350,8 @@ export class Gitvault {
             repo_id: repoId,
             project_id: options.project_id ?? record?.project_id ?? null,
             vault: record,
+            reconcile_recipients: reconcileRecipients,
+            enrollment,
             keystore: {
                 present: keystorePresent,
                 identity_fingerprint: identityFingerprint,
@@ -1142,7 +1467,13 @@ export class Gitvault {
         // with no signing key) is reported BESIDE the vault result, never a
         // `push()` throw, same non-blocking contract as the mirror hook above.
         const reconcileRecipients = await this.#tryReconcileEnvelopeRecipients(handle.vault);
-        return { ...result, snapshot, gitvault_commit: snapshot.oid, gitvault_commit_line: line, mirror_push: mirrorPush, byo_chain_copy: byoChainCopy, reconcile_recipients: reconcileRecipients };
+        // gitvault-multi-writer (task 5.7) — the SAME best-effort contract,
+        // fired right beside the encryption-recipient reconcile above: a fresh
+        // push proves this session's own key is an active writer, so this is
+        // the natural place a just-admitted member's own next push clears
+        // whatever candidacy it left behind for OTHER pending members too.
+        const writerReconcile = await this.#tryReconcileWriterAdmissions(handle.vault);
+        return { ...result, snapshot, gitvault_commit: snapshot.oid, gitvault_commit_line: line, mirror_push: mirrorPush, byo_chain_copy: byoChainCopy, reconcile_recipients: reconcileRecipients, writer_reconcile: writerReconcile };
     }
     // ── Handoff / resume (kygit-handoff design D1-D10) ─────────────────────────
     /**
@@ -1159,7 +1490,7 @@ export class Gitvault {
      */
     async handoff(options) {
         const [{ deployRefTransaction }, { captureHandoffSnapshot, snapshotCommitment }, ho] = await Promise.all([this.#publication(), this.#snapshot(), this.#handoff()]);
-        const { assembleHandoffKey, deriveHandoffSecrets, sealHandoffEnvelope, assertHandoffNoteHasNoSecret, HANDOFF_ENVELOPE_KIND } = ho;
+        const { assembleHandoffKey, deriveHandoffSecrets, sealHandoffEnvelopeV2, assertHandoffNoteHasNoSecret, buildWriterAdmissionGrant, deriveWriterAdmissionSeed } = ho;
         const handle = options.address ? (await this.resolveOrCreateAddress({ ...options, address: options.address, allow_create: false })).handle : await this.open(options);
         const repoDir = options.repo_dir ?? process.cwd();
         const repoFile = handle.keystore.readRepo(handle.repo_id);
@@ -1167,6 +1498,34 @@ export class Gitvault {
             throw new LocalError(`no local key material for ${handle.repo_id} — this principal is not yet a member with a materialized envelope (push once first)`, "minting a handoff", { code: "GITVAULT_VAULT_UNRESOLVED" });
         }
         const kRepo = hexToBytes(repoFile.k_repo_hex);
+        // gitvault-multi-writer rev 47 (task 5.5, design D4): only an ACTIVE
+        // WRITER may mint — the gateway enforces this authoritatively at mint
+        // time (`403 HANDOFF_MINT_REQUIRES_WRITER`), but failing that late
+        // would mean this call already paid for a checkpoint capture + push +
+        // envelope seal for nothing. `writer_set_pin` is freshly set by the
+        // `verifyToNewest` this vault's `open()` above just ran (never stale by
+        // more than this session's own most recent verify), so checking it
+        // here is a cheap, typed, LOCAL fail-fast — never the check's source of
+        // truth, which stays server-side.
+        const identity = handle.keystore.readIdentity();
+        const localWriterKeyId = identity?.signing_fingerprint ?? null;
+        if (!localWriterKeyId || !repoFile.writer_set_pin?.writers.some((w) => w.writer_key_id === localWriterKeyId)) {
+            throw new LocalError("this keystore's signing key is not an admitted writer of this vault — minting a handoff requires an ACTIVE writer (design D4); an existing writer must add this key first (`run402 org members add` / repos access sync), or push once to reconcile if a pending admission already exists", "minting a handoff", { code: "GITVAULT_WRITER_NOT_ADMITTED" });
+        }
+        // The grant's `minted_role` must EXACTLY predict what the gateway's own
+        // role-attenuation (`services/gitvault/claims.ts mintHandoff`) will
+        // compute, or the grant fails VALIDATION_FAILED after this call has
+        // already paid for the checkpoint push below — `predictMintedRole`
+        // mirrors that formula against the SAME `ORG_ROLE_RANK` lattice
+        // `gitvault-writer-state.ts` already uses elsewhere in this codebase.
+        const { predictMintedRole } = await this.#writerState();
+        const vaultRecord = await this.get(handle.repo_id);
+        const who = await this.#client.request("/agent/v1/whoami", { context: "resolving this principal's org role for the handoff grant" });
+        const membership = who.memberships.find((m) => m.org_id === vaultRecord.org_id && m.status === "active");
+        if (!membership) {
+            throw new LocalError(`this principal has no active membership on ${vaultRecord.org_id} — an active writer must also be an active org member to mint a handoff`, "minting a handoff", { code: "GITVAULT_ACCESS_DENIED" });
+        }
+        const grantMintedRole = predictMintedRole(options.role, membership.role);
         const snapshot = await captureHandoffSnapshot({
             dir: repoDir,
             ...(options.includeSensitive !== undefined ? { includeSensitive: options.includeSensitive } : {}),
@@ -1205,14 +1564,50 @@ export class Gitvault {
         const handoffId = randomHandoffUuid();
         const { key, handoff_id_bytes, master_secret } = assembleHandoffKey(handoffId, randomBytes(32));
         const secrets = deriveHandoffSecrets(handoff_id_bytes, master_secret);
-        const sealed = sealHandoffEnvelope(handoff_id_bytes, secrets.wrap_key, {
-            v: 1,
+        // gitvault-multi-writer rev 47 (task 5.5, design D4) — the MINTER's own
+        // writer key signs `writer_admission_grant`, authorizing whoever claims
+        // this handoff to become a writer (D224/D225). This is a HARD
+        // requirement distinct from the earlier `writer_set_pin` presence
+        // check: that check only proves the fingerprint is admitted, not that
+        // THIS checkout still holds the seed to sign with — a read-only
+        // recovery identity (no local `signing_seed_hex`) can be an admitted
+        // writer's fingerprint yet be structurally unable to mint from here.
+        //
+        // Built BEFORE the envelope is sealed — design D4's "no hash cycle:
+        // grant first, then seal" — so the v2 envelope below can embed this
+        // grant's own stored-bytes SHA-256, letting the claimant's `resume()`
+        // (task 5.6) cross-check the claim response's grant against what this
+        // call actually sealed, independent of anything the gateway could alter.
+        const signingKeypair = handle.keystore.signingKeypair(identity); // non-null: the writer precheck above already required identity.signing_fingerprint
+        if (!signingKeypair) {
+            throw new LocalError("this keystore has no local signing seed — it can read the vault's writer identity but cannot sign a writer_admission_grant from here (a read-only recovery identity); mint from a checkout that holds the full signing seed", "minting a handoff", { code: "VAULT_UNRECOVERABLE" });
+        }
+        const handoffAdmissionSeed = deriveWriterAdmissionSeed(handoff_id_bytes, master_secret);
+        const grant = buildWriterAdmissionGrant({
+            repo_id: handle.repo_id,
+            handoff_id: handoffId,
+            auth_hash: secrets.auth_hash_hex,
+            checkpoint_generation: pushResult.generation,
+            checkpoint_head_sha256: pushResult.head_sha256,
+            minted_role: grantMintedRole,
+            // Mirrors the gateway's own HANDOFF_DEFAULT_TTL_SECONDS (3600) —
+            // `claim_not_after` is NOT cross-validated against the mint's actual
+            // TTL server-side (only well-formedness is checked), so this only
+            // needs to be a reasonable bound, not an exact prediction.
+            claim_not_after: new Date(Date.now() + (options.ttlSeconds ?? 3600) * 1000).toISOString(),
+            grantor_signing_seed: signingKeypair.seed,
+            handoff_admission_pubkey: ed25519PublicKey(handoffAdmissionSeed),
+        });
+        const grantSha256Local = sha256Hex(jcs(grant));
+        const sealed = sealHandoffEnvelopeV2(handoff_id_bytes, secrets.wrap_key, {
+            v: 2,
             kind: "handoff",
             repo_id: handle.repo_id,
             epoch: repoFile.epoch,
             k_e_hex: repoFile.k_repo_hex,
             checkpoint: { generation: pushResult.generation, commit_oid: snapshot.oid },
             note_schema: "kygit.handoff-note.v1",
+            writer_admission_grant_sha256: grantSha256Local,
         });
         // The wire shape is the gateway's documented one (llms-full.txt
         // "Handoff / resume"): `role` (the minted role), `repo_id` / `org_id` /
@@ -1227,14 +1622,22 @@ export class Gitvault {
                 ...(options.ttlSeconds !== undefined ? { expires_in_seconds: options.ttlSeconds } : {}),
                 checkpoint: { generation: pushResult.generation, snapshot_oid_hmac: snapshotOidHmac },
                 sealed_envelope: sealed.sealed_envelope,
-                envelope_kind: sealed.envelope_kind ?? HANDOFF_ENVELOPE_KIND,
+                envelope_kind: sealed.envelope_kind,
                 auth_hash: secrets.auth_hash_hex,
+                writer_admission_grant: toBase64url(jcs(grant)),
             },
             context: "minting a handoff key",
         });
         if (response.handoff_id !== handoffId) {
             throw new LocalError(`the gateway minted a different handoff_id (${response.handoff_id}) than requested (${handoffId}) — the assembled key would not match; retry`, "minting a handoff key", { code: "HANDOFF_ID_MISMATCH", details: { requested: handoffId, minted: response.handoff_id } });
         }
+        // The gateway names back the SHA-256 of the EXACT writer_admission_grant
+        // bytes it stored — verified against this call's own local computation
+        // (never the other way around) so a gateway that silently altered the
+        // grant is caught here, before the key is ever handed to a recipient.
+        if (response.writer_admission_grant_sha256 !== grantSha256Local) {
+            throw new LocalError(`the gateway echoed a writer_admission_grant_sha256 (${response.writer_admission_grant_sha256}) that does not match what this call sent (${grantSha256Local}) — the stored grant may not be the one this call signed; do not distribute this handoff key`, "minting a handoff key", { code: "HANDOFF_MINT_GRANT_MISMATCH", details: { expected: grantSha256Local, received: response.writer_admission_grant_sha256 } });
+        }
         return {
             handoff_key: key,
             handoff_id: response.handoff_id,
@@ -1292,49 +1695,129 @@ export class Gitvault {
      * git-config pins only → the session-start reconcile so a principal
      * envelope supersedes the bearer one.
      */
+    /**
+     * gitvault-multi-writer rev 47 (task 5.6, design D4/D5) — order: parse →
+     * ensure wallet → ensure identity → derive auth/wrap/admission → build
+     * acceptance → claim → verify grant → open envelope → check the grant
+     * hash → persist repo file with `pending_writer_admission` → clone →
+     * verify chain → submit the ref-neutral activation head → reconcile
+     * principal envelope → apply the checkpoint. Reported as
+     * `writer_activation` and `reconcile_recipients` (D5's "recipient
+     * coverage"), two blocks, because they are two properties.
+     *
+     * Crash-resumable by construction, not by a special-cased retry branch:
+     * the acceptance is derived fresh every call from the (deterministic)
+     * admission seed + this checkout's own identity, so re-running this
+     * ENTIRE method after a crash anywhere before activation lands is safe —
+     * the claim route is itself idempotent (same-claimant replay returns the
+     * SAME grant). The one step that is NOT safely repeatable is submitting
+     * the activation head a second time (the chain burns `handoff_id`
+     * single-use) — `submitWriterActivationHead` handles that by checking
+     * whether this checkout's own key is ALREADY in the freshly-verified
+     * writer set before ever building a transition, exactly mirroring
+     * `handoff()`'s own writer precheck (task 5.5), just inverted: there
+     * "not yet a writer" refuses; here "already a writer" means skip.
+     */
     async resume(options) {
-        const [ho, { GitvaultKeystore }, { createGitvaultHttpTransport }, restore] = await Promise.all([this.#handoff(), this.#keystore(), this.#publication(), this.#restore()]);
-        const { parseHandoffKey, deriveHandoffSecrets, openHandoffEnvelope } = ho;
+        const [ho, { GitvaultKeystore }, restore] = await Promise.all([this.#handoff(), this.#keystore(), this.#restore()]);
+        const { parseHandoffKey, deriveHandoffSecrets, deriveWriterAdmissionSeed, buildWriterAcceptance, openHandoffEnvelopeV2 } = ho;
         const { cloneGitvaultRemote, applyHandoffCheckpoint, resolveResumeTargetDir, readGitCommitMessage } = restore;
+        // parse
         const parsed = parseHandoffKey(options.key);
-        const secrets = deriveHandoffSecrets(parsed.handoff_id_bytes, parsed.master_secret);
-        // A fresh machine has no wallet, and the claim route accepts ONLY a SIWX
-        // wallet signature (a control-plane session, delegate, or service key is
-        // refused HANDOFF_CLAIM_REQUIRES_WALLET — the keystore key the claim
-        // publishes is what makes the recipient a real key-holder). Nothing
-        // upstream creates the allowance for an unpaid request, so `resume` does
-        // it here, exactly as `repos resume --help` promises: a keypair written
-        // to the allowance file, no faucet, no tier, no payment. The 2026-09-02
-        // rehearsal's Session B hit AUTH_REQUIRED on a bare machine for want of
-        // this. A provider without allowance support (an isomorphic one) is
-        // left alone — it authenticates however it authenticates.
+        // ensure wallet — A fresh machine has no wallet, and the claim route
+        // accepts ONLY a SIWX wallet signature (a control-plane session,
+        // delegate, or service key is refused HANDOFF_CLAIM_REQUIRES_WALLET —
+        // the keystore key the claim publishes is what makes the recipient a
+        // real key-holder). Nothing upstream creates the allowance for an
+        // unpaid request, so `resume` does it here, exactly as `repos resume
+        // --help` promises: a keypair written to the allowance file, no
+        // faucet, no tier, no payment. Without it a bare machine answers
+        // AUTH_REQUIRED. A provider without
+        // allowance support (an isomorphic one) is left alone — it
+        // authenticates however it authenticates.
         await this.#ensureLocalWallet(options.onLine);
+        // ensure identity — BEFORE claim (D5): the acceptance below needs this
+        // checkout's own signing key, which the claim REQUEST body carries.
+        const keystore = new GitvaultKeystore(options.keystore_root !== undefined ? { rootDir: options.keystore_root } : {});
+        const identity = keystore.ensureIdentity();
+        const signingKeypair = keystore.signingKeypair(identity);
+        if (!signingKeypair) {
+            throw new LocalError("this keystore has no local signing seed — resuming a gitvault-multi-writer handoff requires signing writer_acceptance with a full Ed25519 seed, which a read-only recovery identity does not hold", "resuming a handoff", { code: "VAULT_UNRECOVERABLE" });
+        }
+        const claimantEncryptionPubkeyRaw = fromBase64url(identity.encryption_pubkey, "identity.encryption_pubkey");
+        // derive auth/wrap/admission
+        const secrets = deriveHandoffSecrets(parsed.handoff_id_bytes, parsed.master_secret);
+        const admissionSeed = deriveWriterAdmissionSeed(parsed.handoff_id_bytes, parsed.master_secret);
+        // build acceptance — before claim: design D4's own point is that the
+        // claimant can construct BOTH signatures before ever seeing the stored
+        // grant, since `handoff_id`/`auth_hash` are already independently known.
+        const acceptance = buildWriterAcceptance({
+            handoff_id: parsed.handoff_id,
+            auth_hash: secrets.auth_hash_hex,
+            admission_seed: admissionSeed,
+            claimant_signing_seed: signingKeypair.seed,
+            claimant_encryption_pubkey_raw: claimantEncryptionPubkeyRaw,
+        });
+        // claim
         const claim = await this.#client.request(`/gitvault/v1/handoffs/${encodeURIComponent(parsed.handoff_id)}/claim`, {
             method: "POST",
             // Base64url, per the documented wire contract (openapi: "Base64url — the
             // HKDF-derived auth_secret half of the parsed kgh1_ key"). The gateway
             // decodes base64/base64url and substitutes 32 zero bytes for anything
-            // else, so a hex-encoded secret — what 4.67.0 through 4.68.0 sent — never
-            // matched any stored hash: every claim answered HANDOFF_KEY_INVALID (the
-            // 2026-09-02 rehearsal, Session B). Each side's own tests passed; only
-            // the cross-side vector below catches this class.
-            body: { auth_secret: toBase64url(secrets.auth_secret) },
+            // else, so a hex-encoded secret never matches any stored hash and every
+            // claim answers HANDOFF_KEY_INVALID. Each side's own tests can pass
+            // independently; only the cross-side vector below catches this class.
+            body: { auth_secret: toBase64url(secrets.auth_secret), writer_acceptance: toBase64url(jcs(acceptance)) },
             context: "claiming a handoff key",
         });
         // The claim names the vault by id only (no slug-form address rides the
         // wire), so the default target directory falls back to the vault id —
         // `--to <dir>` names it explicitly.
         const vault = handoffVaultFromWire(claim);
-        const payload = openHandoffEnvelope(parsed.handoff_id_bytes, secrets.wrap_key, claim.sealed_envelope, claim.envelope_kind);
+        // verify grant — a light structural/binding check, NOT the full
+        // cryptographic verification (which needs the vault's writer set to
+        // resolve the grantor's pubkey, and therefore waits until the chain is
+        // walked below — protocol §4.17's own admission ordering, not skipped,
+        // just not reachable from here yet).
+        let grantBytes;
+        try {
+            grantBytes = fromBase64url(claim.writer_admission_grant, "writer_admission_grant");
+        }
+        catch {
+            throw new LocalError("the claim response's writer_admission_grant is not valid base64url", "resuming a handoff", { code: "VALIDATION_FAILED", details: { field: "writer_admission_grant" } });
+        }
+        let grant;
+        try {
+            grant = JSON.parse(new TextDecoder().decode(grantBytes));
+        }
+        catch {
+            throw new LocalError("the claim response's writer_admission_grant does not decode to valid JSON", "resuming a handoff", { code: "VALIDATION_FAILED", details: { field: "writer_admission_grant" } });
+        }
+        if (grant.handoff_id !== parsed.handoff_id || grant.auth_hash !== secrets.auth_hash_hex || grant.repo_id !== vault.vault_id) {
+            throw new LocalError("the claim response's writer_admission_grant does not bind this handoff — refusing", "resuming a handoff", { code: "VALIDATION_FAILED", details: { field: "writer_admission_grant" } });
+        }
+        const grantSha256 = sha256Hex(grantBytes);
+        // open envelope — v2 (task 5.4): the v2 payload's own
+        // writer_admission_grant_sha256 is what the next step cross-checks;
+        // opening under the SAME v1/v2-requiring rule that refuses a
+        // pre-gitvault-multi-writer mint's envelope outright.
+        const payload = openHandoffEnvelopeV2(parsed.handoff_id_bytes, secrets.wrap_key, claim.sealed_envelope, claim.envelope_kind);
         if (payload.repo_id !== vault.vault_id) {
             throw new LocalError("the opened envelope's repo_id does not match the claim response's vault — refusing", "resuming a handoff", { code: "HANDOFF_ENVELOPE_INVALID" });
         }
-        const keystore = new GitvaultKeystore(options.keystore_root !== undefined ? { rootDir: options.keystore_root } : {});
-        keystore.ensureIdentity();
+        // check the grant hash — design D4's own integrity binding: the SEALED
+        // envelope (wrap_key-authenticated, the gateway never holds wrap_key)
+        // names the grant it was minted alongside; if the claim response's
+        // grant doesn't match, something between mint and claim substituted a
+        // different one — refuse before spending anything on this handoff.
+        if (payload.writer_admission_grant_sha256 !== grantSha256) {
+            throw new LocalError(`the claim response's writer_admission_grant (sha256 ${grantSha256}) does not match the hash sealed into the envelope at mint time (${payload.writer_admission_grant_sha256}) — refusing to activate under a substituted grant`, "resuming a handoff", { code: "HANDOFF_CLAIM_WRITER_KEY_MISMATCH", details: { expected: payload.writer_admission_grant_sha256, received: grantSha256 } });
+        }
         // Genesis must be pinned before ANY materialize call can succeed
         // (`GitvaultVault.genesis()` requires a keystore repo file — this is
         // the one read that happens BEFORE one exists, via the transport
         // directly, mirroring `restoreRepoFromEnvelope`'s own signature check).
+        const { createGitvaultHttpTransport } = await this.#publication();
         const transport = createGitvaultHttpTransport(this.#client);
         const genesisBytes = await transport.getGenesis({ repo_id: vault.vault_id });
         if (!genesisBytes) {
@@ -1345,7 +1828,13 @@ export class Gitvault {
             throw new LocalError("vault_genesis signature does not verify", "resuming a handoff", { code: "GITVAULT_SIGNATURE_INVALID", details: { repo_id: vault.vault_id } });
         }
         const genesisSha = sha256Hex(genesisBytes);
-        // Write the repo file to the keystore BEFORE touching disk (design D10).
+        // persist repo file with pending_writer_admission — BEFORE clone/chain
+        // work below (design D10's "write to keystore before touching disk",
+        // extended): a crash from here on leaves a durable record of the
+        // ALREADY-VERIFIED grant, so a retry never needs to re-claim (the
+        // acceptance is trivially re-derivable from data already in hand, per
+        // this method's own doc comment above; only the grant is not).
+        const myWriterKeyId = identity.signing_fingerprint;
         keystore.saveRepo({
             repo_id: vault.vault_id,
             org_id: vault.organization_id,
@@ -1357,22 +1846,61 @@ export class Gitvault {
             head_pin: null,
             last_ref_transaction: null,
             provenance: "restored_from_handoff",
+            pending_writer_admission: { handoff_id: parsed.handoff_id, writer_admission_grant: grant, claimed_writer_key_id: myWriterKeyId },
         });
         const targetDir = await resolveResumeTargetDir(options.to, vault.address, vault.vault_id);
         options.onLine?.(`resuming into ${targetDir}`);
         const remoteUrl = gitvaultRemoteUrl(vault.organization_id, vault.project_id);
         await cloneGitvaultRemote(remoteUrl, targetDir);
-        const restored = await applyHandoffCheckpoint({ dir: targetDir, stash_oid: payload.checkpoint.commit_oid });
         // Local-only pins (design D10) — never a worktree file, never the
         // global active project. Reuses the SAME pin-writer every other
         // gitvault resolution path uses, which also writes `r402.room`.
         const { pinGitvaultRepo } = await this.#address();
         const addressParts = vault.address ? vault.address.split("/") : null;
         await pinGitvaultRepo(targetDir, vault.vault_id, addressParts && addressParts.length === 2 ? { org_slug: addressParts[0], repo_name: addressParts[1] } : undefined, { project_id: vault.project_id, org_id: vault.organization_id });
-        // The bearer envelope is superseded within minutes of use — run the
-        // same reconcile `push()` runs, best-effort (never a `resume()` throw).
-        const handle = await this.open({ repo_id: vault.vault_id, repo_dir: targetDir, keystore_root: options.keystore_root });
+        // verify chain — `open()` here mainly constructs the `GitvaultVault`
+        // instance: its own `ensureRepoState()` (the cold-open restore path)
+        // no-ops the instant it sees a repo file already on disk — and the
+        // `saveRepo` call above just wrote one. The chain walk this method
+        // actually needs happens a moment later, the FIRST time
+        // `submitWriterActivationHead` calls `materialize()` on `handle.vault`
+        // below — `materialize()` unconditionally runs `verifyToNewest()` on
+        // every call, cold-open or not, which is what freshly pins
+        // `writer_set_pin`. `options.reconcile: "forbidden"` here: the
+        // encryption-envelope reconcile is deliberately deferred to its own
+        // explicit step AFTER activation (D5's ordering), not run implicitly
+        // and possibly twice.
+        const handle = await this.open({ repo_id: vault.vault_id, repo_dir: targetDir, keystore_root: options.keystore_root, reconcile: "forbidden" });
+        // `added_writer.principal_id` names the claimant's OWN control-plane
+        // principal — the claim response never carries it (its `membership`
+        // block names the ORG, not the principal), so resolve it fresh here,
+        // the same one-call pattern `handoff()` already uses for its own role
+        // resolution (task 5.5).
+        const who = await this.#client.request("/agent/v1/whoami", { context: "resolving this principal's id for the writer activation head" });
+        // submit the ref-neutral activation head
+        const activation = await handle.vault.submitWriterActivationHead({
+            addedWriterKeyId: myWriterKeyId,
+            addedSigningPubkeyB64u: identity.signing_pubkey,
+            addedPrincipalId: who.principal.id,
+            handoffId: parsed.handoff_id,
+            grant,
+            acceptance: acceptance,
+        });
+        const activationGeneration = activation.outcome === "activated" ? activation.result.generation : activation.generation;
+        // Clearing pending_writer_admission now that the activation head is
+        // (or already was — the idempotent-skip case) admitted mirrors
+        // writer_status flipping to "active" at the same moment, per this
+        // field's own doc comment in gitvault-keystore.ts.
+        keystore.updateRepo(vault.vault_id, { pending_writer_admission: null });
+        // reconcile principal envelope — the bearer envelope is superseded
+        // within minutes of use; run the same reconcile `push()` runs,
+        // best-effort (never a `resume()` throw), NOW that this checkout is an
+        // admitted writer and the reconcile's own wrap step is meaningful.
         const reconcile = await this.#tryReconcileEnvelopeRecipients(handle.vault);
+        // apply the checkpoint — LAST (D5): a failure anywhere above this line
+        // leaves the working tree untouched (freshly cloned, nothing stashed),
+        // the cleanest possible state to retry `resume()` from.
+        const restored = await applyHandoffCheckpoint({ dir: targetDir, stash_oid: payload.checkpoint.commit_oid });
         const senderIsOwner = claim.membership.role === "owner";
         const nextActions = [...(claim.next_actions ?? [])];
         if (claim.kind === "handoff" && senderIsOwner && !nextActions.some((a) => a.type === "remove_member")) {
@@ -1406,6 +1934,7 @@ export class Gitvault {
             membership: handoffMembershipFromWire(claim.membership),
             members: claim.members ?? [],
             expires_at: claim.expires_at,
+            writer_activation: { outcome: "active", writer_key_id: myWriterKeyId, generation: activationGeneration },
             reconcile_recipients: reconcile,
             next_actions: nextActions,
         };
@@ -1474,18 +2003,46 @@ export class Gitvault {
             return { attempted: false, outcome: "skipped_no_mirror", error: e instanceof Error ? e.message : String(e) };
         }
     }
-    /** Best-effort envelope-recipient reconcile: catches EVERYTHING so a reconcile problem can never surface as a `push()` throw (mirrors {@link #tryMirrorPush}'s contract exactly). */
+    /** Best-effort envelope-recipient reconcile: availability and local-policy failures never surface as a `push()` throw (mirroring {@link #tryMirrorPush}), but INTEGRITY verdicts do — `RECONCILE_FATAL_CODES` propagates tampering evidence instead of demoting it to `skipped_error` (round 3 blocker 2). */
     async #tryReconcileEnvelopeRecipients(vault) {
         try {
             const result = await vault.reconcileEnvelopeRecipients();
             return { attempted: true, outcome: "reconciled", result };
         }
         catch (e) {
+            rethrowFatalReconcile(e);
+            return { attempted: false, outcome: "skipped_error", error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    /**
+     * gitvault-multi-writer (task 5.7) — best-effort writer-admission
+     * reconcile, the SAME non-blocking contract as {@link
+     * #tryReconcileEnvelopeRecipients} beside it: availability failures
+     * (network, an older gateway missing `pending_writers`/`signing_pubkey`,
+     * a CAS-conflict-exhausted admission) never surface as a `push()`/
+     * `deploy()`/`open()` throw — `GitvaultVault.reconcileWriterAdmissions()`
+     * ALREADY returns an empty result rather than throwing for the ordinary
+     * "I am not a writer yet" case, so `skipped_error` here is reserved for
+     * genuinely unexpected failures (a transport fault mid-loop, a thrown
+     * chain-integrity verdict from the `materialize()` this reconcile's own
+     * admission attempts re-run). `rethrowFatalReconcile` is reused as-is:
+     * its `RECONCILE_FATAL_CODES` set is envelope-specific today (no writer-
+     * chain-integrity code is in it yet), so this call is a no-op unless a
+     * future code is added there — cheap, forward-compatible, and consistent
+     * with the sibling method rather than a silently different policy.
+     */
+    async #tryReconcileWriterAdmissions(vault) {
+        try {
+            const result = await vault.reconcileWriterAdmissions();
+            return { attempted: true, outcome: "reconciled", result };
+        }
+        catch (e) {
+            rethrowFatalReconcile(e);
             return { attempted: false, outcome: "skipped_error", error: e instanceof Error ? e.message : String(e) };
         }
     }
     /**
-     * A REAL preview of what {@link push} would publish (kychee-com/run402#565)
+     * A REAL preview of what {@link push} would publish
      * — never publishes anything, and never allocates. `run402 gitvault
      * snapshot --dry-run` and `git-remote-run402`'s `option dry-run true` are
      * both thin adapters over this method.
@@ -1685,7 +2242,7 @@ export class Gitvault {
     }
     /**
      * Open this vault's compaction headroom grant, shared by `compact()` and
-     * `prune({ submit })` (kychee-com/run402#578 fix 3) — both write ceremony
+     * `prune({ submit })` — both write ceremony
      * objects into the vault and both need the same single-flight-per-vault
      * headroom slot. Four outcomes:
      *   - opened: the grant is returned, carrying `effective_pool_limit_bytes`.
@@ -1947,7 +2504,7 @@ export class Gitvault {
             implementation_version: prune.GITVAULT_SDK_VERIFIER_VERSION,
         }, handle.vault.signer());
         const intent = prune.buildPruneIntent(core, [ours, options.submit.verifier_receipt], handle.vault.signer());
-        // kychee-com/run402#578 fix 3: the submission writes ~8 KB of ceremony
+        // The submission writes ~8 KB of ceremony
         // objects (both verifier receipts + the intent) into the vault — on a
         // vault that is over-quota BECAUSE it just compacted, that write is
         // refused QUOTA_EXCEEDED, so the deletion's own paperwork is blocked by
@@ -2004,7 +2561,7 @@ export class Gitvault {
             await handle.vault.transport.uploadObjects({ repo_id: handle.repo_id, objects });
         }
         catch (e) {
-            // kychee-com/run402#578 fix 2: receipt object ids are DETERMINISTIC —
+            // Receipt object ids are DETERMINISTIC —
             // the same core + the same signer produce the same id on every retry —
             // and Ed25519 signing is deterministic too, so the SAME id can only
             // mean the SAME bytes when nothing about the receipt's content
@@ -2081,11 +2638,10 @@ export class Gitvault {
     }
     /**
      * `repos fsck` (repo-surface-consolidation D2/D3): walk the head chain
-     * (what `verify()` did) AND materialize the ref map (what `status({refs:
-     * true})` used to do before `--refs` was removed from `view`), reporting
+     * AND materialize the ref map, reporting
      * BOTH local trust pins — authenticated and materialized — before and
      * after, with an explicit `local_state_changed` flag. This is the one
-     * place chain materialization and pin advance live now; `view` never
+     * place chain materialization and pin advance live; `view` never
      * calls it.
      *
      * `options.write` (default `true`) is the inverse of the CLI's
@@ -2129,7 +2685,10 @@ export class Gitvault {
                 : "pass repo_id, or project_id to resolve it from the control plane", "running gitvault fsck", { code: "GITVAULT_VAULT_UNRESOLVED", details: { project_id: options.project_id ?? null } });
         }
         const write = options.write ?? true;
-        const handle = await this.open({ ...options, repo_id: repoId });
+        // gitvault-agent-envelopes D5: fsck is observational — it never wraps an
+        // envelope, in write mode or not. Investigating a suspicious pending
+        // recipient must not complete the disclosure being investigated.
+        const handle = await this.open({ ...options, repo_id: repoId, reconcile: "forbidden" });
         const state = await handle.vault.verifyToNewest({ persist: write, decryptValidate: true, strict: false });
         const mirror = options.mirror ? await this.mirrorVerify({ ...options, repo_id: repoId }) : null;
         const decrypt = state.decrypt; // decryptValidate: true always populates this
@@ -2251,12 +2810,10 @@ export class Gitvault {
      * gateway `public_key` gap, and why this is a workaround rather than the
      * eventual epoch-rotation design).
      *
-     * `run402 gitvault reconcile` was this method's explicit standalone CLI
-     * surface (design D5's "session start" hook); repo-surface-consolidation
-     * D5/D7/D10 REMOVED it (no `repos` equivalent — `reconcile` is a
-     * workaround, not a permanent verb) and it now answers `COMMAND_REMOVED`
-     * pointing at `repos access` for inspection. This method itself is
-     * unchanged and un-retired: `deploy()` still runs it, best-effort,
+     * `run402 gitvault reconcile` has no `repos` equivalent — `reconcile` is
+     * a workaround, not a permanent verb — and answers `COMMAND_REMOVED`
+     * pointing at `repos access` for inspection. This method itself stays:
+     * `deploy()` runs it, best-effort,
      * whenever a deploy lands a new generation in the vault — design D5's
      * "deploy time" hook, "the same 'one command every agent runs' argument
      * that decided deploy-implies-capture." `push()` (capture-and-publish
@@ -2270,6 +2827,27 @@ export class Gitvault {
         const handle = await this.open(options);
         return handle.vault.reconcileEnvelopeRecipients();
     }
+    /**
+     * gitvault-multi-writer (task 5.7) — admit every eligible `pending_writers[]`
+     * candidate (active org membership at role developer+, a published,
+     * possession-verified signing key, not yet in the writer set) via a fresh
+     * `add_writer_key{"writer"}` head per candidate. This session's OWN key
+     * must already be an active writer — see {@link
+     * import("../node/gitvault-publication.js").GitvaultVault.
+     * reconcileWriterAdmissions}'s doc comment for why that is checked
+     * locally, once, rather than surfaced as N identical gateway refusals.
+     *
+     * The explicit standalone entry point for the SAME reconcile task 5.7
+     * also wires onto session-start/push/snapshot/deploy — calling it here
+     * is idempotent-safe alongside whatever `open()` above already ran
+     * internally (an already-admitted candidate is simply reported under
+     * `already_covered`, never re-admitted), mirroring {@link
+     * reconcileEnvelopeRecipients}'s own identical redundancy-tolerant shape.
+     */
+    async reconcile(options = {}) {
+        const handle = await this.open(options);
+        return handle.vault.reconcileWriterAdmissions();
+    }
     /**
      * 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
@@ -2312,8 +2890,8 @@ export class Gitvault {
      *
      * **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`
+     * revocation/exposure condition outstanding (D193).
+     * `#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
@@ -2356,6 +2934,28 @@ export class Gitvault {
         const repoId = await this.#resolveRepoId(options);
         const record = await this.get(repoId).catch(() => null);
         const orgId = record?.org_id ?? null;
+        // gitvault-agent-envelopes D3/D5: `access` is one of the ordinary reads a
+        // KEY-HOLDER's session starts with — enroll this keystore's key if absent
+        // and fulfil every pending desired recipient once per process, BEFORE the
+        // roster below is read, so the roster reflects the fulfilment. Reported,
+        // never folded into the roster; a machine holding no K_repo stays a pure
+        // read.
+        let reconcileRecipients = null;
+        let enrollment = null;
+        if (options.reconcile !== "forbidden") {
+            try {
+                const { GitvaultKeystore } = await this.#keystore();
+                const probe = new GitvaultKeystore(options.keystore_root !== undefined ? { rootDir: options.keystore_root } : {});
+                if (probe.readRepo(repoId)) {
+                    const handle = await this.open({ ...options, repo_id: repoId });
+                    reconcileRecipients = handle.reconcile_recipients;
+                    enrollment = handle.enrollment;
+                }
+            }
+            catch {
+                // best-effort — the roster read below is the verb's own result
+            }
+        }
         const [directory, coverage] = await Promise.all([
             orgId
                 ? this.#client.request(`/orgs/v1/${encodeURIComponent(orgId)}/encryption-keys`, { context: "reading the org encryption-key directory" })
@@ -2423,7 +3023,41 @@ export class Gitvault {
         // 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;
+        // gitvault-agent-envelopes: THIS machine's keystore is reported for every
+        // principal type — enrolled or not, covered or not — never `null` for a
+        // real keystore (only when there is no local identity at all). The
+        // directory now lists agent keys too, so "own fingerprint in the
+        // directory" is the enrolled case; an unenrolled creator's genesis
+        // envelope still shows as covered-but-unenrolled.
+        let publishState = "unknown";
+        if (ownFingerprint !== null) {
+            try {
+                const who = await this.#client.request("/agent/v1/whoami", { context: "reading this keystore's enrollment state" });
+                const key = who.encryption_key ?? null;
+                publishState = !key ? "absent" : key.ek_fingerprint !== ownFingerprint ? "rotation_required" : key.state === "active" ? "active" : "pending";
+            }
+            catch {
+                publishState = "unknown";
+            }
+        }
+        const thisKeystore = ownFingerprint !== null
+            ? {
+                fingerprint: ownFingerprint,
+                enrolled: publishState === "active",
+                publish_state: publishState,
+                covered_on_this_vault: covered.has(ownFingerprint),
+                covered: covered.has(ownFingerprint),
+                ...(!covered.has(ownFingerprint) && publishState === "active"
+                    ? { next_actions: [
+                            { action: "run402 repos access", why: "poll — 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" },
+                        ] }
+                    : {}),
+                ...(publishState === "rotation_required"
+                    ? { next_actions: [{ action: "restore the keystore backup, or have an org owner revoke the stale key (DELETE /orgs/v1/:org_id/members/:principal_id/encryption-key)", why: "this keystore's key differs from the principal's published key; rotation is never automatic" }] }
+                    : {}),
+            }
+            : 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 " +
@@ -2442,6 +3076,8 @@ export class Gitvault {
         return {
             repo_id: repoId,
             org_id: orgId,
+            reconcile_recipients: reconcileRecipients,
+            enrollment,
             recipients,
             unmatched_covered_fingerprints: unmatched,
             this_keystore: thisKeystore,
@@ -2495,14 +3131,15 @@ export class Gitvault {
         // function so the outcome-gating is unit-testable with fake thunks,
         // without standing up a live vault — see gitvault-deploy-hooks.test.ts.
         const hooked = await attachGitvaultDeployHooks(result, () => this.#tryMirrorPush(handle.repo_id, handle.keystore), () => this.#tryReconcileEnvelopeRecipients(handle.vault));
-        // gitvault-byo-primary-bucket task 3.3 — composed AFTER, not inside,
-        // `attachGitvaultDeployHooks` (kept untouched so its own unit-tested
-        // outcome-gating contract stays byte-for-byte): the SAME "did this
-        // deploy actually land a generation" gate `mirror_push`'s presence
-        // already encodes, so no new outcome-inspection logic here.
+        // gitvault-byo-primary-bucket task 3.3 / gitvault-multi-writer task 5.7
+        // — composed AFTER, not inside, `attachGitvaultDeployHooks` (kept
+        // untouched so its own unit-tested outcome-gating contract stays
+        // byte-for-byte): the SAME "did this deploy actually land a generation"
+        // gate `mirror_push`'s presence already encodes, so no new
+        // outcome-inspection logic here.
         if (hooked.mirror_push === undefined)
             return hooked;
-        return { ...hooked, byo_chain_copy: await this.#tryByoChainCopyPush(handle.repo_id, handle.keystore) };
+        return { ...hooked, byo_chain_copy: await this.#tryByoChainCopyPush(handle.repo_id, handle.keystore), writer_reconcile: await this.#tryReconcileWriterAdmissions(handle.vault) };
     }
     /**
      * Drain every unvaulted-override journal on this machine: push the exact
@@ -2748,6 +3385,9 @@ export class Gitvault {
     #handoff() {
         return nodeOnly(() => import("../node/gitvault-handoff.js"), "handoff");
     }
+    #writerState() {
+        return nodeOnly(() => import("../node/gitvault-writer-state.js"), "handoff");
+    }
     #restore() {
         return nodeOnly(() => import("../node/gitvault-restore.js"), "resume");
     }