@agent-relay/factory 0.1.63 → 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,8 +29,11 @@ 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';
 import { FleetControlPlaneCircuit, FleetControlPlaneCircuitOpenError, guardFleetControlPlane, } from '../fleet/control-plane-circuit.js';
 class ClarificationWakeLeaseLostError extends Error {
 }
@@ -146,8 +149,32 @@ const STARTUP_AGENT_EXIT_DRAIN_TIMEOUT_MS = 30_000;
 const RECONCILED_AGENT_EXIT_CONCURRENCY = 4;
 const SLACK_EVENT_WATERMARK_CACHE_MS = 60_000;
 const SLACK_CONVERSATION_TURN_LEASE_MS = 60_000;
+// Both receipt leases guard an in-flight Slack writeback, and no fixed lease can
+// cover one: MountSlackWriteback budgets 90s for the confirm alone, on top of an
+// unbounded writeFile. Sizing them past that worst case would only trade a stolen
+// claim for a stranded one — a lease long enough to survive the slowest write is
+// equally long enough to hold the receipt hostage to a dead holder. So these
+// bound the *idle* claim and #withRenewedProviderLease extends them for exactly
+// as long as the write they cover is still running.
+const SLACK_REPLY_ACKNOWLEDGEMENT_LEASE_MS = 60_000;
+const SLACK_TERMINAL_RECEIPT_CLAIM_LEASE_MS = 60_000;
+// Renewal without a ceiling is the same defect from the other side: a heartbeat
+// that extends the claim for as long as the write runs also extends it forever
+// when the write never returns, and nothing else can reclaim the receipt short
+// of a restart. So renewal is bounded past the slowest write this daemon budgets
+// for — MountSlackWriteback's 90s confirm on top of its writeFile — and beyond
+// that the write is not slow, it is wedged: the heartbeat stops, the idle lease
+// runs out, and the retry that owns the queued replies can take them back.
+const SLACK_PROVIDER_LEASE_MAX_RENEWAL_MS = 5 * 60_000;
 const SLACK_CONVERSATION_TURN_RETRY_MS = 1_000;
 const SLACK_REPLY_ROUTE_RETRY_MS = 1_000;
+// One pass drains the whole chain (#slackReplyRoutes holds only the newest
+// route per key and every route awaits its predecessor). The extra passes only
+// exist so the drain can prove quiescence rather than assume it.
+const SLACK_REPLY_ROUTE_DRAIN_PASSES = 8;
+const SLACK_TERMINAL_THREAD_GRACE_MS = 24 * 60 * 60_000;
+const SLACK_TERMINAL_RECEIPT_RETRY_MS = 1_000;
+const SLACK_TERMINAL_RECEIPT_RETRY_MAX_MS = 5 * 60_000;
 const MERGE_GATE_MAX_ATTEMPTS = 12;
 const MERGE_GATE_POLL_DELAY_MS = 10_000;
 const MAX_LABEL_IMPLEMENTERS = 4;
@@ -160,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]';
@@ -215,6 +274,39 @@ class DispatchLifecycleOwnedElsewhereError extends Error {
         this.leaseUntilMs = leaseUntilMs;
     }
 }
