@wrongstack/core 0.313.0 → 0.316.1

package/dist/execution/model-runtime.d.ts

@@ -64,12 +64,5 @@ export interface ModelRuntimeMiddlewareOptions {
     /** Optional sink for suppressed-setting warnings (e.g. emit to event bus). */
     onWarning?: ((message: string) => void) | undefined;
 }
-/**
- * Build a `request`-pipeline middleware that applies runtime settings. The
- * returned function mutates the outgoing request by overlaying resolved
- * `reasoning` / `cache` fields and generic parameters. Existing fields on
- * the request are preserved only when the resolver produces nothing for
- * that field.
- */
 export declare function applyModelRuntime(req: Request, opts: ModelRuntimeMiddlewareOptions): Request;
 //# sourceMappingURL=model-runtime.d.ts.map

package/dist/execution/parallel-eternal-engine.d.ts

@@ -1,11 +1,11 @@
-import type { Agent } from '../core/agent.js';
 import type { AgentFactory } from '../coordination/agent-subagent-runner.js';
 import type { DispatchClassifier } from '../coordination/dispatcher.js';
+import { DefaultMultiAgentCoordinator } from '../coordination/multi-agent-coordinator.js';
+import type { Agent } from '../core/agent.js';
 import type { EventBus } from '../kernel/events.js';
-import type { Logger } from '../types/logger.js';
 import type { JournalEntry } from '../storage/goal-store.js';
 import type { Compactor } from '../types/compactor.js';
