@moondeck/station 0.0.1 → 1.0.0

package/lib/release-trust.ts

@@ -0,0 +1,46 @@
+import { LEGACY_HOST_RELEASE_FEED } from "./release-feed";
+import type { PinnedReleaseManifestKey } from "./release-manifest";
+
+/**
+ * Stable manifest location for the public, release-artifact-only feed.
+ *
+ * The release coordinator provisions the first production key in this map in
+ * the same reviewed change that enables publishing. Keeping the empty map in
+ * source makes an unprovisioned updater fail closed; no network-provided key
+ * or environment variable can become a trust anchor.
+ */
+export const STABLE_RELEASE_MANIFEST_URL =
+  LEGACY_HOST_RELEASE_FEED.stableManifestUrl;
+
+/**
+ * Deliberate public-release latch for ADR-099.
+ *
+ * Provisioning a key is necessary but not sufficient to advertise or serve
+ * the one-line installer. The release coordinator flips this only in the same
+ * reviewed change that publishes the complete, version-matched four-platform
+ * release. Flipped 2026-08-19 in the change that provisioned
+ * `uai-release-2026-a` and wired auto-release to sign and publish the
+ * four-platform feed on every host version bump.
+ */
+export const HOST_INSTALLER_RELEASE_PROMOTED = true;
+
+/**
+ * `uai-release-2026-a`: minted by the operator 2026-08-19 (Ed25519; private
+ * key lives in Infisical and reaches CI as UAI_RELEASE_SIGNING_KEY). Rotation
+ * is additive: pin the successor key beside this one, publish releases signed
+ * by it, and retire this entry only after every supported host updated past
+ * a release that pins both.
+ */
+export const PINNED_RELEASE_MANIFEST_KEYS: ReadonlyMap<
+  string,
+  PinnedReleaseManifestKey
+> = new Map([
+  [
+    "uai-release-2026-a",
+    {
+      publicKey: `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAeCBzaLTNYNGkI59T+vNu2M/DMTeTsmfABDtwN9IDejY=
+-----END PUBLIC KEY-----`,
+    },
+  ],
+]);

package/lib/repo-clone.ts

@@ -0,0 +1,38 @@
+/**
+ * Retired bare-mirror host command.
+ *
+ * Project creation stores metadata only. Repository access happens at
+ * task-up, after the task creator and host are known, using that user's
+ * connected GitHub credential or their explicit SSH fallback. This legacy
+ * protocol command cannot express either principal, so running Git here would
+ * necessarily risk borrowing the host operator's ambient credential.
+ *
+ * Keep the command-shaped response for rolling-version compatibility, but
+ * fail closed without touching the filesystem or network. A future preflight
+ * needs a user/host-aware protocol of its own; see
+ * docs/repo-access-preflight.md.
+ */
+
+import { projectRepoMirror } from "./env";
+
+export interface CloneRepoInput {
+  url: string;
+  projectId: string;
+}
+
+export interface CloneRepoResult {
+  status: "ready" | "error";
+  error?: string;
+  /** Absolute path to the bare mirror directory. */
+  absolutePath: string;
+}
+
+export function cloneRepo(input: CloneRepoInput): CloneRepoResult {
+  const target = projectRepoMirror(input.projectId);
+  return {
+    status: "error",
+    absolutePath: target,
+    error:
+      "repo.clone is retired because it has no task creator credential; start a task to perform the user-scoped repository fetch",
+  };
+}

package/lib/routing/shadow.ts