+/**
+ * The durable dispatch-lifecycle claim was refused for one work unit: its
+ * record is already terminal, or another publisher currently holds the lease.
+ * Both are facts about that single unit — the rest of the pass is unaffected —
+ * so the readiness loop skips it and keeps going (#292).
+ *
+ * Typed rather than left as a plain `Error` so the loop can classify it by
+ * construction instead of by matching on `Refusing to dispatch ...` text.
+ */
+class DispatchLifecycleClaimRefusedError extends Error {
+    issueKey;
+    refusal;
+    constructor(issueKey, refusal, message) {
+        super(message);
+        this.issueKey = issueKey;
+        this.refusal = refusal;
+        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)),
@@ -266,6 +358,19 @@ export class FactoryLoop {
     #dispatchInFlight = new Map();
     #slackWatchers = new Map();
     #slackWatcherStarts = new Map();
+    #slackTerminalWatchExpiryTimers = new Map();
+    #slackTerminalReceiptRetryTimers = new Map();
+    #terminalSlackWatchIssues = new Set();
+    /**
+     * The one in-memory record of "this work unit has an in-flight Slack side
+     * effect". Both ordinary reply routes and the writebacks the terminal fence
+     * issues on their behalf register here, because this map is what the terminal
+     * drain waits on: anything that touches Slack for a work unit without
+     * registering is invisible to the drain, and the watcher teardown that follows
+     * a successful drain then pulls that effect's retry timer out from under it.
+     */
+    #slackReplyRoutes = new Map();
+    #slackReplyRouteDrains = new Set();
     #slackConversationTurns;
     #slackConversationOwner = `${process.pid}:${randomUUID()}`;
     #githubIssueCommentWatchers = new Map();
@@ -351,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;
@@ -439,7 +573,39 @@ export class FactoryLoop {
     #discoverySweepRenewTimer;
     #discoverySweepRenewalInFlight;
     #discoverySweepLeaseLost = false;
+    // Registry/heartbeat paths the in-flight runLoop iteration would use. A
+    // per-item dispatch failure now skips instead of aborting the pass (#292),
+    // 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;
@@ -855,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 {
@@ -907,6 +1081,14 @@ export class FactoryLoop {
             await this.#boundedStopTeardown('factory subscription unsubscribe', () => subscription?.unsubscribe());
             await Promise.all([...this.#slackWatchers.values()].map((watcher) => watcher.stop()));
             this.#slackWatchers.clear();
+            for (const timer of this.#slackTerminalWatchExpiryTimers.values())
+                clearTimeout(timer);
+            this.#slackTerminalWatchExpiryTimers.clear();
+            for (const timer of this.#slackTerminalReceiptRetryTimers.values())
+                clearTimeout(timer);
+            this.#slackTerminalReceiptRetryTimers.clear();
+            this.#terminalSlackWatchIssues.clear();
+            this.#slackReplyRouteDrains.clear();
             await Promise.all([...this.#githubIssueCommentWatchers.values()].map((watcher) => watcher.stop()));
             this.#githubIssueCommentWatchers.clear();
             this.#githubIssueCommentWatchStates.clear();
@@ -997,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();
@@ -1033,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.
@@ -1128,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) {
@@ -1176,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,
@@ -1197,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,
@@ -1210,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) {
@@ -1938,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
@@ -1954,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');
@@ -1970,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
@@ -1997,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
@@ -2008,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();
@@ -2047,19 +2443,65 @@ export class FactoryLoop {
                     reason: entry.reason,
                 });
             };
+            // Backstop for the skip-by-default catch below: see #292. Reset only by
+            // a completed dispatch, so the name says "since a dispatch" rather than
+            // "consecutive" — a benign classified skip in between does not clear it.
+            let unclassifiedFailuresSinceDispatch = 0;
             let lastReadyReadProgressAtMs = this.#clock.now();
             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') {
@@ -2144,19 +2586,13 @@ export class FactoryLoop {
                     }
                     const decision = await this.triageIssue(issue);
                     triaged.push(decision);
-                    let result;
-                    try {
-                        result = await this.dispatch(decision, { dryRun });
-                    }
-                    catch (error) {
-                        if (!(error instanceof LiveDispatchStateChangedError))
-                            throw error;
-                        recordSkip({ issue: decision.issue, reason: 'live state changed during dispatch' });
-                        this.#logger.info?.('[factory] skipped issue whose live state changed during dispatch', {
-                            issue: decision.issue.key,
-                        });
-                        continue;
-                    }
+                    const result = await this.dispatch(decision, { dryRun });
+                    // 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'}`
@@ -2169,6 +2605,81 @@ export class FactoryLoop {
                         dispatched.push(result);
                     }
                 }
+                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)) {
+                        // 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
+                        // that dispatched nothing, which is the same silent wedge #292 is
+                        // about, wearing the opposite costume. Fail the pass loudly so
+                        // `readinessReconcile.lastError` carries the cause.
+                        if (unclassifiedFailuresSinceDispatch >= UNCLASSIFIED_DISPATCH_FAILURE_LIMIT) {
+                            throw contextualError(`Aborting readiness pass after ${unclassifiedFailuresSinceDispatch} unclassified dispatch failures without a successful dispatch`, error);
+                        }
+                        this.#increment('dispatchItemFailuresSkipped');
+                        // The raw message is operator-facing only; the run report carries
+                        // the sanitized classification from `perItemDispatchSkipReason`.
+                        this.#logger.warn?.('[factory] skipped a work unit whose dispatch failed; continuing the pass', {
+                            issue: issueRef(issue).key,
+                            unclassifiedFailuresSinceDispatch,
+                            error: describeError(error).errorMessage,
+                        });
+                        this.#error(error, issueRef(issue));
+                    }
+                    else {
+                        // Not an error — the unit simply cannot be dispatched right now —
+                        // so this stays out of `counters.errors` and gets its own counter
+                        // instead, or a terminal-lifecycle backlog would be invisible to
+                        // anyone watching only `dispatchItemFailuresSkipped`.
+                        this.#increment('dispatchItemsSkippedUndispatchable');
+                        this.#logger.info?.('[factory] skipped a work unit that cannot be dispatched right now', {
+                            issue: issueRef(issue).key,
+                            error: describeError(error).errorMessage,
+                        });
+                    }
+                    recordSkip({ issue: issueRef(issue), reason: perItemDispatchSkipReason(error) });
+                    continue;
+                }
                 finally {
                     if (recoveredIdentity)
                         this.#reconciledGithubInProgress.delete(recoveredIdentity);
@@ -2202,6 +2713,103 @@ 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.
+     *
+     * The default is the opposite, and that inversion is the fix for #292.
+     * Issues in a pass are independent work units: a failure that is *about one
+     * unit* — its dispatch-lifecycle record, its live state, a provider fault on
+     * its own writeback — costs that unit and nothing else. Before this, every
+     * error except `LiveDispatchStateChangedError` escaped the `for` loop, so a
+     * single issue whose lifecycle record had gone terminal stopped all dispatch
+     * indefinitely, every pass.
+     *
+     * A condition belongs here only when continuing the pass is meaningless or
+     * actively harmful — when the failure is about the *pass*, not the item:
+     *
+     * - The discovery sweep lease is gone. Another process now owns this
+     *   workspace's sweep, so every remaining read throws the same way and each
+     *   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 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**.
+     *   Dispatch is globally paused — the same condition
+     *   `#assertFleetControlPlaneAvailable` refuses to *start* a live pass on,
+     *   so it must also stop one already in flight. A dry run is exempt: it
+     *   never calls that admission gate and never spawns, so a paused control
+     *   plane is irrelevant to it rather than fatal to it. Without the
+     *   exemption, one live pass that trips the circuit would poison every
+     *   later dry run — including the boot gate's own `run-once --dry-run`
+     *   probe, turning a recoverable circuit-open condition into a failed boot.
+     *   That is a nastier version of the wedge this whole change removes.
+     *
+     * Deliberately NOT here: JavaScript builtin error types. Classifying
+     * "programmer faults" such as `TypeError` as fatal is the obvious next rule
+     * and it is a trap — Node reports a failed `fetch` as `TypeError: fetch
+     * failed`, which is precisely the transient per-item roster lookup that
+     * wedged the second instance (#291). A rule keyed on builtin types would
+     * have preserved that outage verbatim.
+     *
+     * Everything else — a refused lifecycle claim, a terminal lifecycle record,
+     * a transient network fault on one issue — is per-item: record a skip and
+     * keep going. The unclassified-failure fuse in `#performRunOnce` is the
+     * backstop for a pass-wide fault that does not announce itself as one.
+     */
+    #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.#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.
+        return !dryRun && this.#isFleetControlPlaneHalted(error);
+    }
+    /**
+     * Whether dispatch is globally paused by the fleet control-plane circuit.
+     *
+     * Two reads, because the circuit announces itself two different ways. The
+     * state read covers `guardedMutation`, which records a mutation's own
+     * transport failure and rethrows the *original* error rather than the
+     * circuit-open type — converting it there would be wrong, since the mutation
+     * may already have reached the broker and callers key spawn-failure handling
+     * off that original error. The type check covers a rejection raised without
+     * any state transition, such as an already-open circuit refusing admission.
+     */
+    #isFleetControlPlaneHalted(error) {
+        return this.#fleetControlPlane.status().state !== 'closed' ||
+            wrapsErrorOfType(error, FleetControlPlaneCircuitOpenError);
+    }
     #startDiscoverySweepRenewal(epoch) {
         this.#discoverySweepRenewTimer = setInterval(() => {
             if (this.#discoverySweepRenewalInFlight || this.#discoverySweepLeaseLost)
@@ -3047,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,
                 });
             }