-import { DefaultMultiAgentCoordinator } from '../coordination/multi-agent-coordinator.js';
+import type { Logger } from '../types/logger.js';
 export type ParallelEngineState = 'idle' | 'running' | 'stopped';
 export type ParallelIterationStage = {
     phase: 'idle';
@@ -50,12 +50,12 @@ export interface ParallelEternalOptions {
     parallelSlots?: number | undefined;
     /** Per-subagent default timeout in ms. Default: 300_000 (5 min). */
     iterationTimeoutMs?: number | undefined;
-    onIteration?: (((entry: JournalEntry) => void)) | undefined;
+    onIteration?: ((entry: JournalEntry) => void) | undefined;
     onError?: (err: Error | undefined, iteration: number) => void;
     /** Per-tick phase notifications for live UI/status updates. */
-    onStage?: (((stage: ParallelIterationStage) => void)) | undefined;
-    gitStatusReader?: ((() => Promise<string>)) | undefined;
-    now?: ((() => Date)) | undefined;
+    onStage?: ((stage: ParallelIterationStage) => void) | undefined;
+    gitStatusReader?: (() => Promise<string>) | undefined;
+    now?: (() => Date) | undefined;
     compactor?: Compactor | undefined;
     compactEveryNIterations?: number | undefined;
     aggressiveCompactRatio?: number | undefined;

package/dist/execution/prompt-enhancer.js

@@ -1,538 +1,19 @@
-// src/types/blocks.ts
-function isTextBlock(b) {
-  return b.type === "text";
-}
-
-// src/utils/error.ts
-function toErrorMessage(err) {
-  return err instanceof Error ? err.message : String(err);
-}
-
-// src/utils/instruction-file.ts
-import { readFileSync, statSync } from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-var textCache = /* @__PURE__ */ new Map();
-var rootCandidates;
-function readBundledInstructionText(relativePath) {
-  const cached = textCache.get(relativePath);
-  if (cached !== void 0) return cached;
-  let resolved = "";
-  for (const root of instructionRootCandidates()) {
-    try {
-      resolved = readFileSync(path.join(root, relativePath), "utf8").trimEnd();
-      break;
-    } catch {
-    }
-  }
-  textCache.set(relativePath, resolved);
-  return resolved;
-}
-function instructionRootCandidates() {
-  if (rootCandidates !== void 0) return rootCandidates;
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  const candidates = [
-    path.resolve(here, "../../instructions"),
-    path.resolve(here, "../instructions"),
-    path.resolve(here, "instructions")
-  ];
-  rootCandidates = candidates.sort((a, b) => Number(!isDirectory(a)) - Number(!isDirectory(b)));
-  return rootCandidates;
-}
-function isDirectory(candidate) {
-  try {
-    return statSync(candidate).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-// src/execution/prompt-enhancer.ts
-var ENHANCER_SYSTEM_PROMPT = readBundledInstructionText("llm/prompt-enhancer.md");
-var AFFIRMATION_RE = /^(y|n|yes|no|yep|nope|ok|okay|sure|go|go ahead|continue|proceed|stop|cancel|done|next|skip|retry|again|please do|do it)\b[.! ]*$/i;
-function shouldEnhance(text) {
-  const t = text.trim();
-  if (!t) return false;
-  if (t.startsWith("/")) return false;
-  if (t.length < 12) return false;
-  if (AFFIRMATION_RE.test(t)) return false;
-  if (/^[\d\s.,]+$/.test(t)) return false;
-  const words = t.split(/\s+/).filter(Boolean);
-  if (words.length < 3) return false;
-  return true;
-}
-var EFFORT_PREFERENCE = [
-  "low",
-  "minimal",
-  "medium",
-  "high",
-  "xhigh",
-  "max",
-  "none"
-];
-function gatedEnhancerReasoning(rc) {
-  if (!rc) return void 0;
-  if (rc.effortSupported && rc.effortLevels.length > 0) {
-    const lowest = EFFORT_PREFERENCE.find((e) => rc.effortLevels.includes(e)) ?? rc.effortLevels[0];
-    if (lowest) return { effort: lowest };
-  }
-  if (rc.disableSupported) return { enabled: false };
-  return void 0;
-}
-function normalizedEqual(a, b) {
-  const norm = (s) => s.trim().replace(/\s+/g, " ").toLowerCase();
-  return norm(a) === norm(b);
-}
-var ENGLISH_PROMPT_WORDS = /* @__PURE__ */ new Set([
-  "a",
-  "add",
-  "analyze",
-  "and",
-  "api",
-  "as",
-  "build",
-  "change",
-  "check",
-  "code",
-  "configure",
-  "create",
-  "delete",
-  "document",
-  "ensure",
-  "error",
-  "explain",
-  "failure",
-  "feature",
-  "file",
-  "fix",
-  "for",
-  "from",
-  "function",
-  "implement",
-  "improve",
-  "in",
-  "into",
-  "is",
-  "issue",
-  "it",
-  "keep",
-  "make",
-  "model",
-  "of",
-  "only",
-  "output",
-  "parser",
-  "preserve",
-  "prompt",
-  "race",
-  "refactor",
-  "remove",
-  "request",
-  "resolve",
-  "response",
-  "return",
-  "run",
-  "should",
-  "test",
-  "that",
-  "the",
-  "this",
-  "to",
-  "translate",
-  "update",
-  "use",
-  "validate",
-  "version",
-  "when",
-  "with",
-  "write",
-  "condition"
-]);
-var NON_ENGLISH_PROMPT_WORDS = /* @__PURE__ */ new Set([
-  // Turkish
-  "ama",
-  "bir",
-  "bu",
-  "de",
-  "d\xFCzelt",
-  "et",
-  "hata",
-  "hatas\u0131n\u0131",
-  "hatay\u0131",
-  "i\xE7in",
-  "ile",
-  "olarak",
-  "sadece",
-  "ve",
-  "yap",
-  "\u015Fu",
-  // Spanish / Portuguese
-  "con",
-  "corrige",
-  "debe",
-  "el",
-  "en",
-  "erro",
-  "la",
-  "para",
-  "que",
-  "sin",
-  "una",
-  // French
-  "avec",
-  "dans",
-  "des",
-  "doit",
-  "erreur",
-  "et",
-  "le",
-  "les",
-  "pour",
-  "sans",
-  "une",
-  // German
-  "das",
-  "den",
-  "der",
-  "die",
-  "ein",
-  "fehler",
-  "f\xFCr",
-  "mit",
-  "ohne",
-  "und"
-]);
-function languageWords(text) {
-  return text.replaceAll("\u0130", "i").toLowerCase().match(/\p{L}+/gu) ?? [];
-}
-function hasNonLatinScript(text) {
-  return /[\p{Script=Arabic}\p{Script=Cyrillic}\p{Script=Han}\p{Script=Hangul}\p{Script=Hiragana}\p{Script=Katakana}]/u.test(
-    text
-  );
-}
-function languageScores(text) {
-  const words = languageWords(text);
-  let english = 0;
-  let nonEnglish = 0;
-  for (const word of words) {
-    if (ENGLISH_PROMPT_WORDS.has(word)) english++;
-    if (NON_ENGLISH_PROMPT_WORDS.has(word)) nonEnglish++;
-  }
-  if (/[çğıöşüİı]/u.test(text)) nonEnglish += 2;
-  if (hasNonLatinScript(text)) nonEnglish += 3;
-  return { english, nonEnglish, words };
-}
-function isValidEnglishRefinement(text) {
-  const trimmed = text.trim();
-  if (!trimmed) return false;
-  const scores = languageScores(trimmed);
-  return scores.nonEnglish === 0 && scores.english > 0;
-}
-var VIBE_TAG_PATTERN = /\[vibe\]/iu;
-function preserveVibeTag(original, candidate) {
-  if (!VIBE_TAG_PATTERN.test(original) || VIBE_TAG_PATTERN.test(candidate)) return candidate;
-  return `[VIBE] ${candidate}`;
-}
-function latestMessageLanguage(text) {
-  const scores = languageScores(text);
-  if (scores.nonEnglish > scores.english) return "non_english";
-  if (scores.english > scores.nonEnglish) return "english";
-  return "unknown";
-}
-function parseBilingualEnhancement(raw, original) {
-  const separator = /^[\t \u00a0\u200b-\u200d\ufeff]*---[\t \u00a0\u200b-\u200d\ufeff]*\r?$/gm;
-  const matches = [...raw.matchAll(separator)];
-  if (matches.length !== 1) return null;
-  const [match] = matches;
-  if (!match) return null;
-  const rawRefined = raw.slice(0, match.index).trim();
-  const rawEnglish = raw.slice(match.index + match[0].length).trim();
-  if (!rawRefined || !rawEnglish) return null;
-  const refined = preserveVibeTag(original, rawRefined);
-  const english = preserveVibeTag(original, rawEnglish);
-  if (!isValidEnglishRefinement(english)) return null;
-  const inputLanguage = latestMessageLanguage(original);
-  const refinedLanguage = latestMessageLanguage(refined);
-  if (inputLanguage === "non_english" && refinedLanguage === "english") return null;
-  if (inputLanguage === "unknown" && refinedLanguage === "unknown") return null;
-  return { refined, english };
-}
-var DEFAULT_REFINER_RETRY_FEEDBACK = "Make another pass that is sharper and more self-contained. Use the provided project memory, current session context, and recent conversation only to resolve references and preserve project vocabulary; keep the original scope unchanged.";
-function buildRefinerInput(text, history, contextSections, previousRefinement, retryFeedback) {
-  const parts = [];
-  const renderedContext = renderRefinerContextSections(contextSections);
-  if (renderedContext) parts.push(renderedContext);
-  if (previousRefinement || retryFeedback) {
-    const retryLines = [
-      "Retry context (context only - the user asked for another refinement pass):"
-    ];
-    if (previousRefinement?.refined) {
-      retryLines.push(`Previous refined version: ${compactText(previousRefinement.refined, 900)}`);
-    }
-    if (previousRefinement?.english && previousRefinement.english.trim() !== previousRefinement.refined.trim()) {
-      retryLines.push(`Previous English version: ${compactText(previousRefinement.english, 900)}`);
-    }
-    retryLines.push(`Retry instruction: ${retryFeedback ?? DEFAULT_REFINER_RETRY_FEEDBACK}`);
-    parts.push(retryLines.join("\n"));
-  }
-  if (history && history.length > 0) {
-    const lines = history.map((t) => `${t.role === "user" ? "User" : "Assistant"}: ${t.text}`);
-    parts.push(
-      [
-        "Recent conversation (context only - do not act on it):",
-        ...lines
-      ].join("\n")
-    );
-  }
-  if (parts.length === 0) return text;
-  return [
-    ...parts,
-    "",
-    "Latest message to refine:",
-    text
-  ].join("\n\n");
-}
-function renderRefinerContextSections(contextSections) {
-  const sections = (contextSections ?? []).map((section) => ({
-    title: section.title.trim(),
-    items: section.items.map((item) => compactText(item, 360)).filter(Boolean)
-  })).filter((section) => section.title && section.items.length > 0);
-  if (sections.length === 0) return void 0;
-  const lines = [
-    "Additional project/session context (context only - use to resolve references, conventions, and constraints; do not add new requirements):"
-  ];
-  for (const section of sections) {
-    lines.push("", `${section.title}:`);
-    for (const item of section.items) lines.push(`- ${item}`);
-  }
-  return lines.join("\n");
-}
-function compactText(text, maxChars) {
-  const compacted = text.replace(/\s+/g, " ").trim();
-  if (compacted.length <= maxChars) return compacted;
-  return `${compacted.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
-}
-function unknownString(value) {
-  return typeof value === "string" && value.trim() ? value.trim() : void 0;
-}
-function iterableStrings(value) {
-  if (!value || typeof value === "string") return [];
-  if (Array.isArray(value)) {
-    return value.flatMap((item) => {
-      const text = unknownString(item);
-      return text ? [text] : [];
-    });
-  }
-  if (value instanceof Set) {
-    return [...value].flatMap((item) => {
-      const text = unknownString(item);
-      return text ? [text] : [];
-    });
-  }
-  if (typeof value === "object" && typeof value[Symbol.iterator] === "function") {
-    try {
-      return Array.from(value).flatMap((item) => {
-        const text = unknownString(item);
-        return text ? [text] : [];
-      });
-    } catch {
-      return [];
-    }
-  }
-  return [];
-}
-function lastItems(values, maxItems) {
-  return values.slice(Math.max(0, values.length - maxItems));
-}
-function todoLines(value, maxItems) {
-  if (!Array.isArray(value)) return [];
-  const open = value.filter((item) => {
-    if (!item || typeof item !== "object") return false;
-    const status = item["status"];
-    return status === "pending" || status === "in_progress";
-  });
-  return open.slice(0, maxItems).flatMap((todo) => {
-    const content = unknownString(todo["activeForm"]) ?? unknownString(todo["content"]);
-    if (!content) return [];
-    return [`open todo (${String(todo["status"])}): ${compactText(content, 220)}`];
-  });
-}
-function buildRefinerSessionContextSection(context) {
-  if (!context) return void 0;
-  const items = [];
-  const projectRoot = unknownString(context.projectRoot);
-  const workingDir = unknownString(context.workingDir) ?? unknownString(context.cwd);
-  if (projectRoot) items.push(`project root: ${projectRoot}`);
-  if (workingDir && workingDir !== projectRoot) items.push(`working dir: ${workingDir}`);
-  for (const file of lastItems(iterableStrings(context.readFiles), 6)) {
-    items.push(`recently read file: ${file}`);
-  }
-  for (const file of lastItems(iterableStrings(context.writtenFiles), 6)) {
-    items.push(`recently written file: ${file}`);
-  }
-  items.push(...todoLines(context.todos, 6));
-  return items.length > 0 ? { title: "Current session state", items } : void 0;
-}
-function formatMemoryEntry(entry) {
-  const meta = [entry.scope, entry.type, entry.priority].filter(Boolean).join("/");
-  const tags = entry.tags && entry.tags.length > 0 ? ` tags: ${entry.tags.slice(0, 5).join(", ")}` : "";
-  return `${meta ? `[${meta}] ` : ""}${compactText(entry.text, 260)}${tags}`;
-}
-async function collectMemoryEntries(memoryStore, text, scope, limit) {
-  const scored = memoryStore.scoreRelevant ? await memoryStore.scoreRelevant({ currentTask: text }, scope, limit).catch(() => []) : [];
-  if (scored.length > 0) return scored;
-  return memoryStore.search(text || "prompt refinement", scope, limit).catch(() => []);
-}
-async function buildRefinerMemoryContextSection(memoryStore, text) {
-  if (!memoryStore) return void 0;
-  const seen = /* @__PURE__ */ new Set();
-  const entries = [];
-  for (const scope of ["project-memory", "user-memory"]) {
-    const remaining = Math.max(0, 6 - entries.length);
-    if (remaining === 0) break;
-    for (const entry of await collectMemoryEntries(memoryStore, text.trim(), scope, remaining)) {
-      const key = `${entry.scope}:${entry.text}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      entries.push(entry);
-      if (entries.length >= 6) break;
-    }
-  }
-  if (entries.length === 0) return void 0;
-  return { title: "Relevant project memory", items: entries.map(formatMemoryEntry) };
-}
-async function buildRefinerContextSections(opts) {
-  const sections = [];
-  const memory = await buildRefinerMemoryContextSection(opts.memoryStore, opts.text);
-  if (memory) sections.push(memory);
-  const session = buildRefinerSessionContextSection(opts.context);
-  if (session) sections.push(session);
-  return sections;
-}
-async function completeRefinerPass(input, opts) {
-  if (opts.oneShotOrchestrator) {
-    const result = await opts.oneShotOrchestrator.call({
-      system: ENHANCER_SYSTEM_PROMPT,
-      messages: [{ role: "user", content: input }],
-      maxTokens: opts.request.maxTokens,
-      timeoutMs: opts.timeoutMs,
-      signal: opts.signal
-    });
-    return result.error ? { text: "", error: result.error } : { text: result.text.trim() };
-  }
-  const response = await opts.provider.complete(
-    { ...opts.request, messages: [{ role: "user", content: input }] },
-    { signal: opts.signal }
-  );
-  return {
-    text: response.content.filter(isTextBlock).map((block) => block.text).join("\n").trim()
-  };
-}
-async function enhanceUserPrompt(opts) {
-  const { provider, model, text } = opts;
-  const timeoutMs = opts.timeoutMs ?? 9e4;
-  const maxTokens = opts.maxTokens ?? 2048;
-  const refinerInput = buildRefinerInput(
-    text,
-    opts.history,
-    opts.contextSections,
-    opts.previousRefinement,
-    opts.retryFeedback
-  );
-  const req = {
-    model,
-    system: [{ type: "text", text: ENHANCER_SYSTEM_PROMPT }],
-    messages: [{ role: "user", content: refinerInput }],
-    maxTokens,
-    // NOTE: deliberately NO `temperature`. The main agent loop never sets it,
-    // and reasoning models (DeepSeek reasoner, o1/o3, …) return HTTP 400 when
-    // `temperature` is present — which would make every refine call fail and
-    // silently fall back to the original (no panel shown).
-    //
-    // A reasoning hint is forwarded ONLY when the caller supplies one (it must
-    // already be gated to the model's advertised support — see
-    // `gatedEnhancerReasoning`). Absent it, no reasoning field is sent, which
-    // is identical to the original behavior.
-    ...opts.reasoning ? { reasoning: opts.reasoning } : {}
-  };
-  let timedOut = false;
-  const runPass = async (input) => {
-    const timer = new AbortController();
-    const timeout = setTimeout(() => timer.abort(new Error("enhancer timeout")), timeoutMs);
-    const signal = opts.signal ? AbortSignal.any([opts.signal, timer.signal]) : timer.signal;
-    try {
-      return await completeRefinerPass(input, {
-        provider,
-        oneShotOrchestrator: opts.oneShotOrchestrator,
-        request: req,
-        signal,
-        timeoutMs
-      });
-    } catch (error) {
-      if (timer.signal.aborted && !opts.signal?.aborted) timedOut = true;
-      throw error;
-    } finally {
-      timer.abort();
-      clearTimeout(timeout);
-    }
-  };
-  try {
-    const first = await runPass(refinerInput);
-    if (first.error) {
-      opts.onError?.(first.error, "provider_error");
-      return null;
-    }
-    const parsed = parseBilingualEnhancement(first.text, text);
-    if (parsed) return parsed;
-    const correctionInput = [
-      "Your previous response did not satisfy the required bilingual output contract.",
-      'Return exactly two non-empty versions separated by one line containing only "---".',
-      "The first version must match the language of the latest message. The second version must be English.",
-      "Do not add labels, headings, fences, commentary, or additional separators.",
-      "",
-      `Latest message to refine:
-${text}`,
-      "",
-      `Invalid previous response:
-${compactText(first.text || "(empty response)", 1800)}`
-    ].join("\n");
-    const corrected = await runPass(correctionInput);
-    if (corrected.error) {
-      opts.onError?.(corrected.error, "provider_error");
-      return null;
-    }
-    const correctedParsed = parseBilingualEnhancement(corrected.text, text);
-    if (correctedParsed) return correctedParsed;
-    opts.onError?.("model returned malformed bilingual output after one corrective retry", "empty");
-    return null;
-  } catch (err) {
-    if (opts.signal?.aborted) return null;
-    if (timedOut) {
-      opts.onError?.(`timed out after ${Math.round(timeoutMs / 1e3)}s`, "timeout");
-      return null;
-    }
-    opts.onError?.(toErrorMessage(err), "provider_error");
-    return null;
-  }
-}
-function messageText(content) {
-  if (typeof content === "string") return content;
-  return content.filter(isTextBlock).map((b) => b.text).join("\n").trim();
-}
-function recentTextTurns(messages, maxTurns = 6, maxChars = 1500) {
-  const turns = [];
-  for (let i = messages.length - 1; i >= 0 && turns.length < maxTurns; i--) {
-    const m = messages[i];
-    if (!m || m.role !== "user" && m.role !== "assistant") continue;
-    const text = messageText(m.content);
-    if (!text) continue;
-    turns.unshift({
-      role: m.role,
-      text: text.length > maxChars ? `${text.slice(0, maxChars - 1)}\u2026` : text
-    });
-  }
-  return turns;
-}
+import {
+  DEFAULT_REFINER_RETRY_FEEDBACK,
+  ENHANCER_SYSTEM_PROMPT,
+  buildRefinerContextSections,
+  completeRefinerPass,
+  enhanceUserPrompt,
+  gatedEnhancerReasoning,
+  isValidEnglishRefinement,
+  normalizedEqual,
+  parseBilingualEnhancement,
+  recentTextTurns,
+  shouldEnhance
+} from "../chunk-5XDUGTKN.js";
+import "../chunk-5S437PRC.js";
+import "../chunk-O37BQ65S.js";
+import "../chunk-TBRL2RCC.js";
 export {
   DEFAULT_REFINER_RETRY_FEEDBACK,
   ENHANCER_SYSTEM_PROMPT,

package/dist/execution/retry-policy.d.ts

@@ -27,6 +27,35 @@ import type { RetryPolicy } from '../types/retry-policy.js';
  *   kind IS fallback-worthy, so another provider gets tried immediately.
  */
 export declare const MODEL_RETRIES = 3;
+/**
+ * First-retry wait for the exponential schedule, in ms.
+ *
+ * The schedule is `RETRY_BASE_DELAY_MS * 2^attempt + jitter`, so with a
+ * base of 4s and {@link MODEL_RETRIES} attempts a struggling route waits
+ * 4s → 8s → 16s before the turn hands over to the fallback chain.
+ *
+ * It used to be 1000 (1s → 2s → 4s). That schedule was too eager for the
+ * failure it actually fires on: a provider that just refused a request
+ * because of a network blip, an overload, or a burst-rate window is
+ * almost never healthy again 1 second later, so the first two retries
+ * mostly bought another two failures — three requests hammered out inside
+ * ~7 seconds — and then reported the same error anyway. Starting at 4s
+ * gives the far side a realistic window to recover, and still exhausts
+ * all three in-place attempts in well under half a minute.
+ *
+ * NOTE: this is only the *fallback* schedule. A provider that sends a
+ * `Retry-After` still wins outright (see {@link DefaultRetryPolicy.delayMs}).
+ */
+export declare const RETRY_BASE_DELAY_MS = 4000;
+/**
+ * Width of the uniform jitter added to every exponential wait, in ms.
+ *
+ * Deliberately decoupled from {@link RETRY_BASE_DELAY_MS}: jitter exists to
+ * de-synchronise concurrent agents retrying the same route, and one second
+ * of spread is plenty for that. Scaling it with the base would have turned
+ * the first retry into a 4–8s coin flip for no added benefit.
+ */
+export declare const RETRY_JITTER_MS = 1000;
 export declare class DefaultRetryPolicy implements RetryPolicy {
     shouldRetry(err: Error | ProviderError, attempt: number): boolean;
     maxAttempts(err: Error | ProviderError): number;
@@ -39,7 +68,8 @@ export declare class DefaultRetryPolicy implements RetryPolicy {
      *      [0, MAX_RETRY_AFTER_MS]. The provider told us exactly when
      *      to come back; we should listen.
      *   2. Otherwise fall through to the exponential-with-jitter
-     *      schedule (`1000 * 2^attempt + jitter`, capped at 30s).
+     *      schedule (`RETRY_BASE_DELAY_MS * 2^attempt + jitter`, capped
+     *      at 30s) — 4s → 8s → 16s for the three in-place attempts.
      *
      * `err` is optional for back-compat with the existing interface;
      * callers should pass it whenever available.