@serfab/cadre-core 1.17.0 → 1.19.0

package/src/strand-solicitation.ts

@@ -24,6 +24,7 @@ import {
   isValidResponderCreatesResult,
   type FormationResultMessage
 } from './strand-formation-protocol.js';
+import { classifyTokenRead, type FormationTokenRead } from './formation-token.js';
 
 const log = debug('sereus:cadre:solicitation');
 
@@ -40,6 +41,25 @@ export interface DisclosureValidator {
   validateDisclosure(token: string, disclosure: StrandFormationDisclosure): Promise<boolean>;
 }
 
+/**
+ * A bound invite's host strand as {@link FormationUsageRecorder.resolveStrand} read it, once
+ * per session: the membership invitation is issued from it and the consent row recorded
+ * against it without reading the `Strand` row again.
+ */
+export interface BoundHostStrand {
+  strandId: string;
+  /** `'c'` closed: the joiner gets a membership invitation; `'o'` open: nothing to invite into. */
+  strandType: 'o' | 'c';
+  /**
+   * The row's one-off `StampId`, which the consent row names (`FormationUsage.StrandStampId`).
+   * Fixed for the life of the row; a row removed and re-seated in between gets a new one, and
+   * the `StrandExists` CHECK then refuses the consent row.
+   */
+  strandStampId: string;
+  /** The closed-strand read-gating secret; null for an open strand. */
+  memberPrivateKey: string | null;
+}
+
 /**
  * Discriminated result of resolving the host strand an invite binds to (responder side):
  *
@@ -52,16 +72,13 @@ export interface DisclosureValidator {
  *   non-existent strand, which would fail the deferred `FormationUsage.StrandExists` CHECK at
  *   commit and drop the result frame.
  *
- * 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.
+ * the recorder that performs the write takes it from the session's {@link FormationTokenRead},
+ * so the choice of which hook to trust never travels through a caller.
  */
 export type ResolvedHostStrand =
   | { kind: 'unbound' }
-  | { kind: 'bound'; strandId: string; memberPrivateKey: string | null }
+  | ({ kind: 'bound' } & BoundHostStrand)
   | { kind: 'missing'; strandId: string };
 
 /** One redemption of an invite against an already-existing host strand (the record-only consent write). */
