@usesigil/kit 0.17.0 → 0.19.0

package/dist/dashboard/mutations.js

@@ -6,7 +6,7 @@
  */
 import { getProgramDerivedAddress, getAddressEncoder } from "../kit-adapter.js";
 import { getSigilModuleLogger } from "../logger.js";
-import { pipe, createTransactionMessage, setTransactionMessageFeePayer, setTransactionMessageLifetimeUsingBlockhash, appendTransactionMessageInstructions, addSignersToTransactionMessage, signTransactionMessageWithSigners, getBase64EncodedWireTransaction, } from "../kit-adapter.js";
+import { pipe, createTransactionMessage, setTransactionMessageFeePayer, setTransactionMessageLifetimeUsingBlockhash, appendTransactionMessageInstructions, addSignersToTransactionMessage, signTransactionMessageWithSigners, partiallySignTransactionMessageWithSigners, getBase64EncodedWireTransaction, } from "../kit-adapter.js";
 import { getSetComputeUnitLimitInstruction, getSetComputeUnitPriceInstruction, } from "@solana-program/compute-budget";
 import { sendAndConfirmTransaction, getBlockhashCache, } from "../rpc-helpers.js";
 import { AccountRole } from "../kit-adapter.js";
@@ -16,7 +16,9 @@ import { redactCause } from "../network-errors.js";
 import { SIGIL_PROGRAM_ADDRESS, MAX_ALLOWED_PROTOCOLS } from "../types.js";
 import { fetchAgentVault } from "../generated/accounts/agentVault.js";
 import { fetchPolicyConfig } from "../generated/accounts/policyConfig.js";
-import { computePolicyPreviewDigest } from "../policy/compute-policy-preview-digest.js";
+import { computePolicyPreviewDigest, computeAgentSetHash, } from "../policy/compute-policy-preview-digest.js";
+import { computeAgentPermsCosignDigest } from "../policy/compute-agent-perms-cosign-digest.js";
+import { computeCosignDigest } from "../policy/compute-cosign-digest.js";
 // Phase 3: Simple mutations
 import { getFreezeVaultInstructionAsync } from "../generated/instructions/freezeVault.js";
 import { getReactivateVaultInstructionAsync } from "../generated/instructions/reactivateVault.js";
@@ -38,7 +40,7 @@ import { getApplyPendingPolicyInstructionAsync } from "../generated/instructions
 import { getCancelPendingPolicyInstructionAsync } from "../generated/instructions/cancelPendingPolicy.js";
 import { getQueueAgentPermissionsUpdateInstructionAsync } from "../generated/instructions/queueAgentPermissionsUpdate.js";
 import { getApplyAgentPermissionsUpdateInstructionAsync } from "../generated/instructions/applyAgentPermissionsUpdate.js";
-import { getCancelAgentPermissionsUpdateInstruction } from "../generated/instructions/cancelAgentPermissionsUpdate.js";
+import { getCancelAgentPermissionsUpdateInstructionAsync } from "../generated/instructions/cancelAgentPermissionsUpdate.js";
 import { getCreatePostAssertionsInstructionAsync } from "../generated/instructions/createPostAssertions.js";
 import { getClosePostAssertionsInstructionAsync } from "../generated/instructions/closePostAssertions.js";
 // M-2 (pre-redeploy audit 2026-05-21): Phase 8 ownership-transfer ix builders.