@@ -0,0 +1,261 @@
+/**
+ * ADR-141 rung 1 — the SHADOW router.
+ *
+ * Nothing here changes what runs. On every human delivery to an agent in a
+ * workspace the cloud flagged (`ChannelEnsureInput.routing.shadow`), the
+ * runner classifies the message the way Auto mode would, resolves what Auto
+ * would have picked under the Balanced preset, and reports both beside what
+ * actually ran as an `agent.route.shadow` host event. A week of those rows
+ * turns the on-paper saving into a measured one.
+ *
+ * Shape, kept deliberately: the MODEL answers one fuzzy question ("how hard
+ * is this, and what kind of work"); everything with policy in it is code.
+ *
+ *   fast path (rules)  →  classify (one-shot on the agent's own account)
+ *                      →  hedge (rules that force the ceiling)
+ *                      →  resolve (class → tier → model within the envelope)
+ *
+ * The one-shot runs INSIDE the task environment, as `node`, with the engine
+ * account the agent itself runs on — so Uai never pays for routing and the
+ * classifier sees the same credential the agent does. Rung 0 (2026-09-15)
+ * showed Claude, Codex and Grok all host the rubric within the noise floor
+ * (74–77% tier agreement, Haiku against itself included), so the host is
+ * simply whichever engine the agent is on.
+ */
+
+export const ROUTE_CLASSES = ["trivial", "routine", "hard", "decision"] as const;
+export type RouteClass = (typeof ROUTE_CLASSES)[number];
+export const WORK_KINDS = ["edit", "debug", "explain", "plan", "research", "write", "browser", "other"] as const;
+export type WorkKind = (typeof WORK_KINDS)[number];
+
+/** hard and decision both route to the ceiling; that is what the resolver
+ *  compares, and what rung 0 measured agreement on. */
+export const TIER_OF: Record<RouteClass, 0 | 1 | 2> = {
+  trivial: 0,
+  routine: 1,
+  hard: 2,
+  decision: 2,
+};
+
+export const RUBRIC = `You classify ONE human message sent to a coding agent inside a task channel.
+
+Pick exactly one class:
+- trivial: acknowledgements, greetings, yes/no, "go ahead", "continue", thanks,
+  a one-line question about current state. No repository work is needed.
+- routine: a clear, bounded ask done in one or two steps: explain a file, small
+  fix, rename, run the tests, answer a factual question about the code.
+- hard: multi-step implementation, debugging where the cause is unknown, a
+  change across several files, a bug report, anything needing exploration first.
+- decision: architecture, design or trade-off questions, planning, "should we…",
+  reviewing a proposal — judgement matters more than execution.
+
+And one kind of work: edit, debug, explain, plan, research, write, browser, other.
+
+The preceding channel turns are context only. Judge the LAST human message.
+Return ONLY this JSON, nothing else:
+{"class":"<trivial|routine|hard|decision>","kind":"<edit|debug|explain|plan|research|write|browser|other>","reason":"<8 words max>"}`;
+
+// ---------------------------------------------------------------------------
+// Fast path: turns that never need the model. Rung 0's regex caught only 10 of
+// 135 trivials; this one is wider on purpose and still conservative: short,
+// no path, no code, no question about anything specific.
+const ACK = new RegExp(
+  "^(ok(ay)?|yes|yeah|yep|ya|no|nope|go|go ahead|continue|proceed|do it|ship it|" +
+    "thanks|thank you|ty|thx|cool|nice|great|good|done|sure|k|kk|lgtm|approved|" +
+    "sounds good|perfect|awesome|please do|yes please|no thanks|not now|later|" +
+    "👍|🙏|✅)[.!\\s]*$",
+  "i",
+);
+const LOOKS_LIKE_WORK = /[\/\\`{}()=;]|\.(ts|js|tsx|py|md|json|sql|sh|yml|yaml)\b|https?:\/\//i;
+
+export function fastPath(text: string): RouteClass | null {
+  const t = text.trim();
+  if (t.length === 0) return "trivial";
+  if (ACK.test(t)) return "trivial";
+  // A very short message with no code-shaped content and no question mark
+  // is a reaction, not a request ("k .11 is shipping", "@luigi").
+  if (t.length <= 24 && !LOOKS_LIKE_WORK.test(t) && !t.includes("?")) return "trivial";
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Hedges: deterministic upgrades to the ceiling. Rung 0's systematic miss was
+// bug reports and multi-ask messages labelled routine; these cut Codex's cold
+// misses from 6 to 3 of 51 at one needless escalation in 70.
+const BUG = /\b(bug|broken|not working|doesn'?t work|isn'?t working|won'?t|error|fail(ed|ing|s)?|duplicated|wrong|stuck|crash(ed|es)?|regression|não está|nao esta|não funciona|quebr(ou|ado))\b/i;
+const ATTACH = /\[image:|attachments\/|screenshot|\bprint\b/i;
+const MULTI = /(\n\s*[-*•]|\n\s*\d+[.)-]|another thing|a couple more|one more thing|also,|and then|then i want|\b[12]-\s)/i;
+const DECIDE = /\b(should we|how is that gonna|how would that|what should|what would|do we need|is it (risky|worth|safe)|let'?s think|thoughts on|what do you think)\b/i;
+
+export function hedge(text: string, cls: RouteClass): RouteClass {
+  if (TIER_OF[cls] === 2) return cls;
+  const long = text.length > 60;
+  if (DECIDE.test(text) && text.length > 40) return "decision";
+  if (BUG.test(text) && (ATTACH.test(text) || long)) return "hard";
+  if (MULTI.test(text) && text.length > 80) return "hard";
+  return cls;
+}
+
+// ---------------------------------------------------------------------------
+// Resolve: class → tier → model, per engine, under the Balanced preset. Rung 1
+// keeps the agent's own engine (cross-engine is rung 3) and a static tier
+// table; the catalog's tier column replaces this once it exists.
+export interface WouldRoute {
+  engine: string;
+  model: string | null;
+}
+
+const BALANCED: Record<string, [string, string, string] | undefined> = {
+  // [floor, default, ceiling]
+  claude: ["haiku", "sonnet", "opus"],
+  uai: ["haiku-4.5", "sonnet-5", "opus-5"],
+  codex: ["gpt-5.6-luna", "gpt-5.6-terra", "gpt-5.6-sol"],
+};
+
+export function resolveBalanced(cls: RouteClass, engine: string): WouldRoute {
+  const ladder = BALANCED[engine];
+  if (!ladder) return { engine, model: null };
+  return { engine, model: ladder[TIER_OF[cls]] };
+}
+
+/** The cheapest model each engine serves on a connected account — what the
+ *  classifier itself runs on. Verified 2026-09-15: a ChatGPT-account Codex
+ *  refuses gpt-5-mini and the codex-mini variants but serves Luna. */
+export const CLASSIFIER_MODEL: Record<string, string | null> = {
+  claude: "haiku",
+  codex: "gpt-5.6-luna",
+  grok: null, // the CLI's default; the login decides
+};
+
+// ---------------------------------------------------------------------------
+// One-shot completion argv per engine. No tools, no session, plain text back.
+export interface OneShot {
+  argv: [string, ...string[]];
+  /** Where the answer lands: the process's stdout, or a file it writes. */
+  output: { kind: "stdout-json"; field: string } | { kind: "file"; path: string };
+}
+
+export function oneShotFor(engine: string, prompt: string, scratchDir: string): OneShot | null {
+  switch (engine) {
+    case "claude":
+    case "uai":
+      return {
+        argv: ["claude", "-p", prompt, "--model", "haiku", "--output-format", "json", "--no-session-persistence"],
+        output: { kind: "stdout-json", field: "result" },
+      };
+    case "codex": {
+      const out = `${scratchDir}/router-last.txt`;
+      return {
+        argv: [
+          "codex", "exec", "--skip-git-repo-check", "--ephemeral", "-s", "read-only",
+          "-m", "gpt-5.6-luna", "-o", out, prompt,
+        ],
+        output: { kind: "file", path: out },
+      };
+    }
+    case "grok":
+      return {
+        argv: ["grok", "-p", prompt, "--output-format", "json", "--disable-web-search"],
+        output: { kind: "stdout-json", field: "text" },
+      };
+    default:
+      return null;
+  }
+}
+
+export interface Label {
+  cls: RouteClass;
+  kind: WorkKind | null;
+  reason: string;
+}
+
+/** Tolerant of chatter around the JSON and of a model inventing a class. */
+export function parseLabel(text: string): Label | null {
+  const m = text.match(/\{[^{}]*"class"[^{}]*\}/);
+  if (!m) return null;
+  try {
+    const o = JSON.parse(m[0]) as { class?: unknown; kind?: unknown; reason?: unknown };
+    const cls = String(o.class ?? "").toLowerCase() as RouteClass;
+    if (!ROUTE_CLASSES.includes(cls)) return null;
+    const kind = String(o.kind ?? "").toLowerCase() as WorkKind;
+    return {
+      cls,
+      kind: WORK_KINDS.includes(kind) ? kind : null,
+      reason: typeof o.reason === "string" ? o.reason.slice(0, 80) : "",
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function buildPrompt(message: string, context: string): string {
+  const ctx = context.trim().length > 0 ? context.trim().slice(-900) : "(none)";
+  return `${RUBRIC}\n\nRECENT CHANNEL (context only):\n${ctx}\n\nLAST HUMAN MESSAGE:\n${message.slice(0, 1600)}`;
+}
+
+// ---------------------------------------------------------------------------
+// The pass itself, with every side effect injected so it is testable without
+// an orchestrator.
+export interface ShadowDeps {
+  /** Run a one-shot in the task environment; null when it cannot run at all. */
+  exec: (argv: [string, ...string[]]) => Promise<{ exitCode: number | null; stdout: string } | null>;
+  readFile: (path: string) => Promise<string | null>;
+  scratchDir: string;
+  now?: () => number;
+}
+
+export interface ShadowResult {
+  cls: RouteClass;
+  kind: WorkKind | null;
+  via: "rules" | "account" | "none";
+  host: string | null;
+  would: WouldRoute;
+  ms: number;
+}
+
+export async function shadowRoute(
+  message: string,
+  context: string,
+  engine: string,
+  deps: ShadowDeps,
+): Promise<ShadowResult> {
+  const now = deps.now ?? Date.now;
+  const t0 = now();
+  const fast = fastPath(message);
+  if (fast) {
+    return { cls: fast, kind: null, via: "rules", host: null, would: resolveBalanced(fast, engine), ms: now() - t0 };
+  }
+  const shot = oneShotFor(engine, buildPrompt(message, context), deps.scratchDir);
+  let label: Label | null = null;
+  let host: string | null = null;
+  if (shot) {
+    const res = await deps.exec(shot.argv).catch(() => null);
+    if (res && res.exitCode === 0) {
+      let text = "";
+      if (shot.output.kind === "file") {
+        text = (await deps.readFile(shot.output.path).catch(() => null)) ?? "";
+      } else {
+        try {
+          const d = JSON.parse(res.stdout) as Record<string, unknown>;
+          text = typeof d[shot.output.field] === "string" ? (d[shot.output.field] as string) : res.stdout;
+        } catch {
+          text = res.stdout;
+        }
+      }
+      label = parseLabel(text);
+      if (label) host = engine;
+    }
+  }
+  // No usable answer: the deterministic layer still routes — default tier,
+  // hedged upward where the message says so.
+  const base: RouteClass = label?.cls ?? "routine";
+  const cls = hedge(message, base);
+  return {
+    cls,
+    kind: label?.kind ?? null,
+    via: label ? "account" : "none",
+    host,
+    would: resolveBalanced(cls, engine),
+    ms: now() - t0,
+  };
+}

package/lib/runner-boot.ts

@@ -0,0 +1,10 @@
+/**
+ * Identity of this runner process lifetime.
+ *
+ * The bridge replay cursor and ADR-154's in-memory credential replicas must
+ * use the same value. Keeping the singleton in its own module prevents two
+ * subsystems from each drawing a plausible but different boot id.
+ */
+import { newId } from "./ulid";
+
+export const RUNNER_BOOT_ID = newId();

package/lib/runtime-activation-tail.ts

@@ -0,0 +1,279 @@
+/**
+ * `retry`: a transient failure, followed up within the epoch's bounded
+ * budget. `rerun`: the attempt was cut short by a one-time, monotonic
+ * transition (ADR-154: the runner leaving its own credentials), and the
+ * pass it now needs (one that sweeps first) runs at once, outside that
+ * budget and with a fresh one of its own, at most once per epoch.
+ */
+export type RuntimeActivationAttemptResult = "complete" | "retry" | "rerun";
+
+type ActivationAttempt = () => Promise<RuntimeActivationAttemptResult>;
+type RetrySchedule = (callback: () => void, delayMs: number) => () => void;
+
+interface RuntimeRecoveryGateOptions {
+  isCurrent(): boolean;
+  recover(isCurrent: () => boolean): Promise<boolean>;
+  runtimeReady(): Promise<boolean>;
+  afterRecovery(): Promise<void>;
+}
+
+/** Keep the operational publication path strictly behind a true recovery
+ * verdict. A false verdict probes the daemon only to choose between normal
+ * no-runtime handling and a post-tail retry; it never calls `afterRecovery`. */
+export async function runRuntimeRecoveryGate(
+  options: RuntimeRecoveryGateOptions,
+): Promise<RuntimeActivationAttemptResult> {
+  const recovered = await options.recover(options.isCurrent);
+  if (!options.isCurrent()) return "complete";
+  if (!recovered) {
+    const ready = await options.runtimeReady();
+    return ready && options.isCurrent() ? "retry" : "complete";
+  }
+  await options.afterRecovery();
+  return "complete";
+}
+
+export type RuntimeMaintenanceVerdict = "ready" | "retry" | "stale";
+
+interface MaintainedRuntimeActivationOptions {
+  isCurrent(): boolean;
+  /** One-way rolling fence before the first shared-volume writer. */
+  beforeMaintenance(): Promise<RuntimeMaintenanceVerdict>;
+  maintenance(): Promise<RuntimeMaintenanceVerdict>;
+  recover(isCurrent: () => boolean): Promise<boolean>;
+  runtimeReady(): Promise<boolean>;
+  afterRecoveryBeforeFinalMaintenance(): Promise<void>;
+  publishOperational(): Promise<void>;
+}
+
+/**
+ * Keep both standard-image/shared-volume maintenance passes on the same side
+ * of the recovery and operational-publication fences. A live daemon plus a
+ * transient maintenance failure requests the activation tail's bounded retry;
+ * a stale daemon generation simply completes and lets its readiness edge own
+ * the next attempt.
+ */
+export async function runMaintainedRuntimeActivation(
+  options: MaintainedRuntimeActivationOptions,
+): Promise<RuntimeActivationAttemptResult> {
+  if (!options.isCurrent()) return "complete";
+  const prepared = await options.beforeMaintenance();
+  if (prepared !== "ready") {
+    return prepared === "retry" ? "retry" : "complete";
+  }
+  if (!options.isCurrent()) return "complete";
+  const initial = await options.maintenance();
+  if (initial !== "ready") {
+    return initial === "retry" ? "retry" : "complete";
+  }
+
+  let retryAfterRecovery = false;
+  const recoveryResult = await runRuntimeRecoveryGate({
+    isCurrent: options.isCurrent,
+    recover: options.recover,
+    runtimeReady: options.runtimeReady,
+    afterRecovery: async () => {
+      await options.afterRecoveryBeforeFinalMaintenance();
+      if (!options.isCurrent()) return;
+      const final = await options.maintenance();
+      if (final !== "ready") {
+        retryAfterRecovery = final === "retry";
+        return;
+      }
+      await options.publishOperational();
+    },
+  });
+  return retryAfterRecovery ? "retry" : recoveryResult;
+}
+
+interface RuntimeActivationTailOptions {
+  isCurrent(epoch: number): boolean;
+  retryDelayMs?: number;
+  maxRetries?: number;
+  schedule?: RetrySchedule;
+  onError?(error: unknown): void;
+  onExhausted?(epoch: number, attempts: number): void;
+}
+
+interface ActivationInFlight {
+  epoch: number;
+  promise: Promise<void>;
+}
+
+const defaultSchedule: RetrySchedule = (callback, delayMs) => {
+  const timer = setTimeout(callback, delayMs);
+  timer.unref?.();
+  return () => clearTimeout(timer);
+};
+
+/**
+ * Serialize runtime activation generations and turn a retry verdict into a
+ * bounded follow-up attempt. The retry timer is installed from the active
+ * promise's `finally`, after the tail has been cleared, so it cannot merely
+ * join the attempt that requested it.
+ */
+export class RuntimeActivationTail {
+  private readonly isCurrent: (epoch: number) => boolean;
+  private readonly retryDelayMs: number;
+  private readonly maxRetries: number;
+  private readonly schedule: RetrySchedule;
+  private readonly onError: (error: unknown) => void;
+  private readonly onExhausted: (epoch: number, attempts: number) => void;
+  private inFlight: ActivationInFlight | null = null;
+  private retryEpoch: number | null = null;
+  private retryAttempts = 0;
+  private cancelRetry: (() => void) | null = null;
+  private exhaustionReported = false;
+  private stopped = false;
+  /** Who waits for no activation to be under way (whenSettled). */
+  private settledWaiters: Array<() => void> = [];
+  /** The epochs whose one rerun has been run. */
+  private readonly rerunEpochs = new Set<number>();
+
+  constructor(options: RuntimeActivationTailOptions) {
+    this.isCurrent = options.isCurrent;
+    this.retryDelayMs = options.retryDelayMs ?? 20_000;
+    this.maxRetries = Math.max(0, options.maxRetries ?? 3);
+    this.schedule = options.schedule ?? defaultSchedule;
+    this.onError = options.onError ?? (() => {});
+    this.onExhausted = options.onExhausted ?? (() => {});
+  }
+
+  request(epoch: number, attempt: ActivationAttempt): Promise<void> {
+    if (this.stopped || !this.isCurrent(epoch)) return Promise.resolve();
+    if (this.inFlight?.epoch === epoch) return this.inFlight.promise;
+
+    this.selectEpoch(epoch);
+    // An explicit activation supersedes a delayed retry for the same epoch.
+    // Keep the consumed retry count so repeated external nudges cannot reset
+    // the bound without creating a new daemon generation.
+    this.cancelScheduledRetry();
+
+    const predecessor = this.inFlight?.promise;
+    let result: RuntimeActivationAttemptResult = "complete";
+    const run = async (): Promise<void> => {
+      if (this.stopped || !this.isCurrent(epoch)) return;
+      try {
+        result = await attempt();
+      } catch (error) {
+        result = "retry";
+        try {
+          this.onError(error);
+        } catch {
+          // Diagnostics must not break the retry tail.
+        }
+      }
+    };
+
+    let running!: Promise<void>;
+    running = (predecessor
+      ? predecessor.catch(() => {}).then(run)
+      : run()
+    ).finally(() => {
+      if (this.inFlight?.promise !== running) return;
+      this.inFlight = null;
+      if (
+        result === "rerun" &&
+        !this.stopped &&
+        this.isCurrent(epoch) &&
+        !this.rerunEpochs.has(epoch)
+      ) {
+        // Outside the transient budget, with a fresh one of its own.
+        this.rerunEpochs.add(epoch);
+        this.cancelScheduledRetry();
+        this.retryAttempts = 0;
+        this.exhaustionReported = false;
+        void this.request(epoch, attempt);
+      } else if (
+        (result === "retry" || result === "rerun") &&
+        !this.stopped &&
+        this.isCurrent(epoch)
+      ) {
+        this.scheduleRetry(epoch, attempt);
+      } else {
+        this.resolve(epoch);
+      }
+      this.notifySettled();
+    });
+    this.inFlight = { epoch, promise: running };
+    return running;
+  }
+
+  /** Schedule a retry requested outside the activation tail (for example, by
+   * reconnect revalidation). An active attempt for the epoch already owns the
+   * verdict and will schedule its own retry if needed. */
+  scheduleRetry(epoch: number, attempt: ActivationAttempt): boolean {
+    if (this.stopped || !this.isCurrent(epoch)) return false;
+    if (this.inFlight?.epoch === epoch) return true;
+    this.selectEpoch(epoch);
+    if (this.cancelRetry) return true;
+    if (this.retryAttempts >= this.maxRetries) {
+      if (!this.exhaustionReported) {
+        this.exhaustionReported = true;
+        this.onExhausted(epoch, this.retryAttempts);
+      }
+      return false;
+    }
+
+    this.retryAttempts += 1;
+    let cancel!: () => void;
+    cancel = this.schedule(() => {
+      if (this.cancelRetry !== cancel) return;
+      this.cancelRetry = null;
+      if (this.stopped || !this.isCurrent(epoch)) {
+        this.notifySettled();
+        return;
+      }
+      void this.request(epoch, attempt);
+    }, this.retryDelayMs);
+    this.cancelRetry = cancel;
+    return true;
+  }
+
+  /** Whether an activation is under way: one running, or a retry of one
+   *  scheduled (#p2jdax: a recheck asked for meanwhile waits for it). */
+  underWay(): boolean {
+    return !this.stopped && (this.inFlight !== null || this.cancelRetry !== null);
+  }
+
+  /** Resolves once no activation is under way; never, once stopped (a
+   *  stopping host starts nothing more). */
+  whenSettled(): Promise<void> {
+    if (this.stopped) return new Promise<void>(() => {});
+    if (!this.underWay()) return Promise.resolve();
+    return new Promise<void>((resolve) => this.settledWaiters.push(resolve));
+  }
+
+  /** Clear retry bookkeeping after another path proves the epoch operational. */
+  resolve(epoch: number): void {
+    if (this.retryEpoch !== epoch) return;
+    this.cancelScheduledRetry();
+    this.retryEpoch = null;
+    this.retryAttempts = 0;
+    this.exhaustionReported = false;
+    this.notifySettled();
+  }
+
+  private notifySettled(): void {
+    if (this.stopped || this.underWay()) return;
+    for (const resolve of this.settledWaiters.splice(0)) resolve();
+  }
+
+  stop(): void {
+    this.stopped = true;
+    this.cancelScheduledRetry();
+  }
+
+  private selectEpoch(epoch: number): void {
+    if (this.retryEpoch === epoch) return;
+    this.cancelScheduledRetry();
+    this.retryEpoch = epoch;
+    this.retryAttempts = 0;
+    this.exhaustionReported = false;
+  }
+
+  private cancelScheduledRetry(): void {
+    this.cancelRetry?.();
+    this.cancelRetry = null;
+  }
+}