@agent-relay/factory 0.1.64 → 0.1.65

package/dist/orchestrator/factory.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, resolve } from 'node:path';
-import { FactoryConfigSchema } from '../config/schema.js';
+import { DEFAULT_READINESS_RECONCILE_TIMEOUT_MS, FactoryConfigSchema } from '../config/schema.js';
 import { linearByStatePath, linearByIdPath, linearByUuidPath } from '../constants/linear.js';
 import { stateResolutionFromIds } from '../linear/state-resolver.js';
 import { GithubMergeGate, closeProbePr } from '../github/index.js';
@@ -29,6 +29,8 @@ import { CoalescedTaskQueue } from './coalesced-task-queue.js';
 import { findAgentProcessByName, readProcessIdentity } from './process-identity.js';
 import { readFactoryInFlightRegistry, terminatePids } from './reaper.js';
 import { createFactoryCloudEventV1, factoryCloudReleaseReasonV1, } from '../observability/events.js';
+import { telemetryErrorClass } from '../observability/error-class.js';
+import { derivedReadinessReconcileState, publicHealthFromHeartbeat, readinessReconcileInFlightMs, } from './public-health.js';
 import { boundedRunCostTotal, CostLedger } from '../cost/ledger.js';
 import { createTicketDispatchDelivery } from '../delivery/ticket-dispatch.js';
 import { canonicalTrajectorySessionRef, renderTrajectoryPointer, stripTrajectoryPointers, } from '../trajectory.js';
@@ -185,6 +187,38 @@ const DISCOVERY_SWEEP_RENEW_MS = 30_000;
 const READINESS_RECONCILE_FAILURE_THRESHOLD = 3;
 const DISCOVERY_CHANGE_EVENT_LIMIT = 1_000;
 const DISCOVERY_OVERLOAD_BACKOFF_MAX_MS = 5 * 60_000;
+/** First rung of the ladder when the 429 advertises no `Retry-After`. */
+const DISCOVERY_OVERLOAD_BACKOFF_BASE_MS = 5_000;
+/**
+ * Floor for the advertised delay. `Retry-After: 0` would otherwise pin the
+ * whole ladder at zero (`0 * 2 ** n` is still zero) and turn respecting the
+ * dependency into hammering it.
+ */
+const DISCOVERY_OVERLOAD_BACKOFF_MIN_MS = 1_000;
+/**
+ * Ceiling for the ladder once the dependency has told us how long to wait.
+ *
+ * relayfile sheds an overloaded workspace DO with a 429 in milliseconds
+ * carrying `Retry-After: 5`, and #297 is what happened when the ladder ignored
+ * that and climbed to `DISCOVERY_OVERLOAD_BACKOFF_MAX_MS` anyway: the
+ * dependency asked for five seconds, Factory slept for five minutes, probed
+ * for recovery once per cap-length window, and presented a transient upstream
+ * blip as a sustained outage. The ratchet still escalates — it is just bounded
+ * by roughly what was actually asked for, and never *below* it, so this is a
+ * ceiling and not a licence to retry sooner than the dependency allows.
+ */
+const DISCOVERY_OVERLOAD_ADVERTISED_BACKOFF_MAX_MS = 30_000;
+/**
+ * How many relayfile operations one sweep may have shed before the sweep is
+ * abandoned rather than continued.
+ *
+ * Per-item overload skips that item and keeps going (#297, the same principle
+ * as #292), but skipping must not degenerate into grinding a shedding
+ * dependency through an entire backlog one 429 at a time. Past this many, the
+ * dependency is not serving this sweep at all: abort, back off, and let the
+ * ratchet do its job.
+ */
+const DISCOVERY_OVERLOAD_PER_SWEEP_LIMIT = 5;
 const GITHUB_FACTORY_LABEL = 'factory';
 const GITHUB_LIFECYCLE_LABELS = new Set(['factory:in-progress', 'factory:human-review']);
 const GITHUB_MIRROR_TITLE_PREFIX = '[factory]';
@@ -259,6 +293,20 @@ class DispatchLifecycleClaimRefusedError extends Error {
         this.name = 'DispatchLifecycleClaimRefusedError';
     }
 }