@@ -147,12 +149,38 @@ async function siblingHandlerExpectedDigest(rpc, vault, override) {
         // this via `queue_policy_update` only.
         cosignRequired: livePolicy.data.cosignRequired,
         // D-5 (Bucket 2 audit 2026-05-21, F-RP3-1): pass-through from live
-        // policy. Position 22 of the canonical TA-19 digest. Sibling handlers
+        // policy. Position 21 of the canonical TA-19 digest. Sibling handlers
         // never mutate this — owner sets via queue_policy_update only.
         cosignSessionPubkey: livePolicy.data.cosignSessionPubkey,
+        // M-1 (audit 2026-06-11): per-protocol caps (positions 23-24). Sibling
+        // handlers never mutate the caps — pass-through from live policy so the
+        // re-bind digest matches the on-chain recompute (create_post_assertions
+        // .rs:138-139 / close_post_assertions.rs read policy.has_protocol_caps +
+        // policy.protocol_caps).
+        hasProtocolCaps: livePolicy.data.hasProtocolCaps,
+        protocolCaps: livePolicy.data.protocolCaps,
+        // HIGH (audit 2026-06-11 follow-up): create_post_assertions.rs:129 and
+        // close_post_assertions.rs recompute agent_set_hash from the LIVE vault
+        // agents, and :136 reads operator_grant_delay_seconds from live policy.
+        // Omitting them here defaulted the digest to EMPTY_AGENT_SET_HASH / 0n,
+        // mismatching the on-chain recompute (PolicyPreviewMismatch) for ANY vault
+        // with >=1 agent or a non-zero operator-grant delay — i.e. every real vault.
+        // vault.agents is the active-agent Vec (register pushes; owner-revoke
+        // removes the entry, auto-revoke zeroes its capability in place — either
+        // way membership matches the on-chain Vec), mapped 1:1 by
+        // computeAgentSetHash (mirrors compute_agent_set_hash).
+        agentSetHash: computeAgentSetHash(liveVault.data.agents),
+        operatorGrantDelaySeconds: livePolicy.data.operatorGrantDelaySeconds,
     });
 }