@@ -87,48 +104,52 @@ export interface AuthorizedFormationUsage {
 }
 
 /**
- * Interface for recording formation usage
+ * The responder's view of the formation-invite tables. A session reads its token once
+ * ({@link readToken}) and hands that read to every later step, so no step reads the invite again.
  */
 export interface FormationUsageRecorder {
   /**
-   * Record that a formation invite was used. Where {@link authorizeUsage} is implemented, this
-   * is the same as authorizing and then calling `record()` straight away.
+   * Record that a formation invite was used, reading the invite for itself. Where
+   * {@link authorizeUsage} is implemented, this is the same as reading the token, authorizing,
+   * and calling `record()` straight away.
    */
   recordUsage(params: FormationUsageParams): Promise<void>;
 
   /**
    * Everything {@link recordUsage} does short of the write: obtain the outside approval (when
-   * the invite demands one) and pre-check the seat budget, returning a handle whose `record()`
-   * writes the consent row with exactly the fields that were approved. Lets the manager ask
-   * before it writes anything into the host strand, and write consent only after.
+   * `read` says the invite demands one) and, after an obtained approval, re-check the seat
+   * budget, returning a handle whose `record()` writes the consent row with exactly the fields
+   * that were approved. Lets the manager ask before it writes anything into the host strand,
+   * and write consent only after. `host` is the resolved host strand the consent row names.
    * Optional: a recorder without it is treated as having nothing to ask up front.
    */
-  authorizeUsage?(params: FormationUsageParams): Promise<AuthorizedFormationUsage>;
-
-  /**
-   * Check if a token has already been used (for single-use invites)
-   */
-  isTokenUsed(token: string): Promise<boolean>;
+  authorizeUsage?(
+    params: FormationUsageParams,
+    read: FormationTokenRead,
+    host: BoundHostStrand
+  ): Promise<AuthorizedFormationUsage>;
 
   /**
-   * Check if a token is valid and not expired. An invalid answer says why: `'unknown'` (no
-   * invitation row here — it may not have replicated yet) or `'expired'`. An answer without
-   * a reason is treated as `'unknown'`, the retryable one.
+   * Read one token as a formation session acts on it: the invite row (null when there is none
+   * here — it may not have replicated yet) and, for a metered unexpired invite, its recorded
+   * use count. One read per session; `classifyTokenRead` turns it into the token check.
    */
-  isTokenValid(token: string): Promise<{ valid: boolean; reason?: 'unknown' | 'expired'; invitation?: OpenInvitation }>;
+  readToken(token: string): Promise<FormationTokenRead>;
 
   /**
-   * Resolve the host strand an invite binds to, classifying it as unbound / bound /
-   * missing (see {@link ResolvedHostStrand}). Optional: a recorder that does not bind
-   * strands omits it, and {@link StrandFormationManager} treats every invite as `unbound`
-   * and falls back to its provisioner. Keeping resolution behind this interface keeps the
-   * manager DB-agnostic and unit-testable with an in-memory fake.
+   * Resolve the host strand the read invite binds to, classifying it as unbound / bound /
+   * missing (see {@link ResolvedHostStrand}). Reads the `Strand` row, never the invite.
+   * Optional: a recorder that does not bind strands omits it, and
+   * {@link StrandFormationManager} treats every invite as `unbound` and falls back to its
+   * provisioner. Keeping resolution behind this interface keeps the manager DB-agnostic and
+   * unit-testable with an in-memory fake.
    */
-  resolveStrand?(token: string): Promise<ResolvedHostStrand>;
+  resolveStrand?(read: FormationTokenRead): Promise<ResolvedHostStrand>;
 
   /**
    * Provision a NEW strand for an UNBOUND invite and record consent against it
    * ATOMICALLY (single `FormationUsage` row → single-use enforced on the next redemption).
+   * Takes the invite's approval hook and seat budget from `read`.
    * 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.AuthorizedInsert` `FormationUsage` branch authorizes. Returns the
@@ -147,14 +168,14 @@ export interface FormationUsageRecorder {
     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 }>;
+  }, read: FormationTokenRead): 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.
+   * exemption open. Distinct from the per-token {@link readToken} — the
+   * connection gate has no token to ask about.
    */
   hasOutstandingInvitation?(): Promise<boolean>;
 }
@@ -470,8 +491,8 @@ export class StrandSolicitationService {
    *     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).