+/**
+ * The deadline that makes a hung sweep reachable by the existing recovery path.
+ * Its message is fully internal (one integer), so it is safe to persist into
+ * the operator-facing `readinessReconcile.lastError`.
+ */
+class ReadinessReconcileTimeoutError extends Error {
+    timeoutMs;
+    code = 'FACTORY_READINESS_RECONCILE_TIMEOUT';
+    constructor(timeoutMs) {
+        super(`readiness reconcile sweep exceeded its ${timeoutMs}ms deadline`);
+        this.timeoutMs = timeoutMs;
+        this.name = 'ReadinessReconcileTimeoutError';
+    }
+}
 const realClock = {
     now: () => Date.now(),
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
@@ -408,12 +456,41 @@ export class FactoryLoop {
     #readinessReconcileTimer;
     #readinessReconcileInFlight;
     #readinessReconcileIntervalMs = 60_000;
+    #readinessReconcileTimeoutMs = DEFAULT_READINESS_RECONCILE_TIMEOUT_MS;
+    // Set for exactly as long as a sweep is running. `state` is derived from
+    // this, so an in-flight pass can no longer masquerade as the last settled one.
+    #readinessReconcileInFlightSinceMs;
+    /**
+     * The work a deadline gave up waiting on. The deadline bounds the wait, not
+     * the sweep, so this is still live: shutdown has to drain it, and `state` has
+     * to keep counting from when it actually started.
+     *
+     * Two fields rather than a collection, because every live abandoned wait
+     * converges on the same sweep. They are all `runOnce()` calls with the same
+     * `dryRun`, so whatever they are queued behind, the first one out starts the
+     * sweep and the rest coalesce onto it — they settle together. So the newest
+     * wait is a sufficient drain target, and the earliest start is the honest
+     * age. Both matter (#301 review): keeping only the newest start advanced the
+     * age by two intervals every two intervals, so at `reconcileTimeoutMs ===
+     * reconcileIntervalMs` it never reached three and `stalled` was never
+     * reported; keeping one record per wait grew without bound in exactly the
+     * never-settling case this change exists for.
+     *
+     * The wait, deliberately, and never `#runOnceInFlight`: a mismatched-`dryRun`
+     * sweep is waited BEHIND rather than coalesced onto, so that handle can name
+     * an unrelated sweep, and the readiness pass would then start its own work
+     * after shutdown believed it had drained everything. The wait covers the
+     * queueing and the sweep it eventually runs, in every branch.
+     */
+    #readinessReconcileAbandonedWait;
+    #readinessReconcileAbandonedSinceMs;
     #readinessReconcileConsecutiveFailures = 0;
     #readinessReconcileLastDurationMs;
     #readinessReconcileLastStartedAtMs;
     #readinessReconcileLastCompletedAtMs;
     #readinessReconcileLastFailureAtMs;
     #readinessReconcileLastError;
+    #readinessReconcileLastErrorClass;
     #liveEventQueue = [];
     #liveEventDrainScheduled = false;
     #liveEventDrainActive = false;
@@ -501,7 +578,34 @@ export class FactoryLoop {
     // so the loop's catch no longer runs the failure-handoff reaper for it; the
     // pass reaps inline and must write to the same paths runLoop would.
     #loopReapPaths;
+    /**
+     * The first 429 relayfile raised during this sweep, kept for its
+     * `Retry-After` and reason when the sweep decides how long to back off.
+     *
+     * Before #297 this doubled as a sweep-wide kill switch: any 429 from any
+     * relayfile call latched here and `#runOnceWithDiscoveryFence` then threw it
+     * away along with everything the sweep had already accomplished. It is now
+     * only evidence, never a verdict — see `#discoverySweepOverloads` for the
+     * fuse that still ends a sweep the dependency is genuinely refusing to serve.
+     */
     #discoveryOverloadError;
+    /** Relayfile operations this sweep has been shed on. */
+    #discoverySweepOverloads = 0;
+    /**
+     * The longest `Retry-After` any operation in this sweep advertised.
+     *
+     * `#discoveryOverloadError` latches the FIRST 429, so deriving the backoff
+     * from it alone would let the durable window expire before a later, longer
+     * advertised delay permits — breaking the very guarantee #297 is about. The
+     * backoff takes the maximum instead.
+     */
+    #discoverySweepRetryAfterSeconds;
+    /**
+     * Whether relayfile served at least one ready work unit end to end during
+     * this sweep — its issue read, or a dispatch built on it. This is what
+     * decays the durable overload ratchet; see `#discoveryOverloadOutcome`.
+     */
+    #discoverySweepProgress = false;
     #resolvedIssueSource;
     #integrationInstructions;
     #integrationInstructionsRefresh;
@@ -917,6 +1021,14 @@ export class FactoryLoop {
             clearTimeout(this.#previewSweepTimer);
         this.#previewSweepTimer = undefined;
         await this.#readinessReconcileInFlight;
+        // #301 review: the deadline ends the *wait*, so `#readinessReconcileInFlight`
+        // can settle with its `runOnce()` still live. Shutdown releases dispatch
+        // lifecycle leases and disposes ports below, and `#isPassFatalFailure` only
+        // fences a stopping sweep once something in it throws — so a sweep whose
+        // dependency recovers cleanly would otherwise dispatch through torn-down
+        // state. Draining here restores exactly the pre-deadline shutdown contract:
+        // stop() outlives the sweep it started.
+        await this.#readinessReconcileAbandonedWait;
         await this.#previewSweepInFlight;
         this.#stoppingHeartbeatRefreshActive = await this.#stopLiveHeartbeat('stopping');
         try {
@@ -1067,6 +1179,9 @@ export class FactoryLoop {
         const options = this.#liveOptions(overrides);
         this.#liveTransport = options.transport;
         this.#readinessReconcileIntervalMs = options.reconcileIntervalMs;
+        // `start()` overrides skip the schema's cross-field check, so re-apply its
+        // floor here: a deadline under one interval would kill every pass.
+        this.#readinessReconcileTimeoutMs = Math.max(options.reconcileTimeoutMs, options.reconcileIntervalMs);
         this.#liveConnectStartedAtMs = this.#clock.now();
         this.#liveReplaySkewMarginMs = options.replaySkewMarginMs;
         const highWatermark = await this.#currentEventHighWatermark();
@@ -1103,10 +1218,27 @@ export class FactoryLoop {
             this.#logger.info?.('[factory] running startup ready-issue backfill before draining buffered events', {
                 highWatermarkRouteUnavailable: highWatermark.routeUnavailable,
             });
+            // Review follow-up on #300 (P1, cubic). The startup backfill is a
+            // discovery pass like any other, and it is the one most likely to hang:
+            // #36 measured 61 minutes here while the Relayfile mirror hydrated on a
+            // cold container. Stamping it means a wedged FIRST pass is visible as
+            // in-flight, instead of leaving the timestamps empty and the derived
+            // state reading `healthy` forever.
+            //
+            // Only the timestamps. `consecutiveFailures` and `lastError` belong to
+            // the reconcile loop's own failure accounting, which owns the degraded
+            // threshold and the #297 reason allowlist; a startup failure is already
+            // counted by `liveStartupBackfillErrors` and reported through `#error`.
+            const backfillStartedAtMs = this.#clock.now();
+            this.#readinessReconcileLastStartedAtMs = backfillStartedAtMs;
             try {
                 await this.runOnce();
+                this.#readinessReconcileLastDurationMs = this.#elapsedSince(backfillStartedAtMs);
+                this.#readinessReconcileLastCompletedAtMs = this.#clock.now();
             }
             catch (error) {
+                this.#readinessReconcileLastDurationMs = this.#elapsedSince(backfillStartedAtMs);
+                this.#readinessReconcileLastFailureAtMs = this.#clock.now();
                 // A startup backfill failure must not abort the daemon: log it and fall
                 // back to the live event stream (plus any buffered events) instead of
                 // leaving the factory down.
@@ -1198,6 +1330,7 @@ export class FactoryLoop {
             eventLimit: overrides.eventLimit ?? this.#config.liveSubscription.eventLimit,
             replaySkewMarginMs: overrides.replaySkewMarginMs ?? this.#config.liveSubscription.replaySkewMarginMs,
             reconcileIntervalMs: overrides.reconcileIntervalMs ?? this.#config.liveSubscription.reconcileIntervalMs,
+            reconcileTimeoutMs: overrides.reconcileTimeoutMs ?? this.#config.liveSubscription.reconcileTimeoutMs,
         };
     }
     async #currentEventCursor(limit) {
@@ -1246,19 +1379,82 @@ export class FactoryLoop {
         }, delayMs);
         this.#readinessReconcileTimer.unref?.();
     }
+    /**
+     * Runs one sweep under a deadline (#296).
+     *
+     * The sweep itself cannot be cancelled — `runOnce()` owns a durable discovery
+     * lease and abandoning it mid-flight is not safe — so expiry rejects *this*
+     * wait and leaves the underlying pass to finish on its own. That is enough:
+     * the rejection is what reaches the failure path, which re-arms the timer.
+     * A later reconcile pass coalesces onto the still-running `runOnce()` and
+     * fails on its own deadline too, so a persistent hang keeps counting up to
+     * `degraded` instead of going quiet.
+     */
+    async #runOnceWithReadinessDeadline() {
+        const timeoutMs = this.#readinessReconcileTimeoutMs;
+        const startedAtMs = this.#clock.now();
+        const sweep = this.runOnce();
+        let timer;
+        try {
+            return await new Promise((resolve, reject) => {
+                timer = setTimeout(() => {
+                    this.#increment('readinessReconcileDeadlineExceeded');
+                    if (this.#readinessReconcileAbandonedSinceMs === undefined) {
+                        // `state` ages from the FIRST wait that gave up on this work, not
+                        // from whenever the latest one began.
+                        this.#readinessReconcileAbandonedSinceMs = startedAtMs;
+                        // The abandoned pass is still running against the live control
+                        // plane. Report where it lands, so an operator can tell a
+                        // dependency that recovered late from one that never answered.
+                        // Attached once, so a wedge is reported once and not per expiry.
+                        void sweep.then((report) => this.#logger.warn?.('[factory] abandoned readiness sweep completed after its deadline', {
+                            timeoutMs,
+                            overrunMs: this.#elapsedSince(startedAtMs) - timeoutMs,
+                            dispatched: report.dispatched.length,
+                        }), (error) => this.#logger.warn?.('[factory] abandoned readiness sweep failed after its deadline', {
+                            timeoutMs,
+                            overrunMs: this.#elapsedSince(startedAtMs) - timeoutMs,
+                            error: describeError(error).errorMessage,
+                        })).catch(() => undefined);
+                    }
+                    // Newest wait wins as the drain target: it settles no earlier than
+                    // the ones before it, and clearing on it clears them all.
+                    const wait = sweep.catch(() => undefined).then(() => {
+                        if (this.#readinessReconcileAbandonedWait !== wait)
+                            return;
+                        this.#readinessReconcileAbandonedWait = undefined;
+                        this.#readinessReconcileAbandonedSinceMs = undefined;
+                    });
+                    this.#readinessReconcileAbandonedWait = wait;
+                    reject(new ReadinessReconcileTimeoutError(timeoutMs));
+                }, timeoutMs);
+                timer.unref?.();
+                // Attaching handlers here is also what keeps a late rejection from the
+                // abandoned pass from surfacing as an unhandled rejection.
+                sweep.then(resolve, reject);
+            });
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     async #reconcileReadyIssues() {
         const startedAtMs = this.#clock.now();
         this.#readinessReconcileLastStartedAtMs = startedAtMs;
+        this.#readinessReconcileInFlightSinceMs = startedAtMs;
         this.#increment('readinessReconcileSweeps');
         this.#logger.info?.('[factory] periodic readiness reconciliation started', {
             intervalMs: this.#readinessReconcileIntervalMs,
+            timeoutMs: this.#readinessReconcileTimeoutMs,
         });
         try {
-            const report = await this.runOnce();
+            const report = await this.#runOnceWithReadinessDeadline();
             this.#readinessReconcileConsecutiveFailures = 0;
             this.#readinessReconcileLastDurationMs = this.#elapsedSince(startedAtMs);
             this.#readinessReconcileLastCompletedAtMs = this.#clock.now();
             this.#readinessReconcileLastError = undefined;
+            this.#readinessReconcileLastErrorClass = undefined;
             this.#logger.info?.('[factory] periodic readiness reconciliation completed', {
                 durationMs: this.#readinessReconcileLastDurationMs,
                 candidates: report.pulled.length,
@@ -1267,11 +1463,28 @@ export class FactoryLoop {
             });
         }
         catch (error) {
-            const errorMessage = describeError(error).errorMessage;
+            // #297: all four relayfile overload reason codes share one message, and
+            // `lastError` is what an operator reads from /evidence. Without the
+            // reason, "workspace durable object is busy" cannot be told apart from
+            // three other conditions with three different remedies.
+            //
+            // Allowlisted, because this is a persisted operator-facing surface and
+            // not just a log line: `lastError` is returned from `status()` and
+            // written into the loop heartbeat file, so an unbounded
+            // dependency-controlled string would land on disk.
+            const overload = relayfileOverload(error);
+            const errorMessage = overload
+                ? `${describeError(error).errorMessage} ` +
+                    `[relayfile ${overload.status} ${relayfileOverloadReasonLabel(overload.reason)}` +
+                    `${overload.retryAfterSeconds === undefined ? '' : `; retry-after=${overload.retryAfterSeconds}s`}]`
+                : describeError(error).errorMessage;
             this.#readinessReconcileConsecutiveFailures += 1;
             this.#readinessReconcileLastDurationMs = this.#elapsedSince(startedAtMs);
             this.#readinessReconcileLastFailureAtMs = this.#clock.now();
             this.#readinessReconcileLastError = errorMessage;
+            // The class, unlike the message, is publishable: #295 puts it on the
+            // unauthenticated health surface through the same allowlist.
+            this.#readinessReconcileLastErrorClass = telemetryErrorClass(error);
             this.#increment('readinessReconcileErrors');
             this.#logger.warn?.('[factory] periodic readiness reconciliation failed; retry remains scheduled', {
                 error: errorMessage,
@@ -1280,6 +1493,11 @@ export class FactoryLoop {
                 degraded: this.#readinessReconcileConsecutiveFailures >= READINESS_RECONCILE_FAILURE_THRESHOLD,
             });
         }