-async function run(rpc, owner, network, instructions, opts = {}) {
+async function run(rpc, owner, network, instructions, opts = {}, 
+// Elevated-cosign surface (audit 2026-06-12): additional signers beyond the
+// owner (e.g. a cosign-session signer for an elevated queue mutation). The
+// cosigner must ALSO be present in the instruction's account metas as a
+// readonly-signer (the elevated wrappers append it); attaching it here makes
+// its signature land in the wire tx. Default [] preserves the owner-only path
+// for every existing non-elevated caller.
+cosigners = []) {
     try {
         const cu = opts.computeUnits ?? CU_OWNER_ACTION;
         const allIx = [
@@ -171,7 +199,7 @@ async function run(rpc, owner, network, instructions, opts = {}) {
         const cache = getBlockhashCache(rpc);
         const blockhash = await cache.get(rpc);
         const txMessage = pipe(createTransactionMessage({ version: 0 }), (tx) => setTransactionMessageFeePayer(owner.address, tx), (tx) => setTransactionMessageLifetimeUsingBlockhash(blockhash, tx), (tx) => appendTransactionMessageInstructions(allIx, tx));
-        const txWithSigners = addSignersToTransactionMessage([owner], txMessage);
+        const txWithSigners = addSignersToTransactionMessage([owner, ...cosigners], txMessage);
         const signedTx = await signTransactionMessageWithSigners(txWithSigners);
         const wire = getBase64EncodedWireTransaction(signedTx);
         const signature = await sendAndConfirmTransaction(rpc, wire);
@@ -326,7 +354,7 @@ export async function cancelAgentGrant(rpc, vault, owner, network, opts) {
  * created/destroyed between the read and TX execution, the on-chain program
  * will reject the TX. This is a known race window — retry on failure.
  */
-export async function closeVault(rpc, vault, owner, network, opts) {
+async function buildCloseVaultFinalIx(rpc, vault, owner, network) {
     const net = network === "mainnet" ? "mainnet-beta" : "devnet";
     // Resolve vault state to determine which remaining_accounts are needed
     const state = await resolveVaultStateForOwner(rpc, vault, undefined, net);
@@ -420,6 +448,16 @@ export async function closeVault(rpc, vault, owner, network, opts) {
             ],
         }
         : ix;
+    return finalIx;
+}
+/**
+ * Close a vault (owner-only path — for vaults WITHOUT cosign). On a
+ * cosign-required vault the on-chain `close_vault` rejects an owner-only close
+ * with `ErrCosignRequired`; use {@link buildCloseVaultElevated} (partial-sign,
+ * bound cosigner co-signs) instead.
+ */
+export async function closeVault(rpc, vault, owner, network, opts) {
+    const finalIx = await buildCloseVaultFinalIx(rpc, vault, owner, network);
     return run(rpc, owner, network, [finalIx], {
         computeUnits: opts?.computeUnits ?? 400_000,
         priorityFeeMicroLamports: opts?.priorityFeeMicroLamports,
@@ -525,6 +563,37 @@ export async function withdraw(rpc, vault, owner, network, mint, amount, opts) {
  *   - `sessionExpirySeconds` range (5..=90 when > 0; audit F5-H1)
  */
 export async function queuePolicyUpdate(rpc, vault, owner, network, changes, opts) {
+    // Non-elevated path: cosign_session = Pubkey::default(), no cosigner in
+    // remaining_accounts, owner-only signature. Shares buildPolicyUpdateIx (the
+    // merged-effective projection + TA-19 digest) with queuePolicyElevated — the
+    // single source of truth that prevents digest drift between the two surfaces.
+    // An elevated change submitted here (e.g. raising a cap on a cosign_required
+    // vault) fails closed on-chain with ErrCosignRequired; use queuePolicyElevated.
+    const ix = await buildPolicyUpdateIx(rpc, owner, vault, changes, DEFAULT_COSIGN_SESSION);
+    return run(rpc, owner, network, [ix], opts);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Elevated-cosign surface (audit 2026-06-12) — policy path.
+//
+// queuePolicyElevated / buildQueuePolicyElevated mirror the agent-perms pair for
+// policy changes. They share buildPolicyUpdateIx with queuePolicyUpdate (DRY —
+// the single source of truth for the merged-effective projection + TA-19 digest;
+// duplicating it is the exact digest-drift failure mode the 2026-06-11 audit
+// fixed). The only difference between non-elevated and elevated is the
+// cosign_session arg (default vs a real cosigner pubkey) + the elevated-only
+// change fields, all plumbed through `eff = changes.X ?? live`.
+// ═══════════════════════════════════════════════════════════════════════════
+/** Pubkey::default() (System Program) — the non-elevated cosign_session arg. */
+const DEFAULT_COSIGN_SESSION = "11111111111111111111111111111111";
+/**
+ * Shared queue_policy_update instruction builder. Validates `changes`, fetches
+ * live policy+vault, projects the merged-effective policy (`eff = changes.X ??
+ * live.X` for EVERY field, so omitted fields fall through to live — the
+ * non-elevated path is byte-identical to the prior inline impl), computes the
+ * TA-19 digest over it, and builds the ix with the supplied `cosignSession`
+ * (DEFAULT_COSIGN_SESSION = non-elevated; a real cosigner pubkey = elevated).
+ */
+async function buildPolicyUpdateIx(rpc, owner, vault, changes, cosignSession) {
     if (Object.keys(changes).length === 0) {
         throw toDxError(new Error("At least one policy change is required"));
     }
@@ -542,10 +611,6 @@ export async function queuePolicyUpdate(rpc, vault, owner, network, changes, opt
         changes.approvedApps.length > MAX_ALLOWED_PROTOCOLS) {
         throw toDxError(new Error(`approvedApps length exceeds on-chain MAX_ALLOWED_PROTOCOLS (${MAX_ALLOWED_PROTOCOLS}). Got ${changes.approvedApps.length}. On-chain rejects TooManyAllowedProtocols.`));
     }
-    // Phase 2 TA-19: fetch live policy + vault state to compute the digest of
-    // the merged-effective policy that WILL result if this update is applied.
-    // The on-chain handler re-asserts the same digest at queue time, so any
-    // owner blind-sign that diverges from the SDK-projected update is rejected.
     const [policyPda] = await getPolicyPDA(vault);
     const livePolicy = await fetchPolicyConfig(rpc, policyPda);
     const liveVault = await fetchAgentVault(rpc, vault);
@@ -559,13 +624,21 @@ export async function queuePolicyUpdate(rpc, vault, owner, network, changes, opt
     const effDaily = changes.dailyCap ?? livePolicy.data.dailySpendingCapUsd;
     const effMaxTx = changes.maxPerTrade ?? livePolicy.data.maxTransactionSizeUsd;
     const effMaxSlip = changes.maxSlippageBps ?? livePolicy.data.maxSlippageBps;
-    // PEN-CROSS-6: developer_fee_rate is now part of the digest. Project the
-    // merged-effective value the same way as other Option<…> fields.
     const effDeveloperFeeRate = changes.developerFeeRate ?? livePolicy.data.developerFeeRate;
     const effTimelock = changes.timelock != null
         ? BigInt(changes.timelock)
         : livePolicy.data.timelockDuration;
     const effSessionExpiry = changes.sessionExpirySeconds ?? livePolicy.data.sessionExpirySeconds;
+    const effHasProtocolCaps = changes.hasProtocolCaps ?? livePolicy.data.hasProtocolCaps;
+    const effProtocolCaps = changes.protocolCaps ?? livePolicy.data.protocolCaps;
+    // Elevated-only fields (audit 2026-06-12): same merged-effective projection.
+    // Undefined ⇒ live pass-through, so queuePolicyUpdate's digest is unchanged.
+    const effStableFloor = changes.stableBalanceFloor ?? livePolicy.data.stableBalanceFloor;
+    const effPerRecip = changes.perRecipientDailyCapUsd ?? livePolicy.data.perRecipientDailyCapUsd;
+    const effCosignRequired = changes.cosignRequired ?? livePolicy.data.cosignRequired;
+    const effCosignSessionPubkey = changes.cosignSessionPubkey ?? livePolicy.data.cosignSessionPubkey;
+    const effOperatorDelay = changes.operatorGrantDelaySeconds ??
+        livePolicy.data.operatorGrantDelaySeconds;
     const newPolicyPreviewDigest = computePolicyPreviewDigest({
         dailySpendingCapUsd: effDaily,
         maxTransactionSizeUsd: effMaxTx,
@@ -579,31 +652,18 @@ export async function queuePolicyUpdate(rpc, vault, owner, network, changes, opt
         sessionExpirySeconds: effSessionExpiry,
         observeOnly: liveVault.data.observeOnly,
         hasPostAssertions: livePolicy.data.hasPostAssertions,
-        // PEN-CROSS-2: created_at_slot is immutable post-init — read from live.
         createdAtSlot: livePolicy.data.createdAtSlot,
-        // TA-05 (Phase 3): operating_hours is policy-owned and bound by TA-19.
-        // queueAgentPermissions does not currently mutate it through the
-        // dashboard mutation surface — read from live policy.
         operatingHours: livePolicy.data.operatingHours,
-        // TA-07/17 (Phase 3): same — not mutated by this dashboard surface.
         autoPromoteGrays: livePolicy.data.autoPromoteGrays,
         autoRevokeThreshold: livePolicy.data.autoRevokeThreshold,
-        // TA-12/14 (Phase 5): post-exec invariants. Not mutated by this surface;
-        // pass-through from live policy. Mutating them is elevated per TA-09.
-        stableBalanceFloor: livePolicy.data.stableBalanceFloor,
-        perRecipientDailyCapUsd: livePolicy.data.perRecipientDailyCapUsd,
-        // G6 (audit 2026-05-18 cosign opt-in): pass-through from live policy.
-        // The non-elevated dashboard surface does NOT mutate cosign_required;
-        // owners change cosign opt-in via a separate elevated workflow that
-        // includes the cosign signer (or, for false→true direction, can also
-        // be done non-elevated by passing the override directly through the
-        // ix arg below — but this dashboard helper keeps the policy stable
-        // for the default path).
-        cosignRequired: livePolicy.data.cosignRequired,
-        // F-Q6 (2026-06-02): operator_grant_delay not mutated by this dashboard
-        // surface — pass-through from live policy so the digest matches the
-        // on-chain merged (eff) value at canonical position 22.
-        operatorGrantDelaySeconds: livePolicy.data.operatorGrantDelaySeconds,
+        stableBalanceFloor: effStableFloor,
+        perRecipientDailyCapUsd: effPerRecip,
+        cosignRequired: effCosignRequired,
+        operatorGrantDelaySeconds: effOperatorDelay,
+        hasProtocolCaps: effHasProtocolCaps,
+        protocolCaps: effProtocolCaps,
+        agentSetHash: computeAgentSetHash(liveVault.data.agents),
+        cosignSessionPubkey: effCosignSessionPubkey,
     });
     const ix = await getQueuePolicyUpdateInstructionAsync({
         owner,
@@ -620,55 +680,55 @@ export async function queuePolicyUpdate(rpc, vault, owner, network, changes, opt
         hasProtocolCaps: changes.hasProtocolCaps ?? null,
         protocolCaps: changes.protocolCaps ?? null,
         destinationMode: changes.destinationMode ?? null,
-        // TA-05 (Phase 3): operating_hours is not mutated by this mutation
-        // surface — pass null to fall through to live policy at on-chain merge.
         operatingHours: null,
-        // TA-12/14 (Phase 5): not mutated by this non-elevated surface — pass
-        // null to fall through to live policy. Elevated mutations (lowering
-        // floor, raising per-recipient cap) require cosign and the
-        // `queuePolicyElevated()` helper.
-        stableBalanceFloor: null,
-        perRecipientDailyCapUsd: null,
-        // G6 (audit 2026-05-18 cosign opt-in): not mutated by this non-
-        // elevated surface — pass null to fall through to live policy.
-        // Toggling cosign on/off goes through a dedicated path that is
-        // aware of the one-way-ratchet semantics (true→false requires
-        // cosign; false→true does not).
-        cosignRequired: null,
-        // D-5 (Bucket 2 audit 2026-05-21, F-RP3-1): not mutated by this
-        // non-elevated surface — pass null to keep live policy value. Owner
-        // sets cosign_session_pubkey via a dedicated elevated helper that
-        // verifies the new pubkey isn't a Sigil-protected PDA at queue time.
-        cosignSessionPubkey: null,
-        // F-Q6 (2026-06-02): not mutated by this dashboard surface — pass null
-        // (falls through to live policy at on-chain merge). Configurability is
-        // available via the raw codama builder + owner paths.
-        operatorGrantDelaySeconds: null,
-        // TA-09 (Phase 3): non-elevated path by default — pass the
-        // System Program / zero-pubkey ("11111111111111111111111111111111").
-        // Elevated mutations through this dashboard surface require a
-        // follow-on `queuePolicyElevated()` helper (cosign-helper.ts, G4).
-        //
-        // CANONICAL `cosign_session` ARG CONTRACT (Round 2 §RP-2 B4 F-3,
-        // 2026-05-19) — for non-Codama callers reading this file as a
-        // reference impl:
-        //   - Non-elevated queue (this branch): pass `Pubkey::default()`
-        //     and OMIT any cosigner from `remaining_accounts`.
-        //   - Elevated queue (raising daily_cap, expanding destinations /
-        //     protocols, lowering stable_balance_floor, raising
-        //     per_recipient_daily_cap_usd, disabling protocol_caps, mutating
-        //     protocol_caps entries, or disabling cosign): pass a REAL session
-        //     pubkey + include it in `remaining_accounts` with
-        //     `is_signer == true`. Build the bundle via
-        //     `buildCosignBundle()` in `sdk/kit/src/cosign-helper.ts`.
-        //   - Reject path: a non-default `cosign_session` on a non-elevated
-        //     queue surfaces `InvalidPermissions` (6088). INTENTIONAL — the
-        //     on-chain handler refuses to silently downgrade a caller's
-        //     declared intent (Option A behaviour).
-        cosignSession: "11111111111111111111111111111111",
+        stableBalanceFloor: changes.stableBalanceFloor ?? null,
+        perRecipientDailyCapUsd: changes.perRecipientDailyCapUsd ?? null,
+        cosignRequired: changes.cosignRequired ?? null,
+        cosignSessionPubkey: changes.cosignSessionPubkey ?? null,
+        operatorGrantDelaySeconds: changes.operatorGrantDelaySeconds ?? null,
+        cosignSession,
         newPolicyPreviewDigest,
     });
-    return run(rpc, owner, network, [ix], opts);
+    return ix;
+}
+/**
+ * Elevated policy queue — single-builder dual-sign. Caller holds the cosigner
+ * key; signs [owner, cosigner] + sends. For true 2-party async use
+ * buildQueuePolicyElevated.
+ */
+export async function queuePolicyElevated(rpc, vault, owner, network, changes, cosigner, opts) {
+    requireValidAddress(cosigner.address, "Cosigner address");
+    if (cosigner.address === owner.address) {
+        throw toDxError(new Error("Cosigner must be distinct from the owner (on-chain ErrCosignRequired)"));
+    }
+    const ix = await buildPolicyUpdateIx(rpc, owner, vault, changes, cosigner.address);
+    return run(rpc, owner, network, [withCosignerSigner(ix, cosigner.address)], opts, [cosigner]);
+}
+/**
+ * Elevated policy queue — partial-sign handoff. Owner-signs + returns the
+ * partial tx + the policy cosign digest for the cosigner to complete + send.
+ * The cosign digest binds the RAW queued args (mirrors compute_cosign_digest).
+ */
+export async function buildQueuePolicyElevated(rpc, vault, owner, changes, cosignSession, opts) {
+    requireValidAddress(cosignSession, "Cosigner address");
+    if (cosignSession === owner.address) {
+        throw toDxError(new Error("Cosigner must be distinct from the owner (on-chain ErrCosignRequired)"));
+    }
+    const ix = await buildPolicyUpdateIx(rpc, owner, vault, changes, cosignSession);
+    const partialTransactionBase64 = await buildOwnerPartialSignedTx(rpc, owner, [withCosignerSigner(ix, cosignSession)], opts);
+    const cosignDigest = computeCosignDigest({
+        cosignSession,
+        dailySpendingCapUsd: changes.dailyCap ?? null,
+        maxTransactionAmountUsd: changes.maxPerTrade ?? null,
+        allowedDestinations: changes.allowedDestinations ?? null,
+        protocols: changes.approvedApps ?? null,
+        stableBalanceFloor: changes.stableBalanceFloor ?? null,
+        perRecipientDailyCapUsd: changes.perRecipientDailyCapUsd ?? null,
+        hasProtocolCaps: changes.hasProtocolCaps ?? null,
+        protocolCaps: changes.protocolCaps ?? null,
+        cosignRequired: changes.cosignRequired ?? null,
+    });
+    return { partialTransactionBase64, cosignSession, cosignDigest };
 }
 export async function applyPendingPolicy(rpc, vault, owner, network, opts) {
     const ix = await getApplyPendingPolicyInstructionAsync({ owner, vault });
@@ -710,13 +770,118 @@ cooldownSeconds = 0n) {
         //     pass a REAL session pubkey + include it as a signer in
         //     `remaining_accounts`.
         //   - Reject path: passing a non-default `cosign_session` on a
-        //     non-elevated queue surfaces `InvalidPermissions` (6088).
+        //     non-elevated queue surfaces `InvalidPermissions` (6036).
         //     INTENTIONAL — the on-chain handler refuses to silently
         //     downgrade a caller's declared intent (Option A behaviour).
         cosignSession: "11111111111111111111111111111111",
     });
     return run(rpc, owner, network, [ix], opts);
 }
+// ═══════════════════════════════════════════════════════════════════════════
+// Elevated-cosign surface (audit 2026-06-12).
+//
+// On a `cosign_required` vault, raising an agent's capability or spending limit,
+// or setting a non-zero cooldown, is an ELEVATED mutation: the on-chain
+// queue_agent_permissions_update handler requires a non-default `cosign_session`
+// that is (a) distinct from the owner and (b) present as a signer in
+// remaining_accounts. Two caller models:
+//   - queueAgentPermissionsElevated(...)      single-builder dual-sign: caller
+//     supplies the cosigner as a TransactionSigner; we sign [owner, cosigner].
+//   - buildQueueAgentPermissionsElevated(...)  partial-sign handoff: caller
+//     supplies only the cosigner PUBKEY; we owner-partial-sign and return the
+//     base64 partial tx + the cosign digest for the cosigner to complete + send.
+// ═══════════════════════════════════════════════════════════════════════════
+/** Append a cosign-session signer to a generated instruction's account metas. */
+function withCosignerSigner(ix, cosignSession) {
+    return {
+        ...ix,
+        accounts: [
+            ...(ix.accounts ?? []),
+            { address: cosignSession, role: AccountRole.READONLY_SIGNER },
+        ],
+    };
+}
+/**
+ * Assemble the compute-budget-prefixed message and OWNER-partial-sign it (the
+ * cosigner — a required signer via the appended account meta — signs later).
+ * Returns the base64 wire transaction for handoff. Mirrors run()'s message
+ * assembly but does NOT send.
+ */
+async function buildOwnerPartialSignedTx(rpc, owner, instructions, opts = {}) {
+    const cu = opts.computeUnits ?? CU_OWNER_ACTION;
+    const allIx = [
+        getSetComputeUnitLimitInstruction({
+            units: cu,
+        }),
+        ...(opts.priorityFeeMicroLamports
+            ? [
+                getSetComputeUnitPriceInstruction({
+                    microLamports: BigInt(opts.priorityFeeMicroLamports),
+                }),
+            ]
+            : []),
+        ...instructions,
+    ];
+    const blockhash = await getBlockhashCache(rpc).get(rpc);
+    const txMessage = pipe(createTransactionMessage({ version: 0 }), (tx) => setTransactionMessageFeePayer(owner.address, tx), (tx) => setTransactionMessageLifetimeUsingBlockhash(blockhash, tx), (tx) => appendTransactionMessageInstructions(allIx, tx));
+    const withOwner = addSignersToTransactionMessage([owner], txMessage);
+    const partial = await partiallySignTransactionMessageWithSigners(withOwner);
+    return getBase64EncodedWireTransaction(partial);
+}
+/**
+ * Elevated agent-permissions queue — single-builder dual-sign. The caller holds
+ * the cosigner key (server-side / single-operator). Signs [owner, cosigner] and
+ * sends. For a true 2-party async flow use `buildQueueAgentPermissionsElevated`.
+ */
+export async function queueAgentPermissionsElevated(rpc, vault, owner, network, agent, permissions, spendingLimit, cooldownSeconds, cosigner, opts) {
+    requireValidAddress(agent, "Agent address");
+    requireValidPermissions(permissions);
+    requireValidAddress(cosigner.address, "Cosigner address");
+    if (cosigner.address === owner.address) {
+        throw toDxError(new Error("Cosigner must be distinct from the owner (on-chain ErrCosignRequired)"));
+    }
+    const ix = await getQueueAgentPermissionsUpdateInstructionAsync({
+        owner,
+        vault,
+        agent,
+        newCapability: Number(permissions),
+        spendingLimitUsd: spendingLimit,
+        cooldownSeconds,
+        cosignSession: cosigner.address,
+    });
+    return run(rpc, owner, network, [withCosignerSigner(ix, cosigner.address)], opts, [cosigner]);
+}
+/**
+ * Elevated agent-permissions queue — partial-sign handoff. Owner-signs and
+ * returns the partial transaction + cosign digest; the cosigner signs and sends
+ * out-of-band (true 2-of-2). Validation mirrors the dual-sign path.
+ */
+export async function buildQueueAgentPermissionsElevated(rpc, vault, owner, agent, permissions, spendingLimit, cooldownSeconds, cosignSession, opts) {
+    requireValidAddress(agent, "Agent address");
+    requireValidPermissions(permissions);
+    requireValidAddress(cosignSession, "Cosigner address");
+    if (cosignSession === owner.address) {
+        throw toDxError(new Error("Cosigner must be distinct from the owner (on-chain ErrCosignRequired)"));
+    }
+    const ix = await getQueueAgentPermissionsUpdateInstructionAsync({
+        owner,
+        vault,
+        agent,
+        newCapability: Number(permissions),
+        spendingLimitUsd: spendingLimit,
+        cooldownSeconds,
+        cosignSession,
+    });
+    const partialTransactionBase64 = await buildOwnerPartialSignedTx(rpc, owner, [withCosignerSigner(ix, cosignSession)], opts);
+    const cosignDigest = computeAgentPermsCosignDigest({
+        cosignSession,
+        agent,
+        newCapability: Number(permissions),
+        spendingLimitUsd: spendingLimit,
+        cooldownSeconds,
+    });
+    return { partialTransactionBase64, cosignSession, cosignDigest };
+}
 export async function applyAgentPermissions(rpc, vault, owner, network, agent, opts) {
     requireValidAddress(agent, "Agent address");
     const [overlayPda] = await getAgentOverlayPDA(vault, 0);
@@ -732,13 +897,92 @@ export async function applyAgentPermissions(rpc, vault, owner, network, agent, o
 export async function cancelAgentPermissions(rpc, vault, owner, network, agent, opts) {
     requireValidAddress(agent, "Agent address");
     const pendingPda = await derivePendingAgentPermsPDA(vault, agent);
-    const ix = getCancelAgentPermissionsUpdateInstruction({
+    const ix = await getCancelAgentPermissionsUpdateInstructionAsync({
         owner,
         vault,
         pendingAgentPerms: pendingPda,
     });
     return run(rpc, owner, network, [ix], opts);
 }
+function assertDistinctCosigner(owner, cosignSession) {
+    requireValidAddress(cosignSession, "Cosigner address");
+    if (cosignSession === owner.address) {
+        throw toDxError(new Error("Cosigner must be distinct from the owner (on-chain ErrCosignRequired)"));
+    }
+}
+/** Partial-sign: cancel a pending AGENT GRANT on a cosign-required vault. */
+export async function buildCancelAgentGrantElevated(rpc, vault, owner, cosignSession, opts) {
+    assertDistinctCosigner(owner, cosignSession);
+    const ix = await getCancelAgentGrantInstructionAsync({ owner, vault });
+    const partialTransactionBase64 = await buildOwnerPartialSignedTx(rpc, owner, [withCosignerSigner(ix, cosignSession)], opts);
+    return { partialTransactionBase64, cosignSession };
+}
+/** Partial-sign: cancel a pending AGENT-PERMISSIONS update (M2b gate). */
+export async function buildCancelAgentPermissionsElevated(rpc, vault, owner, agent, cosignSession, opts) {
+    assertDistinctCosigner(owner, cosignSession);
+    requireValidAddress(agent, "Agent address");
+    const pendingPda = await derivePendingAgentPermsPDA(vault, agent);
+    const ix = await getCancelAgentPermissionsUpdateInstructionAsync({
+        owner,
+        vault,
+        pendingAgentPerms: pendingPda,
+    });
+    const partialTransactionBase64 = await buildOwnerPartialSignedTx(rpc, owner, [withCosignerSigner(ix, cosignSession)], opts);
+    return { partialTransactionBase64, cosignSession };
+}
+/** Partial-sign: cancel a pending POLICY update (M2a gate). */
+export async function buildCancelPendingPolicyElevated(rpc, vault, owner, cosignSession, opts) {
+    assertDistinctCosigner(owner, cosignSession);
+    const ix = await getCancelPendingPolicyInstructionAsync({ owner, vault });
+    const partialTransactionBase64 = await buildOwnerPartialSignedTx(rpc, owner, [withCosignerSigner(ix, cosignSession)], opts);
+    return { partialTransactionBase64, cosignSession };
+}
+/**
+ * Partial-sign: APPLY a queued agent-permissions update on a cosign-required
+ * vault. The on-chain H-1 gate requires the LIVE bound cosigner to sign at apply
+ * (defends the pre-signed-apply-survives-rotation class).
+ */
+export async function buildApplyAgentPermissionsElevated(rpc, vault, owner, agent, cosignSession, opts) {
+    assertDistinctCosigner(owner, cosignSession);
+    requireValidAddress(agent, "Agent address");
+    const [overlayPda] = await getAgentOverlayPDA(vault, 0);
+    const pendingPda = await derivePendingAgentPermsPDA(vault, agent);
+    const ix = await getApplyAgentPermissionsUpdateInstructionAsync({
+        owner,
+        vault,
+        agentSpendOverlay: overlayPda,
+        pendingAgentPerms: pendingPda,
+    });
+    const partialTransactionBase64 = await buildOwnerPartialSignedTx(rpc, owner, [withCosignerSigner(ix, cosignSession)], opts);
+    return { partialTransactionBase64, cosignSession };
+}
+/**
+ * Partial-sign: APPLY a pending policy update that DISABLES cosign on a
+ * cosign-required vault (the on-chain disable gate requires the bound cosigner).
+ * Non-disable applies do NOT need the cosigner — use owner-only
+ * {@link applyPendingPolicy}.
+ */
+export async function buildApplyPendingPolicyElevated(rpc, vault, owner, cosignSession, opts) {
+    assertDistinctCosigner(owner, cosignSession);
+    const ix = await getApplyPendingPolicyInstructionAsync({ owner, vault });
+    const partialTransactionBase64 = await buildOwnerPartialSignedTx(rpc, owner, [withCosignerSigner(ix, cosignSession)], opts);
+    return { partialTransactionBase64, cosignSession };
+}
+/**
+ * Partial-sign: CLOSE a cosign-required vault. `close_vault` is now cosign-gated
+ * (a leaked owner key alone cannot close → cannot start the close->reinit
+ * drain). Reuses the owner-only close's pending-PDA cleanup enumeration, then
+ * binds the cosigner.
+ */
+export async function buildCloseVaultElevated(rpc, vault, owner, network, cosignSession, opts) {
+    assertDistinctCosigner(owner, cosignSession);
+    const finalIx = await buildCloseVaultFinalIx(rpc, vault, owner, network);
+    const partialTransactionBase64 = await buildOwnerPartialSignedTx(rpc, owner, [withCosignerSigner(finalIx, cosignSession)], {
+        computeUnits: opts?.computeUnits ?? 400_000,
+        priorityFeeMicroLamports: opts?.priorityFeeMicroLamports,
+    });
+    return { partialTransactionBase64, cosignSession };
+}
 // ─── Post-execution assertions (Phase 2) ─────────────────────────────────────
 // Composes with pre-execution InstructionConstraints — NOT a replacement.
 //