+   *     construction; with one, a token whose row it reads as expired or used up
+   *     is deleted (both are 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.
    *
@@ -488,7 +509,13 @@ export class StrandSolicitationService {
       if (!this.formationUsageRecorder) {
         return true;
       }
-      if (!(await this.formationUsageRecorder.isTokenUsed(token))) {
+      // NOTE: a read of its own, not shared with a formation session's: this runs while a
+      // stranger's connection is being admitted, before any stream or token exists, under the
+      // gate's fail-open deadline, and the session that follows reads on a different call.
+      // An unknown token stays outstanding (its row may not be published yet); an expired or
+      // used-up row is dropped, the same `token-spent` the formation handler would answer.
+      const check = classifyTokenRead(await this.formationUsageRecorder.readToken(token), now);
+      if (check.valid || check.code === 'token-unknown') {
         return true;
       }
       this.mintedInvitations.delete(token);

package/src/strand-watcher.ts

@@ -1,4 +1,6 @@
 import debug from 'debug';
+import { scheduleRuns } from './table-change-watch.js';
+import type { TableChangeWatch, TableChangeWatchOptions } from './table-change-watch.js';
 import type { StrandFilter, StrandRow } from './types.js';
 
 const log = debug('sereus:cadre:strand-watcher');
@@ -7,7 +9,7 @@ const log = debug('sereus:cadre:strand-watcher');
  * Outcome of evaluating a strand against the current filter.
  * - `pass`: admit (final)
  * - `reject`: exclude
- * - `defer`: admit provisionally; sAppId not yet known, re-evaluate next poll
+ * - `defer`: admit provisionally; sAppId not yet known, re-evaluate when it is learned
  */
 type FilterDecision = 'pass' | 'reject' | 'defer';
 
@@ -15,10 +17,34 @@ 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`.
+ * must not re-attempt on every run and storm the host app with `strand:error`.
  */
 const MAX_RETRY_BACKOFF_MS = 5 * 60 * 1000;
 
+/**
+ * Default backstop: the longest the watcher goes without re-reading when no change to
+ * `Strand` or `JoinedStrand` is heard (`docs/architecture.md` → "Table change subscriptions"
+ * says what the change subscription misses).
+ *
+ * NOTE: on a cadre larger than `CONTROL_REPLICATION_BREADTH` (16), a machine outside the
+ * `Strand` block's cohort hears no change event, so this backstop is its only path and a
+ * strand founded elsewhere reaches it up to 5 minutes later. If that matters, shorten the
+ * backstop for such machines rather than for everyone.
+ */
+export const DEFAULT_STRAND_WATCH_BACKSTOP_MS = 5 * 60 * 1000;
+
+/**
+ * First step of the launch-retry and read-retry ladders, unless the backstop is shorter: a
+ * test or scenario that passes a short interval keeps the short base it always had.
+ */
+const LAUNCH_RETRY_BASE_MS = 5000;
+
+/** Ceiling on the read-retry ladder (see `StrandWatcher.scheduleReadRetry`), unless the backstop is shorter. */
+const READ_RETRY_CAP_MS = 60_000;
+
+/** Delay before the first run, so `start()` never reads synchronously. */
+const INITIAL_RUN_DELAY_MS = 100;
+
 /** Per-strand consecutive-failure state driving the launch retry backoff. */
 interface StrandFailureState {
   /** Consecutive `onStrandAdded` failures since the last success. */
@@ -45,10 +71,14 @@ export interface StrandWatcherCallbacks {
 }
 
 /**
- * Interface for querying strands from control network
+ * What the watcher reads, and how it hears that what it reads changed.
  */
 export interface StrandQueryable {
   queryStrands(): Promise<StrandRow[]>;
+  /** Subscribe to changes of the tables {@link queryStrands} reads. Absent: runs come from `trigger` and the backstop only. */
+  watchChanges?(onChange: () => Promise<void>, options: TableChangeWatchOptions): TableChangeWatch;
+  /** True when the last {@link queryStrands} answered part of its result from a stand-in after a failed read. */
+  lastReadPartial?(): boolean;
 }
 
 /**
@@ -63,11 +93,16 @@ export interface SAppIdLookup {
  * Watches the control network's Strand table for changes and triggers
  * strand instance start/stop via callbacks.
  *
- * Uses polling until Optimystic supports reactive subscriptions.
+ * Every read is one run on a {@link TableChangeWatch}: once at start, on a change to the
+ * tables the queryable reads, on the watcher's own retries, and on the backstop.
  */
 export class StrandWatcher {
   private readonly filter: StrandFilter;
-  private readonly pollInterval: number;
+  /** Longest gap between runs when no change is heard. */
+  private readonly backstopMs: number;
+  /** First step of the launch-retry and read-retry ladders. */
+  private readonly retryBaseMs: number;
+  private readonly readRetryCapMs: number;
   private readonly callbacks: StrandWatcherCallbacks;
   private readonly queryable: StrandQueryable;
   private readonly sAppIdLookup?: SAppIdLookup;
@@ -81,7 +116,7 @@ export class StrandWatcher {
   private readonly now: () => number;
 
   private knownStrands: Map<string, StrandRow> = new Map();
-  /** Ids admitted under a `defer` decision; re-evaluated each poll until they resolve. */
+  /** Ids admitted under a `defer` decision; re-evaluated each run 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();
@@ -92,31 +127,39 @@ export class StrandWatcher {
    * strand, the permanence has to be recorded explicitly.
    */
   private suppressed: Set<string> = new Set();
-  private pollTimer: ReturnType<typeof setInterval> | null = null;
-  private initialPollTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Consecutive runs whose read failed or was partial; drives {@link scheduleReadRetry}. */
+  private readFailures = 0;
+  /** Built by {@link start}, disposed by {@link stop}; a restart builds a new one. */
+  private watch: TableChangeWatch | null = null;
   private running = false;
 
+  /**
+   * @param backstopMs - `CadreNodeConfig.strandWatchInterval`: the longest the watcher goes
+   *   without re-reading when no change is heard. Also caps the retry ladders' first step.
+   */
   constructor(
     queryable: StrandQueryable,
     callbacks: StrandWatcherCallbacks,
     filter: StrandFilter = { mode: 'all' },
-    pollInterval: number = 5000,
+    backstopMs: number = DEFAULT_STRAND_WATCH_BACKSTOP_MS,
     sAppIdLookup?: SAppIdLookup,
     now: () => number = Date.now
   ) {
     this.queryable = queryable;
     this.callbacks = callbacks;
     this.filter = filter;
-    this.pollInterval = pollInterval;
+    this.backstopMs = backstopMs;
+    this.retryBaseMs = Math.min(backstopMs, LAUNCH_RETRY_BASE_MS);
+    this.readRetryCapMs = Math.min(backstopMs, READ_RETRY_CAP_MS);
     this.sAppIdLookup = sAppIdLookup;
     this.now = now;
-    log('StrandWatcher created with filter: %o, interval: %dms', filter, pollInterval);
+    log('StrandWatcher created with filter: %o, backstop: %dms', filter, backstopMs);
   }
 
   /**
    * Evaluate a strand against the current filter, distinguishing a not-yet-known
    * sAppId (`defer`) from a known non-match (`reject`). A `defer` admission is
-   * provisional and re-checked on subsequent polls.
+   * provisional and re-checked on subsequent runs (see {@link sAppIdLearned}).
    */
   private evaluateFilter(strand: StrandRow): FilterDecision {
     switch (this.filter.mode) {
@@ -133,7 +176,7 @@ export class StrandWatcher {
         }
         const sAppId = this.sAppIdLookup.getSAppId(strand.Id);
         if (sAppId === undefined) {
-          // sAppId not yet known - admit provisionally and re-evaluate next poll.
+          // sAppId not yet known - admit provisionally and re-evaluate once it is learned.
           log('sAppId unknown for strand %s - deferring filter decision', strand.Id);
           return 'defer';
         }
@@ -149,20 +192,73 @@ export class StrandWatcher {
 
   /**
    * Record a failed launch attempt and schedule when the strand may be retried:
-   * `pollInterval * 2^(failures-1)`, capped at {@link MAX_RETRY_BACKOFF_MS}.
+   * `retryBaseMs * 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);
+    const delay = Math.min(this.retryBaseMs * 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.
+   * One run: read, reconcile, then arm the follow-up runs this run needs. A run the watch
+   * starts clears every pending wake, so each run re-arms the retries still owed. A
+   * {@link forcePoll} run clears none, so what it arms may sit beside an equivalent wake;
+   * whichever fires first runs and clears the other.
    */
-  private async poll(): Promise<void> {
-    if (!this.running) return;
+  private async runOnce(): Promise<void> {
+    const startedAt = this.now();
+    const readComplete = await this.poll();
+    if (this.running) {
+      this.scheduleLaunchRetry(startedAt);
+      this.scheduleReadRetry(readComplete);
+    }
+  }
+
+  /**
+   * Wake for the earliest launch retry falling due after `since`. A backoff that expired at
+   * or before `since` belongs to a strand the run starting then either attempted or skipped
+   * for a reason other than backoff (suppressed, filtered out); waking for it would spin.
+   * Without this a failed launch would wait for an unrelated change or the backstop.
+   */
+  private scheduleLaunchRetry(since: number): void {
+    let earliest = Infinity;
+    for (const { nextAttemptAt } of this.failureStates.values()) {
+      if (nextAttemptAt > since) {
+        earliest = Math.min(earliest, nextAttemptAt);
+      }
+    }
+    if (earliest !== Infinity) {
+      this.watch?.trigger(Math.max(0, earliest - this.now()));
+    }
+  }
+
+  /**
+   * After a failed or partial read, run again on a ladder from `retryBaseMs`, doubling per
+   * consecutive failed run up to `readRetryCapMs`; a complete read resets it. Not left to
+   * the backstop because the plugin arms a table's replicated-change bridge on the table's
+   * first successful initialization: a machine whose first read failed (cut off from its
+   * party, or its sibling unreachable for a never-written `JoinedStrand`) would otherwise
+   * hear nothing until then.
+   */
+  private scheduleReadRetry(readComplete: boolean): void {
+    if (readComplete) {
+      this.readFailures = 0;
+      return;
+    }
+    this.readFailures++;
+    const delay = Math.min(this.retryBaseMs * 2 ** (this.readFailures - 1), this.readRetryCapMs);
+    log('Strand read incomplete (%d consecutive) - re-reading in %dms', this.readFailures, delay);
+    this.watch?.trigger(delay);
+  }
+
+  /**
+   * Read and reconcile. Resolves true when the read answered in full: false when it threw,
+   * or when the queryable answered part of it from a stand-in.
+   */
+  private async poll(): Promise<boolean> {
+    if (!this.running) return true;
 
     try {
       const currentStrands = await this.queryable.queryStrands();
@@ -173,17 +269,17 @@ export class StrandWatcher {
         if (this.suppressed.has(strand.Id)) continue; // deliberately stopped locally
         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
+        // Clock read per candidate, not once per run: 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.
+        // Set BEFORE the await: this doubles as the in-flight guard that stops a
+        // concurrent run (`forcePoll` beside a scheduled one) from launching the strand twice.
         this.knownStrands.set(strand.Id, strand);
         if (decision === 'defer') {
-          // Provisional admission: sAppId unknown, re-check on later polls.
+          // Provisional admission: sAppId unknown, re-check on later runs.
           this.provisional.add(strand.Id);
         }
         try {
@@ -215,7 +311,7 @@ export class StrandWatcher {
             log('Error handling strand remove for %s: %o', strandId, error);
           }
         }
-        // decision === 'defer': still unknown, leave provisional for next poll.
+        // decision === 'defer': still unknown, leave provisional until sAppIdLearned wakes a run.
       }
 
       // Find removed strands. A strand whose launch failed is no longer in
@@ -242,8 +338,8 @@ export class StrandWatcher {
           this.failureStates.delete(strandId);
         }
       }
-      // NOTE: the clear needs a poll that actually SEES the row absent, so a sibling that
-      // unpublishes and re-publishes a locally-stopped id inside one poll interval leaves
+      // NOTE: the clear needs a run that actually SEES the row absent, so a sibling that
+      // unpublishes and re-publishes a locally-stopped id between two runs leaves
       // it suppressed for the session. Contrived today — re-seating a removed id is
       // owner-gated and manual — and there is no row version to distinguish the new row
       // from the old. If re-publishing a removed id ever becomes routine, give the row a
@@ -253,14 +349,17 @@ export class StrandWatcher {
           this.suppressed.delete(strandId);
         }
       }
+      return !(this.queryable.lastReadPartial?.() ?? false);
     } catch (error) {
       // NOTE: a machine cut off from its party before it ever received the `Strand` block
-      // fails this read `cohort-unreachable` on every poll and logs here (observed in
-      // `control-cohort-edge-carries-data`). Harmless: nothing was ever launched from a block
-      // this machine never held, and this catch keeps the known set. Do not answer it as
-      // empty the way `ControlDatabase.queryRevokedStamps` does for `Revocation` — an empty
-      // answer here runs the removed-strand loop above. Revisit if the log volume matters.
+      // fails this read `cohort-unreachable` on every step of the read-retry ladder and logs
+      // here (observed in `control-cohort-edge-carries-data`). Harmless: nothing was ever
+      // launched from a block this machine never held, and this catch keeps the known set. Do
+      // not answer it as empty the way `ControlDatabase.queryRevokedStamps` does for
+      // `Revocation` — an empty answer here runs the removed-strand loop above. Revisit if
+      // the log volume matters.
       log('Error polling strands: %o', error);
+      return false;
     }
   }
 
@@ -274,23 +373,24 @@ export class StrandWatcher {
     }
 
     log('Starting StrandWatcher');
+    // Subscribed before the first read, so a commit landing between them is either seen by
+    // that read or wakes a follow-up run.
+    this.watch = this.subscribe();
     this.running = true;
-
-    // Set up periodic polling
-    this.pollTimer = setInterval(() => {
-      void this.poll();
-    }, this.pollInterval);
-
-    // Defer the first poll so start() doesn't block the caller.
-    // Strands added via addStrand() typically arrive after start() completes.
-    this.initialPollTimer = setTimeout(() => {
-      this.initialPollTimer = null;
-      void this.poll();
-    }, 100);
+    // Deferred so start() doesn't block the caller; strands added via addStrand()
+    // typically arrive after start() completes.
+    this.watch.trigger(INITIAL_RUN_DELAY_MS);
 
     log('StrandWatcher started');
   }
 
+  /** The watch every run goes through: the queryable's change subscription, or a timer-only one. */
+  private subscribe(): TableChangeWatch {
+    const onChange = (): Promise<void> => this.runOnce();
+    const options: TableChangeWatchOptions = { label: 'strand-watcher', backstopMs: this.backstopMs };
+    return this.queryable.watchChanges?.(onChange, options) ?? scheduleRuns(onChange, options);
+  }
+
   /**
    * Stop watching for strand changes
    */
@@ -301,27 +401,22 @@ export class StrandWatcher {
 
     log('Stopping StrandWatcher');
     this.running = false;
-
-    if (this.initialPollTimer) {
-      clearTimeout(this.initialPollTimer);
-      this.initialPollTimer = null;
-    }
-
-    if (this.pollTimer) {
-      clearInterval(this.pollTimer);
-      this.pollTimer = null;
-    }
+    // A run already in flight finishes; `running` keeps it from arming anything further.
+    this.watch?.dispose();
+    this.watch = null;
 
     this.knownStrands.clear();
     this.provisional.clear();
     this.failureStates.clear();
     this.suppressed.clear();
+    this.readFailures = 0;
     log('StrandWatcher stopped');
   }
 
   /**
-   * Forget a strand whose launch failed outside this watcher, so a later poll
-   * re-offers it — gated by the same backoff a watcher-driven failure gets.
+   * Forget a strand whose launch failed outside this watcher, so a later run
+   * re-offers it — gated by the same backoff a watcher-driven failure gets, and woken
+   * when that backoff expires.
    *
    * A failed launch normally leaves nothing running (StrandInstanceManager drops the
    * record), which is what makes re-offering it correct. One case does leave something
@@ -335,6 +430,27 @@ export class StrandWatcher {
     this.knownStrands.delete(strandId);
     this.provisional.delete(strandId);
     this.recordFailure(strandId);
+    if (this.running) {
+      this.scheduleLaunchRetry(this.now());
+    }
+  }
+
+  /**
+   * Re-read soon: something the queryable merges in beside the watched tables changed
+   * (`CadreNode`'s machine-local joined-strand records). A no-op once stopped.
+   */
+  refresh(): void {
+    this.watch?.trigger();
+  }
+
+  /**
+   * The host just learned `strandId`'s sAppId: if the strand was admitted provisionally
+   * under an `sAppId` filter, run so the admission resolves now rather than on the backstop.
+   */
+  sAppIdLearned(strandId: string): void {
+    if (this.provisional.has(strandId)) {
+      this.watch?.trigger();
+    }
   }
 
   /**
@@ -379,10 +495,13 @@ export class StrandWatcher {
   }
 
   /**
-   * Force an immediate poll (useful for testing)
+   * Run once now, outside the watch's schedule (tests, and callers that just wrote a row
+   * and want this node to converge before returning). May overlap a scheduled run:
+   * `knownStrands` is updated before each callback's await, so neither launches nor
+   * removes a strand twice.
    */
   async forcePoll(): Promise<void> {
-    await this.poll();
+    await this.runOnce();
   }
 }