+        finally {
+            // Cleared before the heartbeat write below, so a slow-but-successful pass
+            // does not stamp its own tail as `stalled`.
+            this.#readinessReconcileInFlightSinceMs = undefined;
+        }
         await this.#refreshLiveHeartbeat();
     }
     #scheduleLivePoll(delayMs, options) {
@@ -2008,13 +2226,29 @@ export class FactoryLoop {
         this.#discoverySweepStartedAtMs = sweepStartedAtMs;
         this.#discoverySweepLeaseLost = false;
         this.#discoveryOverloadError = undefined;
+        this.#discoverySweepOverloads = 0;
+        this.#discoverySweepRetryAfterSeconds = undefined;
+        this.#discoverySweepProgress = false;
         this.#startDiscoverySweepRenewal(claim.lease.epoch);
         let leaseReleased = false;
         try {
             this.#discoverySession = await this.#prepareDiscoverySession(claim);
+            // #297: a 429 raised anywhere in the sweep used to latch and be rethrown
+            // here, discarding a completed pass — every issue read, every dispatch —
+            // because of one transient shed operation. The work this sweep did is
+            // now kept instead, and the ratchet below records that the dependency is
+            // shedding but still serving.
             const report = await this.#performRunOnce(opts);
-            if (this.#discoveryOverloadError)
+            // The exception, and the reason skipping shed units cannot make a sweep
+            // unconditionally green: a sweep that was shed AND got no work unit
+            // through accomplished nothing. There is no progress to preserve, and
+            // committing it would report a clean sweep over a dependency that served
+            // none of it — leaving `readinessReconcile` healthy while Factory
+            // dispatches nothing, which is the #292 wedge wearing the other costume.
+            // Fail it so the ratchet escalates and readiness reflects reality.
+            if (this.#discoveryOverloadError !== undefined && !this.#discoverySweepProgress) {
                 throw this.#discoveryOverloadError;
+            }
             const checkpoint = await this.#finalizeDiscoveryCheckpoint();
             // Do not clear the durable lease while a renewal can still be waiting on
             // the same state-file lock. A late renewal that observes the completed
@@ -2024,7 +2258,8 @@ export class FactoryLoop {
             if (this.#discoverySweepLeaseLost) {
                 throw new Error('discovery sweep lease was lost before checkpoint commit');
             }
-            const completed = await this.#state.completeDiscoverySweep(this.#workspaceId, this.#discoverySweepOwner, claim.lease.epoch, checkpoint);
+            const residual = this.#discoveryOverloadOutcome(claim.state.consecutiveOverloads, 'committed');
+            const completed = await this.#commitDiscoverySweep(claim.lease.epoch, checkpoint, residual);
             leaseReleased = completed;
             if (!completed)
                 throw new Error('discovery sweep lease was lost before completion');
@@ -2040,18 +2275,18 @@ export class FactoryLoop {
             await this.#stopDiscoverySweepRenewal();
             const overload = relayfileOverload(error);
             if (overload) {
-                const consecutiveOverloads = claim.state.consecutiveOverloads + 1;
-                const delayMs = discoveryOverloadBackoffMs(overload.retryAfterSeconds, consecutiveOverloads);
-                const backoffUntilMs = this.#clock.now() + delayMs;
-                leaseReleased = await this.#state.deferDiscoverySweep(this.#workspaceId, this.#discoverySweepOwner, claim.lease.epoch, backoffUntilMs, consecutiveOverloads);
-                this.#increment('discoveryOverloadBackoffs');
+                const outcome = this.#discoveryOverloadOutcome(claim.state.consecutiveOverloads, 'aborted', error);
+                leaseReleased = await this.#state.deferDiscoverySweep(this.#workspaceId, this.#discoverySweepOwner, claim.lease.epoch, outcome.backoffUntilMs, outcome.consecutiveOverloads);
                 this.#logger.warn?.('[factory] Relayfile discovery overloaded; backing off before another sweep', {
                     status: overload.status,
                     reason: overload.reason,
-                    retryAfterSeconds: overload.retryAfterSeconds,
-                    delayMs,
-                    backoffUntilMs,
-                    consecutiveOverloads,
+                    retryAfterSeconds: outcome.retryAfterSeconds,
+                    delayMs: outcome.delayMs,
+                    backoffUntilMs: outcome.backoffUntilMs,
+                    consecutiveOverloads: outcome.consecutiveOverloads,
+                    previousOverloads: claim.state.consecutiveOverloads,
+                    sweepOverloads: this.#discoverySweepOverloads,
+                    sweepProgress: this.#discoverySweepProgress,
                 });
                 // backoffUntilMs is already durable via deferDiscoverySweep, and the
                 // next runOnce() honors it at the pre-claim wait above — sleeping
@@ -2067,6 +2302,9 @@ export class FactoryLoop {
             this.#discoverySweepEpoch = undefined;
             this.#discoverySweepStartedAtMs = undefined;
             this.#discoveryOverloadError = undefined;
+            this.#discoverySweepOverloads = 0;
+            this.#discoverySweepRetryAfterSeconds = undefined;
+            this.#discoverySweepProgress = false;
             // This sweep is over either way (committed, deferred, or lease lost) —
             // a stale `true` here would otherwise make every #listRelayfileTree
             // call outside a fresh claim (Slack lookups, PR confirmation, the
@@ -2078,6 +2316,94 @@ export class FactoryLoop {
             }
         }
     }
+    /**
+     * Commit the sweep, carrying any residual overload backoff into the store.
+     *
+     * `completeDiscoverySweepWithOverload` is optional on the port so a store
+     * written before #297 keeps working. When one of those is injected and this
+     * sweep HAS a residual, the backoff cannot be persisted and the next sweep
+     * would retry immediately — so this says so, loudly and with a counter,
+     * rather than degrading in silence. The sweep itself still commits: losing
+     * the backoff is worse than pre-#297 behaviour only if nobody notices.
+     */
+    async #commitDiscoverySweep(epoch, checkpoint, residual) {
+        if (residual && this.#state.completeDiscoverySweepWithOverload) {
+            return await this.#state.completeDiscoverySweepWithOverload(this.#workspaceId, this.#discoverySweepOwner, epoch, checkpoint, { consecutiveOverloads: residual.consecutiveOverloads, backoffUntilMs: residual.backoffUntilMs });
+        }
+        if (residual) {
+            this.#increment('discoveryOverloadResidualUnsupported');
+            this.#logger.warn?.('[factory] state store cannot persist the Relayfile overload backoff; it will be lost', {
+                store: this.#state.constructor?.name,
+                consecutiveOverloads: residual.consecutiveOverloads,
+                backoffUntilMs: residual.backoffUntilMs,
+                delayMs: residual.delayMs,
+            });
+        }
+        return await this.#state.completeDiscoverySweep(this.#workspaceId, this.#discoverySweepOwner, epoch, checkpoint);
+    }
+    /**
+     * How the durable overload ratchet should read after this sweep, or
+     * `undefined` if relayfile never shed anything and the ordinary reset
+     * applies.
+     *
+     * #297, deliverable 3. `consecutiveOverloads` used to clear only on a
+     * *fully* clean sweep, so under sustained mild load the ratchet essentially
+     * never cleared: it climbed to the cap on the first bad sweep and stayed
+     * there, probing for recovery once per cap-length window, long after the
+     * dependency had recovered. Requiring perfection to clear a ratchet means
+     * the ratchet does not clear.
+     *
+     * The signal that replaces "was this sweep perfect" is "did relayfile serve
+     * any of this sweep's work units", because that is what the ratchet is
+     * actually for. A shedding DO rejects ALL background traffic —
+     * `oldest_inflight_age` does this regardless of how few requests are in
+     * flight — so a sweep against a genuinely overloaded workspace gets not one
+     * unit through and still escalates, all the way to the cap. A sweep that did
+     * get units through proves the dependency is serving us, so it decays by one
+     * rung. Decay, not reset: getting work done while being shed is not evidence
+     * that the overload is over, only that it is survivable.
+     */
+    #discoveryOverloadOutcome(previousOverloads, sweepOutcome, error) {
+        const overload = relayfileOverload(error) ?? relayfileOverload(this.#discoveryOverloadError);
+        if (!overload)
+            return undefined;
+        // The longest delay anything in this sweep asked for, not just the one the
+        // latched or terminating error carried — see `#discoverySweepRetryAfterSeconds`.
+        const advertised = [this.#discoverySweepRetryAfterSeconds, overload.retryAfterSeconds]
+            .filter((value) => value !== undefined);
+        const retryAfterSeconds = advertised.length > 0 ? Math.max(...advertised) : undefined;
+        // Deliberately NOT "the sweep reached its end". A sweep in which relayfile
+        // shed EVERY unit still runs the loop to the end, and it got nothing done;
+        // treating that as progress would decay the ratchet in exactly the case it
+        // exists for. (`#runOnceWithDiscoveryFence` turns that sweep into an
+        // aborted one before it can commit, so the escalate branch here is reached
+        // only through `sweepOutcome === 'aborted'` — but the rule is a property of
+        // progress, not of which caller asked, and is written that way.)
+        const consecutiveOverloads = this.#discoverySweepProgress
+            ? Math.max(0, previousOverloads - 1)
+            : previousOverloads + 1;
+        const delayMs = discoveryOverloadBackoffMs(retryAfterSeconds, consecutiveOverloads);
+        const backoffUntilMs = this.#clock.now() + delayMs;
+        this.#increment('discoveryOverloadBackoffs');
+        if (sweepOutcome === 'committed') {
+            this.#logger.warn?.('[factory] discovery sweep committed despite Relayfile overload', {
+                status: overload.status,
+                reason: overload.reason,
+                retryAfterSeconds,
+                sweepOverloads: this.#discoverySweepOverloads,
+                previousOverloads,
+                consecutiveOverloads,
+                delayMs,
+                backoffUntilMs,
+            });
+        }
+        return {
+            consecutiveOverloads,
+            backoffUntilMs,
+            delayMs,
+            ...(retryAfterSeconds === undefined ? {} : { retryAfterSeconds }),
+        };
+    }
     async #performRunOnce(opts = {}) {
         const dryRun = opts.dryRun ?? this.#config.dryRun;
         const startedAtMs = this.#clock.now();
