@did-btcr2/method 0.36.0 → 0.37.0

package/dist/browser.mjs

@@ -100123,7 +100123,7 @@ var SchnorrMultikey = class _SchnorrMultikey {
    * @readonly
    * Get signing ability of the Multikey: true if a local Secp256k1SecretKey
    * is present (note: the SchnorrKeyPair.secretKey getter throws when absent;
-   * that throw is the historical error contract — see multikey tests) or if
+   * that throw is the historical error contract - see multikey tests) or if
    * an external signer is available.
    */
   get signer() {
@@ -100228,6 +100228,7 @@ var SchnorrMultikey = class _SchnorrMultikey {
 init_shim();
 
 // src/core/aggregation/service.ts
+init_secp256k1();
 init_utils();
 
 // src/core/aggregation/beacon-strategy.ts
@@ -100528,9 +100529,12 @@ var CAS_STRATEGY = {
   getDistributePayload(cohort) {
     return { casAnnouncement: cohort.casAnnouncement };
   },
-  validateParticipantView({ participantDid, expectedHash, body }) {
+  validateParticipantView({ participantDid, included, expectedHash, body }) {
     const casAnnouncement = body.casAnnouncement;
     if (!casAnnouncement) return { matches: false };
+    if (!included) {
+      return { matches: !(participantDid in casAnnouncement), casAnnouncement };
+    }
     return {
       matches: casAnnouncement[participantDid] === expectedHash,
       casAnnouncement
@@ -100546,15 +100550,20 @@ var SMT_STRATEGY = {
     const proof = cohort.smtProofs?.get(participantDid);
     return { smtProof: proof };
   },
-  validateParticipantView({ participantDid, submittedUpdate, body }) {
+  validateParticipantView({ participantDid, included, submittedUpdate, body }) {
     const smtProof = body.smtProof;
-    if (!smtProof?.updateId || !smtProof?.nonce) return { matches: false };
+    const index = didToIndex(participantDid);
+    if (!included) {
+      if (!smtProof?.nonce || smtProof?.updateId) return { matches: false, smtProof };
+      const candidateHash2 = blockHash(blockHash(base64UrlToHash(smtProof.nonce)));
+      return { matches: verifySerializedProof(smtProof, index, candidateHash2), smtProof };
+    }
+    if (!smtProof?.updateId || !smtProof?.nonce || !submittedUpdate) return { matches: false, smtProof };
     const canonicalBytes = new TextEncoder().encode(canonicalize2(submittedUpdate));
     const expectedUpdateId = hashToBase64Url(blockHash(canonicalBytes));
     if (smtProof.updateId !== expectedUpdateId) {
       return { matches: false, smtProof };
     }
-    const index = didToIndex(participantDid);
     const candidateHash = blockHash(blockHash(base64UrlToHash(smtProof.nonce)), base64UrlToHash(smtProof.updateId));
     return {
       matches: verifySerializedProof(smtProof, index, candidateHash),
@@ -101553,6 +101562,15 @@ function checkScript(script, redeemScript, witnessScript) {
       checkWSH(r2, witnessScript);
   }
 }
+function uniqPubkey(pubkeys) {
+  const map3 = {};
+  for (const pub of pubkeys) {
+    const key = hex.encode(pub);
+    if (map3[key])
+      throw new Error(`Multisig: non-uniq pubkey: ${pubkeys.map(hex.encode)}`);
+    map3[key] = true;
+  }
+}
 var p2pkh = (publicKey2, network = NETWORK) => {
   if (!isValidPubkey(publicKey2, PubT.ecdsa))
     throw new Error("P2PKH: invalid publicKey");
@@ -101725,6 +101743,14 @@ function p2tr(internalPubKey, tree2, network = NETWORK, allowUnknownOutputs = fa
     };
   }
 }
+function p2tr_ms(m2, pubkeys, allowSamePubkeys = false) {
+  if (!allowSamePubkeys)
+    uniqPubkey(pubkeys);
+  return {
+    type: "tr_ms",
+    script: OutScript.encode({ type: "tr_ms", pubkeys, m: m2 })
+  };
+}
 var base58check = createBase58check(sha256);
 function validateWitness(version3, data) {
   if (data.length < 2 || data.length > 40)
@@ -103200,6 +103226,104 @@ var SigningSessionError = class extends MethodError {
   }
 };
 
+// src/core/aggregation/recovery-policy.ts
+init_shim();
+init_secp256k1();
+init_utils();
+var DEFAULT_FUNDING_MODEL = "operator-funded";
+var DEFAULT_RECOVERY_SEQUENCE = 144;
+var MAX_RECOVERY_SEQUENCE = 65535;
+var TAPROOT_LEAF_VERSION = 192;
+function compactSize(n2) {
+  if (n2 < 253) return new Uint8Array([n2]);
+  if (n2 <= 65535) return new Uint8Array([253, n2 & 255, n2 >> 8 & 255]);
+  return new Uint8Array([254, n2 & 255, n2 >> 8 & 255, n2 >> 16 & 255, n2 >> 24 & 255]);
+}
+function tapLeafHash2(script, leafVersion = TAPROOT_LEAF_VERSION) {
+  return schnorr2.utils.taggedHash(
+    "TapLeaf",
+    concatBytes(new Uint8Array([leafVersion]), compactSize(script.length), script)
+  );
+}
+function resolveFallbackThreshold(advertised, n2) {
+  return advertised ?? Math.max(1, n2 - 1);
+}
+function assertFallbackParams({ cohortKeys, fallbackThreshold }) {
+  const n2 = cohortKeys.length;
+  if (n2 === 0) {
+    throw new AggregationCohortError(
+      "Cannot build fallback leaf: no cohort keys.",
+      "NO_COHORT_KEYS"
+    );
+  }
+  for (const key of cohortKeys) {
+    if (key.length !== 33) {
+      throw new AggregationCohortError(
+        `Cohort key must be a 33-byte compressed public key, got ${key.length} bytes.`,
+        "INVALID_COHORT_KEY",
+        { length: key.length }
+      );
+    }
+  }
+  if (!Number.isInteger(fallbackThreshold) || fallbackThreshold < 1 || fallbackThreshold > n2) {
+    throw new AggregationCohortError(
+      `Fallback threshold must be an integer in [1, ${n2}] (k-of-n), got ${fallbackThreshold}.`,
+      "INVALID_FALLBACK_THRESHOLD",
+      { fallbackThreshold, n: n2 }
+    );
+  }
+}
+function buildFallbackLeaf(params) {
+  assertFallbackParams(params);
+  const xOnlyKeys = sortKeys(params.cohortKeys).map((k) => k.slice(1));
+  return p2tr_ms(params.fallbackThreshold, xOnlyKeys).script;
+}
+function assertRecoveryParams({ recoveryKey, recoverySequence }) {
+  if (recoveryKey.length !== 32) {
+    throw new AggregationCohortError(
+      `Recovery key must be a 32-byte x-only public key, got ${recoveryKey.length} bytes.`,
+      "INVALID_RECOVERY_KEY"
+    );
+  }
+  if (!Number.isInteger(recoverySequence) || recoverySequence < 1 || recoverySequence > MAX_RECOVERY_SEQUENCE) {
+    throw new AggregationCohortError(
+      `Recovery sequence must be a block-based BIP-68 relative timelock in [1, ${MAX_RECOVERY_SEQUENCE}], got ${recoverySequence}.`,
+      "INVALID_RECOVERY_SEQUENCE"
+    );
+  }
+}
+function buildRecoveryScript(params) {
+  assertRecoveryParams(params);
+  return Script.encode([
+    params.recoverySequence,
+    "CHECKSEQUENCEVERIFY",
+    "DROP",
+    params.recoveryKey,
+    "CHECKSIG"
+  ]);
+}
+function buildRecoveryLeaves(fundingModel, params) {
+  switch (fundingModel) {
+    case "operator-funded":
+      return [
+        { script: buildFallbackLeaf(params) },
+        { script: buildRecoveryScript(params) }
+      ];
+    case "participant-funded":
+      throw new AggregationCohortError(
+        "Funding model 'participant-funded' is reserved and not yet implemented.",
+        "UNSUPPORTED_FUNDING_MODEL",
+        { fundingModel }
+      );
+    default:
+      throw new AggregationCohortError(
+        `Unknown funding model: ${fundingModel}.`,
+        "UNKNOWN_FUNDING_MODEL",
+        { fundingModel }
+      );
+  }
+}
+
 // src/core/aggregation/cohort.ts
 var AggregationCohort = class {
   /** Unique identifier for the cohort. */
@@ -103215,8 +103339,8 @@ var AggregationCohort = class {
   /** List of participant DIDs that have been accepted into the cohort. */
   participants = [];
   /**
-   * Mapping from participant DID → their compressed secp256k1 public key.
-   * Distinct from {@link cohortKeys} (which is sorted per BIP-327) — this lets
+   * Mapping from participant DID to their compressed secp256k1 public key.
+   * Distinct from {@link cohortKeys} (which is sorted per BIP-327): this lets
    * callers look up a participant's key without knowing their position in the
    * sorted array. Populated by the service at `acceptParticipant` time.
    */
@@ -103224,16 +103348,41 @@ var AggregationCohort = class {
   /** Sorted list of cohort participants' compressed public keys. */
   #cohortKeys = [];
   /**
-   * BIP-341 TapTweak — `taggedHash("TapTweak", internalPubkey)` for a key-path-only
-   * Taproot output. Despite prior naming, this is NOT a Merkle root: key-path-only
-   * spends have no script tree.
+   * BIP-341 TapTweak scalar: `taggedHash("TapTweak", internalPubkey || tapMerkleRoot)`.
+   * The beacon output is an internal key (the MuSig2 aggregate) plus a script
+   * tree (the recovery leaves), so the tweak commits to the tree's Merkle root.
+   * The MuSig2 signing session applies this as an x-only tweak; a value that does
+   * not match the root the funded address was derived from silently yields an
+   * invalid key-path signature.
    */
   tapTweak = new Uint8Array();
-  /** The n-of-n MuSig2 Taproot beacon address. */
+  /** The n-of-n MuSig2 aggregate internal key, x-only (32 bytes), set by computeBeaconAddress(). */
+  internalKey = new Uint8Array();
+  /** BIP-341 Taproot Merkle root of the recovery script tree, set by computeBeaconAddress(). */
+  tapMerkleRoot = new Uint8Array();
+  /** Operator recovery key, x-only (32 bytes). Used to build the CSV recovery leaf. */
+  recoveryKey;
+  /** Relative-timelock (BIP-68 nSequence) before the recovery leaf is spendable. */
+  recoverySequence;
+  /** Funding model governing the recovery leaves (default 'operator-funded'). */
+  fundingModel;
+  /**
+   * Advertised k of the k-of-n fallback leaf, or undefined to default to n-1 at
+   * address computation. Read the resolved value via {@link effectiveFallbackThreshold}.
+   */
+  fallbackThreshold;
+  /** The Taproot beacon address: key path is the MuSig2 aggregate, script path is fallback + recovery. */
   beaconAddress = "";
   /** Pending DID updates submitted by participants, keyed by DID. */
   pendingUpdates = /* @__PURE__ */ new Map();
-  /** CAS Beacon Announcement Map (DID → updateHash), set by buildCASAnnouncement(). */
+  /**
+   * Participant DIDs that explicitly declined to submit an update this round
+   * (cooperative non-inclusion). A decliner is absent from the CAS Announcement
+   * Map and carries a non-inclusion leaf in the SMT, yet still signs. Kept
+   * disjoint from {@link pendingUpdates} so CAS correctness holds by construction.
+   */
+  nonIncluded = /* @__PURE__ */ new Set();
+  /** CAS Beacon Announcement Map (DID to updateHash), set by buildCASAnnouncement(). */
   casAnnouncement;
   /** Per-participant SMT proofs, set by buildSMTTree(). */
   smtProofs;
@@ -103243,12 +103392,16 @@ var AggregationCohort = class {
   validationAcks = /* @__PURE__ */ new Set();
   /** Set of participant DIDs that have rejected the aggregated data. */
   validationRejections = /* @__PURE__ */ new Set();
-  constructor({ id, minParticipants, serviceDid, network, beaconType }) {
+  constructor({ id, minParticipants, serviceDid, network, beaconType, recoveryKey, recoverySequence, fundingModel, fallbackThreshold }) {
     this.id = id || crypto.randomUUID();
     this.minParticipants = minParticipants ?? 2;
     this.serviceDid = serviceDid || "";
     this.network = network;
     this.beaconType = beaconType || "CASBeacon";
+    this.recoveryKey = recoveryKey;
+    this.recoverySequence = recoverySequence;
+    this.fundingModel = fundingModel ?? DEFAULT_FUNDING_MODEL;
+    this.fallbackThreshold = fallbackThreshold;
   }
   /** Sorted cohort keys (sorted on assignment per BIP-327). */
   get cohortKeys() {
@@ -103258,8 +103411,26 @@ var AggregationCohort = class {
     this.#cohortKeys = sortKeys(keys);
   }
   /**
-   * Computes the n-of-n MuSig2 Taproot beacon address from cohort keys.
-   * Sets `tapTweak` to the BIP-341 key-path-only tweak.
+   * The resolved k of the k-of-n fallback leaf: the advertised
+   * {@link fallbackThreshold}, or n-1 (floored at 1) when unadvertised, where n is
+   * the current cohort size. This is the value the beacon address commits to and
+   * the spend builders must reproduce. Returns 0 before any cohort keys are set.
+   */
+  get effectiveFallbackThreshold() {
+    if (this.#cohortKeys.length === 0) return 0;
+    return resolveFallbackThreshold(this.fallbackThreshold, this.#cohortKeys.length);
+  }
+  /**
+   * Computes the Taproot beacon address from the cohort keys and recovery params.
+   *
+   * The output's key path is the n-of-n MuSig2 aggregate of the cohort keys; its
+   * script path is the recovery tree (a CSV recovery leaf so a missing signer
+   * cannot permanently lock the UTXO). Sets `internalKey`, `tapMerkleRoot`, and
+   * the `tapTweak` the MuSig2 session must apply for the key-path spend.
+   *
+   * The tweak is derived from the Merkle root the address was built with (read
+   * back from the payment), never recomputed by hand, so the MuSig2 key-path
+   * signature is guaranteed to validate against the funded address.
    */
   computeBeaconAddress() {
     if (this.#cohortKeys.length === 0) {
@@ -103269,10 +103440,25 @@ var AggregationCohort = class {
         { cohortId: this.id }
       );
     }
+    if (!this.recoveryKey || this.recoveryKey.length === 0 || this.recoverySequence === void 0) {
+      throw new AggregationCohortError(
+        "Cannot compute beacon address: missing recovery key or sequence.",
+        "NO_RECOVERY_PARAMS",
+        { cohortId: this.id }
+      );
+    }
     const keyAggContext = keyAggregate(this.#cohortKeys);
     const aggPubkey = keyAggExport(keyAggContext);
-    const payment = p2tr(aggPubkey, void 0, getNetwork(this.network));
-    this.tapTweak = schnorr2.utils.taggedHash("TapTweak", aggPubkey);
+    const leaves = buildRecoveryLeaves(this.fundingModel, {
+      recoveryKey: this.recoveryKey,
+      recoverySequence: this.recoverySequence,
+      cohortKeys: this.#cohortKeys,
+      fallbackThreshold: resolveFallbackThreshold(this.fallbackThreshold, this.#cohortKeys.length)
+    });
+    const payment = p2tr(aggPubkey, leaves, getNetwork(this.network), true);
+    this.internalKey = aggPubkey;
+    this.tapMerkleRoot = payment.tapMerkleRoot;
+    this.tapTweak = schnorr2.utils.taggedHash("TapTweak", concatBytes(aggPubkey, payment.tapMerkleRoot));
     if (!payment.address) {
       throw new AggregationCohortError(
         "Failed to compute Taproot address",
@@ -103328,20 +103514,54 @@ var AggregationCohort = class {
     }
     this.pendingUpdates.set(participantDid, signedUpdate);
   }
+  /**
+   * Record that a participant declined to submit an update this round
+   * (cooperative non-inclusion). The member stays in the cohort and still signs.
+   */
+  addNonInclusion(participantDid) {
+    if (!this.participants.includes(participantDid)) {
+      throw new AggregationCohortError(
+        `Participant ${participantDid} is not in cohort ${this.id}.`,
+        "UNKNOWN_PARTICIPANT",
+        { cohortId: this.id, participantDid }
+      );
+    }
+    if (this.pendingUpdates.has(participantDid)) {
+      throw new AggregationCohortError(
+        `Participant ${participantDid} already submitted an update; cannot also decline.`,
+        "CONFLICTING_RESPONSE",
+        { cohortId: this.id, participantDid }
+      );
+    }
+    this.nonIncluded.add(participantDid);
+  }
   hasAllUpdates() {
     return this.pendingUpdates.size === this.participants.length;
   }
+  /**
+   * True when every participant has responded for this round, either with an
+   * update or with an explicit non-inclusion. This is the aggregation gate when
+   * non-inclusion is in play; it generalizes {@link hasAllUpdates} the same way
+   * {@link hasAllValidationResponses} generalizes a unanimous ack.
+   */
+  hasAllResponses() {
+    return this.pendingUpdates.size + this.nonIncluded.size === this.participants.length;
+  }
   /**
    * Builds a CAS Announcement Map from collected updates.
-   * Maps each participant DID → base64url canonical hash of their signed update.
+   * Maps each participant DID to base64url canonical hash of their signed update.
    * Computes signal bytes as SHA-256 of canonicalized announcement.
+   *
+   * Members who declined (cooperative non-inclusion) are naturally absent from
+   * the map: the body iterates {@link pendingUpdates}, which never holds a
+   * decliner. Absence from the map is exactly the CAS non-inclusion signal.
    */
   buildCASAnnouncement() {
-    if (!this.hasAllUpdates()) {
+    if (!this.hasAllResponses()) {
       throw new AggregationCohortError(
-        "Cannot build CAS Announcement: not all updates collected.",
-        "INCOMPLETE_UPDATES",
-        { cohortId: this.id, collected: this.pendingUpdates.size, total: this.participants.length }
+        "Cannot build CAS Announcement: not all participants have responded.",
+        "INCOMPLETE_RESPONSES",
+        { cohortId: this.id, updates: this.pendingUpdates.size, declined: this.nonIncluded.size, total: this.participants.length }
       );
     }
     const announcement = {};
@@ -103353,31 +103573,41 @@ var AggregationCohort = class {
     return announcement;
   }
   /**
-   * Builds an SMT tree from collected updates.
-   * Each entry uses a random 32-byte nonce + canonicalized signed update bytes.
-   * Stores per-participant proofs and the SMT root as signalBytes.
+   * Builds an SMT tree with one leaf per participant.
+   *
+   * A member who submitted an update gets an inclusion leaf
+   * (SHA-256(SHA-256(nonce) || SHA-256(update))); a member who declined gets a
+   * non-inclusion leaf (SHA-256(SHA-256(nonce)), the `signedUpdate` entry field
+   * omitted). The cohort mints each member's nonce and returns it inside that
+   * member's serialized proof, so a decliner can self-validate its own
+   * non-inclusion slot and the resolver can recompute the leaf. Stores
+   * per-participant proofs and the SMT root as signalBytes.
    */
   buildSMTTree() {
-    if (!this.hasAllUpdates()) {
+    if (!this.hasAllResponses()) {
       throw new AggregationCohortError(
-        "Cannot build SMT tree: not all updates collected.",
-        "INCOMPLETE_UPDATES",
-        { cohortId: this.id }
+        "Cannot build SMT tree: not all participants have responded.",
+        "INCOMPLETE_RESPONSES",
+        { cohortId: this.id, updates: this.pendingUpdates.size, declined: this.nonIncluded.size, total: this.participants.length }
       );
     }
     const tree2 = new BTCR2MerkleTree();
     const entries = [];
     const encoder4 = new TextEncoder();
-    for (const [did, signedUpdate] of this.pendingUpdates) {
-      const canonicalBytes = encoder4.encode(canonicalize2(signedUpdate));
+    for (const did of this.participants) {
       const nonce = randomBytes(32);
-      entries.push({ did, nonce, signedUpdate: canonicalBytes });
+      const signedUpdate = this.pendingUpdates.get(did);
+      if (signedUpdate) {
+        entries.push({ did, nonce, signedUpdate: encoder4.encode(canonicalize2(signedUpdate)) });
+      } else {
+        entries.push({ did, nonce });
+      }
     }
     tree2.addEntries(entries);
     tree2.finalize();
     this.signalBytes = tree2.rootHash;
     this.smtProofs = /* @__PURE__ */ new Map();
-    for (const [did] of this.pendingUpdates) {
+    for (const did of this.participants) {
       this.smtProofs.set(did, tree2.proof(did));
     }
     return this.smtProofs;
@@ -103403,7 +103633,7 @@ var AggregationCohort = class {
     return this.validationAcks.size + this.validationRejections.size === this.participants.length;
   }
   /**
-   * True when all participants approved. Note: differs from {@link hasAllValidationResponses} —
+   * True when all participants approved. Note: differs from {@link hasAllValidationResponses},
    * this returns false if any participant rejected, even if all responses are in.
    */
   isFullyValidated() {
@@ -103414,6 +103644,7 @@ var AggregationCohort = class {
 // src/core/aggregation/conditions.ts
 init_shim();
 var KNOWN_BEACON_TYPES = ["CASBeacon", "SMTBeacon"];
+var KNOWN_FUNDING_MODELS = ["operator-funded", "participant-funded"];
 function checkPair(problems, label, min, max) {
   if (min !== void 0 && (!Number.isInteger(min) || min < 0)) {
     problems.push(`min${label} must be an integer >= 0`);
@@ -103457,11 +103688,128 @@ function validateCohortConditions(c2) {
   if (c2.pendingUpdateTrigger !== void 0 && (!Number.isInteger(c2.pendingUpdateTrigger) || c2.pendingUpdateTrigger < 1)) {
     problems.push("pendingUpdateTrigger must be an integer >= 1");
   }
+  if (c2.fallbackThreshold !== void 0) {
+    if (!Number.isInteger(c2.fallbackThreshold) || c2.fallbackThreshold < 1) {
+      problems.push("fallbackThreshold must be an integer >= 1");
+    } else if (c2.maxParticipants !== void 0 && Number.isInteger(c2.maxParticipants) && c2.fallbackThreshold > c2.maxParticipants) {
+      problems.push("fallbackThreshold must be <= maxParticipants");
+    }
+  }
   checkCost(problems, "costOfEnrollment", c2.costOfEnrollment);
   checkCost(problems, "costPerAnnouncement", c2.costPerAnnouncement);
+  if (typeof c2.recoveryKey !== "string" || !/^[0-9a-fA-F]{64}$/.test(c2.recoveryKey)) {
+    problems.push("recoveryKey must be a 64-character hex string (x-only public key)");
+  }
+  if (!Number.isInteger(c2.recoverySequence) || c2.recoverySequence < 1 || c2.recoverySequence > MAX_RECOVERY_SEQUENCE) {
+    problems.push(`recoverySequence must be a block-based BIP-68 relative timelock in [1, ${MAX_RECOVERY_SEQUENCE}]`);
+  }
+  if (c2.fundingModel !== void 0 && !KNOWN_FUNDING_MODELS.includes(c2.fundingModel)) {
+    problems.push(`fundingModel must be one of ${KNOWN_FUNDING_MODELS.join(", ")}`);
+  }
   return problems;
 }
 
+// src/core/aggregation/fallback-spend.ts
+init_shim();
+init_secp256k1();
+function bytesEqual(a2, b) {
+  return a2.length === b.length && a2.every((x, i4) => x === b[i4]);
+}
+function fallbackSighash(tx, inputIndex, prevOutScript, prevOutValue, fallbackLeafScript) {
+  return tx.preimageWitnessV1(
+    inputIndex,
+    [prevOutScript],
+    SigHash.DEFAULT,
+    [prevOutValue],
+    void 0,
+    fallbackLeafScript,
+    TAPROOT_LEAF_VERSION
+  );
+}
+function buildFallbackSpend(params) {
+  const {
+    pendingTx,
+    cohortKeys,
+    recoveryKey,
+    recoverySequence,
+    fundingModel,
+    network,
+    prevOutScript,
+    prevOutValue,
+    signatures
+  } = params;
+  const inputIndex = params.inputIndex ?? 0;
+  if (cohortKeys.length === 0) {
+    throw new AggregationCohortError(
+      "Cannot build fallback spend: no cohort keys.",
+      "NO_COHORT_KEYS"
+    );
+  }
+  const fallbackThreshold = resolveFallbackThreshold(params.fallbackThreshold, cohortKeys.length);
+  const internalKey = keyAggExport(keyAggregate(sortKeys(cohortKeys)));
+  const leaves = buildRecoveryLeaves(fundingModel ?? DEFAULT_FUNDING_MODEL, {
+    recoveryKey,
+    recoverySequence,
+    cohortKeys,
+    fallbackThreshold
+  });
+  const net = getNetwork(network);
+  const payment = p2tr(internalKey, leaves, net, true);
+  if (!bytesEqual(payment.script, prevOutScript)) {
+    throw new AggregationCohortError(
+      "Reconstructed beacon output script does not match the spent prevout script.",
+      "PREVOUT_SCRIPT_MISMATCH"
+    );
+  }
+  const fallbackLeaf = buildFallbackLeaf({ cohortKeys, fallbackThreshold });
+  const leafEntry = payment.tapLeafScript?.find(([, scriptVer]) => {
+    const script = scriptVer.slice(0, scriptVer.length - 1);
+    return bytesEqual(script, fallbackLeaf);
+  });
+  if (!leafEntry) {
+    throw new AggregationCohortError(
+      "Could not locate the fallback leaf in the reconstructed beacon output.",
+      "FALLBACK_LEAF_NOT_FOUND"
+    );
+  }
+  const cohortXOnly = sortKeys(cohortKeys).map((k) => k.slice(1));
+  const tx = pendingTx;
+  const sighash = fallbackSighash(tx, inputIndex, prevOutScript, prevOutValue, fallbackLeaf);
+  const leafHash = tapLeafHash2(fallbackLeaf);
+  const accepted = /* @__PURE__ */ new Map();
+  for (const { pubKey, signature } of signatures) {
+    if (pubKey.length !== 32 || signature.length !== 64) continue;
+    const isCohortKey = cohortXOnly.some((k) => bytesEqual(k, pubKey));
+    if (!isCohortKey) continue;
+    const hex2 = Array.from(pubKey, (b) => b.toString(16).padStart(2, "0")).join("");
+    if (accepted.has(hex2)) continue;
+    let ok = false;
+    try {
+      ok = schnorr2.verify(signature, sighash, pubKey);
+    } catch {
+      ok = false;
+    }
+    if (ok) accepted.set(hex2, signature);
+  }
+  if (accepted.size < fallbackThreshold) {
+    throw new AggregationCohortError(
+      `Not enough valid fallback signatures: have ${accepted.size}, need ${fallbackThreshold}.`,
+      "NOT_ENOUGH_FALLBACK_SIGNATURES",
+      { have: accepted.size, need: fallbackThreshold }
+    );
+  }
+  const chosen = cohortXOnly.filter((k) => accepted.has(Array.from(k, (b) => b.toString(16).padStart(2, "0")).join(""))).slice(0, fallbackThreshold);
+  tx.updateInput(inputIndex, {
+    tapLeafScript: [leafEntry],
+    tapScriptSig: chosen.map((pubKey) => {
+      const hex2 = Array.from(pubKey, (b) => b.toString(16).padStart(2, "0")).join("");
+      return [{ pubKey, leafHash }, accepted.get(hex2)];
+    })
+  });
+  tx.finalize();
+  return tx;
+}
+
 // src/core/aggregation/messages/base.ts
 init_shim();
 var AGGREGATION_WIRE_VERSION = 1;
@@ -103501,12 +103849,15 @@ var COHORT_OPT_IN = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_opt_in`;
 var COHORT_OPT_IN_ACCEPT = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_opt_in_accept`;
 var COHORT_READY = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_ready`;
 var SUBMIT_UPDATE = `${AGGREGATION_MESSAGE_PREFIX}/update/submit_update`;
+var SUBMIT_NONINCLUDED = `${AGGREGATION_MESSAGE_PREFIX}/update/submit_nonincluded`;
 var DISTRIBUTE_AGGREGATED_DATA = `${AGGREGATION_MESSAGE_PREFIX}/update/distribute_aggregated_data`;
 var VALIDATION_ACK = `${AGGREGATION_MESSAGE_PREFIX}/update/validation_ack`;
 var AUTHORIZATION_REQUEST = `${AGGREGATION_MESSAGE_PREFIX}/sign/authorization_request`;
 var NONCE_CONTRIBUTION = `${AGGREGATION_MESSAGE_PREFIX}/sign/nonce_contribution`;
 var AGGREGATED_NONCE = `${AGGREGATION_MESSAGE_PREFIX}/sign/aggregated_nonce`;
 var SIGNATURE_AUTHORIZATION = `${AGGREGATION_MESSAGE_PREFIX}/sign/signature_authorization`;
+var FALLBACK_AUTHORIZATION_REQUEST = `${AGGREGATION_MESSAGE_PREFIX}/sign/fallback_authorization_request`;
+var FALLBACK_SIGNATURE = `${AGGREGATION_MESSAGE_PREFIX}/sign/fallback_signature`;
 
 // src/core/aggregation/messages/factories.ts
 init_shim();
@@ -103530,6 +103881,10 @@ function createSubmitUpdateMessage(fields) {
   const { from: from8, to, ...body } = fields;
   return new BaseMessage({ type: SUBMIT_UPDATE, from: from8, to, body });
 }
+function createSubmitNonIncludedMessage(fields) {
+  const { from: from8, to, ...body } = fields;
+  return new BaseMessage({ type: SUBMIT_NONINCLUDED, from: from8, to, body });
+}
 function createDistributeAggregatedDataMessage(fields) {
   const { from: from8, to, ...body } = fields;
   return new BaseMessage({ type: DISTRIBUTE_AGGREGATED_DATA, from: from8, to, body });
@@ -103554,6 +103909,14 @@ function createSignatureAuthorizationMessage(fields) {
   const { from: from8, to, ...body } = fields;
   return new BaseMessage({ type: SIGNATURE_AUTHORIZATION, from: from8, to, body });
 }
+function createFallbackAuthorizationRequestMessage(fields) {
+  const { from: from8, to, ...body } = fields;
+  return new BaseMessage({ type: FALLBACK_AUTHORIZATION_REQUEST, from: from8, to, body });
+}
+function createFallbackSignatureMessage(fields) {
+  const { from: from8, to, ...body } = fields;
+  return new BaseMessage({ type: FALLBACK_SIGNATURE, from: from8, to, body });
+}
 
 // src/core/aggregation/phases.ts
 init_shim();
@@ -103568,6 +103931,7 @@ var ServiceCohortPhase = /* @__PURE__ */ ((ServiceCohortPhase2) => {
   ServiceCohortPhase2["SigningStarted"] = "SigningStarted";
   ServiceCohortPhase2["NoncesCollected"] = "NoncesCollected";
   ServiceCohortPhase2["AwaitingPartialSigs"] = "AwaitingPartialSigs";
+  ServiceCohortPhase2["FallbackRequested"] = "FallbackRequested";
   ServiceCohortPhase2["Complete"] = "Complete";
   ServiceCohortPhase2["Failed"] = "Failed";
   return ServiceCohortPhase2;
@@ -103577,11 +103941,13 @@ var ParticipantCohortPhase = /* @__PURE__ */ ((ParticipantCohortPhase2) => {
   ParticipantCohortPhase2["OptedIn"] = "OptedIn";
   ParticipantCohortPhase2["CohortReady"] = "CohortReady";
   ParticipantCohortPhase2["UpdateSubmitted"] = "UpdateSubmitted";
+  ParticipantCohortPhase2["NonIncluded"] = "NonIncluded";
   ParticipantCohortPhase2["AwaitingValidation"] = "AwaitingValidation";
   ParticipantCohortPhase2["ValidationSent"] = "ValidationSent";
   ParticipantCohortPhase2["AwaitingSigning"] = "AwaitingSigning";
   ParticipantCohortPhase2["NonceSent"] = "NonceSent";
   ParticipantCohortPhase2["AwaitingPartialSig"] = "AwaitingPartialSig";
+  ParticipantCohortPhase2["AwaitingFallbackSig"] = "AwaitingFallbackSig";
   ParticipantCohortPhase2["Complete"] = "Complete";
   ParticipantCohortPhase2["Failed"] = "Failed";
   return ParticipantCohortPhase2;
@@ -103609,11 +103975,11 @@ var BeaconSigningSession = class {
   prevOutScripts;
   /** Previous output values for Taproot sighash computation. */
   prevOutValues;
-  /** Map of participant publicKey-hex → public nonce contribution. */
+  /** Map of participant publicKey-hex to public nonce contribution. */
   nonceContributions = /* @__PURE__ */ new Map();
   /** Aggregated MuSig2 nonce (66 bytes). */
   aggregatedNonce;
-  /** Map of participant DID → partial signature. */
+  /** Map of participant DID to partial signature. */
   partialSignatures = /* @__PURE__ */ new Map();
   /** Final 64-byte Schnorr signature. */
   signature;
@@ -103796,7 +104162,7 @@ var BeaconSigningSession = class {
       throw new SigningSessionError("Aggregated nonce not available.", "MISSING_AGGREGATED_NONCE");
     }
     if (!this.#secretNonce) {
-      throw new SigningSessionError("Secret nonce not available \u2014 generateNonceContribution() must be called first.", "MISSING_SECRET_NONCE");
+      throw new SigningSessionError("Secret nonce not available - generateNonceContribution() must be called first.", "MISSING_SECRET_NONCE");
     }
     const session = new Session(
       this.aggregatedNonce,
@@ -103866,6 +104232,9 @@ var AggregationService = class {
       case SUBMIT_UPDATE:
         this.#handleSubmitUpdate(message2);
         break;
+      case SUBMIT_NONINCLUDED:
+        this.#handleSubmitNonInclusion(message2);
+        break;
       case VALIDATION_ACK:
         this.#handleValidationAck(message2);
         break;
@@ -103875,6 +104244,9 @@ var AggregationService = class {
       case SIGNATURE_AUTHORIZATION:
         this.#handleSignatureAuthorization(message2);
         break;
+      case FALLBACK_SIGNATURE:
+        this.#handleFallbackSignature(message2);
+        break;
       default:
         break;
     }
@@ -103893,7 +104265,7 @@ var AggregationService = class {
   }
   /**
    * Create a new cohort with the given config. Returns the cohort ID.
-   * Cohort starts in `Created` phase — call `advertise()` to broadcast.
+   * Cohort starts in `Created` phase - call `advertise()` to broadcast.
    */
   createCohort(config) {
     const problems = validateCohortConditions(config);
@@ -103908,7 +104280,11 @@ var AggregationService = class {
       serviceDid: this.did,
       minParticipants: config.minParticipants,
       network: config.network,
-      beaconType: config.beaconType
+      beaconType: config.beaconType,
+      recoveryKey: hexToBytes(config.recoveryKey),
+      recoverySequence: config.recoverySequence,
+      fundingModel: config.fundingModel,
+      fallbackThreshold: config.fallbackThreshold
     });
     this.#cohortStates.set(cohort.id, {
       phase: "Created" /* Created */,
@@ -104109,11 +104485,64 @@ var AggregationService = class {
       });
       return;
     }
+    if (state.cohort.nonIncluded.has(message2.from)) {
+      state.rejections.push({
+        from: message2.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Participant already declined this round; cannot also submit an update"
+      });
+      return;
+    }
+    if (state.cohort.pendingUpdates.has(message2.from)) {
+      state.rejections.push({
+        from: message2.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Participant already submitted an update this round; cannot resubmit"
+      });
+      return;
+    }
     state.cohort.addUpdate(message2.from, signedUpdate);
     if (state.phase === "CohortSet" /* CohortSet */) {
       state.phase = "CollectingUpdates" /* CollectingUpdates */;
     }
-    if (state.cohort.hasAllUpdates()) {
+    if (state.cohort.hasAllResponses()) {
+      state.phase = "UpdatesCollected" /* UpdatesCollected */;
+    }
+  }
+  /**
+   * Handle an incoming SUBMIT_NONINCLUDED message: a member declares it has no
+   * update this round (cooperative non-inclusion). Membership is proven by the
+   * signed transport envelope, so the body carries only the cohortId. The member
+   * stays in the cohort and still signs; it is absent from the CAS map and
+   * carries a non-inclusion leaf in the SMT.
+   */
+  #handleSubmitNonInclusion(message2) {
+    const cohortId = message2.body?.cohortId;
+    if (!cohortId) return;
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) return;
+    if (state.phase !== "CohortSet" /* CohortSet */ && state.phase !== "CollectingUpdates" /* CollectingUpdates */) return;
+    if (!state.cohort.participants.includes(message2.from)) {
+      state.rejections.push({
+        from: message2.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Sender is not a member of this cohort"
+      });
+      return;
+    }
+    if (state.cohort.pendingUpdates.has(message2.from) || state.cohort.nonIncluded.has(message2.from)) {
+      state.rejections.push({
+        from: message2.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Participant already responded this round"
+      });
+      return;
+    }
+    state.cohort.addNonInclusion(message2.from);
+    if (state.phase === "CohortSet" /* CohortSet */) {
+      state.phase = "CollectingUpdates" /* CollectingUpdates */;
+    }
+    if (state.cohort.hasAllResponses()) {
       state.phase = "UpdatesCollected" /* UpdatesCollected */;
     }
   }
@@ -104223,7 +104652,7 @@ var AggregationService = class {
   }
   /**
    * Start a signing session by creating auth requests for all participants.
-   * The caller provides the transaction data — typically built via
+   * The caller provides the transaction data - typically built via
    * `buildBeaconTransaction()` against a Bitcoin connection.
    */
   startSigning(cohortId, txData) {
@@ -104330,11 +104759,144 @@ var AggregationService = class {
       state.result = {
         cohortId,
         signature,
-        signedTx: state.signingSession.pendingTx
+        signedTx: state.signingSession.pendingTx,
+        path: "key-path"
       };
       state.phase = "Complete" /* Complete */;
     }
   }
+  /**
+   * Abandon the optimistic n-of-n key path and ask members to authorize the
+   * k-of-n fallback (script-path) spend of the SAME beacon transaction (graceful
+   * liveness, ADR 042). Reuses the in-flight signing session's transaction and
+   * spent output, so the announcement and its outputs are unchanged: only the
+   * witness path differs. Returns one FALLBACK_AUTHORIZATION_REQUEST per
+   * participant.
+   *
+   * Callable once optimistic signing has started (the session and its tx exist)
+   * and before it completes. A cohort can take exactly one of the two paths: the
+   * caller (runner) must commit to fallback and stop driving the optimistic path.
+   */
+  startFallbackSigning(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) {
+      throw new AggregationServiceError(`Cohort ${cohortId} not found.`, "COHORT_NOT_FOUND", { cohortId });
+    }
+    if (!state.signingSession) {
+      throw new AggregationServiceError(
+        `Cannot start fallback for cohort ${cohortId}: no signing session.`,
+        "NO_SIGNING_SESSION",
+        { cohortId }
+      );
+    }
+    const signingPhases = [
+      "SigningStarted" /* SigningStarted */,
+      "NoncesCollected" /* NoncesCollected */,
+      "AwaitingPartialSigs" /* AwaitingPartialSigs */
+    ];
+    if (!signingPhases.includes(state.phase)) {
+      throw new AggregationServiceError(
+        `Cannot start fallback for cohort ${cohortId}: phase is ${state.phase}.`,
+        "INVALID_PHASE",
+        { cohortId, phase: state.phase }
+      );
+    }
+    const session = state.signingSession;
+    const prevOutScript = session.prevOutScripts[0];
+    const prevOutValue = session.prevOutValues[0];
+    if (!prevOutScript || prevOutValue === void 0) {
+      throw new AggregationServiceError(
+        `Cannot start fallback for cohort ${cohortId}: signing session missing prevout data.`,
+        "MISSING_PREV_OUT",
+        { cohortId }
+      );
+    }
+    const fallbackLeaf = buildFallbackLeaf({
+      cohortKeys: state.cohort.cohortKeys,
+      fallbackThreshold: state.cohort.effectiveFallbackThreshold
+    });
+    state.fallbackSignatures = /* @__PURE__ */ new Map();
+    state.phase = "FallbackRequested" /* FallbackRequested */;
+    const messages2 = [];
+    for (const participantDid of state.cohort.participants) {
+      messages2.push(createFallbackAuthorizationRequestMessage({
+        from: this.did,
+        to: participantDid,
+        cohortId,
+        sessionId: session.id,
+        pendingTx: session.pendingTx.hex,
+        prevOutScriptHex: bytesToHex(prevOutScript),
+        prevOutValue: prevOutValue.toString(),
+        fallbackLeafScriptHex: bytesToHex(fallbackLeaf)
+      }));
+    }
+    return messages2;
+  }
+  /**
+   * Handle an incoming FALLBACK_SIGNATURE: a member's standalone BIP-340
+   * signature over the fallback script-path sighash. The signature is
+   * authenticated to the sender (its `signerPk` must be the sender's own cohort
+   * key and the signature must verify against the sighash) and collected. Once k
+   * valid signatures are in, the k-of-n fallback spend is assembled and the
+   * cohort completes via the script path.
+   */
+  #handleFallbackSignature(message2) {
+    const cohortId = message2.body?.cohortId;
+    if (!cohortId) return;
+    const state = this.#cohortStates.get(cohortId);
+    if (!state || !state.signingSession || !state.fallbackSignatures) return;
+    if (state.phase !== "FallbackRequested" /* FallbackRequested */) return;
+    const sessionId = message2.body?.sessionId;
+    if (sessionId !== state.signingSession.id) return;
+    const signerPk = message2.body?.signerPk;
+    const fallbackSignature = message2.body?.fallbackSignature;
+    if (!signerPk || !fallbackSignature) return;
+    const prevOutScript = state.signingSession.prevOutScripts[0];
+    const prevOutValue = state.signingSession.prevOutValues[0];
+    if (!prevOutScript || prevOutValue === void 0) return;
+    const memberKey = state.cohort.participantKeys.get(message2.from);
+    if (!memberKey) {
+      state.rejections.push({ from: message2.from, code: "UPDATE_MALFORMED", reason: "Fallback signature from a non-member" });
+      return;
+    }
+    const memberXOnly = memberKey.slice(1);
+    if (signerPk.length !== 32 || !memberXOnly.every((b, i4) => b === signerPk[i4])) {
+      state.rejections.push({ from: message2.from, code: "UPDATE_MALFORMED", reason: "Fallback signerPk does not match the sender cohort key" });
+      return;
+    }
+    const fallbackLeaf = buildFallbackLeaf({
+      cohortKeys: state.cohort.cohortKeys,
+      fallbackThreshold: state.cohort.effectiveFallbackThreshold
+    });
+    const sighash = fallbackSighash(state.signingSession.pendingTx, 0, prevOutScript, prevOutValue, fallbackLeaf);
+    let valid = false;
+    try {
+      valid = fallbackSignature.length === 64 && schnorr2.verify(fallbackSignature, sighash, signerPk);
+    } catch {
+      valid = false;
+    }
+    if (!valid) {
+      state.rejections.push({ from: message2.from, code: "UPDATE_VERIFICATION_FAILED", reason: "Fallback signature failed verification" });
+      return;
+    }
+    state.fallbackSignatures.set(message2.from, { pubKey: signerPk, signature: fallbackSignature });
+    if (state.fallbackSignatures.size >= state.cohort.effectiveFallbackThreshold) {
+      const signedTx = buildFallbackSpend({
+        pendingTx: state.signingSession.pendingTx,
+        cohortKeys: state.cohort.cohortKeys,
+        fallbackThreshold: state.cohort.effectiveFallbackThreshold,
+        recoveryKey: state.cohort.recoveryKey,
+        recoverySequence: state.cohort.recoverySequence,
+        fundingModel: state.cohort.fundingModel,
+        network: state.cohort.network,
+        prevOutScript,
+        prevOutValue,
+        signatures: [...state.fallbackSignatures.values()]
+      });
+      state.result = { cohortId, signature: new Uint8Array(), signedTx, path: "script-path" };
+      state.phase = "Complete" /* Complete */;
+    }
+  }
   getResult(cohortId) {
     return this.#cohortStates.get(cohortId)?.result;
   }
@@ -104366,6 +104928,7 @@ var AggregationService = class {
 
 // src/core/aggregation/participant.ts
 init_shim();
+init_secp256k1();
 init_utils();
 
 // src/core/aggregation/messages/bodies.ts
@@ -104379,6 +104942,14 @@ var optIntMin = (b, k, min) => {
   const v = b ? b[k] : void 0;
   return v === void 0 || typeof v === "number" && Number.isInteger(v) && v >= min;
 };
+var intInRange = (b, k, min, max) => {
+  const v = b ? b[k] : void 0;
+  return typeof v === "number" && Number.isInteger(v) && v >= min && v <= max;
+};
+var optStrOneOf = (b, k, allowed) => {
+  const v = b ? b[k] : void 0;
+  return v === void 0 || typeof v === "string" && allowed.includes(v);
+};
 var hasBool = (b, k) => !!b && typeof b[k] === "boolean";
 var hasBytes = (b, k) => !!b && b[k] instanceof Uint8Array;
 var hasBytesArray = (b, k) => {
@@ -104386,7 +104957,7 @@ var hasBytesArray = (b, k) => {
   return Array.isArray(v) && v.every((x) => x instanceof Uint8Array);
 };
 function isCohortAdvertMessage(m2) {
-  return m2.type === COHORT_ADVERT && hasStr(m2.body, "cohortId") && hasIntMin(m2.body, "minParticipants", 1) && optIntMin(m2.body, "maxParticipants", 1) && hasStr(m2.body, "beaconType") && hasStr(m2.body, "network") && hasBytes(m2.body, "communicationPk");
+  return m2.type === COHORT_ADVERT && hasStr(m2.body, "cohortId") && hasIntMin(m2.body, "minParticipants", 1) && optIntMin(m2.body, "maxParticipants", 1) && hasStr(m2.body, "beaconType") && hasStr(m2.body, "network") && hasStr(m2.body, "recoveryKey") && intInRange(m2.body, "recoverySequence", 1, MAX_RECOVERY_SEQUENCE) && optStrOneOf(m2.body, "fundingModel", KNOWN_FUNDING_MODELS) && optIntMin(m2.body, "fallbackThreshold", 1) && hasBytes(m2.body, "communicationPk");
 }
 function isCohortOptInMessage(m2) {
   return m2.type === COHORT_OPT_IN && hasStr(m2.body, "cohortId") && hasBytes(m2.body, "participantPk") && hasBytes(m2.body, "communicationPk");
@@ -104400,6 +104971,9 @@ function isCohortReadyMessage(m2) {
 function isSubmitUpdateMessage(m2) {
   return m2.type === SUBMIT_UPDATE && hasStr(m2.body, "cohortId") && !!m2.body && typeof m2.body.signedUpdate === "object";
 }
+function isSubmitNonIncludedMessage(m2) {
+  return m2.type === SUBMIT_NONINCLUDED && hasStr(m2.body, "cohortId");
+}
 function isDistributeAggregatedDataMessage(m2) {
   return m2.type === DISTRIBUTE_AGGREGATED_DATA && hasStr(m2.body, "cohortId") && hasStr(m2.body, "beaconType") && hasStr(m2.body, "signalBytesHex");
 }
@@ -104418,8 +104992,38 @@ function isAggregatedNonceMessage(m2) {
 function isSignatureAuthorizationMessage(m2) {
   return m2.type === SIGNATURE_AUTHORIZATION && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasBytes(m2.body, "partialSignature");
 }
+function isFallbackAuthorizationRequestMessage(m2) {
+  return m2.type === FALLBACK_AUTHORIZATION_REQUEST && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasStr(m2.body, "pendingTx") && hasStr(m2.body, "prevOutScriptHex") && hasStr(m2.body, "prevOutValue") && hasStr(m2.body, "fallbackLeafScriptHex");
+}
+function isFallbackSignatureMessage(m2) {
+  return m2.type === FALLBACK_SIGNATURE && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasBytes(m2.body, "signerPk") && hasBytes(m2.body, "fallbackSignature");
+}
 
 // src/core/aggregation/participant.ts
+function txEmbedsSignal(tx, signalHex) {
+  let expected;
+  try {
+    expected = hexToBytes(signalHex);
+  } catch {
+    return false;
+  }
+  if (expected.length === 0) return false;
+  for (let i4 = 0; i4 < tx.outputsLength; i4++) {
+    const script = tx.getOutput(i4)?.script;
+    if (!script) continue;
+    let decoded;
+    try {
+      decoded = Script.decode(script);
+    } catch {
+      continue;
+    }
+    if (decoded.length === 2 && decoded[0] === "RETURN" && decoded[1] instanceof Uint8Array) {
+      const payload = decoded[1];
+      if (payload.length === expected.length && payload.every((b, j) => b === expected[j])) return true;
+    }
+  }
+  return false;
+}
 var AggregationParticipant = class {
   did;
   /** MuSig2 signing capability. The raw secret never lives as a field here. */
@@ -104436,7 +105040,7 @@ var AggregationParticipant = class {
   }
   /**
    * Process an incoming message. Updates internal state but never produces
-   * outgoing messages — those come exclusively from action methods.
+   * outgoing messages: those come exclusively from action methods.
    */
   receive(message2) {
     if (message2.version === void 0 || message2.version !== AGGREGATION_WIRE_VERSION) {
@@ -104462,6 +105066,9 @@ var AggregationParticipant = class {
       case AGGREGATED_NONCE:
         this.#handleAggregatedNonce(message2);
         break;
+      case FALLBACK_AUTHORIZATION_REQUEST:
+        this.#handleFallbackAuthorizationRequest(message2);
+        break;
       default:
         break;
     }
@@ -104507,12 +105114,17 @@ var AggregationParticipant = class {
         { cohortId, phase: state?.phase }
       );
     }
+    const advert = state.advert;
     const cohort = new AggregationCohort({
       id: cohortId,
       serviceDid: state.serviceDid,
-      minParticipants: state.advert.minParticipants,
-      network: state.advert.network,
-      beaconType: state.advert.beaconType
+      minParticipants: advert.minParticipants,
+      network: advert.network,
+      beaconType: advert.beaconType,
+      recoveryKey: advert.recoveryKey ? hexToBytes(advert.recoveryKey) : void 0,
+      recoverySequence: advert.recoverySequence,
+      fundingModel: advert.fundingModel,
+      fallbackThreshold: advert.fallbackThreshold
     });
     state.cohort = cohort;
     state.phase = "OptedIn" /* OptedIn */;
@@ -104527,7 +105139,7 @@ var AggregationParticipant = class {
   }
   #handleOptInAccept(message2) {
   }
-  /** Cohorts that have been finalized — beacon address available. */
+  /** Cohorts that have been finalized: beacon address available. */
   get joinedCohorts() {
     const map3 = /* @__PURE__ */ new Map();
     for (const [id, state] of this.#cohortStates) {
@@ -104570,6 +105182,7 @@ var AggregationParticipant = class {
       );
     }
     state.submittedUpdate = signedUpdate;
+    state.included = true;
     state.phase = "UpdateSubmitted" /* UpdateSubmitted */;
     const message2 = createSubmitUpdateMessage({
       from: this.did,
@@ -104579,6 +105192,30 @@ var AggregationParticipant = class {
     });
     return [message2];
   }
+  /**
+   * User action: decline to submit an update this round (cooperative
+   * non-inclusion). The member stays in the cohort and still signs; it will be
+   * absent from the CAS Announcement Map, or carry a non-inclusion leaf in the
+   * SMT. Returns the SUBMIT_NONINCLUDED message to send.
+   */
+  declineUpdate(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state || state.phase !== "CohortReady" /* CohortReady */) {
+      throw new AggregationParticipantError(
+        `Cannot decline in cohort ${cohortId}: not in CohortReady phase.`,
+        "INVALID_PHASE",
+        { cohortId, phase: state?.phase }
+      );
+    }
+    state.included = false;
+    state.phase = "NonIncluded" /* NonIncluded */;
+    const message2 = createSubmitNonIncludedMessage({
+      from: this.did,
+      to: state.serviceDid,
+      cohortId
+    });
+    return [message2];
+  }
   /** Aggregated data awaiting user validation. */
   get pendingValidations() {
     const map3 = /* @__PURE__ */ new Map();
@@ -104589,22 +105226,35 @@ var AggregationParticipant = class {
     }
     return map3;
   }
+  /**
+   * The validated aggregated data retained for a cohort, regardless of phase.
+   * Unlike {@link pendingValidations} (which lists only cohorts still awaiting
+   * the validate decision), this returns the stored validation, including the
+   * participant's sidecar (the CAS Announcement map or its SMT inclusion proof),
+   * so it is still readable once the cohort reaches Complete. Returns
+   * undefined before aggregated data has been received.
+   */
+  getValidation(cohortId) {
+    return this.#cohortStates.get(cohortId)?.validation;
+  }
   #handleDistributeAggregatedData(message2) {
     const cohortId = message2.body?.cohortId;
     if (!cohortId) return;
     const state = this.#cohortStates.get(cohortId);
-    if (!state || state.phase !== "UpdateSubmitted" /* UpdateSubmitted */) return;
-    if (!state.submittedUpdate) return;
+    if (!state || state.phase !== "UpdateSubmitted" /* UpdateSubmitted */ && state.phase !== "NonIncluded" /* NonIncluded */) return;
+    const declined = state.included === false;
+    if (!declined && !state.submittedUpdate) return;
     const beaconType = message2.body?.beaconType;
     if (!beaconType) return;
     const strategy = getBeaconStrategy(beaconType);
     if (!strategy) return;
     const signalBytesHex = message2.body?.signalBytesHex ?? "";
-    const expectedHash = canonicalHash(state.submittedUpdate);
+    const expectedHash = declined ? "" : canonicalHash(state.submittedUpdate);
     const result = strategy.validateParticipantView({
       participantDid: this.did,
-      submittedUpdate: state.submittedUpdate,
-      expectedHash,
+      included: !declined,
+      submittedUpdate: declined ? void 0 : state.submittedUpdate,
+      expectedHash: declined ? void 0 : expectedHash,
       body: message2.body
     });
     state.validation = {
@@ -104614,7 +105264,8 @@ var AggregationParticipant = class {
       expectedHash,
       matches: result.matches,
       casAnnouncement: result.casAnnouncement,
-      smtProof: result.smtProof
+      smtProof: result.smtProof,
+      included: !declined
     };
     state.phase = "AwaitingValidation" /* AwaitingValidation */;
   }
@@ -104688,6 +105339,31 @@ var AggregationParticipant = class {
     };
     state.phase = "AwaitingSigning" /* AwaitingSigning */;
   }
+  /**
+   * Bind a signing approval to the announcement the member validated: a beacon
+   * transaction MUST carry an OP_RETURN with the exact 32-byte signal stored when
+   * the aggregated data was distributed. Both the optimistic nonce approval and
+   * the fallback approval sign with SIGHASH_DEFAULT (committing to every output)
+   * while the coordinator drives output selection, so without this check a
+   * coordinator could anchor a different signal under the member's signature.
+   */
+  #assertTxAnchorsValidatedSignal(cohortId, state, tx) {
+    const signalHex = state.validation?.signalBytesHex;
+    if (!signalHex) {
+      throw new AggregationParticipantError(
+        `Cohort ${cohortId} has no validated signal to bind the signature to.`,
+        "MISSING_STATE",
+        { cohortId }
+      );
+    }
+    if (!txEmbedsSignal(tx, signalHex)) {
+      throw new AggregationParticipantError(
+        `Transaction for cohort ${cohortId} does not anchor the validated signal.`,
+        "SIGNAL_MISMATCH",
+        { cohortId }
+      );
+    }
+  }
   /**
    * User action: approve signing and generate nonce contribution.
    */
@@ -104707,7 +105383,8 @@ var AggregationParticipant = class {
         { cohortId }
       );
     }
-    const tx = Transaction.fromRaw(hexToBytes(state.signingRequest.pendingTxHex));
+    const tx = Transaction.fromRaw(hexToBytes(state.signingRequest.pendingTxHex), { allowUnknownOutputs: true });
+    this.#assertTxAnchorsValidatedSignal(cohortId, state, tx);
     const prevOutScripts = [hexToBytes(state.signingRequest.prevOutScriptHex)];
     const prevOutValues = [BigInt(state.signingRequest.prevOutValue)];
     const session = new BeaconSigningSession({
@@ -104743,7 +105420,7 @@ var AggregationParticipant = class {
   }
   /**
    * User action: generate and return the partial signature.
-   * In most UIs this is automatic after AwaitingPartialSig — but exposing it
+   * In most UIs this is automatic after AwaitingPartialSig, but exposing it
    * as an explicit action lets the client UI confirm before signing if desired.
    */
   generatePartialSignature(cohortId) {
@@ -104775,6 +105452,83 @@ var AggregationParticipant = class {
       partialSignature: partialSig
     })];
   }
+  /** Fallback signing requests awaiting user approval (UI: review the fallback spend). */
+  get pendingFallbackRequests() {
+    const map3 = /* @__PURE__ */ new Map();
+    for (const [id, state] of this.#cohortStates) {
+      if (state.phase === "AwaitingFallbackSig" /* AwaitingFallbackSig */ && state.fallbackRequest) {
+        map3.set(id, state.fallbackRequest);
+      }
+    }
+    return map3;
+  }
+  #handleFallbackAuthorizationRequest(message2) {
+    const cohortId = message2.body?.cohortId;
+    if (!cohortId) return;
+    const state = this.#cohortStates.get(cohortId);
+    if (!state || !state.cohort) return;
+    const acceptFrom = [
+      "ValidationSent" /* ValidationSent */,
+      "AwaitingSigning" /* AwaitingSigning */,
+      "NonceSent" /* NonceSent */,
+      "AwaitingPartialSig" /* AwaitingPartialSig */,
+      "Complete" /* Complete */
+    ];
+    if (!acceptFrom.includes(state.phase)) return;
+    const sessionId = message2.body?.sessionId;
+    const pendingTxHex = message2.body?.pendingTx;
+    const prevOutScriptHex = message2.body?.prevOutScriptHex;
+    const prevOutValue = message2.body?.prevOutValue;
+    const fallbackLeafScriptHex = message2.body?.fallbackLeafScriptHex;
+    if (!sessionId || !pendingTxHex || !prevOutScriptHex || !prevOutValue || !fallbackLeafScriptHex) return;
+    state.fallbackRequest = { cohortId, sessionId, pendingTxHex, prevOutScriptHex, prevOutValue, fallbackLeafScriptHex };
+    state.signingSession?.clearSecrets();
+    state.phase = "AwaitingFallbackSig" /* AwaitingFallbackSig */;
+  }
+  /**
+   * User action: authorize the fallback spend. Recomputes the k-of-n fallback
+   * leaf from the member's OWN cohort state (not the service-provided script),
+   * computes the BIP-341 script-path sighash over the requested transaction, and
+   * returns a standalone BIP-340 signature (no nonce round). The member completes
+   * once it has contributed; the service needs only k of these.
+   */
+  approveFallback(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state || state.phase !== "AwaitingFallbackSig" /* AwaitingFallbackSig */) {
+      throw new AggregationParticipantError(
+        `Cannot approve fallback for cohort ${cohortId}: not in AwaitingFallbackSig phase.`,
+        "INVALID_PHASE",
+        { cohortId, phase: state?.phase }
+      );
+    }
+    if (!state.fallbackRequest || !state.cohort) {
+      throw new AggregationParticipantError(
+        `Cohort ${cohortId} missing fallback request or cohort state.`,
+        "MISSING_STATE",
+        { cohortId }
+      );
+    }
+    const req = state.fallbackRequest;
+    const tx = Transaction.fromRaw(hexToBytes(req.pendingTxHex), { allowUnknownOutputs: true });
+    const prevOutScript = hexToBytes(req.prevOutScriptHex);
+    const prevOutValue = BigInt(req.prevOutValue);
+    this.#assertTxAnchorsValidatedSignal(cohortId, state, tx);
+    const fallbackLeaf = buildFallbackLeaf({
+      cohortKeys: state.cohort.cohortKeys,
+      fallbackThreshold: state.cohort.effectiveFallbackThreshold
+    });
+    const sighash = fallbackSighash(tx, 0, prevOutScript, prevOutValue, fallbackLeaf);
+    const signature = this.#signer.withSecret((secretKey) => schnorr2.sign(sighash, secretKey));
+    state.phase = "Complete" /* Complete */;
+    return [createFallbackSignatureMessage({
+      from: this.did,
+      to: state.serviceDid,
+      cohortId,
+      sessionId: req.sessionId,
+      signerPk: this.publicKey.slice(1),
+      fallbackSignature: signature
+    })];
+  }
   getCohortPhase(cohortId) {
     return this.#cohortStates.get(cohortId)?.phase;
   }
@@ -104811,6 +105565,85 @@ var KeyPairAggregationSigner = class {
   }
 };
 
+// src/core/aggregation/recovery-spend.ts
+init_shim();
+init_secp256k1();
+var DUST_LIMIT_SATS = 546n;
+function bytesEqual2(a2, b) {
+  return a2.length === b.length && a2.every((x, i4) => x === b[i4]);
+}
+function buildRecoverySpend(params) {
+  const {
+    cohortKeys,
+    recoverySecretKey,
+    recoveryKey,
+    recoverySequence,
+    fallbackThreshold,
+    fundingModel,
+    network,
+    utxo,
+    destinationAddress,
+    fee,
+    beaconAddress
+  } = params;
+  if (cohortKeys.length === 0) {
+    throw new AggregationCohortError(
+      "Cannot build recovery spend: no cohort keys.",
+      "NO_COHORT_KEYS"
+    );
+  }
+  const derivedPub = schnorr2.getPublicKey(recoverySecretKey);
+  if (!bytesEqual2(derivedPub, recoveryKey)) {
+    throw new AggregationCohortError(
+      "Recovery secret key does not correspond to the committed recovery key.",
+      "RECOVERY_KEY_MISMATCH"
+    );
+  }
+  const out = utxo.value - fee;
+  if (out <= 0n) {
+    throw new AggregationCohortError(
+      `Recovery fee ${fee} exceeds UTXO value ${utxo.value}.`,
+      "FEE_EXCEEDS_VALUE",
+      { fee: fee.toString(), value: utxo.value.toString() }
+    );
+  }
+  if (out < DUST_LIMIT_SATS) {
+    throw new AggregationCohortError(
+      `Recovered output ${out} is below the dust limit ${DUST_LIMIT_SATS}; the spend would not relay.`,
+      "DUST_OUTPUT",
+      { output: out.toString(), dustLimit: DUST_LIMIT_SATS.toString() }
+    );
+  }
+  const internalKey = keyAggExport(keyAggregate(sortKeys(cohortKeys)));
+  const leaves = buildRecoveryLeaves(fundingModel ?? DEFAULT_FUNDING_MODEL, {
+    recoveryKey,
+    recoverySequence,
+    cohortKeys,
+    fallbackThreshold: resolveFallbackThreshold(fallbackThreshold, cohortKeys.length)
+  });
+  const net = getNetwork(network);
+  const payment = p2tr(internalKey, leaves, net, true);
+  if (beaconAddress !== void 0 && payment.address !== beaconAddress) {
+    throw new AggregationCohortError(
+      `Reconstructed beacon address ${payment.address} does not match the cohort's funded address ${beaconAddress}.`,
+      "BEACON_ADDRESS_MISMATCH",
+      { reconstructed: payment.address, expected: beaconAddress }
+    );
+  }
+  const tx = new Transaction({ version: 2, allowUnknownInputs: true });
+  tx.addInput({
+    txid: utxo.txid,
+    index: utxo.vout,
+    witnessUtxo: { script: payment.script, amount: utxo.value },
+    tapLeafScript: payment.tapLeafScript,
+    sequence: recoverySequence
+  });
+  tx.addOutputAddress(destinationAddress, out, net);
+  tx.signIdx(recoverySecretKey, 0);
+  tx.finalize();
+  return tx;
+}
+
 // src/core/aggregation/logger.ts
 init_shim();
 var CONSOLE_LOGGER = {
@@ -104843,6 +105676,7 @@ var KEYGEN_VALUES = /* @__PURE__ */ new Set([
 ]);
 var UPDATE_VALUES = /* @__PURE__ */ new Set([
   SUBMIT_UPDATE,
+  SUBMIT_NONINCLUDED,
   DISTRIBUTE_AGGREGATED_DATA,
   VALIDATION_ACK
 ]);
@@ -104850,7 +105684,9 @@ var SIGN_VALUES = /* @__PURE__ */ new Set([
   AUTHORIZATION_REQUEST,
   NONCE_CONTRIBUTION,
   AGGREGATED_NONCE,
-  SIGNATURE_AUTHORIZATION
+  SIGNATURE_AUTHORIZATION,
+  FALLBACK_AUTHORIZATION_REQUEST,
+  FALLBACK_SIGNATURE
 ]);
 function isAggregationMessageType(type) {
   return KEYGEN_VALUES.has(type) || UPDATE_VALUES.has(type) || SIGN_VALUES.has(type);
@@ -111011,7 +111847,7 @@ var NostrTransport = class _NostrTransport {
    * backfill historical events to late subscribers: republishing gives late
    * joiners a window to discover the message without requiring protocol
    * changes. Relay rate-limit / publish failures inside the interval are
-   * caught and logged rather than propagated — the caller should stop the
+   * caught and logged rather than propagated - the caller should stop the
    * repeater once the protocol condition is satisfied.
    */
   publishRepeating(message2, sender, intervalMs, recipient) {
@@ -111465,35 +112301,29 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
   session;
   #transport;
   #did;
-  #config;
+  #defaultConfig;
   #onOptInReceived;
   #onReadyToFinalize;
   #onProvideTxData;
   #cohortTtlMs;
   #phaseTimeoutMs;
   #advertRepeatIntervalMs;
-  #cohortId;
+  #autoFallbackOnStall;
+  /** Phases during which a stall can be salvaged by the k-of-n fallback (ADR 042). */
+  static #SIGNING_PHASES = [
+    "SigningStarted" /* SigningStarted */,
+    "NoncesCollected" /* NoncesCollected */,
+    "AwaitingPartialSigs" /* AwaitingPartialSigs */
+  ];
+  /** Per-cohort run state, keyed by cohortId. */
+  #contexts = /* @__PURE__ */ new Map();
   #handlersRegistered = false;
   #stopped = false;
-  /**
-   * Guard against the async race where two concurrent #handleOptIn invocations
-   * both pass the `participants.length >= minParticipants` check before either
-   * mutates the cohort phase. Set synchronously before any `await` so subsequent
-   * handlers observe it on their next resumption.
-   */
-  #finalizing = false;
-  #resolveRun;
-  #rejectRun;
-  #cohortTtlTimer;
-  #phaseTimer;
-  #lastObservedPhase;
-  /** Stop handle for the repeating COHORT_ADVERT publish loop. */
-  #stopAdvertRepeat;
   constructor(options2) {
     super();
     this.#transport = options2.transport;
     this.#did = options2.did;
-    this.#config = options2.config;
+    this.#defaultConfig = options2.config;
     this.#onOptInReceived = options2.onOptInReceived ?? (async () => ({ accepted: true }));
     this.#onReadyToFinalize = options2.onReadyToFinalize ?? (async ({ acceptedCount, minRequired }) => ({
       finalize: acceptedCount >= minRequired
@@ -111502,6 +112332,7 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
     this.#cohortTtlMs = options2.cohortTtlMs;
     this.#phaseTimeoutMs = options2.phaseTimeoutMs;
     this.#advertRepeatIntervalMs = options2.advertRepeatIntervalMs ?? DEFAULT_ADVERT_REPEAT_INTERVAL_MS;
+    this.#autoFallbackOnStall = options2.autoFallbackOnStall ?? false;
     this.session = new AggregationService({
       // The coordinator never signs, so the state machine receives only the
       // public half of the operator's keypair (see ADR 038). The full keypair
@@ -111511,55 +112342,126 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
       maxUpdateSizeBytes: options2.maxUpdateSizeBytes
     });
   }
+  /** Resolve the {@link RunContext} an inbound message belongs to, by cohortId. */
+  #contextFor(msg) {
+    const cohortId = msg.body?.cohortId;
+    if (!cohortId) return void 0;
+    return this.#contexts.get(cohortId);
+  }
   /**
-   * Drain any silent rejections the state machine recorded during the most
-   * recent receive() and surface them as `message-rejected` events. Safe to
-   * call even before a cohortId is assigned.
+   * Drain any silent rejections the state machine recorded for a cohort during
+   * the most recent receive() and surface them as `message-rejected` events.
    */
-  #drainRejections() {
-    if (!this.#cohortId) return;
-    for (const r2 of this.session.drainRejections(this.#cohortId)) {
-      this.emit("message-rejected", { cohortId: this.#cohortId, ...r2 });
+  #drainRejections(ctx) {
+    for (const r2 of this.session.drainRejections(ctx.cohortId)) {
+      this.emit("message-rejected", { cohortId: ctx.cohortId, ...r2 });
     }
   }
   /**
-   * Run the protocol to completion. Resolves with the final aggregation result
-   * (signature + signed transaction) once signing is complete.
+   * Advertise a new cohort and begin driving it to completion. Callable many
+   * times on one runner; each cohort runs concurrently and independently.
+   *
+   * @param config Per-cohort conditions + network (see {@link CohortConfig}).
+   * @returns The new cohort's id and a `completion` promise that resolves with
+   *   that cohort's {@link AggregationResult} (or rejects if it fails/stalls).
+   * @throws If the runner has been stopped, or the config is invalid
+   *   (fail-fast via `createCohort`).
+   */
+  advertiseCohort(config) {
+    if (this.#stopped) {
+      throw new AggregationServiceError("Cannot advertise on a stopped runner.", "RUNNER_STOPPED", {});
+    }
+    this.#registerHandlers();
+    const cohortId = this.session.createCohort(config);
+    let resolve;
+    let reject;
+    const completion = new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    const ctx = {
+      cohortId,
+      config,
+      resolve,
+      reject,
+      completion,
+      finalizing: false,
+      settled: false
+    };
+    this.#contexts.set(cohortId, ctx);
+    try {
+      this.#startTimers(ctx);
+      const advertMsgs = this.session.advertise(cohortId);
+      this.#onPhaseMaybeChanged(ctx);
+      this.emit("cohort-advertised", { cohortId });
+      if (this.#advertRepeatIntervalMs > 0) {
+        this.#startAdvertRepeat(ctx, advertMsgs);
+      } else {
+        this.#sendAll(advertMsgs).catch((err) => this.#failCohort(ctx, err));
+      }
+    } catch (err) {
+      this.#failCohort(ctx, err);
+    }
+    return { cohortId, completion };
+  }
+  /**
+   * Run a single cohort to completion using the `config` supplied in the
+   * runner options. Thin convenience over {@link advertiseCohort} for the
+   * single-cohort case (and the path {@link AggregationRunner.solo} rides).
    *
    * @returns {Promise<AggregationResult>} The final result with signature and signed tx.
    */
   run() {
-    return new Promise((resolve, reject) => {
-      this.#resolveRun = resolve;
-      this.#rejectRun = reject;
-      try {
-        this.#registerHandlers();
-        this.#cohortId = this.session.createCohort(this.#config);
-        this.#startTimers();
-        const advertMsgs = this.session.advertise(this.#cohortId);
-        this.#onPhaseMaybeChanged();
-        this.emit("cohort-advertised", { cohortId: this.#cohortId });
-        if (this.#advertRepeatIntervalMs > 0) {
-          this.#startAdvertRepeat(advertMsgs);
-        } else {
-          this.#sendAll(advertMsgs).catch((err) => this.#fail(err));
-        }
-      } catch (err) {
-        this.#fail(err);
+    if (!this.#defaultConfig) {
+      return Promise.reject(new AggregationServiceError(
+        "run() requires `config` in the runner options; use advertiseCohort(config) to drive cohorts explicitly.",
+        "MISSING_COHORT_CONFIG",
+        {}
+      ));
+    }
+    try {
+      return this.advertiseCohort(this.#defaultConfig).completion;
+    } catch (err) {
+      return Promise.reject(err);
+    }
+  }
+  /**
+   * Wait for every currently-outstanding cohort to settle and return the
+   * successful results. Dynamic drain: cohorts advertised while this is pending
+   * are included, and it resolves only once no cohorts remain. Failed cohorts
+   * are surfaced via `error` / `cohort-failed` events and their rejected
+   * `completion` promises; they are omitted from the returned array (this
+   * method does not throw). Bound long-running cohorts with `cohortTtlMs` /
+   * `phaseTimeoutMs` or this may never resolve.
+   *
+   * @returns {Promise<AggregationResult[]>} Results of the cohorts that completed.
+   */
+  async runAll() {
+    const collected = /* @__PURE__ */ new Map();
+    const onComplete = (result) => {
+      collected.set(result.cohortId, result);
+    };
+    this.on("signing-complete", onComplete);
+    try {
+      while (this.#contexts.size > 0) {
+        await Promise.allSettled([...this.#contexts.values()].map((c2) => c2.completion));
       }
-    });
+    } finally {
+      this.off("signing-complete", onComplete);
+    }
+    return [...collected.values()];
   }
   /**
-   * Begin publishing the cohort advert immediately and on a repeating interval
-   * until {@link #stopAdvertRepeating} is called. Each advert is broadcast
-   * (no recipient) via the transport's `publishRepeating` primitive.
+   * Begin publishing a cohort's advert immediately and on a repeating interval
+   * until the cohort's advert loop is stopped. Each advert is broadcast (no
+   * recipient) via the transport's `publishRepeating` primitive.
    */
-  #startAdvertRepeat(advertMsgs) {
+  #startAdvertRepeat(ctx, advertMsgs) {
     const stops = [];
     for (const msg of advertMsgs) {
       stops.push(this.#transport.publishRepeating(msg, this.#did, this.#advertRepeatIntervalMs));
     }
-    this.#stopAdvertRepeat = () => {
+    ctx.stopAdvertRepeat = () => {
       for (const stop2 of stops) {
         try {
           stop2();
@@ -111568,81 +112470,176 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
       }
     };
   }
-  /** Stop the advert republish loop. Idempotent. */
-  #stopAdvertRepeating() {
-    if (!this.#stopAdvertRepeat) return;
-    const stop2 = this.#stopAdvertRepeat;
-    this.#stopAdvertRepeat = void 0;
+  /** Stop a cohort's advert republish loop. Idempotent. */
+  #stopAdvertRepeating(ctx) {
+    if (!ctx.stopAdvertRepeat) return;
+    const stop2 = ctx.stopAdvertRepeat;
+    ctx.stopAdvertRepeat = void 0;
     stop2();
   }
-  /** Schedule cohort TTL + phase timeout at the start of a run. */
-  #startTimers() {
+  /** Schedule a cohort's TTL + phase timeout when it is advertised. */
+  #startTimers(ctx) {
     if (this.#cohortTtlMs !== void 0) {
-      this.#cohortTtlTimer = setTimeout(() => {
-        const reason = `Cohort ${this.#cohortId ?? ""} exceeded TTL of ${this.#cohortTtlMs}ms`;
-        this.emit("cohort-failed", { cohortId: this.#cohortId ?? "", reason });
-        this.#fail(new Error(reason));
+      ctx.cohortTtlTimer = setTimeout(() => {
+        const reason = `Cohort ${ctx.cohortId} exceeded TTL of ${this.#cohortTtlMs}ms`;
+        this.emit("cohort-failed", { cohortId: ctx.cohortId, reason });
+        this.#failCohort(ctx, new Error(reason));
       }, this.#cohortTtlMs);
     }
-    this.#resetPhaseTimer();
+    this.#resetPhaseTimer(ctx);
   }
-  /** Reset the per-phase stall timer. Called when a phase transition is observed. */
-  #resetPhaseTimer() {
-    if (this.#phaseTimer) clearTimeout(this.#phaseTimer);
-    this.#phaseTimer = void 0;
+  /** Reset a cohort's per-phase stall timer. Called when a phase transition is observed. */
+  #resetPhaseTimer(ctx) {
+    if (ctx.phaseTimer) clearTimeout(ctx.phaseTimer);
+    ctx.phaseTimer = void 0;
     if (this.#phaseTimeoutMs === void 0) return;
-    this.#phaseTimer = setTimeout(() => {
-      const reason = `Cohort ${this.#cohortId ?? ""} stalled in phase ${this.#lastObservedPhase ?? "?"} for ${this.#phaseTimeoutMs}ms`;
-      this.emit("cohort-failed", { cohortId: this.#cohortId ?? "", reason });
-      this.#fail(new Error(reason));
+    ctx.phaseTimer = setTimeout(() => {
+      const phase = this.session.getCohortPhase(ctx.cohortId);
+      const inSigning = phase !== void 0 && _AggregationServiceRunner.#SIGNING_PHASES.includes(phase);
+      if (this.#autoFallbackOnStall && inSigning && !ctx.committedPath && !ctx.settled) {
+        this.triggerFallback(ctx.cohortId).catch((err) => this.#failCohort(ctx, err));
+        return;
+      }
+      const reason = `Cohort ${ctx.cohortId} stalled in phase ${ctx.lastObservedPhase ?? "?"} for ${this.#phaseTimeoutMs}ms`;
+      this.emit("cohort-failed", { cohortId: ctx.cohortId, reason });
+      this.#failCohort(ctx, new Error(reason));
     }, this.#phaseTimeoutMs);
   }
-  /** Detect a phase change since the last observation and reset the phase timer. */
-  #onPhaseMaybeChanged() {
-    if (!this.#cohortId) return;
-    const phase = this.session.getCohortPhase(this.#cohortId);
-    if (phase !== this.#lastObservedPhase) {
-      this.#lastObservedPhase = phase;
-      this.#resetPhaseTimer();
-    }
+  /**
+   * Abandon the optimistic n-of-n key path for a cohort and collect k-of-n
+   * fallback (script-path) signatures instead (ADR 042). Idempotent and safe
+   * against the optimistic completion: it commits the cohort to the fallback
+   * path synchronously (the `committedPath` latch) before sending anything, so a
+   * late optimistic signature can no longer complete-and-broadcast a competing
+   * spend of the same UTXO. No-op if the cohort is unknown, already settled, or
+   * already committed to a path.
+   *
+   * Wired automatically to the phase-stall timer when `autoFallbackOnStall` is
+   * set; otherwise call it from an operator decision (a UI "fall back now"
+   * action). Throws only if the underlying state machine rejects the transition
+   * (e.g. signing has not started).
+   */
+  async triggerFallback(cohortId) {
+    const ctx = this.#contexts.get(cohortId);
+    if (!ctx || ctx.settled || ctx.committedPath) return;
+    const messages2 = this.session.startFallbackSigning(cohortId);
+    ctx.committedPath = "fallback";
+    this.#stopAdvertRepeating(ctx);
+    this.#onPhaseMaybeChanged(ctx);
+    const sessionId = this.session.getSigningSessionId(cohortId) ?? "";
+    this.emit("fallback-started", { cohortId, sessionId });
+    await this.#sendAll(messages2);
+  }
+  /** Detect a phase change for a cohort since the last observation and reset its phase timer. */
+  #onPhaseMaybeChanged(ctx) {
+    const phase = this.session.getCohortPhase(ctx.cohortId);
+    if (phase !== ctx.lastObservedPhase) {
+      ctx.lastObservedPhase = phase;
+      this.#resetPhaseTimer(ctx);
+    }
+  }
+  /** Clear a cohort's timers. Called on completion, stop, and failure. */
+  #clearTimers(ctx) {
+    if (ctx.cohortTtlTimer) clearTimeout(ctx.cohortTtlTimer);
+    if (ctx.phaseTimer) clearTimeout(ctx.phaseTimer);
+    ctx.cohortTtlTimer = void 0;
+    ctx.phaseTimer = void 0;
   }
-  /** Clear both timers. Called on successful completion, stop(), and #fail. */
-  #clearTimers() {
-    if (this.#cohortTtlTimer) clearTimeout(this.#cohortTtlTimer);
-    if (this.#phaseTimer) clearTimeout(this.#phaseTimer);
-    this.#cohortTtlTimer = void 0;
-    this.#phaseTimer = void 0;
+  /**
+   * Reclaim one cohort's runner-layer bookkeeping: stop its advert loop, clear
+   * its timers, and drop its {@link RunContext}. Does NOT touch sibling cohorts
+   * and does NOT detach the shared transport handlers. Leaves the cohort in the
+   * state machine; whether that cohort's `session` state is also removed is the
+   * caller's choice (see {@link #completeCohort} vs {@link #failCohort}).
+   */
+  #disposeCohort(ctx) {
+    this.#stopAdvertRepeating(ctx);
+    this.#clearTimers(ctx);
+    this.#contexts.delete(ctx.cohortId);
+  }
+  /**
+   * Settle one cohort successfully. Reclaims the runner context but leaves the
+   * completed cohort in `session` so callers can read its beaconAddress / cohort
+   * via `session.getCohort(result.cohortId)`; reclaim it with
+   * `session.removeCohort(cohortId)` when done. Idempotent via `ctx.settled`.
+   */
+  #completeCohort(ctx, result) {
+    if (ctx.settled) return;
+    ctx.settled = true;
+    this.#disposeCohort(ctx);
+    this.emit("signing-complete", result);
+    ctx.resolve(result);
+  }
+  /**
+   * Fail one cohort. Reclaims its runner context, drops its now-dead state from
+   * the state machine, and rejects only its completion; siblings keep running
+   * and the shared transport handlers stay registered. Idempotent via
+   * `ctx.settled`.
+   */
+  #failCohort(ctx, err) {
+    if (ctx.settled) return;
+    ctx.settled = true;
+    this.#disposeCohort(ctx);
+    this.session.removeCohort(ctx.cohortId);
+    this.emit("error", err);
+    ctx.reject(err);
+  }
+  /**
+   * Stop a single cohort early without affecting the rest of the runner. Drops
+   * the cohort's state machine state; its `completion` promise rejects with a
+   * stopped error.
+   */
+  stopCohort(cohortId) {
+    const ctx = this.#contexts.get(cohortId);
+    if (!ctx || ctx.settled) return;
+    ctx.settled = true;
+    this.#disposeCohort(ctx);
+    this.session.removeCohort(cohortId);
+    ctx.reject(new AggregationServiceError(`Cohort ${cohortId} stopped.`, "COHORT_STOPPED", { cohortId }));
   }
   /**
-   * Stop the runner early. Marks the runner stopped and detaches transport
-   * handlers so a restart or a new runner doesn't inherit stale dispatch.
+   * Stop the whole runner. Fails every outstanding cohort, then detaches the
+   * shared transport handlers so a restart or a new runner doesn't inherit
+   * stale dispatch. Safe to call repeatedly.
    */
   stop() {
     this.#stopped = true;
-    this.#stopAdvertRepeating();
-    this.#clearTimers();
+    for (const ctx of [...this.#contexts.values()]) {
+      if (ctx.settled) continue;
+      ctx.settled = true;
+      this.#disposeCohort(ctx);
+      this.session.removeCohort(ctx.cohortId);
+      ctx.reject(new AggregationServiceError("Service runner stopped.", "RUNNER_STOPPED", { cohortId: ctx.cohortId }));
+    }
+    this.#contexts.clear();
     this.#unregisterHandlers();
-    if (this.#cohortId) this.session.removeCohort(this.#cohortId);
   }
   /** Message types this runner listens for on the transport. */
   static #HANDLED_MESSAGE_TYPES = [
     COHORT_OPT_IN,
     SUBMIT_UPDATE,
+    SUBMIT_NONINCLUDED,
     VALIDATION_ACK,
     NONCE_CONTRIBUTION,
-    SIGNATURE_AUTHORIZATION
+    SIGNATURE_AUTHORIZATION,
+    FALLBACK_SIGNATURE
   ];
   /**
-   * Internal: handler registration with the transport. Idempotent.
+   * Internal: handler registration with the transport. Idempotent. Handlers
+   * are DID-scoped and cohort-agnostic - one registration serves every cohort
+   * this runner drives; demux to the right {@link RunContext} happens in each
+   * handler via the inbound message's cohortId.
    */
   #registerHandlers() {
     if (this.#handlersRegistered) return;
     this.#handlersRegistered = true;
     this.#transport.registerMessageHandler(this.#did, COHORT_OPT_IN, this.#handleOptIn.bind(this));
     this.#transport.registerMessageHandler(this.#did, SUBMIT_UPDATE, this.#handleSubmitUpdate.bind(this));
+    this.#transport.registerMessageHandler(this.#did, SUBMIT_NONINCLUDED, this.#handleSubmitUpdate.bind(this));
     this.#transport.registerMessageHandler(this.#did, VALIDATION_ACK, this.#handleValidationAck.bind(this));
     this.#transport.registerMessageHandler(this.#did, NONCE_CONTRIBUTION, this.#handleNonceContribution.bind(this));
     this.#transport.registerMessageHandler(this.#did, SIGNATURE_AUTHORIZATION, this.#handleSignatureAuthorization.bind(this));
+    this.#transport.registerMessageHandler(this.#did, FALLBACK_SIGNATURE, this.#handleFallbackSignature.bind(this));
   }
   /** Internal: detach from the transport. Safe to call repeatedly. */
   #unregisterHandlers() {
@@ -111654,23 +112651,25 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
   }
   /**
    * Internal: message handlers for each protocol step. Each handler:
-   * 1) feeds the message into the state machine via session.receive()
-   * 2) emits a high-level event for external observers
-   * 3) checks if the new state triggers any automatic next steps, and if so:
+   * 1) resolves the cohort the message belongs to (by cohortId); ignores it if unknown
+   * 2) feeds the message into the state machine via session.receive()
+   * 3) emits a high-level event (carrying cohortId) for external observers
+   * 4) checks if the new state triggers any automatic next steps, and if so:
    *    a) calls the appropriate decision callback(s)
    *    b) sends any resulting messages from the state machine
+   * Errors fail only the owning cohort. A stopped runner ignores messages.
    * @param {BaseMessage} msg - The incoming message to handle.
    * @returns {Promise<void>} Resolves when handling is complete.
-    * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-    * Note: if the runner has been stopped, handlers will ignore incoming messages.
    */
   async #handleOptIn(msg) {
     if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
     try {
       this.session.receive(msg);
-      this.#drainRejections();
-      this.#onPhaseMaybeChanged();
-      const optIn = this.session.pendingOptIns(this.#cohortId).get(msg.from);
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      const optIn = this.session.pendingOptIns(ctx.cohortId).get(msg.from);
       if (!optIn) return;
       this.emit("opt-in-received", optIn);
       if (optIn.communicationPk) {
@@ -111678,34 +112677,34 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
       }
       const decision = await this.#onOptInReceived(optIn);
       if (!decision.accepted) return;
-      const maxParticipants = this.#config.maxParticipants;
-      const cohortNow = this.session.getCohort(this.#cohortId);
+      const maxParticipants = ctx.config.maxParticipants;
+      const cohortNow = this.session.getCohort(ctx.cohortId);
       if (maxParticipants !== void 0 && cohortNow && cohortNow.participants.length >= maxParticipants) {
         return;
       }
-      await this.#sendAll(this.session.acceptParticipant(this.#cohortId, msg.from));
-      this.emit("participant-accepted", { participantDid: msg.from });
-      const cohort = this.session.getCohort(this.#cohortId);
-      if (cohort.participants.length >= this.#config.minParticipants && !this.#finalizing) {
-        this.#finalizing = true;
+      await this.#sendAll(this.session.acceptParticipant(ctx.cohortId, msg.from));
+      this.emit("participant-accepted", { cohortId: ctx.cohortId, participantDid: msg.from });
+      const cohort = this.session.getCohort(ctx.cohortId);
+      if (cohort.participants.length >= ctx.config.minParticipants && !ctx.finalizing) {
+        ctx.finalizing = true;
         const finalizeDecision = await this.#onReadyToFinalize({
           acceptedCount: cohort.participants.length,
-          minRequired: this.#config.minParticipants
+          minRequired: ctx.config.minParticipants
         });
         if (!finalizeDecision.finalize) {
-          this.#finalizing = false;
+          ctx.finalizing = false;
           return;
         }
-        const readyMsgs = this.session.finalizeKeygen(this.#cohortId);
-        this.#stopAdvertRepeating();
+        const readyMsgs = this.session.finalizeKeygen(ctx.cohortId);
+        this.#stopAdvertRepeating(ctx);
         this.emit("keygen-complete", {
-          cohortId: this.#cohortId,
+          cohortId: ctx.cohortId,
           beaconAddress: cohort.beaconAddress
         });
         await this.#sendAll(readyMsgs);
       }
     } catch (err) {
-      this.#fail(err);
+      this.#failCohort(ctx, err);
     }
   }
   /**
@@ -111713,23 +112712,23 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
    * and distributes the data for validation.
    * @param {BaseMessage} msg - The incoming message to handle.
    * @returns {Promise<void>} Resolves when handling is complete.
-   * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-   * Note: if the runner has been stopped, handlers will ignore incoming messages.
    */
   async #handleSubmitUpdate(msg) {
     if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
     try {
       this.session.receive(msg);
-      this.#drainRejections();
-      this.#onPhaseMaybeChanged();
-      this.emit("update-received", { participantDid: msg.from });
-      if (this.session.getCohortPhase(this.#cohortId) === "UpdatesCollected" /* UpdatesCollected */) {
-        const distributeMsgs = this.session.buildAndDistribute(this.#cohortId);
-        this.emit("data-distributed", { cohortId: this.#cohortId });
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      this.emit("update-received", { cohortId: ctx.cohortId, participantDid: msg.from });
+      if (this.session.getCohortPhase(ctx.cohortId) === "UpdatesCollected" /* UpdatesCollected */) {
+        const distributeMsgs = this.session.buildAndDistribute(ctx.cohortId);
+        this.emit("data-distributed", { cohortId: ctx.cohortId });
         await this.#sendAll(distributeMsgs);
       }
     } catch (err) {
-      this.#fail(err);
+      this.#failCohort(ctx, err);
     }
   }
   /**
@@ -111737,111 +112736,121 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
    * automatically requests tx data and starts signing.
    * @param {BaseMessage} msg - The incoming message to handle.
    * @returns {Promise<void>} Resolves when handling is complete.
-   * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-   * Note: if the runner has been stopped, handlers will ignore incoming messages.
    */
   async #handleValidationAck(msg) {
     if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
     try {
       this.session.receive(msg);
-      this.#drainRejections();
-      this.#onPhaseMaybeChanged();
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
       const approved = !!msg.body?.approved;
-      this.emit("validation-received", { participantDid: msg.from, approved });
-      const phase = this.session.getCohortPhase(this.#cohortId);
+      this.emit("validation-received", { cohortId: ctx.cohortId, participantDid: msg.from, approved });
+      const phase = this.session.getCohortPhase(ctx.cohortId);
       if (phase === "Failed" /* Failed */) {
         const reason = `Validation rejected by participant ${msg.from}`;
-        this.emit("cohort-failed", { cohortId: this.#cohortId, reason });
-        this.#fail(new Error(reason));
+        this.emit("cohort-failed", { cohortId: ctx.cohortId, reason });
+        this.#failCohort(ctx, new Error(reason));
         return;
       }
       if (phase === "Validated" /* Validated */) {
-        const cohort = this.session.getCohort(this.#cohortId);
+        const cohort = this.session.getCohort(ctx.cohortId);
         const txData = await this.#onProvideTxData({
-          cohortId: this.#cohortId,
+          cohortId: ctx.cohortId,
           beaconAddress: cohort.beaconAddress,
           signalBytes: cohort.signalBytes
         });
-        const authMsgs = this.session.startSigning(this.#cohortId, txData);
-        const sessionId = this.session.getSigningSessionId(this.#cohortId) ?? "";
-        this.emit("signing-started", { sessionId });
+        const authMsgs = this.session.startSigning(ctx.cohortId, txData);
+        const sessionId = this.session.getSigningSessionId(ctx.cohortId) ?? "";
+        this.emit("signing-started", { cohortId: ctx.cohortId, sessionId });
         await this.#sendAll(authMsgs);
       }
     } catch (err) {
-      this.#fail(err);
+      this.#failCohort(ctx, err);
     }
   }
   /**
-   * Handler for receiving nonce contributions and signature authorizations. When all nonces or
-   * signatures are received,
+   * Handler for receiving nonce contributions. When all nonces are received, sends the aggregated
+   * nonce back to the cohort.
    * @param {BaseMessage} msg - The incoming message to handle.
    * @returns {Promise<void>} Resolves when handling is complete.
-   * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-   * Note: if the runner has been stopped, handlers will ignore incoming messages.
    */
   async #handleNonceContribution(msg) {
     if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
     try {
       this.session.receive(msg);
-      this.#drainRejections();
-      this.#onPhaseMaybeChanged();
-      this.emit("nonce-received", { participantDid: msg.from });
-      if (this.session.getCohortPhase(this.#cohortId) === "NoncesCollected" /* NoncesCollected */) {
-        await this.#sendAll(this.session.sendAggregatedNonce(this.#cohortId));
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      this.emit("nonce-received", { cohortId: ctx.cohortId, participantDid: msg.from });
+      if (this.session.getCohortPhase(ctx.cohortId) === "NoncesCollected" /* NoncesCollected */) {
+        await this.#sendAll(this.session.sendAggregatedNonce(ctx.cohortId));
       }
     } catch (err) {
-      this.#fail(err);
+      this.#failCohort(ctx, err);
     }
   }
   /**
    * Handler for receiving signature authorizations. When all partial signatures are received, the
-   * session automatically completes and the final result is emitted and the run() promise is resolved.
+   * session automatically completes; the final result is emitted and the cohort's completion
+   * promise resolves.
    * @param {BaseMessage} msg - The incoming message to handle.
    * @returns {Promise<void>} Resolves when handling is complete.
-   * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-   * Note: if the runner has been stopped, handlers will ignore incoming messages.
    */
   async #handleSignatureAuthorization(msg) {
     if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
+    try {
+      this.session.receive(msg);
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      if (ctx.committedPath === "fallback") return;
+      const result = this.session.getResult(ctx.cohortId);
+      if (result) {
+        ctx.committedPath = "optimistic";
+        this.#completeCohort(ctx, result);
+      }
+    } catch (err) {
+      this.#failCohort(ctx, err);
+    }
+  }
+  /**
+   * Handler for receiving fallback (k-of-n script-path) signatures. The state
+   * machine assembles and finalizes the fallback spend once k valid signatures
+   * are in; the result is then emitted and the cohort's completion resolves. The
+   * cohort is already committed to the fallback path (via {@link triggerFallback}).
+   * @param {BaseMessage} msg - The incoming FALLBACK_SIGNATURE message.
+   * @returns {Promise<void>} Resolves when handling is complete.
+   */
+  async #handleFallbackSignature(msg) {
+    if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
     try {
       this.session.receive(msg);
-      this.#drainRejections();
-      this.#onPhaseMaybeChanged();
-      const result = this.session.getResult(this.#cohortId);
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      const result = this.session.getResult(ctx.cohortId);
       if (result) {
-        this.#clearTimers();
-        this.#unregisterHandlers();
-        this.emit("signing-complete", result);
-        this.#resolveRun?.(result);
+        this.#completeCohort(ctx, result);
       }
     } catch (err) {
-      this.#fail(err);
+      this.#failCohort(ctx, err);
     }
   }
   /**
    * Internal: helper to send all messages sequentially. Catches and propagates errors.
    * @param {BaseMessage[]} msgs - The messages to send.
    * @returns {Promise<void>} Resolves when all messages have been sent.
-   * @throws {Error} If sending any message fails, the error is emitted and the run promise is
-   * rejected.
    */
   async #sendAll(msgs) {
     for (const m2 of msgs) {
       await this.#transport.sendMessage(m2, this.#did, m2.to);
     }
   }
-  /**
-   * Internal: helper to handle errors. Emits an 'error' event and rejects the run promise.
-   * @param {Error} err - The error to handle.
-   */
-  #fail(err) {
-    this.#stopAdvertRepeating();
-    this.#clearTimers();
-    this.#unregisterHandlers();
-    if (this.#cohortId) this.session.removeCohort(this.#cohortId);
-    this.emit("error", err);
-    this.#rejectRun?.(err);
-  }
 };
 
 // src/core/aggregation/runner/participant-runner.ts
@@ -111890,7 +112899,8 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
     COHORT_READY,
     DISTRIBUTE_AGGREGATED_DATA,
     AUTHORIZATION_REQUEST,
-    AGGREGATED_NONCE
+    AGGREGATED_NONCE,
+    FALLBACK_AUTHORIZATION_REQUEST
   ];
   /** Internal: detach from the transport. Safe to call repeatedly. */
   #unregisterHandlers() {
@@ -111902,7 +112912,8 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
   }
   /**
    * Single-shot helper: start, join the first cohort that passes `shouldJoin`,
-   * drive it to completion, and resolve. Convenient for tests and demos.
+   * drive it to completion, and resolve. Convenient for tests and demos. The
+   * single-cohort special case of {@link joinMatching} (count = 1).
    */
   static async joinFirst(options2) {
     return new Promise((resolve, reject) => {
@@ -111915,6 +112926,37 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
       runner.start().catch(reject);
     });
   }
+  /**
+   * Multi-cohort helper: start, join EVERY cohort whose advert passes
+   * `shouldJoin`, drive each to completion in parallel, and resolve once
+   * `count` cohorts have completed (the runner stops at that point). The
+   * N-cohort generalization of {@link joinFirst}, for a participant that joins
+   * several cohorts advertised by one service.
+   *
+   * For an open-ended, long-lived subscriber (no fixed count), construct an
+   * {@link AggregationParticipantRunner} directly, set `shouldJoin`, call
+   * `start()`, and listen for `cohort-complete` - the runner already drives
+   * any number of cohorts concurrently.
+   *
+   * @param options Participant runner options (set `shouldJoin` to select cohorts).
+   * @param count Number of completed cohorts to collect before resolving.
+   * @returns The {@link CohortCompleteInfo} for each completed cohort, in completion order.
+   */
+  static async joinMatching(options2, count) {
+    return new Promise((resolve, reject) => {
+      const runner = new _AggregationParticipantRunner(options2);
+      const completed = [];
+      runner.on("cohort-complete", (info) => {
+        completed.push(info);
+        if (completed.length >= count) {
+          runner.stop();
+          resolve(completed);
+        }
+      });
+      runner.on("error", reject);
+      runner.start().catch(reject);
+    });
+  }
   /**
    * Internal: handler registration with the transport. Idempotent and safe to call multiple times,
    * but only registers handlers once.
@@ -111928,6 +112970,7 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
     this.#transport.registerMessageHandler(this.#did, DISTRIBUTE_AGGREGATED_DATA, this.#handleDistributeData.bind(this));
     this.#transport.registerMessageHandler(this.#did, AUTHORIZATION_REQUEST, this.#handleAuthorizationRequest.bind(this));
     this.#transport.registerMessageHandler(this.#did, AGGREGATED_NONCE, this.#handleAggregatedNonce.bind(this));
+    this.#transport.registerMessageHandler(this.#did, FALLBACK_AUTHORIZATION_REQUEST, this.#handleFallbackAuthorizationRequest.bind(this));
   }
   /**
    * Internal: handler for cohort adverts. Applies the `shouldJoin` filter and joins if approved.
@@ -111983,8 +113026,13 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
         cohortId,
         beaconAddress: info.beaconAddress
       });
-      await this.#sendAll(this.session.submitUpdate(cohortId, signedUpdate));
-      this.emit("update-submitted", { cohortId });
+      if (signedUpdate === null) {
+        await this.#sendAll(this.session.declineUpdate(cohortId));
+        this.emit("update-declined", { cohortId });
+      } else {
+        await this.#sendAll(this.session.submitUpdate(cohortId, signedUpdate));
+        this.emit("update-submitted", { cohortId });
+      }
     } catch (err) {
       this.emit("error", err);
     }
@@ -112060,23 +113108,62 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
       const cohortId = msg.body?.cohortId;
       if (!cohortId) return;
       await this.#sendAll(this.session.generatePartialSignature(cohortId));
-      if (this.session.getCohortPhase(cohortId) === "Complete" /* Complete */) {
-        const info = this.session.joinedCohorts.get(cohortId);
-        if (info) {
-          const validation = this.session.pendingValidations.get(cohortId);
-          this.emit("cohort-complete", {
-            cohortId,
-            beaconAddress: info.beaconAddress,
-            beaconType: validation?.beaconType ?? "",
-            casAnnouncement: validation?.casAnnouncement,
-            smtProof: validation?.smtProof
-          });
-        }
+      this.#emitCohortCompleteIfDone(cohortId);
+    } catch (err) {
+      this.emit("error", err);
+    }
+  }
+  /**
+   * Internal: handler for fallback authorization requests. The service abandoned
+   * the optimistic key path; the member authorizes the k-of-n script-path spend
+   * of the same beacon transaction (ADR 042). Reuses `onApproveSigning` to gate
+   * the decision, signs the fallback, and completes once it has contributed (the
+   * service needs only k members).
+   * @param {BaseMessage} msg - The received fallback authorization request message.
+   * @returns {Promise<void>} Resolves when processing is complete.
+   */
+  async #handleFallbackAuthorizationRequest(msg) {
+    if (this.#stopped) return;
+    try {
+      this.session.receive(msg);
+      const cohortId = msg.body?.cohortId;
+      if (!cohortId) return;
+      const req = this.session.pendingFallbackRequests.get(cohortId);
+      if (!req) return;
+      this.emit("fallback-requested", req);
+      const decision = await this.#onApproveSigning(req);
+      if (!decision.approved) {
+        this.emit("cohort-failed", { cohortId, reason: "Fallback signing rejected by participant" });
+        return;
       }
+      await this.#sendAll(this.session.approveFallback(cohortId));
+      this.#emitCohortCompleteIfDone(cohortId);
     } catch (err) {
       this.emit("error", err);
     }
   }
+  /**
+   * Internal: emit `cohort-complete` with the participant's retained sidecar once
+   * the cohort has reached the Complete phase. Surfaces the CAS Announcement map
+   * (CAS beacons) or the SMT proof (SMT beacons) the participant keeps for future
+   * DID resolution. Read via getValidation (not pendingValidations, which lists
+   * only the AwaitingValidation phase) so the sidecar is still available at
+   * Complete. Shared by the optimistic and fallback completion paths.
+   */
+  #emitCohortCompleteIfDone(cohortId) {
+    if (this.session.getCohortPhase(cohortId) !== "Complete" /* Complete */) return;
+    const info = this.session.joinedCohorts.get(cohortId);
+    if (!info) return;
+    const validation = this.session.getValidation(cohortId);
+    this.emit("cohort-complete", {
+      cohortId,
+      beaconAddress: info.beaconAddress,
+      beaconType: validation?.beaconType ?? "",
+      included: validation?.included ?? true,
+      casAnnouncement: validation?.casAnnouncement,
+      smtProof: validation?.smtProof
+    });
+  }
   /**
    * Internal: send helper to ensure messages are sent sequentially. This is important for protocol
    * correctness, as some transports may not guarantee message order if sent in parallel.
@@ -112093,6 +113180,7 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
 
 // src/core/aggregation/runner/aggregation-runner.ts
 init_shim();
+init_utils();
 var AggregationRunner = class {
   /**
    * Run a cohort of ONE participant entirely in-process and return the
@@ -112100,8 +113188,8 @@ var AggregationRunner = class {
    *
    * One party plays both the coordinating service and the lone participant,
    * connected over an {@link InMemoryTransport} (no relay or HTTP server). This
-   * makes the single-participant aggregate-beacon path — the N=1 corner of the
-   * two-axis beacon matrix (see ADR 037) — first-class, useful for generating
+   * makes the single-participant aggregate-beacon path (the N=1 corner of the
+   * two-axis beacon matrix, see ADR 037) first-class, useful for generating
    * and reproducing single-participant aggregate test vectors.
    *
    * The service advertises a cohort with `minParticipants: 1`; the participant
@@ -112119,11 +113207,13 @@ var AggregationRunner = class {
     transport.registerPeer(options2.participant.did, options2.participant.keys.publicKey.compressed);
     transport.registerPeer(options2.service.did, options2.service.keys.publicKey.compressed);
     transport.start();
+    const recoveryKey = options2.config.recoveryKey ?? bytesToHex(options2.service.keys.publicKey.compressed.slice(1));
+    const recoverySequence = options2.config.recoverySequence ?? DEFAULT_RECOVERY_SEQUENCE;
     const service = new AggregationServiceRunner({
       transport,
       did: options2.service.did,
       keys: options2.service.keys,
-      config: { minParticipants: 1, network: options2.config.network, beaconType: options2.config.beaconType },
+      config: { minParticipants: 1, network: options2.config.network, beaconType: options2.config.beaconType, recoveryKey, recoverySequence, fundingModel: DEFAULT_FUNDING_MODEL },
       onProvideTxData: options2.onProvideTxData,
       cohortTtlMs: options2.cohortTtlMs,
       phaseTimeoutMs: options2.phaseTimeoutMs,
@@ -112253,8 +113343,7 @@ async function fetchSpendableUtxo(bitcoinAddress, bitcoin) {
 async function buildAggregationBeaconTx(opts) {
   const feeEstimator = opts.feeEstimator ?? DEFAULT_FEE_ESTIMATOR;
   const { utxo, prevTxBytes } = await fetchSpendableUtxo(opts.beaconAddress, opts.bitcoin);
-  const tapOut = p2tr(opts.internalPubkey, void 0, opts.network);
-  const witnessScript = tapOut.script;
+  const witnessScript = OutScript.encode(Address(opts.network).decode(opts.beaconAddress));
   const feeSats = await feeEstimator.estimateFee(P2TR_BEACON_TX_VSIZE);
   if (BigInt(utxo.value) <= feeSats) {
     throw new BeaconError(
@@ -112333,7 +113422,7 @@ var SinglePartyBeacon = class {
    *
    * Composed from the three extracted phases ({@link buildSinglePartyTx},
    * {@link signSinglePartyTx}, {@link broadcastRawTx}) so each piece can be exercised
-   * in isolation. Aggregation beacons use {@link buildAggregationBeaconTx} instead —
+   * in isolation. Aggregation beacons use {@link buildAggregationBeaconTx} instead:
    * the multi-party path can't share the signing phase, but the tx-construction
    * plumbing (UTXO fetch + OP_RETURN output + change output) is shared.
    *
@@ -112365,7 +113454,7 @@ var SinglePartyBeacon = class {
    *
    * Detects the beacon address script kind (P2PKH / P2WPKH / P2TR) and configures
    * the input accordingly. Validates that the signer's pubkey produces the beacon
-   * address under that script kind — without this check, a misconfigured caller
+   * address under that script kind: without this check, a misconfigured caller
    * would burn a real UTXO on a tx that fails at broadcast. Fees are computed from
    * the per-kind {@link SINGLETON_BEACON_TX_VSIZE} constant, avoiding any probe-sign
    * round-trip.
@@ -128252,7 +129341,7 @@ var Updater = class _Updater {
   #verificationMethod;
   #beaconService;
   /**
-   * @internal — Use {@link DidBtcr2.update} to create instances.
+   * @internal Use {@link DidBtcr2.update} to create instances.
    */
   constructor(params) {
     this.#sourceDocument = params.sourceDocument;
@@ -128289,7 +129378,7 @@ var Updater = class _Updater {
     const targetDocument = JSONPatch.apply(sourceDocument, patches);
     if (targetDocument.id !== sourceDocument.id) {
       throw new UpdateError(
-        `Patches must not change the DID document id (source "${sourceDocument.id}" \u2192 target "${targetDocument.id}").`,
+        `Patches must not change the DID document id (source "${sourceDocument.id}" to target "${targetDocument.id}").`,
         INVALID_DID_UPDATE,
         { sourceId: sourceDocument.id, targetId: targetDocument.id }
       );
@@ -128373,8 +129462,8 @@ var Updater = class _Updater {
   }
   /**
    * Advance the state machine. Returns either:
-   * - `{ status: 'action-required', needs }` — caller must provide data via {@link provide}
-   * - `{ status: 'complete', result }` — update is signed and broadcast
+   * - `{ status: 'action-required', needs }` caller must provide data via {@link provide}
+   * - `{ status: 'complete', result }` update is signed and broadcast
    */
   advance() {
     while (true) {
@@ -128387,7 +129476,7 @@ var Updater = class _Updater {
           continue;
         }
         // Phase: Sign
-        // Emit NeedSigningKey — the caller supplies the secret key (or a KMS signature).
+        // Emit NeedSigningKey: the caller supplies the secret key (or a KMS signature).
         case "Sign": {
           return {
             status: "action-required",
@@ -128570,8 +129659,8 @@ var DidBtcr2 = class {
    *
    * Factory method that validates the update parameters and returns a sans-I/O
    * {@link Updater} state machine. The caller drives the updater through its
-   * phases (Construct → Sign → Broadcast → Complete) by calling `advance()` and
-   * `provide()`. The method package performs **zero I/O** — signing key retrieval
+   * phases (Construct -> Sign -> Broadcast -> Complete) by calling `advance()` and
+   * `provide()`. The method package performs **zero I/O**: signing key retrieval
    * (or KMS delegation) and the on-chain broadcast are the caller's responsibility.
    *
    * For a fully-wired version with Bitcoin broadcast and key handling, see
@@ -128689,7 +129778,7 @@ var Resolver = class _Resolver {
   #unsortedUpdates = [];
   #resolvedResponse = null;
   /**
-   * @internal — Use {@link DidBtcr2.resolve} to create instances.
+   * @internal Use {@link DidBtcr2.resolve} to create instances.
    */
   constructor(didComponents, sidecarData, currentDocument, options2) {
     this.#didComponents = didComponents;
@@ -128925,8 +130014,8 @@ var Resolver = class _Resolver {
   }
   /**
    * Advance the state machine. Returns either:
-   * - `{ status: 'action-required', needs }` — caller must provide data via {@link provide}
-   * - `{ status: 'resolved', result }` — resolution complete
+   * - `{ status: 'action-required', needs }` - caller must provide data via {@link provide}
+   * - `{ status: 'resolved', result }` - resolution complete
    *
    * Analogous to Rust's `Resolver::resolve()`.
    */
@@ -129166,9 +130255,11 @@ export {
   DEFAULT_ADVERT_REPEAT_INTERVAL_MS,
   DEFAULT_BROADCAST_LOOKBACK_MS,
   DEFAULT_CLOCK_SKEW_SEC,
+  DEFAULT_FUNDING_MODEL,
   DEFAULT_MAX_UPDATE_SIZE_BYTES,
   DEFAULT_NONCE_LEN_BYTES,
   DEFAULT_NOSTR_RELAYS,
+  DEFAULT_RECOVERY_SEQUENCE,
   DID_REGEX,
   DISTRIBUTE_AGGREGATED_DATA,
   DidBtcr2,
@@ -129177,6 +130268,8 @@ export {
   DidDocumentBuilder,
   DidVerificationMethod,
   Document,
+  FALLBACK_AUTHORIZATION_REQUEST,
+  FALLBACK_SIGNATURE,
   GenesisDocument,
   HTTP_ENVELOPE_VERSION,
   HTTP_ROUTE,
@@ -129190,7 +130283,9 @@ export {
   InMemoryTransport,
   InboxBuffer,
   KNOWN_BEACON_TYPES,
+  KNOWN_FUNDING_MODELS,
   KeyPairAggregationSigner,
+  MAX_RECOVERY_SEQUENCE,
   NONCE_CONTRIBUTION,
   NonceCache,
   NostrTransport,
@@ -129207,6 +130302,7 @@ export {
   SMTBeacon,
   SMTBeaconError,
   SSE_EVENT,
+  SUBMIT_NONINCLUDED,
   SUBMIT_UPDATE,
   ServiceCohortPhase,
   SigningSessionError,
@@ -129215,6 +130311,7 @@ export {
   SingletonBeacon,
   SingletonBeaconError,
   StaticFeeEstimator,
+  TAPROOT_LEAF_VERSION,
   TransportAdapterError,
   TransportError,
   TransportFactory,
@@ -129222,6 +130319,11 @@ export {
   Updater,
   VALIDATION_ACK,
   buildAggregationBeaconTx,
+  buildFallbackLeaf,
+  buildFallbackSpend,
+  buildRecoveryLeaves,
+  buildRecoveryScript,
+  buildRecoverySpend,
   buildRequestAuth,
   createAggregatedNonceMessage,
   createAuthorizationRequestMessage,
@@ -129230,13 +130332,17 @@ export {
   createCohortOptInMessage,
   createCohortReadyMessage,
   createDistributeAggregatedDataMessage,
+  createFallbackAuthorizationRequestMessage,
+  createFallbackSignatureMessage,
   createNonceContributionMessage,
   createSignatureAuthorizationMessage,
+  createSubmitNonIncludedMessage,
   createSubmitUpdateMessage,
   createValidationAckMessage,
   defaultReconnectBackoff,
   deriveSingletonAddress,
   detectSingletonScriptKind,
+  fallbackSighash,
   formatSseComment,
   formatSseEvent,
   getBeaconStrategy,
@@ -129248,10 +130354,13 @@ export {
   isCohortOptInMessage,
   isCohortReadyMessage,
   isDistributeAggregatedDataMessage,
+  isFallbackAuthorizationRequestMessage,
+  isFallbackSignatureMessage,
   isKeygenMessageType,
   isNonceContributionMessage,
   isSignMessageType,
   isSignatureAuthorizationMessage,
+  isSubmitNonIncludedMessage,
   isSubmitUpdateMessage,
   isUpdateMessageType,
   isValidationAckMessage,
@@ -129260,8 +130369,10 @@ export {
   parseRequestAuth,
   parseSseStream,
   registerBeaconStrategy,
+  resolveFallbackThreshold,
   reviveFromWire,
   signEnvelope,
+  tapLeafHash2 as tapLeafHash,
   validateCohortConditions,
   verifyEnvelope,
   verifyRequestAuth