@serfab/cadre-core 0.9.0 → 0.10.0

package/src/strand-solicitation.ts

@@ -3,12 +3,16 @@ import { toString as uint8ArrayToString } from 'uint8arrays';
 import { generateKeyPair, privateKeyToProtobuf } from '@libp2p/crypto/keys';
 import { peerIdFromPrivateKey } from '@libp2p/peer-id';
 import type { Libp2p } from '@libp2p/interface';
+import { sign } from '@optimystic/quereus-plugin-crypto';
 import type {
   OpenInvitation,
   FormStrandResult,
-  ValidateFormationResult,
   StrandFormationDisclosure
 } from './types.js';
+// control-database does not import this service, so these imports introduce no cycle.
+import { generateStampId, formationConsentMessage } from './control-database.js';
+import { canonicalJson } from './canonical-json.js';
+import { ed25519KeyPairFromLibp2p } from './ed25519-key.js';
 import {
   StrandFormationManager,
   type StrandFormationManagerConfig
@@ -47,6 +51,10 @@ export interface DisclosureValidator {
  *
  * Replaces the older `{ strandId, memberPrivateKey } | null` shape, which conflated `bound`
  * and `missing` (both produced a non-null result whenever the invite had a `StrandId`).
+ *
+ * The invite's `ValidationUrl` (the outside approval hook) is deliberately NOT surfaced here:
+ * the recorder that performs the write reads it itself, so the choice of which hook to trust
+ * never travels through a caller.
  */
 export type ResolvedHostStrand =
   | { kind: 'unbound' }
@@ -60,7 +68,20 @@ export interface FormationUsageRecorder {
   /**
    * Record that a formation invite was used
    */
-  recordUsage(token: string, initiatorKey: string, strandId: string): Promise<void>;
+  recordUsage(params: {
+    token: string;
+    /** The joining peer's own ed25519 public key — written to `FormationUsage.PeerKey` and inside BOTH signed digests. */
+    peerKey: string;
+    /** The joiner's signature over the `'consent'` digest — written to `FormationUsage.PeerSig`. */
+    peerSignature: string;
+    /** Joiner-minted single-use nonce; both signed digests cover it. */
+    usageStampId: string;
+    strandId: string;
+    /** Exact text to write to `FormationUsage.Disclosure`; joiner and approver both sign these bytes. */
+    disclosure: string;
+    /** Aborted when the caller has given up; observed BEFORE any write so the invite stays unspent. */
+    signal?: AbortSignal;
+  }): Promise<void>;
 
   /**
    * Check if a token has already been used (for single-use invites)
@@ -86,14 +107,32 @@ export interface FormationUsageRecorder {
    * ATOMICALLY (single `FormationUsage` row → single-use enforced on the next redemption).
    * Optional: a recorder that only supports provision-then-record omits it, and the
    * manager falls back to its {@link StrandProvisioner}. Mirrors the create-strand-by-consent
-   * path the schema's `Strand.Authorized` `FormationUsage` branch authorizes. Returns the
+   * path the schema's `Strand.AuthorizedInsert` `FormationUsage` branch authorizes. Returns the
    * minted strand id plus its membership key (null for an open responder-provisioned strand).
    */
-  provisionAndRecord?(
-    token: string,
-    initiatorKey: string,
-    sAppId: string
-  ): Promise<{ strandId: string; memberPrivateKey: string | null }>;
+  provisionAndRecord?(params: {
+    token: string;
+    /** The joining peer's own ed25519 public key — written to `FormationUsage.PeerKey` and inside BOTH signed digests. */
+    peerKey: string;
+    /** The joiner's signature over the `'consent'` digest — written to `FormationUsage.PeerSig`. */
+    peerSignature: string;
+    /** Joiner-minted single-use nonce; both signed digests cover it. */
+    usageStampId: string;
+    sAppId: string;
+    /** Exact text to write to `FormationUsage.Disclosure`; joiner and approver both sign these bytes. */
+    disclosure: string;
+    /** Aborted when the caller has given up; observed BEFORE any write so the invite stays unspent. */
+    signal?: AbortSignal;
+  }): Promise<{ strandId: string; memberPrivateKey: string | null }>;
+
+  /**
+   * Is ANY invitation this recorder knows about unexpired and not fully
+   * consumed? Optional: a recorder that cannot enumerate invitations omits it,
+   * and only locally-minted invitations hold the connection gate's formation
+   * exemption open. Distinct from the per-token {@link isTokenValid} /
+   * {@link isTokenUsed} pair — the connection gate has no token to ask about.
+   */
+  hasOutstandingInvitation?(): Promise<boolean>;
 }
 
 /**
@@ -110,19 +149,6 @@ export interface StrandProvisioner {
   ): Promise<{ strandId: string }>;
 }
 
-/**
- * Interface for signing formation approvals
- */
-export interface FormationSigner {
-  /**
-   * Sign a formation approval
-   */
-  signFormation(token: string, disclosure: StrandFormationDisclosure): Promise<{
-    validationKey: string;
-    validationSignature: string;
-  }>;
-}
-
 /**
  * Interface for validating the responder's formation result on the initiator side.
  *
@@ -161,7 +187,6 @@ export interface StrandSolicitationServiceOptions {
   disclosureValidator?: DisclosureValidator;
   formationUsageRecorder?: FormationUsageRecorder;
   strandProvisioner?: StrandProvisioner;
-  formationSigner?: FormationSigner;
   /** Validates the responder's result on the initiator side (defaults to a structural check) */
   formationResponseValidator?: FormationResponseValidator;
   /** Party ID for this node (used in protocol messages) */
@@ -177,7 +202,10 @@ export interface StrandSolicitationServiceOptions {
  *
  * This service handles the high-level API defined in api.md:
  * - formStrand(invitation, disclosure, node) - called by initiator
- * - validateStrandFormation(token, disclosure) - called by responder
+ *
+ * Outside approval of a redemption (an invite's `ValidationUrl`) is NOT here: it belongs to
+ * the redeeming node, which alone mints the nonce the approval is bound to. See
+ * `formation-approval.ts`.
  *
  * When a libp2p node is provided, the underlying protocol is handled by the
  * native cadre-core formation transport via StrandFormationManager.
@@ -186,18 +214,28 @@ export class StrandSolicitationService {
   private readonly disclosureValidator?: DisclosureValidator;
   private readonly formationUsageRecorder?: FormationUsageRecorder;
   private readonly strandProvisioner?: StrandProvisioner;
-  private readonly formationSigner?: FormationSigner;
   private readonly formationResponseValidator?: FormationResponseValidator;
   private readonly partyId: string;
   private readonly cadrePeerAddrs: string[];
   private formationManager?: StrandFormationManager;
   private readonly formationConfig?: StrandFormationManagerConfig;
+  /**
+   * Tokens this process has minted (or published), mapped to their expiry
+   * epoch-ms — the in-memory half of {@link hasOutstandingInvitation}. Dies with
+   * the process, exactly like `CadreNode`'s enrollment window; a token that also
+   * reached the durable `FormationInvite` table survives via the recorder.
+   *
+   * NOTE: pruned only while {@link hasOutstandingInvitation} runs, so a node that
+   * mints steadily and never receives an inbound stranger retains every entry for
+   * the process's life. Bounded by mint rate today; if a host ever mints at scale,
+   * prune on a timer (or cap the map) instead of only on read.
+   */
+  private readonly mintedInvitations = new Map<string, number>();
 
   constructor(options?: StrandSolicitationServiceOptions) {
     this.disclosureValidator = options?.disclosureValidator;
     this.formationUsageRecorder = options?.formationUsageRecorder;
     this.strandProvisioner = options?.strandProvisioner;
-    this.formationSigner = options?.formationSigner;
     this.formationResponseValidator = options?.formationResponseValidator;
     this.partyId = options?.partyId ?? `party-${Date.now()}`;
     this.cadrePeerAddrs = options?.cadrePeerAddrs ?? [];
@@ -275,9 +313,29 @@ export class StrandSolicitationService {
     // If we have a full invitation and a node, use the real protocol
     if (typeof invitation !== 'string' && node) {
       log('Using native cadre-core formation transport');
+      const { privateKeyB64, publicKeyB64 } = ed25519KeyPairFromLibp2p(privateKey);
+      const usageStampId = generateStampId(memberKey);
+      // Built ONCE, AFTER the partyId override: this exact object travels to the
+      // responder, and its canonical serialization is the disclosure text the consent
+      // signature covers and the responder writes to `FormationUsage.Disclosure`.
+      const fullDisclosure = { ...disclosure, partyId: memberKey };
+      const peerSignature = sign(
+        formationConsentMessage({
+          token,
+          usageStampId,
+          peerKey: publicKeyB64,
+          disclosure: canonicalJson(fullDisclosure)
+        }),
+        privateKeyB64,
+        'ed25519',
+        'bytes',
+        'base64url',
+        'base64url'
+      ) as string;
       const result = await this.getFormationManager().formStrand(
         invitation,
-        { ...disclosure, partyId: memberKey },
+        fullDisclosure,
+        { peerKey: publicKeyB64, usageStampId, peerSignature },
         node
       );
       return {
@@ -301,67 +359,6 @@ export class StrandSolicitationService {
     };
   }
 
-  /**
-   * Validate a strand formation request.
-   *
-   * Called by the responder (the party who created the open invitation) when
-   * an initiator contacts them to form a strand. Validates the disclosure
-   * and returns a signed approval.
-   *
-   * @param token The invitation token being used
-   * @param disclosure The disclosure from the initiator
-   * @returns Validation key and signature if approved
-   * @throws If validation fails or token is invalid
-   */
-  async validateStrandFormation(
-    token: string,
-    disclosure: StrandFormationDisclosure
-  ): Promise<ValidateFormationResult> {
-    log('Validating strand formation for token: %s', token);
-
-    // Check token validity
-    if (this.formationUsageRecorder) {
-      const tokenCheck = await this.formationUsageRecorder.isTokenValid(token);
-      if (!tokenCheck.valid) {
-        log('Token invalid or expired: %s', token);
-        throw new Error('Invalid or expired token');
-      }
-
-      // Check if already used (for single-use tokens)
-      const isUsed = await this.formationUsageRecorder.isTokenUsed(token);
-      if (isUsed) {
-        log('Token already used: %s', token);
-        throw new Error('Token has already been used');
-      }
-    }
-
-    // Validate the disclosure
-    if (this.disclosureValidator) {
-      const isValid = await this.disclosureValidator.validateDisclosure(token, disclosure);
-      if (!isValid) {
-        log('Disclosure validation failed for token: %s', token);
-        throw new Error('Disclosure validation failed');
-      }
-    }
-
-    // Sign the formation approval
-    if (!this.formationSigner) {
-      throw new Error('FormationSigner not configured');
-    }
-
-    const { validationKey, validationSignature } = await this.formationSigner.signFormation(
-      token,
-      disclosure
-    );
-
-    log('Formation validated, key: %s', validationKey);
-
-    return {
-      validationKey,
-      validationSignature
-    };
-  }
-
   /**
    * Create an open invitation for others to form strands with this party.
    *
@@ -378,6 +375,7 @@ export class StrandSolicitationService {
     // Generate a unique token
     const token = `invite-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
     const expiration = new Date(Date.now() + expirationMs);
+    this.registerMintedInvitation(token, expiration.getTime());
 
     log('Created open invitation: %s (expires %s)', token, expiration.toISOString());
 
@@ -389,17 +387,84 @@ export class StrandSolicitationService {
     };
   }
 
+  /**
+   * Remember a token this node minted (or published) so
+   * {@link hasOutstandingInvitation} can answer "yes" before the durable
+   * `FormationInvite` row is readable — or when there is no durable store at
+   * all. `expiresAtMs` may be `Number.POSITIVE_INFINITY` for an invitation that
+   * never expires.
+   */
+  registerMintedInvitation(token: string, expiresAtMs: number): void {
+    this.mintedInvitations.set(token, expiresAtMs);
+    log('Registered minted invitation %s (expires %d)', token, expiresAtMs);
+  }
+
+  /**
+   * Does this node currently expect a stranger — i.e. is at least one open
+   * invitation unexpired and not yet fully consumed? Sole input to the
+   * control-network connection gate's formation exemption.
+   *
+   * Two sources, in order:
+   *
+   *  1. The local mint registry ({@link registerMintedInvitation}), which is
+   *     in-memory and dies with the process. Expired entries are dropped. With
+   *     no {@link FormationUsageRecorder} configured there is no consumption
+   *     oracle, so an unexpired minted token counts as outstanding by
+   *     construction; with one, a token it reports used is deleted (consumption
+   *     is permanent, so the registry never reconsiders it).
+   *  2. The recorder's optional {@link FormationUsageRecorder.hasOutstandingInvitation},
+   *     which survives restarts and sees invitations replicated in from siblings.
+   *
+   * Re-entrant: concurrent inbound connections each call this independently and
+   * the only mutation is deleting expired/consumed entries, which is monotonic.
+   */
+  async hasOutstandingInvitation(): Promise<boolean> {
+    const now = Date.now();
+    for (const [token, expiresAtMs] of this.mintedInvitations) {
+      if (expiresAtMs <= now) {
+        this.mintedInvitations.delete(token);
+        continue;
+      }
+      if (!this.formationUsageRecorder) {
+        return true;
+      }
+      if (!(await this.formationUsageRecorder.isTokenUsed(token))) {
+        return true;
+      }
+      this.mintedInvitations.delete(token);
+    }
+    return (await this.formationUsageRecorder?.hasOutstandingInvitation?.()) ?? false;
+  }
+
   /**
    * Record that a formation was completed successfully.
    * Called after strand provisioning to track usage.
+   *
+   * `consent` carries the joiner-signed fields `recordUsage` now requires
+   * (see {@link FormationUsageRecorder.recordUsage}); this helper only passes them through.
+   *
+   * NOTE: this reaches `recordUsage` without passing through
+   * `StrandFormationManager.provisionAsResponder`, so `disclosure` skips that path's
+   * `MAX_DISCLOSURE_BYTES` cap. Harmless today — its only callers are integration-test mocks
+   * that all default to `''` — but if a production caller ever passes a real disclosure here,
+   * cap it too (the approver signs those bytes verbatim).
    */
   async recordFormationComplete(
     token: string,
-    initiatorKey: string,
-    strandId: string
+    peerKey: string,
+    strandId: string,
+    consent: { usageStampId: string; peerSignature: string },
+    disclosure = ''
   ): Promise<void> {
     if (this.formationUsageRecorder) {
-      await this.formationUsageRecorder.recordUsage(token, initiatorKey, strandId);
+      await this.formationUsageRecorder.recordUsage({
+        token,
+        peerKey,
+        peerSignature: consent.peerSignature,
+        usageStampId: consent.usageStampId,
+        strandId,
+        disclosure
+      });
       log('Recorded formation usage: token=%s strand=%s', token, strandId);
     }
   }

package/src/strand-transport-key.ts

@@ -0,0 +1,58 @@
+import { generateKeyPairFromSeed } from '@libp2p/crypto/keys';
+import type { PrivateKey } from '@libp2p/interface';
+import { digest } from '@optimystic/quereus-plugin-crypto';
+import { ed25519KeyPairFromLibp2p } from './ed25519-key.js';
+
+/**
+ * Domain-separation tag for the strand-transport-key derivation. Versioned so a
+ * future change to the derivation (different KDF, different inputs) can bump to
+ * `.v2` and be recognized as a deliberate identity migration rather than silent
+ * peerId churn — a strand node's transport peerId must stay stable across
+ * process restarts, or any peer-store entry or `MemberPeer` row that names it
+ * goes stale on every boot.
+ */
+const STRAND_TRANSPORT_KEY_DOMAIN = 'sereus.strand-transport-key.v1';
+
+/**
+ * Derive a strand node's libp2p transport key from the cadre identity key and
+ * the strand id.
+ *
+ * A `CadreNode` runs its control node and each strand node as separate libp2p
+ * instances. Handing them all the same private key gives them all the same
+ * peerId, and `@libp2p/circuit-relay-v2` keys reservations and hop-connects by
+ * peerId — so a control node and a strand node reserving through one shared
+ * relay collide, and relayed streams for one land on the other
+ * (https://github.com/gotchoices/sereus/issues/1). Each strand node therefore
+ * gets its own transport identity. Cadre *authority* is untouched: the control
+ * node keeps the identity key, and every peerId→authority derivation
+ * (`ed25519PublicKeyB64FromPeerId`) is a control-network path.
+ *
+ * The derivation is deterministic — `sha256(domain, identity seed, strandId)`
+ * as an Ed25519 seed — rather than a fresh random key per launch, so the
+ * strand's transport peerId survives restarts. The identity *private* seed is
+ * an input (not the public key) so that no third party can enumerate a member's
+ * strand peerIds from public data; only the key holder can compute them.
+ *
+ * NOTE: the derived peerId *is* attested at runtime: before a strand node
+ * starts, its control node announces it over the strand-addr RPC, and a
+ * membership-gated relay (a party control node running the relay server) holds
+ * a short-lived delegate admission grant for it (`delegate-admission.ts`) —
+ * without that grant the relay denies the strand node's reservation and
+ * `libp2p.start()` fails. The strand *mesh* itself still does not gate
+ * admission by peerId (strand peers are legitimately cross-party); if
+ * strand-mesh admission control is ever added, the durable binding it needs is
+ * a `MemberPeer(MemberKey, PeerId)` row: the table and its self-signed
+ * `Authorized` constraint already exist in `schemas/strand.qsql`; production
+ * code simply never writes one.
+ *
+ * @param identityKey - The cadre's Ed25519 identity key (the control node's key).
+ * @param strandId - The strand whose transport key to derive.
+ * @returns A stable, per-strand Ed25519 libp2p private key, distinct from the
+ *   identity key and from every other strand's.
+ * @throws If the identity key is not Ed25519.
+ */
+export async function strandTransportKey(identityKey: PrivateKey, strandId: string): Promise<PrivateKey> {
+  const { privateKeyB64 } = ed25519KeyPairFromLibp2p(identityKey);
+  const seed = digest([STRAND_TRANSPORT_KEY_DOMAIN, privateKeyB64, strandId], 'sha256', 'bytes') as Uint8Array;
+  return generateKeyPairFromSeed('Ed25519', seed);
+}

package/src/strand-wake-protocol.ts

@@ -14,13 +14,15 @@
  * stream (like seed delivery), so each side reads to EOF (under a read timeout)
  * and decodes one frame via the shared {@link decodeLengthPrefixedFrame} guard.
  *
- * **Authorization (v1):** the control network already restricts membership —
- * only this party's cadre peers connect (schema-gated `CadrePeer`). A wake is
- * low-risk: it only causes the receiver to spend resources coming online for a
- * strand it already participates in. So the receiver verifies the remote peer is
- * a `CadrePeer` member (via the injected `isMember` gate) and requires no
- * signature beyond control-network membership. A richer per-request signature is
- * deliberately out of scope for v1.
+ * **Authorization (v1):** a wake is low-risk — it only causes the receiver to
+ * spend resources coming online for a strand it already participates in — so the
+ * receiver carries no per-request signature and instead defers entirely to the
+ * injected `isMember` predicate. `CadreNode` injects its AUTHORIZED-membership
+ * predicate there (`isAuthorizedMember`: the sender's `CadrePeer` row must carry
+ * a voucher that verifies against an owner key in the receiver's node-local
+ * trusted-owner anchor), so a peer that merely published rows into the replicated
+ * control DB is refused. This module stays agnostic: it enforces whatever
+ * predicate it is given.
  */
 
 import debug from 'debug';
@@ -28,7 +30,7 @@ import type { Libp2p, Connection } from '@libp2p/interface';
 import type { Multiaddr } from '@multiformats/multiaddr';
 import type { StrandInstance, WakeRequest, WakeAck } from './types.js';
 import { decodeLengthPrefixedFrame } from './seed-bootstrap.js';
-import { type ControlStream, writeFrame, withTimeout, readStreamToEnd } from './control-stream.js';
+import { type ControlStream, writeFrame, withDeadline, exchangeFrame, readStreamToEnd } from './control-stream.js';
 
 const log = debug('sereus:cadre:strand-wake');
 
@@ -205,8 +207,8 @@ export class StrandWakeService {
    * - Already-live strand → no-op, `accepted` with current status.
    */
   async processWakeRequest(request: WakeRequest, remotePeerId: string): Promise<WakeAck> {
-    // Control-network membership is the v1 authorization: only this party's
-    // cadre peers may ask us to wake.
+    // The injected membership predicate is the whole v1 authorization (CadreNode
+    // supplies the voucher-anchored one); only a peer it admits may ask us to wake.
     if (!(await this.options.isMember(remotePeerId))) {
       log('Rejecting wake from non-member %s', remotePeerId);
       return { accepted: false, reason: 'Sender is not a cadre member' };
@@ -260,16 +262,13 @@ export async function dialWake(
 
   let lastError: Error | null = null;
   for (const addr of addrs) {
-    // One controller per attempt: on timeout, `withTimeout`'s `onTimeout` aborts
-    // it, which aborts the in-flight dialProtocol (via the dial `signal`) and the
-    // live stream — so neither the connect nor the unbounded ack-read leaks.
-    const controller = new AbortController();
     try {
-      return await withTimeout(
+      // One deadline per attempt: its signal aborts the in-flight dialProtocol and
+      // resets the live stream, so neither the connect nor the ack-read leaks.
+      return await withDeadline(
         timeoutMs,
         `Wake dial ${addr.toString()}`,
-        () => sendWake(node, addr, protocolId, request, timeoutMs, controller.signal),
-        () => controller.abort(),
+        (signal) => sendWake(node, addr, protocolId, request, timeoutMs, signal),
       );
     } catch (err) {
       lastError = err instanceof Error ? err : new Error(String(err));
@@ -282,12 +281,10 @@ export async function dialWake(
 /**
  * Open one stream, send the request, half-close, and read the ack.
  *
- * `signal` is the per-attempt abort signal from {@link dialWake}: it is passed to
- * `dialProtocol` so a timeout during connect aborts the dial, and once the stream
- * is open an abort listener resets the live stream — releasing the otherwise
- * unbounded ack-read. `readFrame` still applies `timeoutMs` as a backstop for the
- * case where an abort does not propagate (e.g. a stream double whose `abort()` is
- * a no-op).
+ * `signal` is the per-attempt deadline from {@link dialWake}: it goes to
+ * `dialProtocol` so a timeout during connect aborts the dial, and into
+ * {@link exchangeFrame} so a timeout after the stream is open resets it —
+ * releasing the otherwise unbounded ack-read.
  */
 async function sendWake(
   node: Libp2p,
@@ -303,29 +300,15 @@ async function sendWake(
   // relay's data/duration cap, so opening it on the limited connection is safe
   // and is the whole point of dialing the relay address.
   const rawStream = await node.dialProtocol(addr, protocolId, { runOnLimitedConnection: true, signal });
-  const stream = rawStream as unknown as ControlStream;
 
-  const abortErr = new Error('Wake dial aborted by timeout');
-  const onAbort = (): void => stream.abort(abortErr);
-  // If the timeout already fired during connect, release the freshly-opened stream now.
-  if (signal.aborted) {
-    onAbort();
-    throw abortErr;
-  }
-  signal.addEventListener('abort', onAbort, { once: true });
+  const ack = await exchangeFrame(
+    rawStream as unknown as ControlStream,
+    signal,
+    request,
+    (stream) => readFrame<WakeAck>(stream, timeoutMs),
+    'Wake dial aborted by timeout',
+  );
 
-  try {
-    writeFrame(stream, request);
-    // close() half-closes the write end (EOF) while the read end stays open for
-    // the ack — the same libp2p 3.x pattern as seed delivery.
-    await stream.close();
-    const ack = await readFrame<WakeAck>(stream, timeoutMs);
-    log('Wake ack from %s: accepted=%s status=%s', addr.toString(), ack.accepted, ack.status ?? '-');
-    return ack;
-  } catch (err) {
-    stream.abort(err instanceof Error ? err : new Error(String(err)));
-    throw err;
-  } finally {
-    signal.removeEventListener('abort', onAbort);
-  }
+  log('Wake ack from %s: accepted=%s status=%s', addr.toString(), ack.accepted, ack.status ?? '-');
+  return ack;
 }

package/src/strand-watcher.ts

@@ -11,6 +11,22 @@ const log = debug('sereus:cadre:strand-watcher');
  */
 type FilterDecision = 'pass' | 'reject' | 'defer';
 
+/**
+ * Ceiling on the retry delay for a strand whose launch keeps failing. Attempts
+ * are never abandoned — the failure this backoff exists for (a transient network
+ * or storage fault) can last a long time — but a permanently-unlaunchable strand
+ * must not re-attempt on every poll and storm the host app with `strand:error`.
+ */
+const MAX_RETRY_BACKOFF_MS = 5 * 60 * 1000;
+
+/** Per-strand consecutive-failure state driving the launch retry backoff. */
+interface StrandFailureState {
+  /** Consecutive `onStrandAdded` failures since the last success. */
+  failures: number;
+  /** Earliest wall-clock time (ms) at which the next attempt may run. */
+  nextAttemptAt: number;
+}
+
 /**
  * Extended strand row that includes the sAppId for filtering purposes.
  * The sAppId is provided by the hosting application, not from the control network.
@@ -55,10 +71,20 @@ export class StrandWatcher {
   private readonly callbacks: StrandWatcherCallbacks;
   private readonly queryable: StrandQueryable;
   private readonly sAppIdLookup?: SAppIdLookup;
+  /**
+   * Wall-clock source for the retry backoff. Read fresh at each use rather than
+   * snapshotted per poll: a poll awaits `onStrandAdded`, and a launch that fails
+   * slowly (e.g. a dial timeout) would otherwise be scheduled off the clock as it
+   * read *before* the attempt, putting `nextAttemptAt` in the past. Injectable so
+   * tests can advance time deterministically without fake timers.
+   */
+  private readonly now: () => number;
 
   private knownStrands: Map<string, StrandRow> = new Map();
   /** Ids admitted under a `defer` decision; re-evaluated each poll until they resolve. */
   private provisional: Set<string> = new Set();
+  /** Ids whose last launch attempt threw, with the backoff gating their retry. */
+  private failureStates: Map<string, StrandFailureState> = new Map();
   private pollTimer: ReturnType<typeof setInterval> | null = null;
   private initialPollTimer: ReturnType<typeof setTimeout> | null = null;
   private running = false;
@@ -68,13 +94,15 @@ export class StrandWatcher {
     callbacks: StrandWatcherCallbacks,
     filter: StrandFilter = { mode: 'all' },
     pollInterval: number = 5000,
-    sAppIdLookup?: SAppIdLookup
+    sAppIdLookup?: SAppIdLookup,
+    now: () => number = Date.now
   ) {
     this.queryable = queryable;
     this.callbacks = callbacks;
     this.filter = filter;
     this.pollInterval = pollInterval;
     this.sAppIdLookup = sAppIdLookup;
+    this.now = now;
     log('StrandWatcher created with filter: %o, interval: %dms', filter, pollInterval);
   }
 
@@ -113,7 +141,18 @@ export class StrandWatcher {
   }
 
   /**
-   * Poll for strand changes
+   * Record a failed launch attempt and schedule when the strand may be retried:
+   * `pollInterval * 2^(failures-1)`, capped at {@link MAX_RETRY_BACKOFF_MS}.
+   */
+  private recordFailure(strandId: string): void {
+    const failures = (this.failureStates.get(strandId)?.failures ?? 0) + 1;
+    const delay = Math.min(this.pollInterval * 2 ** (failures - 1), MAX_RETRY_BACKOFF_MS);
+    this.failureStates.set(strandId, { failures, nextAttemptAt: this.now() + delay });
+    log('Strand %s launch failed (%d consecutive) - next attempt in %dms', strandId, failures, delay);
+  }
+
+  /**
+   * Poll for strand changes.
    */
   private async poll(): Promise<void> {
     if (!this.running) return;
@@ -125,9 +164,15 @@ export class StrandWatcher {
       // Find added strands
       for (const strand of currentStrands) {
         if (this.knownStrands.has(strand.Id)) continue;
+        const failure = this.failureStates.get(strand.Id);
+        // Clock read per candidate, not once per poll: an earlier strand's launch
+        // may have taken a long time, and this one's gate must reflect that.
+        if (failure && this.now() < failure.nextAttemptAt) continue; // backing off after a failed launch
         const decision = this.evaluateFilter(strand);
         if (decision === 'reject') continue;
         log('Strand added: %s', strand.Id);
+        // Set BEFORE the await: this doubles as the in-flight guard that stops the
+        // interval timer from starting a second concurrent launch for the same strand.
         this.knownStrands.set(strand.Id, strand);
         if (decision === 'defer') {
           // Provisional admission: sAppId unknown, re-check on later polls.
@@ -135,8 +180,15 @@ export class StrandWatcher {
         }
         try {
           await this.callbacks.onStrandAdded(strand);
+          this.failureStates.delete(strand.Id);
         } catch (error) {
           log('Error handling strand add for %s: %o', strand.Id, error);
+          // A failed launch leaves nothing running (StrandInstanceManager drops the
+          // record), so forget the strand and let a later poll retry it — gated by
+          // the backoff recorded here.
+          this.knownStrands.delete(strand.Id);
+          this.provisional.delete(strand.Id);
+          this.recordFailure(strand.Id);
         }
       }
 
@@ -163,7 +215,9 @@ export class StrandWatcher {
         // decision === 'defer': still unknown, leave provisional for next poll.
       }
 
-      // Find removed strands
+      // Find removed strands. A strand whose launch failed is no longer in
+      // knownStrands, so it correctly never fires onStrandRemoved — nothing was
+      // ever started for it.
       for (const [strandId] of this.knownStrands) {
         if (!currentMap.has(strandId)) {
           log('Strand removed: %s', strandId);
@@ -176,6 +230,14 @@ export class StrandWatcher {
           }
         }
       }
+
+      // Drop backoff state for strands whose control-network row is gone; a row
+      // that reappears is a fresh strand and gets a fresh first attempt.
+      for (const strandId of [...this.failureStates.keys()]) {
+        if (!currentMap.has(strandId)) {
+          this.failureStates.delete(strandId);
+        }
+      }
     } catch (error) {
       log('Error polling strands: %o', error);
     }
@@ -231,6 +293,7 @@ export class StrandWatcher {
 
     this.knownStrands.clear();
     this.provisional.clear();
+    this.failureStates.clear();
     log('StrandWatcher stopped');
   }