@@ -3085,6 +3719,7 @@ export class FactoryLoop {
         const maxConsecutiveFailures = Math.min(5, Math.max(1, Math.trunc(opts.maxConsecutiveFailures ?? this.#config.loop.maxConsecutiveFailures)));
         const heartbeatPath = opts.heartbeatPath ?? this.#config.loop.heartbeatPath;
         const registryPath = opts.registryPath ?? this.#config.loop.registryPath;
+        this.#loopReapPaths = { heartbeatPath, registryPath };
         const reports = [];
         let consecutiveFailures = 0;
         let completed = false;
@@ -3140,6 +3775,7 @@ export class FactoryLoop {
             return reports;
         }
         finally {
+            this.#loopReapPaths = undefined;
             if (!completed) {
                 await this.#writeLoopHeartbeat(heartbeatPath, registryPath, 'stopping', reports.length, maxIterations);
             }
@@ -3615,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 }
                 : {}),
@@ -3639,6 +4324,9 @@ export class FactoryLoop {
                 ? { lastFailureAtMs: this.#readinessReconcileLastFailureAtMs }
                 : {}),
             ...(this.#readinessReconcileLastError ? { lastError: this.#readinessReconcileLastError } : {}),
+            ...(this.#readinessReconcileLastErrorClass
+                ? { lastErrorClass: this.#readinessReconcileLastErrorClass }
+                : {}),
         };
     }
     on(event, listener) {
@@ -4142,10 +4830,11 @@ export class FactoryLoop {
             seed.decision = decisionWithLifecycleBranches(seed.decision, seed.runId);
         const claim = await this.#state.claimDispatchLifecycle(this.#workspaceId, key, seed, this.#dispatchLifecycleOwner, this.#clock.now(), DISPATCH_LIFECYCLE_LEASE_MS);
         if (!claim.acquired || !claim.lease) {
-            const reason = isTerminalDispatchLifecycle(claim.lifecycle)
+            const terminal = isTerminalDispatchLifecycle(claim.lifecycle);
+            const reason = terminal
                 ? 'dispatch lifecycle is already terminal'
                 : `dispatch lifecycle is owned by ${claim.lifecycle.lease?.owner ?? 'another publisher'}`;
-            throw new Error(`Refusing to dispatch ${decision.issue.key}: ${reason}`);
+            throw new DispatchLifecycleClaimRefusedError(decision.issue.key, terminal ? 'terminal' : 'owned-elsewhere', `Refusing to dispatch ${decision.issue.key}: ${reason}`);
         }
         this.#dispatchLifecycleEpochs.set(claim.key ?? key, claim.lease.epoch);
         this.#hydrateCostLedger(claim.lifecycle);
@@ -5008,7 +5697,7 @@ export class FactoryLoop {
         for (const [name] of record.agents) {
             this.#fleet.markAgentTerminal?.(name, 'durable-dispatch-abandoned');
         }
-        await this.#stopSlackWatcher(record.issue);
+        await this.#retireSlackWatcher(record);
         await this.#stopGithubIssueCommentWatcherForIssue(record.issue);
         await this.#writeInFlightRegistry();
         this.#increment('dispatchLifecycleStaleIssuesAbandoned');
@@ -6114,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);
@@ -6131,12 +6843,19 @@ export class FactoryLoop {
             },
         });
     }
-    async #reapDispatchFailureHandoffsNow(heartbeatPath, registryPath) {
-        const handoffs = await this.#state.listFailureHandoffs(this.#workspaceId);
-        if (handoffs.length === 0) {
-            return;
-        }
+    async #reapDispatchFailureHandoffsNow(heartbeatPath = this.#loopReapPaths?.heartbeatPath ?? this.#config.loop.heartbeatPath, registryPath = this.#loopReapPaths?.registryPath ?? this.#config.loop.registryPath) {
         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();
@@ -7149,6 +7868,7 @@ export class FactoryLoop {
     }
     async #publishImplementerPullRequest(record, implementer, opts = {}) {
         const key = `${issueKey(record.issue)}:${implementer.spec.repo}`;
+        const trajectorySessionRef = canonicalTrajectorySessionRef(implementer.sessionRef);
         const expectedHeadRef = implementer.spec.branch;
         if (!expectedHeadRef) {
             throw new Error(`Refusing to publish ${record.issue.key}: implementer has no Factory-derived branch`);
@@ -7214,7 +7934,7 @@ export class FactoryLoop {
             expectedHeadRef,
             baseRef,
             title: `${issue.key}: ${issue.title}`,
-            body: githubPullRequestBody(issue, implementer.spec.preview),
+            body: githubPullRequestBody(issue, implementer.spec.preview, trajectorySessionRef),
             ...(implementer.sessionRef ? { sessionRef: implementer.sessionRef } : {}),
         });
         const published = result.author
@@ -7803,7 +8523,7 @@ export class FactoryLoop {
         await this.#recordDispatchTerminal(record.issue);
         const next = (await this.#batch()).complete(record.issue);
         await this.#drainReadyClarificationWake();
-        await this.#stopSlackWatcher(record.issue);
+        await this.#retireSlackWatcher(record);
         await this.#stopGithubIssueCommentWatcherForIssue(record.issue);
         await this.#writeInFlightRegistry();
         if (next) {
@@ -11763,7 +12483,7 @@ export class FactoryLoop {
             }
             if (!await this.#saveDispatchLifecycle(record, 'releasing', undefined, releaseReason))
                 return;
-            await this.#stopSlackWatcher(record.issue);
+            await this.#retireSlackWatcher(record);
             await this.#stopGithubIssueCommentWatcherForIssue(record.issue);
             await this.#recordDispatchTerminal(record.issue);
             await this.#finishDurableRelease(record, releaseReason);
@@ -12241,6 +12961,21 @@ export class FactoryLoop {
             return;
         }
         const key = issueKey(record.issue);
+        const previousWatch = (await this.#state.listSlackThreadWatches(this.#workspaceId))
+            .find(([watchKey]) => watchKey === key)?.[1];
+        if (previousWatch?.kind === 'terminal-grace') {
+            // A reopened work unit needs a fresh dispatch notification and a fresh
+            // conversation. Do not let the old grace-period watcher (or its expiry
+            // timer) capture and later tear down the new dispatch.
+            if (!await this.#stopSlackWatcher(record.issue)) {
+                // Fail closed. An undrained reply route still holds the retired thread
+                // and would bind it to this dispatch, delivering a stale human reply to
+                // fresh work. Leave the fence up; the next reconcile retries the drain.
+                this.#logger.warn?.('[factory] deferring Slack dispatch thread for reopened work unit; in-flight reply route not drained', { issue: record.issue.key });
+                this.#increment('slackDispatchThreadsDeferredUndrainedReply');
+                return;
+            }
+        }
         const existingThread = await this.#persistedSlackThread(key);
         const watcherStart = this.#slackWatcherStarts.get(key);
         if (existingThread || watcherStart) {
@@ -12323,9 +13058,10 @@ export class FactoryLoop {
         if (existing) {
             const sessionRef = owned?.tracked.sessionRef;
             const agentName = owned ? (owned.tracked.result?.name ?? owned.name) : undefined;
+            let rebound = false;
             if (owned && sessionRef &&
-                (agentName !== existing.agent.name || (options.forceAgentRebind === true && sessionRef !== existing.agent.sessionRef))) {
-                const rebound = await this.#state.rebindConversationSession(this.#workspaceId, conversationId, {
+                (!existing.agent || agentName !== existing.agent.name || (options.forceAgentRebind === true && sessionRef !== existing.agent.sessionRef))) {
+                rebound = await this.#state.rebindConversationSession(this.#workspaceId, conversationId, {
                     name: agentName,
                     sessionRef,
                     role: owned.tracked.spec.role,
@@ -12339,40 +13075,39 @@ export class FactoryLoop {
             }
             if (existing.pending.length > 0 || existing.delivery) {
                 const waiting = await this.#state.getWaitingClarification(this.#workspaceId, issueKey(existing.issue));
-                if (!waiting)
+                if (!waiting && (existing.agent || rebound))
                     this.#slackConversationTurns.schedule(conversationId);
             }
             return;
         }
         const sessionRef = owned?.tracked.sessionRef;
-        if (!owned || !sessionRef) {
-            this.#increment('slackConversationSessionsSkippedMissingSession');
-            return;
-        }
         const channelDir = await this.#slackChannelDir() ?? this.#config.slack?.channel;
         if (!channelDir)
             return;
-        const agentName = owned.tracked.result?.name ?? owned.name;
+        const agentName = owned ? (owned.tracked.result?.name ?? owned.name) : undefined;
         const reserved = await this.#state.reserveConversationSession(this.#workspaceId, conversationId, {
             provider: 'slack',
             issue: { ...record.issue },
             externalId: threadId,
             context: { channelDir },
-            agent: {
-                name: agentName,
-                sessionRef,
-                role: owned.tracked.spec.role,
-                node: owned.tracked.result?.node ?? owned.tracked.spec.node,
-                capability: owned.tracked.spec.capability,
-                repo: owned.tracked.spec.repo,
-                clonePath: owned.tracked.spec.clonePath,
-            },
+            ...(owned && sessionRef && agentName ? { agent: {
+                    name: agentName,
+                    sessionRef,
+                    role: owned.tracked.spec.role,
+                    node: owned.tracked.result?.node ?? owned.tracked.spec.node,
+                    capability: owned.tracked.spec.capability,
+                    repo: owned.tracked.spec.repo,
+                    clonePath: owned.tracked.spec.clonePath,
+                } } : {}),
             history: [],
             processedMessageIds: [],
+            acknowledgedMessageIds: [],
+            acknowledgementClaims: {},
             pending: [],
         });
-        if (reserved)
-            this.#increment('slackConversationSessionsOwned');
+        if (reserved) {
+            this.#increment(owned && sessionRef ? 'slackConversationSessionsOwned' : 'slackConversationSessionsReservedUnowned');
+        }
     }
     // Called right after a babysitter is spawned/reattached for an issue's PR so
     // an already-owned Slack conversation session (reserved earlier by the
@@ -12400,11 +13135,15 @@ export class FactoryLoop {
         const claimed = await this.#state.claimConversationTurn(this.#workspaceId, conversationId, this.#slackConversationOwner, claimId, this.#clock.now(), SLACK_CONVERSATION_TURN_LEASE_MS);
         if (!claimed?.delivery) {
             const current = await this.#state.getConversationSession(this.#workspaceId, conversationId);
-            if (current && (current.pending.length > 0 || current.delivery)) {
+            if (current?.agent && (current.pending.length > 0 || current.delivery)) {
                 this.#slackConversationTurns.schedule(conversationId, SLACK_CONVERSATION_TURN_RETRY_MS);
             }
             return;
         }
+        if (!claimed.agent) {
+            await this.#state.releaseConversationTurn(this.#workspaceId, conversationId, this.#slackConversationOwner, claimId);
+            return;
+        }
         if (!await this.#ownsActiveSlackConversationIssue(claimed.issue)) {
             await this.#state.releaseConversationTurn(this.#workspaceId, conversationId, this.#slackConversationOwner, claimId);
             this.#increment('slackConversationTurnsSuppressedStaleOwner');
@@ -12488,10 +13227,13 @@ export class FactoryLoop {
         }
     }
     async #recordSlackConversationResume(session, result) {
+        const sessionAgent = session.agent;
+        if (!sessionAgent)
+            return;
         const record = (await this.#batch()).getIssue(session.issue);
         if (!record)
             return;
-        const entry = [...record.agents.entries()].find(([name, tracked]) => name === session.agent.name || tracked.result?.name === session.agent.name);
+        const entry = [...record.agents.entries()].find(([name, tracked]) => name === sessionAgent.name || tracked.result?.name === sessionAgent.name);
         if (!entry)
             return;
         const [previousName, tracked] = entry;
@@ -12817,7 +13559,14 @@ export class FactoryLoop {
                 `Question: ${triageEscalationQuestion(decision, issue)}`,
             ].join('\n'),
         });
-        await this.#state.setSlackThread(this.#workspaceId, issueKey(decision.issue), root.threadId);
+        const key = issueKey(decision.issue);
+        await this.#state.setSlackThread(this.#workspaceId, key, root.threadId);
+        await this.#state.setSlackThreadWatch(this.#workspaceId, key, {
+            kind: 'triage',
+            issue: { ...decision.issue },
+            decision: structuredClone(decision),
+            threadId: root.threadId,
+        });
         const replayedResult = await this.#watchSlackThread(escalationWatchRecord(decision), root.threadId);
         this.#recordSlackWritebackSuccess('triage-escalation');
         return replayedResult;
@@ -12883,6 +13632,11 @@ export class FactoryLoop {
                 if (!reply || !reply.isThreadReply || reply.threadTs !== threadId || reply.channelDir !== channelDir) {
                     return;
                 }
+                if (allowPreExisting &&
+                    options.replayAfterMs !== undefined &&
+                    slackMessageReceivedAtMs(reply.messageTs, Number.MAX_SAFE_INTEGER) < options.replayAfterMs) {
+                    return;
+                }
                 const replyMessageKey = `${reply.threadTs}:${reply.messageTs}`;
                 if (seenReplyMessages.has(replyMessageKey)) {
                     this.#logger.debug?.('[factory] suppressed duplicate Slack reply message', { issue: record.issue.key, path });
@@ -13061,6 +13815,47 @@ export class FactoryLoop {
                 this.#slackConversationTurns.schedule(conversationId);
             }
         }
+        for (const [key, watch] of await this.#state.listSlackThreadWatches(this.#workspaceId)) {
+            if (this.#slackWatchers.has(key) || this.#slackWatcherStarts.has(key))
+                continue;
+            if (watch.kind === 'terminal-grace' && watch.expiresAtMs <= this.#clock.now()) {
+                await this.#stopSlackWatcher(watch.issue);
+                continue;
+            }
+            await this.#state.setSlackThread(this.#workspaceId, key, watch.threadId);
+            const watchRecord = escalationWatchRecord(watch.decision);
+            if (watch.kind === 'terminal-grace') {
+                const retiredAtMs = terminalSlackWatchRetiredAtMs(watch);
+                if (watch.retiredAtMs !== retiredAtMs) {
+                    await this.#state.setSlackThreadWatch(this.#workspaceId, key, { ...watch, retiredAtMs });
+                }
+                this.#terminalSlackWatchIssues.add(key);
+                const conversationId = slackConversationId(watch.threadId);
+                await this.#slackConversationTurns.cancel(conversationId);
+                try {
+                    await this.#surfaceUndeliveredSlackConversation(watch.threadId);
+                    await this.#state.clearConversationSession(this.#workspaceId, conversationId);
+                }
+                catch (error) {
+                    // The undelivered-reply receipt needs Slack writeback, which may be
+                    // unavailable at startup. That is retryable state maintenance for this
+                    // one thread, not a reason to abandon rehydration: aborting here would
+                    // leave every remaining thread watched by nobody. Keep the queued
+                    // replies (clearing them now would drop replies nobody was told about)
+                    // and carry on re-arming.
+                    this.#logger.warn?.('[factory] failed to settle undelivered Slack replies for terminal watch; will retry', { issue: watch.issue.key, error });
+                    this.#increment('slackTerminalWatchReceiptsDeferred');
+                    this.#scheduleSlackTerminalReceiptRetry(watch.issue, watch.threadId, watch.expiresAtMs);
+                }
+                await this.#rearmSlackWatcher(watchRecord, watch.threadId, {
+                    replayConversationReplies: true,
+                    replayAfterMs: retiredAtMs,
+                });
+                this.#scheduleSlackTerminalWatchExpiry(watch.issue, watch.expiresAtMs);
+                continue;
+            }
+            await this.#rearmSlackWatcher(watchRecord, watch.threadId, { replayConversationReplies: true });
+        }
         await this.#sweepWaitingClarifications();
         for (const [, waiting] of await this.#state.listWaitingClarifications(this.#workspaceId)) {
             if (!waiting.threadId)
@@ -13206,8 +14001,73 @@ export class FactoryLoop {
         this.#clarificationSweepTimer = timer;
         this.#clarificationSweepDueAtMs = dueAtMs;
     }
+    // The terminal fence is the only thing that makes an in-flight reply route
+    // answer "no active agent" instead of binding the retired thread to whatever
+    // dispatch owns this key. Routes are chained per work unit, so awaiting the
+    // newest one drains every reply queued behind it.
+    async #drainSlackReplyRoutes(key) {
+        // Snapshotting #slackReplyRoutes is not enough on its own. A reply handler
+        // that is still inside its mount read when the drain starts registers its
+        // route *after* the snapshot, so it would run once the fence is gone and
+        // bind the retired thread to the next dispatch — the same escape one level
+        // in. Bar *routing* for this key first (the bar and the registration are
+        // both synchronous, so nothing can slip between them), then drain whatever
+        // is already chained, then prove the set is empty before reporting success.
+        // A barred reply still answers the human, and that writeback registers here
+        // like any other effect, so the extra passes are what pick it up: quiescence
+        // means every effect this work unit started has settled, not merely the ones
+        // that existed when the drain began.
+        const nested = this.#slackReplyRouteDrains.has(key);
+        this.#slackReplyRouteDrains.add(key);
+        try {
+            for (let pass = 0; pass < SLACK_REPLY_ROUTE_DRAIN_PASSES; pass += 1) {
+                const route = this.#slackReplyRoutes.get(key);
+                if (!route)
+                    return true;
+                try {
+                    await route;
+                }
+                catch (error) {
+                    // A route that *rejects* is not drained: the watcher replays it after
+                    // SLACK_REPLY_ROUTE_RETRY_MS, and that replay would land on the next
+                    // dispatch. Fail closed and let the caller keep the fence up rather
+                    // than leak a stale human reply onto fresh work.
+                    this.#logger.warn?.('[factory] in-flight Slack reply route did not drain; keeping terminal Slack fence', { issue: key, error });
+                    this.#increment('slackReplyRouteDrainsFailed');
+                    return false;
+                }
+                // The owner clears its own entry when it settles; retiring it here too
+                // keeps the loop monotonic if that finally has not run yet.
+                if (this.#slackReplyRoutes.get(key) === route)
+                    this.#slackReplyRoutes.delete(key);
+            }
+            // Not provably quiescent. Fail closed for the same reason as a rejection.
+            this.#logger.warn?.('[factory] Slack reply routes did not quiesce; keeping terminal Slack fence', { issue: key });
+            this.#increment('slackReplyRouteDrainsFailed');
+            return false;
+        }
+        finally {
+            if (!nested)
+                this.#slackReplyRouteDrains.delete(key);
+        }
+    }
     async #stopSlackWatcher(issue) {
         const key = issueKey(issue);
+        // Drain before clearing the fence. Clearing it first lets a reply that is
+        // already mid-route — or one queued behind it — fall through the fence check
+        // in #routeSlackConversationAnswerUnlocked and rebind the retired thread to
+        // the next dispatch of this work unit.
+        if (!await this.#drainSlackReplyRoutes(key))
+            return false;
+        this.#terminalSlackWatchIssues.delete(key);
+        const expiryTimer = this.#slackTerminalWatchExpiryTimers.get(key);
+        if (expiryTimer)
+            clearTimeout(expiryTimer);
+        this.#slackTerminalWatchExpiryTimers.delete(key);
+        const receiptRetryTimer = this.#slackTerminalReceiptRetryTimers.get(key);
+        if (receiptRetryTimer)
+            clearTimeout(receiptRetryTimer);
+        this.#slackTerminalReceiptRetryTimers.delete(key);
         const watcher = this.#slackWatchers.get(key);
         this.#slackWatchers.delete(key);
         const threadId = await this.#state.getSlackThread(this.#workspaceId, key);
@@ -13218,6 +14078,259 @@ export class FactoryLoop {
             await this.#state.clearConversationSession(this.#workspaceId, conversationId);
         }
         await this.#state.clearSlackThread(this.#workspaceId, key);
+        await this.#state.clearSlackThreadWatch(this.#workspaceId, key);
+        return true;
+    }
+    async #retireSlackWatcher(record) {
+        const key = issueKey(record.issue);
+        const threadId = await this.#state.getSlackThread(this.#workspaceId, key);
+        if (!threadId) {
+            await this.#stopSlackWatcher(record.issue);
+            return;
+        }
+        const existingWatch = (await this.#state.listSlackThreadWatches(this.#workspaceId))
+            .find(([watchKey]) => watchKey === key)?.[1];
+        const retiredAtMs = existingWatch?.kind === 'terminal-grace'
+            ? terminalSlackWatchRetiredAtMs(existingWatch)
+            : this.#clock.now();
+        const expiresAtMs = existingWatch?.kind === 'terminal-grace'
+            ? existingWatch.expiresAtMs
+            : retiredAtMs + SLACK_TERMINAL_THREAD_GRACE_MS;
+        await this.#state.setSlackThreadWatch(this.#workspaceId, key, {
+            kind: 'terminal-grace',
+            issue: { ...record.issue },
+            decision: structuredClone(record.decision),
+            threadId,
+            retiredAtMs,
+            expiresAtMs,
+        });
+        // A terminal thread must never retain a resumable session for an agent that
+        // has already exited. Keep only the exact-thread listener so a late human
+        // reply receives the explicit no-active-agent writeback below.
+        this.#terminalSlackWatchIssues.add(key);
+        await this.#slackReplyRoutes.get(key)?.catch(() => undefined);
+        const conversationId = slackConversationId(threadId);
+        await this.#slackConversationTurns.cancel(conversationId);
+        try {
+            await this.#surfaceUndeliveredSlackConversation(threadId);
+            await this.#state.clearConversationSession(this.#workspaceId, conversationId);
+        }
+        catch (error) {
+            // The receipt fails whenever another handler holds the claim or Slack
+            // writeback is down — neither is a reason to abort retirement. Callers
+            // reach here having already committed the terminal phase and dropped the
+            // pending abandon reason, so a rejection escaping would strand the
+            // registry rewrite, the GitHub watcher stop, and the queued next dispatch
+            // with nothing left to re-run them. Keep the queued replies and let the
+            // retry that owns this receipt settle it inside the grace window.
+            this.#logger.warn?.('[factory] failed to settle undelivered Slack replies while retiring the watcher; will retry', { issue: record.issue.key, error });
+            this.#increment('slackTerminalWatchReceiptsDeferred');
+            this.#scheduleSlackTerminalReceiptRetry(record.issue, threadId, expiresAtMs);
+        }
+        if (!this.#slackWatchers.has(key) && !this.#stopping) {
+            await this.#rearmSlackWatcher(record, threadId);
+        }
+        this.#scheduleSlackTerminalWatchExpiry(record.issue, expiresAtMs);
+        this.#increment('slackTerminalWatchersRetained');
+    }
+    // The durable half of the same record. Every caller here follows the receipt
+    // with a state write (clearing the session), and those two cannot be one
+    // durable step: when the state write fails, the retry that owns it must not
+    // read "replies still queued" as "the human has not been told" and post the
+    // notice again. So the receipt is claimed before the provider write and marked
+    // posted after it, and a retry finds it already settled.
+    async #surfaceUndeliveredSlackConversation(threadId) {
+        const conversationId = slackConversationId(threadId);
+        const session = await this.#state.getConversationSession(this.#workspaceId, conversationId);
+        const pendingCount = session
+            ? session.pending.length + (session.delivery?.messages.length ?? 0)
+            : 0;
+        if (pendingCount === 0)
+            return;
+        if (session?.terminalReceipt?.posted) {
+            this.#increment('slackTerminalReceiptsAlreadySettled');
+            return;
+        }
+        if (!this.#slack)
+            throw new Error(`Slack thread ${threadId} cannot surface undelivered replies without writeback`);
+        const claimId = randomUUID();
+        if (!await this.#state.claimConversationTerminalReceipt(this.#workspaceId, conversationId, claimId, this.#clock.now(), SLACK_TERMINAL_RECEIPT_CLAIM_LEASE_MS)) {
+            const current = await this.#state.getConversationSession(this.#workspaceId, conversationId);
+            if (current?.terminalReceipt?.posted) {
+                this.#increment('slackTerminalReceiptsAlreadySettled');
+                return;
+            }
+            // Another handler is mid-write. Fail closed so the queued replies survive
+            // for whoever settles them rather than racing a second notice onto the
+            // same thread.
+            throw new Error(`Slack thread ${threadId} terminal receipt is claimed by another handler; retrying`);
+        }
+        const noun = pendingCount === 1 ? 'reply' : 'replies';
+        const slack = this.#slack;
+        try {
+            await this.#withRenewedProviderLease('terminal Slack receipt', SLACK_TERMINAL_RECEIPT_CLAIM_LEASE_MS, () => this.#state.renewConversationTerminalReceipt(this.#workspaceId, conversationId, claimId, this.#clock.now()), () => slack.reply(threadId, `Factory could not deliver ${pendingCount} queued ${noun} because this work unit no longer has an active agent. Please continue on the linked issue or pull request.`));
+        }
+        catch (error) {
+            await this.#state.releaseConversationTerminalReceipt(this.#workspaceId, conversationId, claimId);
+            throw error;
+        }
+        if (!await this.#state.completeConversationTerminalReceipt(this.#workspaceId, conversationId, claimId)) {
+            throw new Error(`Slack thread ${threadId} terminal receipt could not be recorded`);
+        }
+        this.#increment('slackConversationRepliesSurfacedTerminal');
+    }
+    // A claim only means something for as long as it outlives the work it covers.
+    // A provider write can legitimately run past a fixed lease, at which point the
+    // claim stops protecting the write it was taken for and a second handler can
+    // post the same thing to the same human. Renewing on a heartbeat scopes the
+    // lease to the work instead of to a guessed duration, and leaves the idle
+    // timeout short enough that a holder that dies mid-write still frees it.
+    //
+    // The heartbeat is bounded on both ends, because a renewal loop that never
+    // stops is a lock with no owner check: a provider write that hangs would hold
+    // the receipt past every retry and past shutdown, and the human whose reply is
+    // queued behind it would be told nothing until the process restarts. So it
+    // stops at the ceiling and it stops when this daemon is stopping, and either
+    // way it says so — from there the claim ages out on its own idle lease and
+    // becomes reclaimable. The write may still land afterwards and duplicate the
+    // notice; a reply nobody can ever reclaim is the worse of the two.
+    async #withRenewedProviderLease(label, leaseMs, renew, run) {
+        const renewUntilMs = this.#clock.now() + SLACK_PROVIDER_LEASE_MAX_RENEWAL_MS;
+        let renewalStopped = false;
+        let renewalInFlight = false;
+        const stopRenewing = (counter, reason) => {
+            renewalStopped = true;
+            this.#increment(counter);
+            this.#logger.warn?.(`[factory] ${label} lease will not be renewed further (${reason}); ` +
+                'its claim expires and the queued replies return to whoever retries them');
+        };
+        const heartbeat = setInterval(() => {
+            if (renewalInFlight || renewalStopped)
+                return;
+            if (this.#stopping) {
+                stopRenewing('slackProviderReceiptLeaseRenewalsStoppedForShutdown', 'shutting down');
+                return;
+            }
+            if (this.#clock.now() >= renewUntilMs) {
+                stopRenewing('slackProviderReceiptLeaseRenewalsExpired', `provider write exceeded ${SLACK_PROVIDER_LEASE_MAX_RENEWAL_MS}ms`);
+                return;
+            }
+            renewalInFlight = true;
+            void renew()
+                .then((renewed) => {
+                if (renewed)
+                    return;
+                // Losing the lease mid-write is not recoverable from in here: the
+                // write may already have landed. Stop renewing and let the caller's
+                // completion check fail closed, which keeps the queued replies for
+                // whoever holds the claim now.
+                renewalStopped = true;
+                this.#increment('slackProviderReceiptLeasesLost');
+                this.#logger.warn?.(`[factory] ${label} lease was lost while its provider write was in flight`);
+            })
+                .catch((error) => this.#logger.warn?.(`[factory] ${label} lease renewal failed`, {
+                error: describeError(error).errorMessage,
+            }))
+                .finally(() => { renewalInFlight = false; });
+        }, Math.max(1_000, Math.floor(leaseMs / 3)));
+        heartbeat.unref?.();
+        try {
+            return await run();
+        }
+        finally {
+            clearInterval(heartbeat);
+        }
+    }
+    // A terminal receipt that could not be written leaves the queued replies
+    // pending with the human who wrote them told nothing. That is retryable
+    // maintenance this daemon owns, not work to leave for the next restart: the
+    // grace watch is the only window in which the receipt can still land on the
+    // retired thread, so keep reattempting inside it and give up when it closes.
+    #scheduleSlackTerminalReceiptRetry(issue, threadId, expiresAtMs, attempt = 0) {
+        if (this.#stopping)
+            return;
+        const key = issueKey(issue);
+        const existing = this.#slackTerminalReceiptRetryTimers.get(key);
+        if (existing)
+            clearTimeout(existing);
+        this.#slackTerminalReceiptRetryTimers.delete(key);
+        const remainingMs = expiresAtMs - this.#clock.now();
+        if (remainingMs <= 0) {
+            this.#increment('slackTerminalWatchReceiptsAbandoned');
+            return;
+        }
+        const backoffMs = Math.min(SLACK_TERMINAL_RECEIPT_RETRY_MAX_MS, SLACK_TERMINAL_RECEIPT_RETRY_MS * 2 ** Math.min(attempt, 16));
+        const timer = setTimeout(() => {
+            this.#slackTerminalReceiptRetryTimers.delete(key);
+            void this.#retrySlackTerminalReceipt(issue, threadId, attempt);
+        }, Math.max(0, Math.min(backoffMs, remainingMs)));
+        timer.unref?.();
+        this.#slackTerminalReceiptRetryTimers.set(key, timer);
+    }
+    async #retrySlackTerminalReceipt(issue, threadId, attempt) {
+        if (this.#stopping)
+            return;
+        const key = issueKey(issue);
+        const watch = (await this.#state.listSlackThreadWatches(this.#workspaceId))
+            .find(([watchKey]) => watchKey === key)?.[1];
+        // The grace watch is gone (expired, or the work unit reopened): the thread
+        // this receipt would settle no longer exists, so there is nothing to say.
+        if (watch?.kind !== 'terminal-grace' || watch.threadId !== threadId)
+            return;
+        try {
+            await this.#surfaceUndeliveredSlackConversation(threadId);
+            await this.#state.clearConversationSession(this.#workspaceId, slackConversationId(threadId));
+            this.#increment('slackTerminalWatchReceiptsRecovered');
+        }
+        catch (error) {
+            this.#logger.warn?.('[factory] terminal Slack receipt retry failed; rescheduling', {
+                issue: issue.key,
+                error,
+            });
+            this.#increment('slackTerminalWatchReceiptRetryFailures');
+            this.#scheduleSlackTerminalReceiptRetry(issue, threadId, watch.expiresAtMs, attempt + 1);
+        }
+    }
+    #scheduleSlackTerminalWatchExpiry(issue, expiresAtMs, retryDelayMs) {
+        if (this.#stopping)
+            return;
+        const key = issueKey(issue);
+        const existing = this.#slackTerminalWatchExpiryTimers.get(key);
+        if (existing)
+            clearTimeout(existing);
+        const timer = setTimeout(() => {
+            this.#slackTerminalWatchExpiryTimers.delete(key);
+            void this.#expireSlackTerminalWatcher(issue, expiresAtMs).catch((error) => {
+                this.#logger.warn?.('[factory] failed to expire terminal Slack reply watcher; retrying', {
+                    issue: issue.key,
+                    error,
+                });
+                this.#scheduleSlackTerminalWatchExpiry(issue, expiresAtMs, SLACK_REPLY_ROUTE_RETRY_MS);
+            });
+        }, retryDelayMs ?? Math.max(0, expiresAtMs - this.#clock.now()));
+        timer.unref?.();
+        this.#slackTerminalWatchExpiryTimers.set(key, timer);
+    }
+    async #expireSlackTerminalWatcher(issue, expiresAtMs) {
+        const key = issueKey(issue);
+        const watch = (await this.#state.listSlackThreadWatches(this.#workspaceId))
+            .find(([watchKey]) => watchKey === key)?.[1];
+        if (watch?.kind !== 'terminal-grace' || watch.expiresAtMs !== expiresAtMs)
+            return;
+        if (watch.expiresAtMs > this.#clock.now()) {
+            this.#scheduleSlackTerminalWatchExpiry(issue, watch.expiresAtMs);
+            return;
+        }
+        // #stopSlackWatcher fails closed when an in-flight reply route will not
+        // drain, leaving the watch and its terminal fence in place. Counting that as
+        // an expiration retires the watch in the metrics while the real one lives
+        // on unwatched by any expiry timer, so reschedule and count only on success.
+        if (!await this.#stopSlackWatcher(issue)) {
+            this.#increment('slackTerminalWatchExpiriesDeferred');
+            this.#scheduleSlackTerminalWatchExpiry(issue, expiresAtMs, SLACK_REPLY_ROUTE_RETRY_MS);
+            return;
+        }
+        this.#increment('slackTerminalWatchersExpired');
     }
     async #readSlackReply(path) {
         try {
@@ -13282,33 +14395,147 @@ export class FactoryLoop {
             await this.#wakeWaitingClarification(clarificationKey, claimed);
             return;
         }
+        return await this.#routeSlackConversationAnswer(record, reply, text, clarificationKey);
+    }
+    async #routeSlackConversationAnswer(record, reply, text, clarificationKey) {
+        if (this.#slackReplyRouteDrains.has(clarificationKey)) {
+            // The terminal fence for this work unit is being drained right now.
+            // Registering an ordinary route here would put it past the drain's
+            // snapshot and run it once the fence is gone. Answer it the way the fence
+            // would have — but as a tracked effect, because this writeback is still a
+            // side effect of this work unit. Left untracked it is the same escape one
+            // level further in: the drain reports quiescence without it, the watcher
+            // stop clears the retry timer that owns this reply, and a slow or failed
+            // receipt leaves the human told nothing at all.
+            this.#increment('slackReplyRoutesFencedDuringDrain');
+            return await this.#trackSlackWorkUnitEffect(clarificationKey, async () => {
+                await this.#writeUnroutableSlackReply(reply.threadTs);
+                return undefined;
+            });
+        }
+        return await this.#trackSlackWorkUnitEffect(clarificationKey, () => this.#routeSlackConversationAnswerUnlocked(record, reply, text, clarificationKey));
+    }
+    // Every Slack side effect a work unit makes on its own behalf runs through
+    // here, so #slackReplyRoutes stays the single record the terminal drain
+    // consults. Effects are chained per work unit: awaiting the newest one drains
+    // everything queued behind it, and a rejection propagates to the drain, which
+    // fails closed rather than tearing the effect's retry path down.
+    async #trackSlackWorkUnitEffect(key, run) {
+        const preceding = this.#slackReplyRoutes.get(key);
+        const effect = (async () => {
+            await preceding?.catch(() => undefined);
+            return await run();
+        })();
+        this.#slackReplyRoutes.set(key, effect);
+        try {
+            return await effect;
+        }
+        finally {
+            if (this.#slackReplyRoutes.get(key) === effect)
+                this.#slackReplyRoutes.delete(key);
+        }
+    }
+    async #routeSlackConversationAnswerUnlocked(record, reply, text, clarificationKey) {
+        if (this.#terminalSlackWatchIssues.has(clarificationKey)) {
+            await this.#writeUnroutableSlackReply(reply.threadTs);
+            return;
+        }
         const conversationId = slackConversationId(reply.threadTs);