@@ -2125,15 +2451,57 @@ export class FactoryLoop {
             let readyIssueReads = 0;
             const issueEntries = [];
             for (const path of paths) {
-                const issue = await this.#readIssue(path);
+                let issue;
+                let shed = false;
+                try {
+                    issue = await this.#readIssue(path);
+                }
+                catch (error) {
+                    // #297: `#readIssue` rethrows relayfile overload and swallows every
+                    // other read fault, so this catch only ever sees the backend
+                    // shedding THIS issue's read. That is a fact about one work unit:
+                    // a sweep that pulled 40 issues and was shed on the 39th must keep
+                    // the other 39, exactly as #292 argued for dispatch failures. The
+                    // fuse is what still ends a sweep the backend is refusing.
+                    const overload = relayfileOverload(error);
+                    // Defensive: anything `#readIssue` did not swallow and is not a 429
+                    // is not ours to reclassify, and must surface as itself.
+                    if (!overload)
+                        throw error;
+                    const fuse = this.#discoveryOverloadFuseError();
+                    if (fuse)
+                        throw fuse;
+                    shed = true;
+                    this.#increment('discoveryOverloadItemsSkipped');
+                    this.#logger.warn?.('[factory] relayfile shed a ready-issue read; skipping it and continuing the sweep', {
+                        path,
+                        status: overload.status,
+                        reason: overload.reason,
+                        retryAfterSeconds: overload.retryAfterSeconds,
+                        sweepOverloads: this.#discoverySweepOverloads,
+                    });
+                    recordSkip({ issue: issueRefFromPath(path), reason: perItemDispatchSkipReason(error) });
+                }
                 readyIssueReads += 1;
