@yycholla/pi-dynamic-workflows 3.3.0

package/dist/task-panel.js

@@ -0,0 +1,422 @@
+/**
+ * Background-run UX, mirroring Claude Code:
+ *  - A live task panel below the input lists in-progress runs while you keep working.
+ *    It is informational; run /workflows to open the full navigator.
+ *  - When a background run finishes, its result is delivered back into the
+ *    conversation so the paused task continues with the outcome.
+ */
+import { join } from "node:path";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { aggregateAgentUsage, fmtCost, fmtTokenSegment, shorten, statusIcon, tokenFigures, } from "./display.js";
+import { shortModel } from "./workflow-ui.js";
+// `tokenUsage` is included so the detailed panel's live token/s counter refreshes
+// as tokens accrue (not only on agent start/end). It is harmless in compact mode —
+// it redraws identical content.
+const RUN_EVENTS = [
+    "agentStart",
+    "agentEnd",
+    "phase",
+    "log",
+    "tokenUsage",
+    "complete",
+    "error",
+    "stopped",
+    "paused",
+    "resumed",
+];
+/** Events after which a run is gone and its token-rate samples can be dropped. */
+const RUN_END_EVENTS = ["complete", "error", "stopped"];
+/** Default cap on the JSON-dump fallback in a delivered result summary. Overridable
+ *  via the `deliveredResultMaxChars` setting in ~/.pi/workflows/settings.json. */
+const DEFAULT_DELIVERED_MAX_CHARS = 400;
+/** Human-readable byte size for the dropped-tail hint: 512 B, 3.2 KB, 1.4 MB. */
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * Pick a clean human-readable summary from a workflow result, in order of
+ * preference: a `verdict`/`report`/`summary`/`synthesis` string field, a bare
+ * string result, else a JSON dump capped at `maxChars`. When the dump is truncated the
+ * dropped size is reported (the full result is still reachable via the pointer
+ * that {@link deliverText} appends).
+ */
+function summarizeResult(result, maxChars = DEFAULT_DELIVERED_MAX_CHARS) {
+    if (typeof result === "string")
+        return result;
+    if (result == null)
+        return "null";
+    if (typeof result === "object") {
+        const obj = result;
+        // `synthesis` is what the built-in multi-perspective workflow returns.
+        for (const key of ["verdict", "report", "summary", "synthesis"]) {
+            const val = obj[key];
+            if (typeof val === "string" && val.trim())
+                return val;
+        }
+    }
+    const json = JSON.stringify(result, null, 2);
+    if (json.length <= maxChars)
+        return json;
+    // Slice once (the kept head); derive the dropped size by byte-length subtraction
+    // so we don't also allocate the (potentially large) truncated tail to measure it.
+    const kept = json.slice(0, maxChars);
+    const droppedBytes = Buffer.byteLength(json, "utf8") - Buffer.byteLength(kept, "utf8");
+    return `${kept}\n…(truncated ${formatBytes(droppedBytes)})`;
+}
+function fitLine(line, width) {
+    if (typeof width !== "number" || !Number.isFinite(width))
+        return line;
+    const maxWidth = Math.max(0, Math.floor(width));
+    if (visibleWidth(line) <= maxWidth)
+        return line;
+    return truncateToWidth(line, maxWidth);
+}
+export function deliverText(run, opts = {}) {
+    const summary = summarizeResult(run.result?.result, opts.maxChars);
+    const tu = run.result?.tokenUsage;
+    const cost = tu?.cost ? ` · ${fmtCost(tu.cost)}` : "";
+    const segment = fmtTokenSegment(tokenFigures(tu), fmtTokensShort);
+    const tokens = `${segment ? ` · ${segment}` : ""}${cost}`;
+    const agents = run.result?.agentCount ?? run.snapshot.agentCount;
+    const duration = run.result?.durationMs ? ` · ${(run.result.durationMs / 1000).toFixed(1)}s` : "";
+    const lines = [
+        `✓ Background workflow "${run.snapshot.name}" finished (${agents} agents${tokens}${duration}).`,
+        "",
+        summary,
+    ];
+    // Always point at the full persisted result so the tail is never lost — even when
+    // the summary above is a complete verdict/summary field or an untruncated dump.
+    if (opts.resultPath)
+        lines.push("", `↳ Full result: ${opts.resultPath}`);
+    return lines.join("\n");
+}
+/** Absolute path to a run's persisted result JSON. Undefined if the persistence
+ *  layer can't be resolved — delivery must never throw in the complete handler. */
+function persistedResultPath(manager, runId) {
+    try {
+        return join(manager.getPersistence().getRunsDir(), `${runId}.json`);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Delivered JSON-dump truncation threshold from settings (already normalized),
+ *  defaulting to 400 when unset or unreadable. */
+function deliveredMaxChars(opts) {
+    try {
+        return opts.loadSettings?.().deliveredResultMaxChars ?? DEFAULT_DELIVERED_MAX_CHARS;
+    }
+    catch {
+        return DEFAULT_DELIVERED_MAX_CHARS;
+    }
+}
+/**
+ * When a background run finishes (or fails), deliver its result back into the
+ * conversation AND continue the turn so the assistant can act on it — without
+ * blocking the user meanwhile:
+ *
+ *  - `triggerTurn: true` starts a fresh turn when the agent is idle, feeding the
+ *    result to the model so the paused conversation continues.
+ *  - `deliverAs: "followUp"` means that if the user is busy in another turn, the
+ *    result is queued and picked up after that turn finishes — never interrupting.
+ *
+ * Set up once per extension; idempotent via an internal guard.
+ */
+export function installResultDelivery(pi, manager, opts = {}) {
+    // Mutable holder on the manager shared by extension generations across /reload.
+    const m = manager;
+    if (m.__deliveryInstalled) {
+        // The manager and listeners survive /reload. Refresh every generation-bound
+        // dependency while leaving listener registration exactly-once.
+        if (m.__holder) {
+            m.__holder.pi = pi;
+            m.__holder.loadSettings = opts.loadSettings;
+        }
+        return;
+    }
+    m.__deliveryInstalled = true;
+    m.__holder = { pi, loadSettings: opts.loadSettings };
+    const deliver = (content) => {
+        try {
+            const ret = m.__holder?.pi.sendMessage({ customType: "workflow-result", content, display: true }, { triggerTurn: true, deliverAs: "followUp" });
+            // sendMessage may return a promise; a sync try/catch can't catch its
+            // rejection, so swallow the async path too. A stale ctx after /reload is
+            // the expected failure — the result is still visible via /workflows.
+            void Promise.resolve(ret).catch(() => { });
+        }
+        catch {
+            // Synchronous failure (e.g. stale ctx) — result still visible via /workflows.
+        }
+    };
+    manager.on("complete", ({ runId }) => {
+        const run = manager.getRun(runId);
+        // Only background/resumed runs are delivered: a foreground (sync) run already
+        // returns its result inline as the tool result, so re-delivering would dup it.
+        if (run?.background) {
+            deliver(deliverText(run, {
+                resultPath: persistedResultPath(manager, runId),
+                maxChars: deliveredMaxChars({ loadSettings: m.__holder?.loadSettings }),
+            }));
+        }
+    });
+    manager.on("error", ({ runId, error }) => {
+        if (!manager.getRun(runId)?.background)
+            return;
+        deliver(`✗ Background workflow ${runId} failed: ${error?.message ?? "unknown error"}`);
+    });
+    // A provider usage/quota limit checkpoints the run as paused (not failed): tell the
+    // user it is resumable once their budget refills, rather than letting it look dead.
+    // Manual pause() also emits "paused" but with no reason — guard so only the
+    // usage-limit case delivers a message.
+    manager.on("paused", ({ runId, reason, error, resetHint, }) => {
+        if (reason !== "usage_limit")
+            return;
+        if (!manager.getRun(runId)?.background)
+            return;
+        const when = resetHint ? ` (${resetHint})` : "";
+        const cause = error?.message ?? "provider usage limit reached";
+        deliver(`⏸ Background workflow ${runId} paused: ${cause}${when}. ` +
+            `Completed steps are saved — run /workflows resume ${runId} once your usage limit resets.`);
+    });
+}
+export function renderPanel(manager, theme, width) {
+    const all = manager.listRuns();
+    const active = all.filter((r) => r.status === "running" || r.status === "paused");
+    if (!active.length)
+        return [];
+    const rows = active.map((r) => {
+        const live = manager.getRun(r.runId);
+        const agents = live?.snapshot.agents ?? r.agents;
+        const done = agents.filter((a) => a.status === "done").length;
+        const icon = r.status === "paused" ? "⏸" : "◆";
+        const phase = live?.snapshot.currentPhase ? ` · ${live.snapshot.currentPhase}` : "";
+        return `  ${icon} ${r.workflowName}  ${done}/${agents.length} agents${phase}`;
+    });
+    // Finished runs leave this live panel but are kept in the navigator. Tell the
+    // user so a completed run doesn't look like it vanished.
+    const finished = all.filter((r) => r.status !== "running" && r.status !== "paused").length;
+    const hint = theme.fg("dim", finished > 0
+        ? `  /workflows — open navigator (${finished} finished kept in history)`
+        : "  /workflows — open navigator");
+    return [theme.bold(`Workflows running (${active.length}):`), ...rows, hint].map((line) => fitLine(line, width));
+}
+// ─── Detailed mode: live token rate ────────────────────────────────────────────
+/** Rolling window for the token/s rate. Older samples age out so a stall decays to 0. */
+const RATE_WINDOW_MS = 10_000;
+/** Per-run (timestamp, cumulative total) samples, keyed by the persisted runId so
+ *  the rolling rate survives pause→resume. Cleared when a run ends. */
+const tokenSamples = new Map();
+/** Record a token-total sample for `runId` at time `now` (ms). */
+export function sampleTokens(runId, total, now) {
+    const samples = tokenSamples.get(runId) ?? [];
+    const last = samples[samples.length - 1];
+    // Collapse repeat renders within the same instant (e.g. width recalcs).
+    if (last && last.ts === now && last.total === total)
+        return;
+    samples.push({ ts: now, total });
+    // Drop samples beyond the rolling window, always keeping ≥2 so a rate is computable.
+    while (samples.length > 2 && now - samples[0].ts > RATE_WINDOW_MS)
+        samples.shift();
+    tokenSamples.set(runId, samples);
+}
+/** Tokens/second over the rolling window; 0 when too few samples or totals plateau. */
+export function tokensPerSecond(runId) {
+    const samples = tokenSamples.get(runId);
+    if (!samples || samples.length < 2)
+        return 0;
+    const oldest = samples[0];
+    const newest = samples[samples.length - 1];
+    const elapsedMs = newest.ts - oldest.ts;
+    if (elapsedMs <= 0)
+        return 0;
+    const delta = newest.total - oldest.total;
+    if (delta <= 0)
+        return 0;
+    return (delta / elapsedMs) * 1000;
+}
+/** Forget a run's samples (call when it finishes) so the map can't grow unbounded. */
+export function clearTokenSamples(runId) {
+    tokenSamples.delete(runId);
+}
+/** Compact token count for the space-constrained panel: 980, 12.4K, 1.3M. */
+function fmtTokensShort(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return "";
+    if (n < 1000)
+        return `${Math.round(n)}`;
+    if (n < 1_000_000)
+        return `${(n / 1000).toFixed(1)}K`;
+    return `${(n / 1_000_000).toFixed(1)}M`;
+}
+/** Normalize the configured per-phase agent cap to a sane integer (default 8). */
+export function clampMaxAgents(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 1)
+        return 8;
+    return Math.min(1000, Math.floor(value));
+}
+/** Per-phase + per-agent body for one run in detailed mode (mirrors renderWorkflowLines). */
+function renderRunBody(snap, agents, maxAgents, theme) {
+    const dim = (t) => theme.fg("dim", t);
+    const lines = [];
+    // Group agents by phase, declared order first then discovery order (as the navigator does).
+    const order = snap.phases.length ? [...snap.phases] : [];
+    const byPhase = new Map();
+    for (const a of agents) {
+        const key = a.phase ?? "(no phase)";
+        if (!byPhase.has(key))
+            byPhase.set(key, []);
+        byPhase.get(key)?.push(a);
+        if (!order.includes(key))
+            order.push(key);
+    }
+    for (const title of order) {
+        const phaseAgents = byPhase.get(title) ?? [];
+        if (!phaseAgents.length)
+            continue;
+        const done = phaseAgents.filter((a) => a.status === "done").length;
+        const running = phaseAgents.filter((a) => a.status === "running").length;
+        const errors = phaseAgents.filter((a) => a.status === "error").length;
+        const skipped = phaseAgents.filter((a) => a.status === "skipped").length;
+        const complete = done + errors + skipped === phaseAgents.length;
+        const marker = running > 0 || (!complete && snap.currentPhase === title) ? "▶" : complete ? "✓" : " ";
+        const phaseMeta = [
+            `${done}/${phaseAgents.length} agents`,
+            running ? `${running} running` : "",
+            errors ? `${errors} errors` : "",
+            fmtTokenSegment(aggregateAgentUsage(phaseAgents), fmtTokensShort),
+        ]
+            .filter(Boolean)
+            .join(" · ");
+        lines.push(theme.fg("accent", `  ${marker} ${title}`) + dim(`  ${phaseMeta}`));
+        const visible = phaseAgents.slice(-maxAgents);
+        for (const a of visible) {
+            const segment = fmtTokenSegment(tokenFigures(a.tokenUsage, a.tokens), fmtTokensShort);
+            const tok = segment ? dim(` ${segment}`) : "";
+            const mdl = shortModel(a.model);
+            const model = mdl ? dim(` · ${mdl}`) : "";
+            lines.push(`    [${a.id}] ${statusIcon(a.status)} ${shorten(a.label, 40)}${tok}${model}`);
+        }
+        if (phaseAgents.length > visible.length) {
+            lines.push(dim(`    … ${phaseAgents.length - visible.length} earlier agents`));
+        }
+    }
+    return lines;
+}
+/**
+ * Detailed variant of {@link renderPanel}: per-run header with aggregate tokens,
+ * cost, and a live token/s rate, followed by per-phase progress and per-agent rows
+ * (capped at `maxAgents` per phase). `now` is injected for testability.
+ */
+export function renderPanelDetailed(manager, theme, width, maxAgents, now) {
+    const all = manager.listRuns();
+    const active = all.filter((r) => r.status === "running" || r.status === "paused");
+    if (!active.length)
+        return [];
+    const dim = (t) => theme.fg("dim", t);
+    const out = [theme.bold(`Workflows running (${active.length}):`)];
+    for (const r of active) {
+        const live = manager.getRun(r.runId);
+        const snap = live?.snapshot;
+        const agents = (snap?.agents ?? r.agents);
+        const done = agents.filter((a) => a.status === "done").length;
+        const icon = r.status === "paused" ? "⏸" : "◆";
+        const usage = snap?.tokenUsage ?? r.tokenUsage;
+        // The run-level tokenUsage aggregate is only finalized when the run ends, so
+        // it reads 0 for the whole live run; per-agent figures update on each agent
+        // completion, so aggregate those instead. The rate samples the same
+        // fresh+cacheRead sum the header displays, so tok/s tracks the visible
+        // figures. Tokens land at agent-completion granularity, so the rate reflects
+        // completion throughput — it decays to 0 during a single long-running agent
+        // or a stall (which is the intended signal). Paused runs don't accrue
+        // tokens, so their rate is suppressed (a stalled rate would mislead).
+        const runUsage = aggregateAgentUsage(agents);
+        sampleTokens(r.runId, runUsage.fresh + runUsage.cacheRead, now);
+        const rate = r.status === "running" ? tokensPerSecond(r.runId) : 0;
+        const meta = [
+            `${done}/${agents.length} agents`,
+            snap?.currentPhase || "",
+            fmtTokenSegment(runUsage, fmtTokensShort),
+            // (cost is only known once the run finalizes its usage.)
+            usage?.cost ? fmtCost(usage.cost) : "",
+            rate > 0 ? `${Math.round(rate)} tok/s` : "",
+        ]
+            .filter(Boolean)
+            .join(" · ");
+        out.push(`  ${icon} ${theme.bold(r.workflowName)}  ${dim(meta)}`);
+        if (snap)
+            out.push(...renderRunBody(snap, agents, maxAgents, theme));
+    }
+    const finished = all.filter((r) => r.status !== "running" && r.status !== "paused").length;
+    out.push(dim(finished > 0
+        ? `  /workflows — open navigator (${finished} finished kept in history)`
+        : "  /workflows — open navigator"));
+    return out.map((line) => fitLine(line, width));
+}
+/**
+ * Install the live "workflows running" panel below the editor. Re-rendered on
+ * every manager event. Informational only — the user opens the navigator with
+ * /workflows. (`_pi` is kept for signature stability.)
+ */
+export function installTaskPanel(_pi, manager, ui, opts = {}) {
+    // Live-read settings with a ~1s TTL: a render-path disk read every frame would
+    // be wasteful, but re-reading at most once a second still makes
+    // /workflows-progress take effect "immediately" (no restart).
+    let cached = {};
+    let cachedAt = Number.NEGATIVE_INFINITY;
+    const settings = () => {
+        if (!opts.loadSettings)
+            return cached;
+        const now = Date.now();
+        if (now - cachedAt > 1000) {
+            try {
+                cached = opts.loadSettings() ?? {};
+            }
+            catch {
+                cached = {};
+            }
+            cachedAt = now;
+        }
+        return cached;
+    };
+    const hasActiveRun = () => manager.listRuns().some((r) => r.status === "running" || r.status === "paused");
+    ui.setWidget("workflow-tasks", (tui, theme) => {
+        const onEvent = () => tui.requestRender();
+        for (const ev of RUN_EVENTS)
+            manager.on(ev, onEvent);
+        const onRunEnd = ({ runId }) => clearTokenSamples(runId);
+        for (const ev of RUN_END_EVENTS)
+            manager.on(ev, onRunEnd);
+        // In detailed mode, force a redraw every 2s while a run is active so the
+        // token/s rate keeps updating between sparse token events — and decays to 0
+        // when an agent stalls. Gated + unref'd so it costs nothing when idle.
+        const timer = setInterval(() => {
+            if (settings().progressPanelMode === "detailed" && hasActiveRun())
+                tui.requestRender();
+        }, 2000);
+        timer.unref?.();
+        // Purely informational: it lists running runs and re-renders on events. To
+        // open the navigator, the user runs /workflows (the panel takes no input).
+        const comp = {
+            render: (width) => {
+                const s = settings();
+                if (s.progressPanelMode === "detailed") {
+                    return renderPanelDetailed(manager, theme, width, clampMaxAgents(s.progressPanelMaxAgents), Date.now());
+                }
+                return renderPanel(manager, theme, width);
+            },
+            invalidate: () => { },
+            dispose: () => {
+                clearInterval(timer);
+                for (const ev of RUN_EVENTS)
+                    manager.off(ev, onEvent);
+                for (const ev of RUN_END_EVENTS)
+                    manager.off(ev, onRunEnd);
+            },
+        };
+        return comp;
+    }, { placement: "belowEditor" });
+}

package/dist/usage-limit-scheduler.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Auto-resume for runs paused on a provider usage limit.
+ *
+ * A workflow run pauses (does not fail) when a provider quota/usage limit is hit
+ * (see errors.ts PROVIDER_USAGE_LIMIT, workflow-manager.ts executeRun()'s catch
+ * block). Left alone, the run just sits there until a human runs /workflows and
+ * hits resume. This module watches the manager's public event stream and, for
+ * runs that are auto-resume-eligible, arms a timer to call manager.resume() once
+ * the provider's quota is likely to have refilled — with exponential backoff if
+ * it keeps hitting the wall, and a hard attempt cap so it never retries forever.
+ *
+ * Deliberately standalone: it consumes ONLY WorkflowManager's public surface
+ * (on/off, listAllRuns, resume, getPersistence) so it stays decoupled from
+ * manager/persistence internals. It owns its own timers and its own bookkeeping
+ * (in-memory, best-effort persisted) — it does not rely on manager.stop(), which
+ * only operates on in-memory runs.
+ */
+import type { PersistedRunState, RunPersistence } from "./run-persistence.js";
+/** Narrow surface this scheduler depends on — satisfied by WorkflowManager. */
+export interface SchedulableWorkflowManager {
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    off(event: string, listener: (...args: any[]) => void): unknown;
+    listAllRuns(): PersistedRunState[];
+    resume(runId: string): Promise<boolean>;
+    getPersistence(): RunPersistence;
+}
+/** Opaque timer handle so tests can inject a fake clock/timer. */
+export type TimerHandle = unknown;
+export interface UsageLimitSchedulerOptions {
+    /** Injectable clock (default Date.now). */
+    now?: () => number;
+    /** Injectable timer scheduler (default setTimeout). */
+    setTimer?: (fn: () => void, ms: number) => TimerHandle;
+    /** Injectable timer canceller (default clearTimeout). */
+    clearTimer?: (handle: TimerHandle) => void;
+    /** Max auto-resume attempts per pause-cycle before giving up. Default 5. */
+    maxAttempts?: number;
+    /** Delay floor — never arm sooner than this. Default 60_000 (1m). */
+    minDelayMs?: number;
+    /** Delay used when the provider's resetHint can't be parsed. Default 300_000 (5m). */
+    fallbackDelayMs?: number;
+    /** Delay ceiling — backoff is clamped here. Default 6h. */
+    maxDelayMs?: number;
+    /** Diagnostics sink; defaults to console.warn. Never throws back into the caller. */
+    onDiagnostic?: (message: string, detail?: unknown) => void;
+}
+/**
+ * Best-effort parse of a provider's human reset hint ("Resets in ~3h",
+ * "resets in 5m", "in 90s", "1h30m") into milliseconds. Sums every
+ * (number, unit) pair found, so combined forms like "1h30m" work for free.
+ * Returns undefined when nothing recognizable is found — callers should fall
+ * back to a fixed delay rather than guess.
+ */
+export declare function parseResetHintMs(hint?: string): number | undefined;
+export interface AutoResumeDelayParams {
+    /** The provider's verbatim reset hint for this pause, if any. */
+    resetHint?: string;
+    /** 1-indexed attempt number for the pause currently being armed. */
+    attempts: number;
+    /** Milliseconds already elapsed since the pause began (0 for a live pause). */
+    elapsedMs: number;
+    minDelayMs: number;
+    fallbackDelayMs: number;
+    maxDelayMs: number;
+}
+/**
+ * delay = clamp(minDelayMs, remaining * 2^(attempts-1), maxDelayMs), where
+ * remaining = parsed(resetHint) ?? fallbackDelayMs, minus time already elapsed.
+ * The exponent is capped defensively so a pathological attempt count can't
+ * overflow the multiplication to Infinity/NaN before the maxDelayMs clamp runs.
+ */
+export declare function computeAutoResumeDelayMs(params: AutoResumeDelayParams): number;
+/**
+ * Watches a WorkflowManager for usage-limit pauses and auto-resumes eligible
+ * runs once the provider's quota is likely to have refilled.
+ *
+ * Event-driven "fire and watch": an attempt is consumed when a run ENTERS a
+ * usage_limit pause (live via the "paused" event, or once at cold start for a
+ * run that was already paused), never when a resume is merely fired. When an
+ * armed timer fires, resume() is called; if it returns false (lease busy, run
+ * already gone, etc.) no attempt is consumed and a short un-backed-off retry is
+ * armed instead, unless the run has reached a terminal state on disk. If resume()
+ * returns true, this scheduler steps back — the existing "paused" subscription
+ * re-arms with backoff if the run hits the wall again, and "complete"/"error"/
+ * "stopped" clean up its timer.
+ */
+export declare class UsageLimitScheduler {
+    private readonly manager;
+    private readonly now;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private readonly maxAttempts;
+    private readonly minDelayMs;
+    private readonly fallbackDelayMs;
+    private readonly maxDelayMs;
+    private readonly diagnostic;
+    private readonly state;
+    private disposed;
+    /**
+     * Runs this scheduler is currently auto-resuming (its own timer fired). Used to
+     * tell an auto-resume's "resumed" event apart from a manual one: an auto-resume
+     * must keep the backoff counter (it IS the backoff), a manual resume resets it.
+     */
+    private readonly autoResumingRunIds;
+    private readonly onPaused;
+    private readonly onTerminal;
+    private readonly onResumed;
+    constructor(manager: SchedulableWorkflowManager, options?: UsageLimitSchedulerOptions);
+    /** Clear every armed timer and unsubscribe from the manager. Idempotent. */
+    dispose(): void;
+    /** Test/diagnostic helper: in-memory attempt count tracked for a run, if any. */
+    getAttemptCount(runId: string): number | undefined;
+    /** Test/diagnostic helper: whether a resume timer is currently armed for a run. */
+    hasArmedTimer(runId: string): boolean;
+    private handlePaused;
+    private cleanup;
+    /**
+     * A run was resumed. If WE resumed it (auto-resume timer fired), leave the
+     * backoff counter alone — that's the sequence doing its job, and it must still
+     * be able to reach the cap. If a human resumed it (via /workflows), treat that
+     * as a deliberate fresh start: drop the in-memory given-up state and reset the
+     * persisted counter so a later pause re-enters the normal backoff from attempt 1
+     * instead of staying silently given-up forever.
+     */
+    private handleResumed;
+    private coldStartRearm;
+    private arm;
+    private onTimerFire;
+    private safeLoad;
+    private safeStatus;
+    /**
+     * Best-effort persist of the in-memory attempt counter, so a cold start after
+     * a crash can approximately resume the backoff sequence instead of restarting
+     * it. Deferred to a microtask so it lands AFTER the manager's own persistRun()
+     * write for this same pause (which happens synchronously, right after the
+     * "paused" event we're reacting to returns control to executeRun()) — writing
+     * synchronously here would just get clobbered, since persistRun() writes a
+     * fresh PersistedRunState object literal that doesn't know about this field.
+     * This is still inherently racy across process crashes (see class docs); it
+     * is a best-effort durability aid, not a correctness requirement for the live
+     * (in-memory) path.
+     */
+    private persistAttempts;
+    private safe;
+}