-        const conversation = await this.#state.getConversationSession(this.#workspaceId, conversationId);
+        let conversation = await this.#state.getConversationSession(this.#workspaceId, conversationId);
+        let liveRecord;
+        if (!conversation) {
+            liveRecord = (await this.#batch()).getIssue(record.issue);
+            if (liveRecord && !liveRecord.dryRun) {
+                await this.#ensureSlackConversationSession(liveRecord, reply.threadTs);
+                conversation = await this.#state.getConversationSession(this.#workspaceId, conversationId);
+            }
+        }
         if (conversation && issueKey(conversation.issue) === clarificationKey) {
+            const replyId = `${reply.threadTs}:${reply.messageTs}`;
             const queued = await this.#state.appendConversationMessage(this.#workspaceId, conversationId, {
-                id: `${reply.threadTs}:${reply.messageTs}`,
+                id: replyId,
                 text,
                 receivedAtMs: slackMessageReceivedAtMs(reply.messageTs, this.#clock.now()),
                 providerSequence: reply.messageTs,
                 author: reply.author,
             });
-            if (!queued) {
+            const durable = queued ?? await this.#state.getConversationSession(this.#workspaceId, conversationId);
+            if (!durable || !durable.processedMessageIds.includes(replyId)) {
+                throw new Error(`Slack reply ${replyId} was not durably queued`);
+            }
+            if (!(durable.acknowledgedMessageIds ?? []).includes(replyId)) {
+                const acknowledgementClaimId = randomUUID();
+                const acknowledgementClaimed = await this.#state.claimConversationMessageAcknowledgement(this.#workspaceId, conversationId, replyId, acknowledgementClaimId, this.#clock.now(), SLACK_REPLY_ACKNOWLEDGEMENT_LEASE_MS);
+                if (acknowledgementClaimed) {
+                    try {
+                        if (!this.#slack)
+                            throw new Error(`Slack reply ${replyId} cannot be acknowledged without writeback`);
+                        const owner = durable.agent?.role === 'babysitter'
+                            ? 'the PR babysitter'
+                            : durable.agent
+                                ? 'the issue implementer'
+                                : 'an issue agent';
+                        const receipt = durable.agent
+                            ? `Factory received this reply and durably queued it for ${owner}.`
+                            : 'Factory received and durably stored this reply; it will route when an issue agent is resumable.';
+                        const slack = this.#slack;
+                        // Same lease scope as the terminal receipt: this claim covers a
+                        // provider write that can outrun any fixed duration, so it is
+                        // renewed for as long as that write is actually running.
+                        await this.#withRenewedProviderLease('Slack reply acknowledgement', SLACK_REPLY_ACKNOWLEDGEMENT_LEASE_MS, () => this.#state.renewConversationMessageAcknowledgement(this.#workspaceId, conversationId, replyId, acknowledgementClaimId, this.#clock.now()), () => slack.reply(reply.threadTs, receipt));
+                        if (!await this.#state.completeConversationMessageAcknowledgement(this.#workspaceId, conversationId, replyId, acknowledgementClaimId)) {
+                            throw new Error(`Slack reply ${replyId} receipt could not be recorded`);
+                        }
+                        this.#increment('slackConversationRepliesAcknowledged');
+                    }
+                    catch (error) {
+                        await this.#state.releaseConversationMessageAcknowledgement(this.#workspaceId, conversationId, replyId, acknowledgementClaimId);
+                        throw error;
+                    }
+                }
+                else {
+                    const acknowledgementState = await this.#state.getConversationSession(this.#workspaceId, conversationId);
+                    if (!(acknowledgementState?.acknowledgedMessageIds ?? []).includes(replyId)) {
+                        throw new Error(`Slack reply ${replyId} receipt is claimed by another handler; retrying`);
+                    }
+                }
+            }
+            if (queued) {
+                this.#increment('slackConversationRepliesQueued');
+            }
+            else {
                 this.#increment('slackConversationDuplicateRepliesSuppressed');
-                return;
             }
-            this.#increment('slackConversationRepliesQueued');
-            this.#slackConversationTurns.schedule(conversationId);
+            const pending = durable.pending.some((message) => message.id === replyId) ||
+                Boolean(durable.delivery?.messages.some((message) => message.id === replyId));
+            if (pending && durable.agent) {
+                this.#slackConversationTurns.schedule(conversationId);
+            }
+            else if (pending) {
+                this.#increment('slackConversationRepliesWaitingForOwner');
+            }
             return;
         }
-        const liveRecord = (await this.#batch()).getIssue(record.issue);
+        liveRecord ??= (await this.#batch()).getIssue(record.issue);
         if (!liveRecord || liveRecord.dryRun) {
             if (isTriageEscalationWatchRecord(record)) {
                 return await this.#handleTriageEscalationSlackAnswer(record, text);
             }
-            this.#increment('slackAnswersIgnoredNoInFlight');
+            await this.#writeUnroutableSlackReply(reply.threadTs);
             return;
         }
         this.#increment('slackAnswersIgnoredNoConversationSession');
+        if (this.#slack) {
+            await this.#slack.reply(reply.threadTs, 'Factory received this reply but could not create a durable agent route. It will remain replayable; please also continue on the linked issue or pull request.');
+            this.#increment('slackAnswersUnroutableVisible');
+        }
+    }
+    async #writeUnroutableSlackReply(threadId) {
+        this.#increment('slackAnswersIgnoredNoInFlight');
+        if (!this.#slack)
+            return;
+        await this.#slack.reply(threadId, 'Factory received this reply but could not route it because this work unit no longer has an active agent. Please continue on the linked issue or pull request.');
+        this.#increment('slackAnswersUnroutableVisible');
     }
     async #wakeWaitingClarification(key, waiting) {
         const existing = this.#clarificationWakeInFlight.get(key);
@@ -13680,6 +14907,7 @@ export class FactoryLoop {
         const batch = await this.#batch();
         if (batch.isInFlight(record.issue) || batch.isQueued(record.issue)) {
             this.#increment('slackTriageAnswersIgnoredAlreadyActive');
+            await this.#state.clearSlackThreadWatch(this.#workspaceId, issueKey(record.issue));
             return;
         }
         if (await this.#dispatchBlockReason(record.issue)) {
@@ -13696,6 +14924,10 @@ export class FactoryLoop {
             if (hasDispatchableRoute(decision)) {
                 this.#pendingSlackClarifications.set(issueKey(decision.issue), text);
                 const result = await this.#startOrQueueSlackClarifiedDecision(dispatchAfterSlackClarification(decision, escalationReason));
+                const active = await this.#batch();
+                if (result || active.isInFlight(decision.issue) || active.isQueued(decision.issue)) {
+                    await this.#state.clearSlackThreadWatch(this.#workspaceId, issueKey(record.issue));
+                }
                 this.#increment('slackTriageAnswersDispatchedWithRemainingEscalation');
                 return result;
             }
@@ -13708,6 +14940,10 @@ export class FactoryLoop {
         }
         this.#pendingSlackClarifications.set(issueKey(decision.issue), text);
         const result = await this.#startOrQueueSlackClarifiedDecision(decision);
+        const active = await this.#batch();
+        if (result || active.isInFlight(decision.issue) || active.isQueued(decision.issue)) {
+            await this.#state.clearSlackThreadWatch(this.#workspaceId, issueKey(record.issue));
+        }
         this.#increment('slackTriageAnswersDispatched');
         return result;
     }
@@ -14237,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.
@@ -16150,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);
@@ -16218,8 +17507,8 @@ const normalizeGithubRepo = (repo, defaultOwner) => {
     }
     return `${owner}/${repo}`;
 };
-const githubPullRequestBody = (issue, preview) => [
-    issue.description,
+const githubPullRequestBody = (issue, preview, sessionRef) => [
+    stripTrajectoryPointers(issue.description),
     '',
     isGithubIssue(issue) && /^\d+$/u.test(issue.key)
         ? `Fixes #${issue.key}`
@@ -16229,7 +17518,25 @@ const githubPullRequestBody = (issue, preview) => [
         `Live preview: ${preview.url}`,
         'Access: Tailscale tailnet membership and the tailnet grants/ACLs are required; this URL is not public.',
     ] : []),
+    '',
+    renderTrajectoryPointer({
+        ...trajectoryWorkUnitForIssue(issue),
+        sessionRef,
+    }),
 ].join('\n').trim();
+const trajectoryWorkUnitForIssue = (issue) => {
+    const github = githubIssueSourceRef(issue);
+    if (github) {
+        return {
+            workUnitId: `${github.owner}/${github.repo}#${github.number}`,
+            workUnitSurface: 'github',
+        };
+    }
+    if (isRealLinearIssue(issue)) {
+        return { workUnitId: issue.key, workUnitSurface: 'linear' };
+    }
+    return { workUnitId: `factory:${issue.uuid}`, workUnitSurface: 'factory' };
+};
 // The broker rejects re-registering a name it never released on exit
 // (relay#1116-family) with a 500 "agent '<name>' already exists". Detect it from
 // the structured payload or the message so resume can treat it as terminal
@@ -16258,6 +17565,9 @@ const slackMessageReceivedAtMs = (messageTs, fallback) => {
     const seconds = Number(messageTs);
     return Number.isFinite(seconds) && seconds > 0 ? Math.floor(seconds * 1_000) : fallback;
 };
+const terminalSlackWatchRetiredAtMs = (watch) => typeof watch.retiredAtMs === 'number' && Number.isFinite(watch.retiredAtMs)
+    ? watch.retiredAtMs
+    : Math.max(0, watch.expiresAtMs - SLACK_TERMINAL_THREAD_GRACE_MS);
 const eventIdentity = (event) => {
     const record = event;
     const rawId = record.id ?? record.event_id ?? record.seq;
@@ -16361,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;
@@ -16569,6 +17875,77 @@ export class LiveDispatchStateChangedError extends Error {
 export function isLiveDispatchStateChangedError(error) {
     return error instanceof LiveDispatchStateChangedError;
 }
+/** How deep to follow `cause` when classifying a wrapped failure. */
+const PASS_FATAL_CAUSE_DEPTH = 4;
+/**
+ * Whether `error`, or anything it wraps, is an instance of `type`.
+ * `contextualError` and the fleet control-plane guard both rethrow wrapped, so
+ * classification has to follow the cause chain rather than trust the outermost
+ * type.
+ */
+const wrapsErrorOfType = (error, type, depth = 0) => {
+    if (depth > PASS_FATAL_CAUSE_DEPTH || !(error instanceof Error))
+        return false;
+    if (error instanceof type)
+        return true;
+    return wrapsErrorOfType(error.cause, type, depth + 1);
+};
+/**
+ * How many *unclassified* per-item failures without an intervening successful
+ * dispatch end the pass. Named per-item conditions (a lifecycle claim refusal,
+ * a live-state race) never count toward it and never reset it: those
+ * legitimately affect many units at once and are exactly the benign case #292
+ * asks the loop to survive, so they are neither evidence of a pass-wide fault
+ * nor evidence against one.
+ */
+const UNCLASSIFIED_DISPATCH_FAILURE_LIMIT = 5;
+/**
+ * Failures the loop recognizes as belonging to one work unit. They are always
+ * skippable and are exempt from the consecutive-failure fuse.
+ */
+const isClassifiedPerItemDispatchFailure = (error) => error instanceof LiveDispatchStateChangedError ||
+    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.
+ *
+ * `factory run-once` serializes the whole report to stdout, so this string is
+ * a public surface: it stays a fixed classification plus an allowlisted error
+ * class name, never raw provider text or filesystem paths. The full message
+ * goes to the operator log instead, the same split
+ * `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) {
+        return error.refusal === 'terminal'
+            ? 'dispatch lifecycle already terminal'
+            : 'dispatch lifecycle owned by another publisher';
+    }
+    return `dispatch failed (${telemetryErrorClass(error)})`;
+};
 const triageEscalationQuestion = (decision, issue) => {
     const routedRepos = decision.routes.map((route) => route.repo).filter(Boolean);
     const subject = issue?.title?.trim() || decision.issue.key;