+                // Relayfile served this work unit's read: the dependency is shedding
+                // but not refusing, which is what decays the ratchet (#297).
+                //
+                // `issue` is required, not just `!shed`: `#readIssue` returns
+                // `undefined` for a body it could not read at all, and the known
+                // phantom condition — the tree listing issue paths whose bodies are
+                // absent — makes every read return `undefined`. Crediting those would
+                // decay the ratchet on a sweep that served nothing.
+                if (!shed && issue)
+                    this.#discoverySweepProgress = true;
                 lastReadyReadProgressAtMs = this.#logTimedProgress(this.#config.issueSource === 'github'
                     ? '[factory] GitHub ready issue read progress'
                     : '[factory] Linear ready issue read progress', startedAtMs, lastReadyReadProgressAtMs, { read: readyIssueReads, total: paths.length, path });
-                if (issue && issueSource === 'linear') {
-                    await this.#recordCanonicalIssueState(issue);
+                if (!shed) {
+                    if (issue && issueSource === 'linear') {
+                        await this.#recordCanonicalIssueState(issue);
+                    }
+                    issueEntries.push({ path, issue });
                 }
-                issueEntries.push({ path, issue });
                 await this.#refreshLiveHeartbeatIfDue();
             }
             if (issueSource === 'github') {
@@ -2222,6 +2590,9 @@ export class FactoryLoop {
                     // A completed dispatch — even one that parks or escalates the issue —
                     // proves the pipeline still works, so the fuse below starts over.
                     unclassifiedFailuresSinceDispatch = 0;
+                    // ...and proves relayfile is still serving this sweep, which is what
+                    // decays the durable overload ratchet (#297).
+                    this.#discoverySweepProgress = true;
                     if (result.agents.length === 0 && !dryRun) {
                         const reason = result.hold?.kind === 'dependency-cycle'
                             ? `dependency cycle detected: ${result.hold.cycle?.join(' -> ') ?? 'unknown cycle'}`
@@ -2235,13 +2606,47 @@ export class FactoryLoop {
                     }
                 }
                 catch (error) {
+                    // The failure may have left half-spawned agents behind, persisted as
+                    // failure handoffs on the way out of `#dispatchUnlocked`. runLoop's
+                    // catch used to reap them because every such error aborted the pass;
+                    // now that most of them are skipped, the reap has to happen here.
+                    //
+                    // BEFORE the fatality check, not after (#298 review, round two): the
+                    // 429 that trips the overload fuse aborts this pass, and a direct
+                    // `runOnce()` — the `factory run-once` CLI, `#reconcileReadyIssues` —
+                    // has no runLoop catch behind it, so the unit that trips the fuse
+                    // would leak the agents it had already spawned. Reaping first covers
+                    // the abort and the skip with one call; it is idempotent, so the
+                    // runLoop catch finding nothing left to do is free.
+                    if (mayHaveSpawnedBeforeFailing(error)) {
+                        await this.#reapDispatchFailureHandoffsNow();
+                    }
                     // #292: issues in a pass are independent work units, so a failure
                     // that is about ONE unit costs that unit and nothing else. Only the
                     // conditions named in `#isPassFatalFailure` — the ones where
                     // continuing the pass is meaningless — abort the whole sweep.
-                    if (this.#isPassFatalFailure(error, dryRun))
-                        throw error;
-                    if (!isClassifiedPerItemDispatchFailure(error)) {
+                    if (this.#isPassFatalFailure(error, dryRun)) {
+                        // The overload fuse may have been tripped by a 429 that a caller
+                        // swallowed, leaving an unrelated error in hand. The fence keys
+                        // the durable backoff off `relayfileOverload(error)`, so hand it
+                        // the 429 rather than whatever surfaced last.
+                        throw this.#discoveryOverloadFuseError() ?? error;
+                    }
+                    const overload = relayfileOverload(error);
+                    if (overload) {
+                        // #297: shedding is a state of the dependency, not a fault of this
+                        // work unit, so it stays out of `counters.errors` and gets its own
+                        // counter — the same split #293 made for undispatchable units.
+                        this.#increment('discoveryOverloadItemsSkipped');
+                        this.#logger.warn?.('[factory] relayfile shed this work unit; skipping it and continuing the sweep', {
+                            issue: issueRef(issue).key,
+                            status: overload.status,
+                            reason: overload.reason,
+                            retryAfterSeconds: overload.retryAfterSeconds,
+                            sweepOverloads: this.#discoverySweepOverloads,
+                        });
+                    }
+                    else if (!isClassifiedPerItemDispatchFailure(error)) {
                         unclassifiedFailuresSinceDispatch += 1;
                         // A pass-wide fault can arrive disguised as a run of per-item
                         // faults. Skipping every unit would then hand back a green report
@@ -2260,11 +2665,6 @@ export class FactoryLoop {
                             error: describeError(error).errorMessage,
                         });
                         this.#error(error, issueRef(issue));
-                        // The failure may have left half-spawned agents behind. runLoop's
-                        // catch used to reap them because this error aborted the pass;
-                        // now that the pass survives, the reap has to happen here or the
-                        // agents leak until the next failed iteration.
-                        await this.#reapDispatchFailureHandoffsNow();
                     }
                     else {
                         // Not an error — the unit simply cannot be dispatched right now —
@@ -2313,6 +2713,21 @@ export class FactoryLoop {
             }
         }
     }
+    /**
+     * The 429 that ended this sweep, when relayfile has shed
+     * `DISCOVERY_OVERLOAD_PER_SWEEP_LIMIT` operations and skipping the next work
+     * unit would just be grinding a shedding dependency. Undefined below that.
+     *
+     * Returns the *latched* 429 rather than whatever error is in hand, because
+     * `#runOnceWithDiscoveryFence` keys the durable backoff off
+     * `relayfileOverload(error)` and a caller may have swallowed the 429 that
+     * tripped the fuse.
+     */
+    #discoveryOverloadFuseError() {
+        if (this.#discoverySweepOverloads < DISCOVERY_OVERLOAD_PER_SWEEP_LIMIT)
+            return undefined;
+        return this.#discoveryOverloadError;
+    }
     /**
      * Whether a failure raised while processing ONE work unit must abort the
      * whole readiness pass instead of skipping that unit.
@@ -2333,10 +2748,11 @@ export class FactoryLoop {
      *   one would be recorded as an ordinary per-issue skip. The run report
      *   would then claim a clean pass over work this process no longer has the
      *   right to touch.
-     * - Relayfile signalled overload for this sweep. The backend is shedding
-     *   load; grinding through the remaining units makes it worse, and
-     *   `#runOnceWithDiscoveryFence` is going to rethrow this at the fence
-     *   anyway.
+     * - Relayfile has shed `DISCOVERY_OVERLOAD_PER_SWEEP_LIMIT` operations in
+     *   this sweep. A single shed operation is per-item and skippable (#297),
+     *   but past this the backend is not serving this sweep at all: grinding
+     *   through the remaining units makes it worse, and the fence needs the 429
+     *   to set the durable backoff.
      * - The factory is stopping. Teardown is in progress and dispatching more
      *   agents now leaks them past the shutdown deadline.
      * - The fleet control-plane circuit is no longer closed, **on a live pass**.
@@ -2365,7 +2781,15 @@ export class FactoryLoop {
     #isPassFatalFailure(error, dryRun) {
         // Sweep-scoped: these are about this process's right or ability to run the
         // pass at all, so they hold for a dry run exactly as for a live one.
-        if (this.#discoverySweepLeaseLost || this.#discoveryOverloadError !== undefined || this.#stopping) {
+        if (this.#discoverySweepLeaseLost || this.#stopping) {
+            return true;
+        }
+        // #297: relayfile overload used to sit alongside those two, and it did not
+        // belong there. A 429 on ONE work unit is a fact about that unit's read or
+        // write, not about this process's right to run the pass — and because the
+        // flag latched for the whole sweep, the first transient shed also made
+        // every later unit fatal. Only sustained shedding is now pass-fatal.
+        if (this.#discoverySweepOverloads >= DISCOVERY_OVERLOAD_PER_SWEEP_LIMIT) {
             return true;
         }
         // Fleet-scoped, and therefore live-only. See the doc comment above.
@@ -3231,14 +3655,40 @@ export class FactoryLoop {
             return result;
         }
         catch (error) {
-            if (relayfileOverload(error) && this.#discoverySweepEpoch !== undefined) {
+            const overload = relayfileOverload(error);
+            if (overload && this.#discoverySweepEpoch !== undefined) {
                 this.#discoveryOverloadError ??= error;
+                this.#discoverySweepOverloads += 1;
+                if (overload.retryAfterSeconds !== undefined) {
+                    this.#discoverySweepRetryAfterSeconds = Math.max(this.#discoverySweepRetryAfterSeconds ?? 0, overload.retryAfterSeconds);
+                }
+                this.#increment('discoveryOverloadOperations');
+                // #297: relayfile's four overload reason codes — inflight_limit,
+                // oldest_inflight_age, router_inflight_limit, durable_object_overloaded
+                // — all share ONE message string, and they mean four different things:
+                // a DO-local admission cap, one stuck op poisoning every background
+                // caller, a Worker-global isolate cap, and the Cloudflare runtime
+                // shedding the object outright. `relayfileOverload()` has always parsed
+                // the reason; nothing on this path ever printed it, and during the
+                // 2026-08-20 outage that ambiguity was the single biggest obstacle to
+                // diagnosis. Unconditional, unlike the failure warn below: a 429 is
+                // always worth one line.
+                this.#increment(`discoveryOverloadReason:${relayfileOverloadReasonLabel(overload.reason)}`);
+                this.#logger.warn?.('[factory] relayfile shed a discovery operation', {
+                    ...metadata,
+                    status: overload.status,
+                    reason: overload.reason,
+                    retryAfterSeconds: overload.retryAfterSeconds,
+                    sweepOverloads: this.#discoverySweepOverloads,
+                    elapsedMs: this.#elapsedSince(startedAtMs),
+                });
             }
             if (opts.logFailure || waitWarnings > 0) {
                 this.#increment('relayfileOperationFailures');
                 this.#logger.warn?.('[factory] relayfile operation failed', {
                     ...metadata,
                     elapsedMs: this.#elapsedSince(startedAtMs),
+                    ...(overload ? { status: overload.status, reason: overload.reason } : {}),
                     error: describeError(error).errorMessage,
                 });
             }
@@ -3801,17 +4251,66 @@ export class FactoryLoop {
     }
     #readinessReconcileStatus() {
         const consecutiveFailures = this.#readinessReconcileConsecutiveFailures;
-        const state = this.#startMode !== 'live'
+        // #296 owns the numerator here, #295/#300 own the derivation. The earliest
+        // sweep still running — after a deadline expiry that is the abandoned one,
+        // not the current wait, or every expiry would restart the clock and a
+        // permanently stuck pass would read as merely `retrying`.
+        const inFlightSinceMs = Math.min(this.#readinessReconcileInFlightSinceMs ?? Number.POSITIVE_INFINITY, this.#readinessReconcileAbandonedSinceMs ?? Number.POSITIVE_INFINITY);
+        const settled = this.#startMode !== 'live'
             ? 'not-running'
+            // Failure-count ladder only. Precedence against `stalled` belongs to
+            // `derivedReadinessReconcileState`, which outranks everything here: a
+            // stall is the more specific fact, and `consecutiveFailures` ships
+            // alongside so nothing an alarm keyed on `degraded` needs is lost.
             : consecutiveFailures >= READINESS_RECONCILE_FAILURE_THRESHOLD
                 ? 'degraded'
                 : consecutiveFailures > 0
                     ? 'retrying'
                     : 'healthy';
+        // The counters above only move when a pass *settles*. A pass that hangs
+        // takes neither path, so `settled` would keep reporting the last finished
+        // pass — `healthy` — for as long as the process is stuck (#295). The
+        // in-flight age is the only field that can express that, so derive the
+        // state from it rather than trusting the last write.
+        const timestamps = {
+            intervalMs: this.#readinessReconcileIntervalMs,
+            ...(Number.isFinite(inFlightSinceMs) ? { inFlightSinceMs } : {}),
+            ...(this.#readinessReconcileLastStartedAtMs !== undefined
+                ? { lastStartedAtMs: this.#readinessReconcileLastStartedAtMs }
+                : {}),
+            ...(this.#readinessReconcileLastCompletedAtMs !== undefined
+                ? { lastCompletedAtMs: this.#readinessReconcileLastCompletedAtMs }
+                : {}),
+            ...(this.#readinessReconcileLastFailureAtMs !== undefined
+                ? { lastFailureAtMs: this.#readinessReconcileLastFailureAtMs }
+                : {}),
+        };
+        const nowMs = this.#clock.now();
+        // Defence in depth (#300 review, CodeRabbit). These derivations are new
+        // code from another module on a path that `status()` and every heartbeat
+        // write depend on. A throw here would take out the liveness signal the
+        // crash reaper reads — the diagnostic causing the outage it exists to
+        // explain — so a failure costs the derived fields and nothing else.
+        let inFlightMs;
+        let derived = settled;
+        try {
+            inFlightMs = readinessReconcileInFlightMs(timestamps, nowMs);
+            derived = derivedReadinessReconcileState({ ...timestamps, state: settled }, nowMs);
+        }
+        catch (error) {
+            this.#logger.warn?.('[factory] readiness health derivation failed; reporting the settled state', {
+                error: describeError(error).errorMessage,
+            });
+            inFlightMs = undefined;
+            derived = settled;
+        }
         return {
-            state,
+            state: derived === 'unknown' ? settled : derived,
             consecutiveFailures,
             failureThreshold: READINESS_RECONCILE_FAILURE_THRESHOLD,
+            intervalMs: this.#readinessReconcileIntervalMs,
+            ...(Number.isFinite(inFlightSinceMs) ? { inFlightSinceMs } : {}),
+            ...(inFlightMs !== undefined ? { inFlightMs } : {}),
             ...(this.#readinessReconcileLastDurationMs !== undefined
                 ? { lastDurationMs: this.#readinessReconcileLastDurationMs }
                 : {}),
@@ -3825,6 +4324,9 @@ export class FactoryLoop {
                 ? { lastFailureAtMs: this.#readinessReconcileLastFailureAtMs }
                 : {}),
             ...(this.#readinessReconcileLastError ? { lastError: this.#readinessReconcileLastError } : {}),
+            ...(this.#readinessReconcileLastErrorClass
+                ? { lastErrorClass: this.#readinessReconcileLastErrorClass }
+                : {}),
         };
     }
     on(event, listener) {
@@ -6301,6 +6803,29 @@ export class FactoryLoop {
             readinessReconcile: this.#readinessReconcileStatus(),
             fleetControlPlane: this.#fleetControlPlane.status(),
         };
+        // The deployed container serves `/healthz` straight out of this file and
+        // has no redaction logic of its own, so publish the already-safe view here
+        // rather than leaving that boundary to whoever reads the file (#295).
+        // Derived against this daemon's clock: every duration in it is a
+        // difference between timestamps this process wrote.
+        //
+        // Guarded (#300 review, CodeRabbit): this heartbeat is what the crash
+        // reaper and `/healthz` read to decide the daemon is alive, and several
+        // callers of this method sit outside any try/catch. A projection failure
+        // must cost the diagnostics block, never the heartbeat — the omitted block
+        // is itself legible, since `factory diagnose` reports a missing one rather
+        // than a false green.
+        try {
+            heartbeat.health = publicHealthFromHeartbeat(heartbeat, {
+                nowMs: updatedAtMs,
+                staleMs: this.#config.loop.heartbeatStaleMs,
+            });
+        }
+        catch (error) {
+            this.#logger.warn?.('[factory] public health projection failed; heartbeat written without it', {
+                error: describeError(error).errorMessage,
+            });
+        }
         await mkdir(dirname(path), { recursive: true });
         await writeFile(path, `${JSON.stringify(heartbeat, null, 2)}\n`, 'utf8');
         await this.#writeInFlightRegistry(registryPath, path);
@@ -6319,11 +6844,18 @@ export class FactoryLoop {
         });
     }
     async #reapDispatchFailureHandoffsNow(heartbeatPath = this.#loopReapPaths?.heartbeatPath ?? this.#config.loop.heartbeatPath, registryPath = this.#loopReapPaths?.registryPath ?? this.#config.loop.registryPath) {
-        const handoffs = await this.#state.listFailureHandoffs(this.#workspaceId);
-        if (handoffs.length === 0) {
-            return;
-        }
         try {
+            // Inside the try, not before it (#298 review). Every caller reaps while
+            // already handling a failure and then propagates that failure: the
+            // per-item catch rethrows the dispatch error, runLoop's catch is mid
+            // teardown. A throw from here would REPLACE the error in flight — and a
+            // replaced 429 is no longer recognised as overload at the discovery
+            // fence, silently dropping the advertised backoff. Reaping is
+            // best-effort by construction; the caller's error always wins.
+            const handoffs = await this.#state.listFailureHandoffs(this.#workspaceId);
+            if (handoffs.length === 0) {
+                return;
+            }
             const protectedPids = await this.#protectedPids();
             let registryChanged = false;
             const readyToClear = new Set();
@@ -14941,6 +15473,15 @@ const githubIssueAuthor = (issue) => {
     }
     return source ? undefined : githubAuthorLogin(payload)?.trim() || undefined;
 };
+/**
+ * An `IssueRef` for a path whose issue body could not be read at all — the
+ * shape a relayfile-shed ready-issue read leaves behind (#297). The key is
+ * what an operator needs to correlate the skip; the uuid falls back to it.
+ */
+const issueRefFromPath = (path) => {
+    const key = keyFromPath(path);
+    return { uuid: uuidFromPath(path) ?? key, key, path };
+};
 const issueRef = (issue) => ({ uuid: issue.uuid, key: issue.key, path: issue.path });
 // Preserve the historical Linear state namespace while keeping GitHub-native
 // issue numbers independent across repositories in the same workspace.
@@ -16854,10 +17395,54 @@ const relayfileOverload = (error) => {
         stringValue(flat.code) ?? stringValue(data.code) ?? 'rate_limited';
     return { status, reason, ...(retryAfterSeconds === undefined ? {} : { retryAfterSeconds }) };
 };
+/**
+ * relayfile's overload reason codes, allowlisted.
+ *
+ * `IterationReport.skipped[].reason` is serialized to stdout by `factory
+ * run-once`, so it stays a fixed classification plus a known code — the same
+ * public-surface rule #293 applied to error class names — rather than
+ * whatever string the dependency happened to send.
+ */
+const RELAYFILE_OVERLOAD_REASONS = new Set([
+    // Admission gate inside the workspace durable object.
+    'inflight_limit',
+    'oldest_inflight_age',
+    'write_admission_limit',
+    // Worker-side backpressure, per isolate rather than per workspace.
+    'router_inflight_limit',
+    // The Cloudflare runtime shed the object; relayfile only relabels it.
+    'durable_object_overloaded',
+    // relayfileOverload()'s fallback when the body carried no reason at all.
+    'rate_limited',
+]);
+/**
+ * Both the run-report reason and the per-reason counter key are built from
+ * this, so an unknown code from the dependency can neither leak into stdout
+ * nor open an unbounded counter namespace.
+ */
+const relayfileOverloadReasonLabel = (reason) => RELAYFILE_OVERLOAD_REASONS.has(reason) ? reason : 'unrecognized';
+/**
+ * How long to wait before the next discovery sweep after relayfile shed this
+ * one.
+ *
+ * The advertised `Retry-After` is authoritative in BOTH directions (#297):
+ * it is the first rung, so we never retry sooner than the dependency allows,
+ * and it bounds the ceiling, so we never sleep for minutes because of a
+ * request to wait seconds. Without an advertised delay there is nothing to
+ * respect and the original five-minute ladder governs unchanged.
+ */
 const discoveryOverloadBackoffMs = (retryAfterSeconds, consecutiveOverloads) => {
-    const retryAfterMs = Math.max(0, Math.ceil((retryAfterSeconds ?? 0) * 1_000));
-    const exponentialMs = Math.min(DISCOVERY_OVERLOAD_BACKOFF_MAX_MS, 5_000 * (2 ** Math.min(10, Math.max(0, consecutiveOverloads - 1))));
-    return Math.max(retryAfterMs, exponentialMs);
+    const advertisedMs = retryAfterSeconds === undefined
+        ? undefined
+        : Math.max(DISCOVERY_OVERLOAD_BACKOFF_MIN_MS, Math.ceil(retryAfterSeconds * 1_000));
+    const baseMs = advertisedMs ?? DISCOVERY_OVERLOAD_BACKOFF_BASE_MS;
+    // A dependency that asks for longer than the advertised ceiling still gets
+    // what it asked for; the ceiling only stops the ladder from overshooting it.
+    const ceilingMs = advertisedMs === undefined
+        ? DISCOVERY_OVERLOAD_BACKOFF_MAX_MS
+        : Math.max(advertisedMs, DISCOVERY_OVERLOAD_ADVERTISED_BACKOFF_MAX_MS);
+    const steps = Math.min(10, Math.max(0, consecutiveOverloads - 1));
+    return Math.min(ceilingMs, baseMs * (2 ** steps));
 };
 const eventSequenceNumber = (eventId) => {
     const whole = Number(eventId);
@@ -17086,10 +17671,6 @@ const telemetryCategory = (value) => {
     const normalized = value.trim().toLowerCase().replace(/[^a-z0-9._:/-]+/gu, '-');
     return normalized.slice(0, 120) || undefined;
 };
-const telemetryErrorClass = (error) => {
-    const name = error instanceof Error ? error.name : '';
-    return /^[A-Za-z][A-Za-z0-9]{0,63}(?:Error|Exception)$/u.test(name) ? name : 'Error';
-};
 const isTimeoutError = (error) => error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError');
 const retryOnTimeout = async (fn, opts) => {
     let lastError;
@@ -17323,7 +17904,26 @@ const UNCLASSIFIED_DISPATCH_FAILURE_LIMIT = 5;
  * skippable and are exempt from the consecutive-failure fuse.
  */
 const isClassifiedPerItemDispatchFailure = (error) => error instanceof LiveDispatchStateChangedError ||
-    error instanceof DispatchLifecycleClaimRefusedError;
+    error instanceof DispatchLifecycleClaimRefusedError ||
+    // Relayfile shedding one operation is a state of the dependency, not an
+    // unexplained fault, and it has its own fuse — see #297 and
+    // DISCOVERY_OVERLOAD_PER_SWEEP_LIMIT.
+    relayfileOverload(error) !== undefined;
+/**
+ * Whether a per-item failure could have left half-spawned agents behind.
+ *
+ * The two lifecycle refusals are decided before `#dispatchUnlocked` spawns
+ * anything, so there is nothing to reap for them. Everything else can fail
+ * *after* a spawn — including relayfile shedding a post-spawn read — having
+ * persisted the agents as failure handoffs on the way out.
+ *
+ * Deliberately a denylist rather than an allowlist: a new failure mode that
+ * nobody classified should default to "reap it", because the cost of a
+ * needless reap is one no-op pass over an empty handoff list, while the cost
+ * of a missed one is leaked agents and duplicate workers on the next retry.
+ */
+const mayHaveSpawnedBeforeFailing = (error) => !(error instanceof LiveDispatchStateChangedError) &&
+    !(error instanceof DispatchLifecycleClaimRefusedError);
 /**
  * The run-report reason recorded for a work unit the pass could not dispatch.
  *
@@ -17334,6 +17934,9 @@ const isClassifiedPerItemDispatchFailure = (error) => error instanceof LiveDispa
  * `describeControlPlaneError` makes for circuit state.
  */
 const perItemDispatchSkipReason = (error) => {
+    const overload = relayfileOverload(error);
+    if (overload)
+        return `relayfile overloaded (${relayfileOverloadReasonLabel(overload.reason)})`;
     if (error instanceof LiveDispatchStateChangedError)
         return 'live state changed during dispatch';
     if (error instanceof DispatchLifecycleClaimRefusedError) {