@agent-relay/factory 0.1.70 → 0.1.72

package/dist/orchestrator/factory.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { dirname, isAbsolute, resolve } from 'node:path';
 import { DEFAULT_READINESS_RECONCILE_TIMEOUT_MS, FactoryConfigSchema } from '../config/schema.js';
+import { DEFAULT_RELAYFILE_OPERATION_TIMEOUT_MS, RelayfileOperationTimeoutError, relayfileTimeoutWithPhase, withRelayfileCallDeadline, } from '../mount/relayfile-operation-timeout.js';
 import { linearByStatePath, linearByIdPath, linearByUuidPath } from '../constants/linear.js';
 import { stateResolutionFromIds } from '../linear/state-resolver.js';
 import { GithubMergeGate, closeProbePr } from '../github/index.js';
@@ -34,6 +35,7 @@ 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 { factorySweepSkipReasonCounts } from './sweep-skip-reason.js';
 import { boundedRunCostTotal, CostLedger } from '../cost/ledger.js';
 import { createTicketDispatchDelivery } from '../delivery/ticket-dispatch.js';
 import { canonicalTrajectorySessionRef, renderTrajectoryPointer, stripTrajectoryPointers, } from '../trajectory.js';
@@ -204,9 +206,25 @@ const DISPATCH_FAILURE_HANDOFF_UNRESOLVED_TTL_MS = 5 * 60_000;
 const DEFAULT_LIVE_HEARTBEAT_INTERVAL_MS = 15_000;
 const REMOTE_OPERATION_PROGRESS_INTERVAL_MS = 15_000;
 const REMOTE_OPERATION_SLOW_WARN_MS = 30_000;
+/** How far the cycle-level relayfile backstop sits above the transport deadline. */
+const RELAYFILE_OPERATION_BACKSTOP_RATIO = 1.25;
 const DISCOVERY_SWEEP_LEASE_MS = 5 * 60_000;
 const DISCOVERY_SWEEP_RENEW_MS = 30_000;
 const READINESS_RECONCILE_FAILURE_THRESHOLD = 3;
+/**
+ * A relayfile fault a swallowing catch must not turn into "no result".
+ *
+ * A 429 already escaped every one of these (#297): it is a fact about the
+ * dependency, not about the one item being read, so folding it into an empty
+ * result reports a clean pass over work that was never served.
+ *
+ * A per-call timeout (#351) is the same fact in a worse costume. The read that
+ * hung will hang for the next item too, and `#githubIssuePaths` swallowing it
+ * turns a wedged dependency into a *successful* sweep that discovered zero
+ * issues — `consecutiveFailures: 0`, no `lastError`, nothing dispatched. That
+ * is the exact silence this bound exists to remove, so it escapes here too.
+ */
+const isPassWideRelayfileFault = (error) => Boolean(relayfileOverload(error)) || error instanceof RelayfileOperationTimeoutError;
 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`. */
@@ -492,6 +510,14 @@ export class FactoryLoop {
     #readinessReconcileInFlight;
     #readinessReconcileIntervalMs = 60_000;
     #readinessReconcileTimeoutMs = DEFAULT_READINESS_RECONCILE_TIMEOUT_MS;
+    /**
+     * Deadline for ONE relayfile call (#351).
+     *
+     * `#readinessReconcileTimeoutMs` bounds the sweep; this bounds the calls
+     * inside it. Only the second one can reach a dependency call that never
+     * returns: a deadline checked between awaits never regains control to check.
+     */
+    #relayfileOperationTimeoutMs = DEFAULT_RELAYFILE_OPERATION_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;
@@ -526,6 +552,19 @@ export class FactoryLoop {
     #readinessReconcileLastFailureAtMs;
     #readinessReconcileLastError;
     #readinessReconcileLastErrorClass;
+    /**
+     * The last *completed* sweep's arithmetic (#355).
+     *
+     * Held as one record rather than four fields so it can only ever be replaced
+     * whole: publishing a `dispatched` from one pass beside a `candidates` from
+     * another would be worse than publishing neither, since the whole use of
+     * these numbers is comparing them to each other.
+     *
+     * `undefined` until a sweep completes, and never initialised to zeroes —
+     * "this daemon has not finished a sweep" and "a sweep finished and found
+     * nothing" are the two readings #355 has to tell apart.
+     */
+    #readinessReconcileLastSweep;
     #liveEventQueue = [];
     #liveEventDrainScheduled = false;
     #liveEventDrainActive = false;
@@ -652,6 +691,9 @@ export class FactoryLoop {
     constructor(config, ports) {
         this.#readOnly = ports.readOnly ?? false;
         this.#config = config;
+        // Also read here, not only in `#startLiveSubscription`: a standalone
+        // `runOnce()` never starts the live subscription and must still be bounded.
+        this.#relayfileOperationTimeoutMs = config.liveSubscription.relayfileOperationTimeoutMs;
         this.#mount = ports.mount;
         // Resolved role<->state mapping. The CLI injects a name-resolved, per-team
         // resolution via ports; fall back to one built from explicit stateIds plus
@@ -1234,6 +1276,7 @@ export class FactoryLoop {
         // `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.#relayfileOperationTimeoutMs = options.relayfileOperationTimeoutMs;
         this.#liveConnectStartedAtMs = this.#clock.now();
         this.#liveReplaySkewMarginMs = options.replaySkewMarginMs;
         const highWatermark = await this.#currentEventHighWatermark();
@@ -1284,7 +1327,11 @@ export class FactoryLoop {
             const backfillStartedAtMs = this.#clock.now();
             this.#readinessReconcileLastStartedAtMs = backfillStartedAtMs;
             try {
-                await this.runOnce();
+                // The startup backfill is a discovery pass like any other, and on a
+                // cold container it is the first — and for the next interval, only —
+                // sweep whose counts exist. Leaving it unrecorded would make a daemon
+                // that has completed a full pass still read as "never ran" (#355).
+                this.#recordReadinessSweepOutcome(await this.runOnce());
                 this.#readinessReconcileLastDurationMs = this.#elapsedSince(backfillStartedAtMs);
                 this.#readinessReconcileLastCompletedAtMs = this.#clock.now();
             }
@@ -1389,6 +1436,8 @@ export class FactoryLoop {
             replaySkewMarginMs: overrides.replaySkewMarginMs ?? this.#config.liveSubscription.replaySkewMarginMs,
             reconcileIntervalMs: overrides.reconcileIntervalMs ?? this.#config.liveSubscription.reconcileIntervalMs,
             reconcileTimeoutMs: overrides.reconcileTimeoutMs ?? this.#config.liveSubscription.reconcileTimeoutMs,
+            relayfileOperationTimeoutMs: overrides.relayfileOperationTimeoutMs
+                ?? this.#config.liveSubscription.relayfileOperationTimeoutMs,
         };
     }
     async #currentEventCursor(limit) {
@@ -1513,11 +1562,18 @@ export class FactoryLoop {
             this.#readinessReconcileLastCompletedAtMs = this.#clock.now();
             this.#readinessReconcileLastError = undefined;
             this.#readinessReconcileLastErrorClass = undefined;
+            // The three integers below have gone to stdout since this loop existed,
+            // and stdout does not reach the deployed container's operator (#355).
+            // Publishing them is what lets a reader tell a sweep that saw eligible
+            // work and rejected it from one that never pulled it at all.
+            this.#recordReadinessSweepOutcome(report);
             this.#logger.info?.('[factory] periodic readiness reconciliation completed', {
                 durationMs: this.#readinessReconcileLastDurationMs,
                 candidates: report.pulled.length,
                 dispatched: report.dispatched.length,
                 skipped: report.skipped.length,
+                skipReasons: this.#readinessReconcileLastSweep?.skipReasons,
+                discoveryDeferred: report.discoveryDeferred,
             });
         }
         catch (error) {
@@ -2491,7 +2547,13 @@ export class FactoryLoop {
             }
             const paths = await this.#readyIssuePaths();
             const orphanRecovery = issueSource === 'github'
-                ? await this.#githubOrphanRecoveryContext()
+                ? await this.#githubOrphanRecoveryContext(dryRun)
+                : undefined;
+            // Preserved-not-reconciled is a fact the caller needs either way, but the
+            // two causes are not the same event: a dry run skips the context by
+            // design, a live sweep that has none failed to build one.
+            const orphanRecoveryDegraded = issueSource === 'github' && orphanRecovery === undefined
+                ? (dryRun ? 'dry-run' : 'context-unavailable')
                 : undefined;
             const pulled = [];
             const triaged = [];
@@ -2503,6 +2565,7 @@ export class FactoryLoop {
                     issue: entry.issue.key,
                     path: entry.issue.path,
                     reason: entry.reason,
+                    code: entry.code,
                 });
             };
             // Backstop for the skip-by-default catch below: see #292. Reset only by
@@ -2542,7 +2605,11 @@ export class FactoryLoop {
                         retryAfterSeconds: overload.retryAfterSeconds,
                         sweepOverloads: this.#discoverySweepOverloads,
                     });
-                    recordSkip({ issue: issueRefFromPath(path), reason: perItemDispatchSkipReason(error) });
+                    recordSkip({
+                        issue: issueRefFromPath(path),
+                        reason: perItemDispatchSkipReason(error),
+                        code: 'read-failed',
+                    });
                 }
                 readyIssueReads += 1;
                 // Relayfile served this work unit's read: the dependency is shedding
@@ -2603,7 +2670,7 @@ export class FactoryLoop {
                 if (!mayRecoverGithubOrphan) {
                     const dispatchBlock = await this.#dispatchBlockReason(issue);
                     if (dispatchBlock) {
-                        recordSkip({ issue: issueRef(issue), reason: dispatchBlock });
+                        recordSkip({ issue: issueRef(issue), ...dispatchBlock });
                         continue;
                     }
                 }
@@ -2613,20 +2680,25 @@ export class FactoryLoop {
                 const recoveredOrphan = orphanResult.recovered;
                 const batch = await this.#batch();
                 if (batch.isInFlight(issue) || batch.isQueued(issue)) {
-                    recordSkip({ issue: issueRef(issue), reason: orphanResult.reason ?? 'already tracked' });
+                    recordSkip({
+                        issue: issueRef(issue),
+                        reason: orphanResult.reason ?? 'already tracked',
+                        code: 'already-tracked',
+                    });
                     continue;
                 }
                 if (!wasReady && !recoveredOrphan) {
                     if (mayRecoverGithubOrphan) {
                         const dispatchBlock = await this.#dispatchBlockReason(issue);
                         if (dispatchBlock) {
-                            recordSkip({ issue: issueRef(issue), reason: dispatchBlock });
+                            recordSkip({ issue: issueRef(issue), ...dispatchBlock });
                             continue;
                         }
                     }
                     recordSkip({
                         issue: issueRef(issue),
                         reason: orphanResult.reason ?? 'live state is not ready-for-agent',
+                        code: 'not-ready',
                     });
                     continue;
                 }
@@ -2635,16 +2707,20 @@ export class FactoryLoop {
                     if (recoveredOrphan) {
                         const dispatchBlock = await this.#dispatchBlockReason(issue);
                         if (dispatchBlock) {
-                            recordSkip({ issue: issueRef(issue), reason: dispatchBlock });
+                            recordSkip({ issue: issueRef(issue), ...dispatchBlock });
                             continue;
                         }
                     }
                     if (!isInFactoryScope(issue, this.#config.safety)) {
-                        recordSkip({ issue: issueRef(issue), reason: 'not factory-e2e scope' });
+                        recordSkip({ issue: issueRef(issue), reason: 'not factory-e2e scope', code: 'out-of-scope' });
                         continue;
                     }
                     if (!isDispatchableIssue(issue)) {
-                        recordSkip({ issue: issueRef(issue), reason: 'not reconciled real Linear issue' });
+                        recordSkip({
+                            issue: issueRef(issue),
+                            reason: 'not reconciled real Linear issue',
+                            code: 'not-dispatchable',
+                        });
                         continue;
                     }
                     const decision = await this.triageIssue(issue);
@@ -2657,12 +2733,17 @@ export class FactoryLoop {
                     // decays the durable overload ratchet (#297).
                     this.#discoverySweepProgress = true;
                     if (result.agents.length === 0 && !dryRun) {
+                        const code = result.hold?.kind === 'dependency-cycle'
+                            ? 'dependency-cycle'
+                            : result.hold?.kind === 'dependency'
+                                ? 'parked-dependency'
+                                : 'queued-or-escalated';
                         const reason = result.hold?.kind === 'dependency-cycle'
                             ? `dependency cycle detected: ${result.hold.cycle?.join(' -> ') ?? 'unknown cycle'}`
                             : result.hold?.kind === 'dependency'
                                 ? `parked on dependencies: ${result.hold.blockers?.join(', ') ?? 'unresolved dependency'}`
                                 : 'queued or escalated';
-                        recordSkip({ issue: decision.issue, reason });
+                        recordSkip({ issue: decision.issue, reason, code });
                     }
                     else {
                         dispatched.push(result);
@@ -2740,7 +2821,11 @@ export class FactoryLoop {
                             error: describeError(error).errorMessage,
                         });
                     }
-                    recordSkip({ issue: issueRef(issue), reason: perItemDispatchSkipReason(error) });
+                    recordSkip({
+                        issue: issueRef(issue),
+                        reason: perItemDispatchSkipReason(error),
+                        code: 'dispatch-failed',
+                    });
                     continue;
                 }
                 finally {
@@ -2748,7 +2833,15 @@ export class FactoryLoop {
                         this.#reconciledGithubInProgress.delete(recoveredIdentity);
                 }
             }
-            report = { pulled, triaged, dispatched, skipped, dryRun, slackDegraded: this.#slackDegraded };
+            report = {
+                pulled,
+                triaged,
+                dispatched,
+                skipped,
+                dryRun,
+                slackDegraded: this.#slackDegraded,
+                ...(orphanRecoveryDegraded ? { orphanRecoveryDegraded } : {}),
+            };
             return report;
         }
         catch (error) {
@@ -2769,6 +2862,7 @@ export class FactoryLoop {
                     dispatched: report.dispatched.length,
                     skipped: report.skipped.length,
                     slackDegraded: report.slackDegraded ?? false,
+                    orphanRecoveryDegraded: report.orphanRecoveryDegraded,
                     relayfileWaitWarnings: (this.#counters.relayfileOperationWaitWarnings ?? 0) - relayfileWaitWarningsAtStart,
                     relayfileSlowOperations: (this.#counters.relayfileSlowOperations ?? 0) - relayfileSlowOperationsAtStart,
                     relayfileOperationFailures: (this.#counters.relayfileOperationFailures ?? 0) - relayfileOperationFailuresAtStart,
@@ -3039,7 +3133,7 @@ export class FactoryLoop {
                 : { available: true, highWatermark };
         }
         catch (error) {
-            if (relayfileOverload(error))
+            if (isPassWideRelayfileFault(error))
                 throw error;
             this.#increment('discoveryHighWatermarkFailures');
             this.#logger.warn?.('[factory] discovery high-watermark unavailable; using a full sweep without caching', {
@@ -3062,7 +3156,7 @@ export class FactoryLoop {
             events = [...page.events].sort(compareDiscoveryEvents);
         }
         catch (error) {
-            if (relayfileOverload(error))
+            if (isPassWideRelayfileFault(error))
                 throw error;
             this.#logger.warn?.('[factory] discovery change feed unavailable; refreshing tree prefixes once', {
                 error: describeError(error).errorMessage,
@@ -3124,7 +3218,34 @@ export class FactoryLoop {
             }
         }
     }
-    async #githubOrphanRecoveryContext() {
+    /**
+     * The safety context orphan recovery needs before it may release a leaked
+     * `factory:in-progress` claim: who is online, which issues are actively
+     * owned, and which durable lifecycle rows look abandoned.
+     *
+     * A dry run never builds it. `#reconcileOrphanedGithubInProgress` refuses to
+     * release a claim under `dryRun` before it so much as looks at the context,
+     * and `mayRecoverGithubOrphan` in `#performRunOnce` is itself `!dryRun` —
+     * so the context was already provably unused on that path. Gathering it
+     * anyway was not free: `fleet.roster()` mints this process's workspace
+     * identity on demand, which is exactly what a read-only client refuses
+     * (#343) and exactly what a dry run must not need. Deciding what a sweep
+     * WOULD do must not require an identity to do it with.
+     *
+     * Returning `undefined` is therefore the honest answer for a dry run, not a
+     * failure: the caller reports the sweep as `orphanRecoveryDegraded:
+     * 'dry-run'` and preserves in-progress issues, which is what a dry run does
+     * regardless. The failure counter and the warn below stay for the live path,
+     * where an absent context IS a degradation.
+     */
+    async #githubOrphanRecoveryContext(dryRun) {
+        if (dryRun) {
+            this.#increment('githubOrphanRecoveryContextSkippedDryRun');
+            this.#logger.info?.('[factory] dry run skipped the orphan-recovery safety context; in-progress issues are preserved', {
+                reason: 'a dry run never releases an in-progress claim, so it needs no workspace identity to build one',
+            });
+            return undefined;
+        }
         try {
             const [registry, roster, lifecycles, waitingClarifications] = await Promise.all([
                 readFactoryInFlightRegistry(this.#config.loop.registryPath),
@@ -3701,7 +3822,17 @@ export class FactoryLoop {
             progressTimer.unref?.();
         }
         try {
-            const result = await fn();
+            // The bound the 2026-08-23 wedge needed (#351). `#readinessReconcileTimeoutMs`
+            // is 90 minutes and rejects only the WAIT — the sweep keeps its discovery
+            // lease and the next cycle coalesces onto it — so a call that never
+            // returns stopped dispatch for as long as the process lived. Bounding the
+            // call instead makes the pass unwind, which releases the lease and lets
+            // the next cycle actually start.
+            //
+            // Slightly above the transport's own deadline so the mount's cancellation
+            // wins the race and reports the more precise error; this is the backstop
+            // for mounts that cannot honour a signal.
+            const result = await withRelayfileCallDeadline(operation, details.phase, this.#relayfileOperationBackstopMs(), fn);
             const elapsedMs = this.#elapsedSince(startedAtMs);
             const count = opts.count?.(result);
             if (opts.logComplete) {
@@ -3758,7 +3889,11 @@ export class FactoryLoop {
                     error: describeError(error).errorMessage,
                 });
             }
-            throw error;
+            // The transport deadline is meant to win the race above, and the mount
+            // does not know which phase it was serving. Without this, `lastError`
+            // would name the call but not the context — one of many list/read sites
+            // (codex on #354).
+            throw relayfileTimeoutWithPhase(error, details.phase);
         }
         finally {
             if (progressTimer) {
@@ -3766,6 +3901,19 @@ export class FactoryLoop {
             }
         }
     }
+    /**
+     * The cycle-level backstop budget: the transport deadline plus a margin.
+     *
+     * Proportional rather than a flat grace so it holds at both ends of the
+     * range — a five-minute production budget and a millisecond test budget both
+     * leave the transport room to fire first.
+     */
+    #relayfileOperationBackstopMs() {
+        const timeoutMs = this.#relayfileOperationTimeoutMs;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            return undefined;
+        return Math.ceil(timeoutMs * RELAYFILE_OPERATION_BACKSTOP_RATIO);
+    }
     #elapsedSince(startedAtMs) {
         return Math.max(0, this.#clock.now() - startedAtMs);
     }
@@ -3914,7 +4062,7 @@ export class FactoryLoop {
         }
         const blockReason = await this.#dispatchBlockReason(decision.issue);
         if (blockReason) {
-            const error = new Error(`Refusing to dispatch ${decision.issue.key}: ${blockReason}`);
+            const error = new Error(`Refusing to dispatch ${decision.issue.key}: ${blockReason.reason}`);
             this.#error(error, decision.issue);
             throw error;
         }
@@ -4366,6 +4514,23 @@ export class FactoryLoop {
         }
         return { state: 'starting' };
     }
+    /**
+     * Snapshot a settled sweep's counts onto the readiness surface (#355).
+     *
+     * Only successful passes reach here: a pass that threw has no report, and
+     * inventing zeroes for it would publish "found nothing" for a sweep that
+     * never got to look. The previous pass's numbers stay put instead, dated by
+     * `lastCompletedAtMs`, which is the honest reading.
+     */
+    #recordReadinessSweepOutcome(report) {
+        this.#readinessReconcileLastSweep = {
+            candidates: report.pulled.length,
+            dispatched: report.dispatched.length,
+            skipped: report.skipped.length,
+            skipReasons: factorySweepSkipReasonCounts(report.skipped),
+            ...(report.discoveryDeferred ? { discoveryDeferred: report.discoveryDeferred } : {}),
+        };
+    }
     #readinessReconcileStatus() {
         const consecutiveFailures = this.#readinessReconcileConsecutiveFailures;
         // #296 owns the numerator here, #295/#300 own the derivation. The earliest
@@ -4440,6 +4605,22 @@ export class FactoryLoop {
             ...(this.#readinessReconcileLastFailureAtMs !== undefined
                 ? { lastFailureAtMs: this.#readinessReconcileLastFailureAtMs }
                 : {}),
+            // Spread whole or not at all: see `#readinessReconcileLastSweep`. Zeroes
+            // are published, which is the entire point — an absent `candidates` and
+            // a zero `candidates` are different diagnoses (#355).
+            ...(this.#readinessReconcileLastSweep
+                ? {
+                    candidates: this.#readinessReconcileLastSweep.candidates,
+                    dispatched: this.#readinessReconcileLastSweep.dispatched,
+                    skipped: this.#readinessReconcileLastSweep.skipped,
+                    ...(Object.keys(this.#readinessReconcileLastSweep.skipReasons).length > 0
+                        ? { skipReasons: { ...this.#readinessReconcileLastSweep.skipReasons } }
+                        : {}),
+                    ...(this.#readinessReconcileLastSweep.discoveryDeferred
+                        ? { discoveryDeferred: this.#readinessReconcileLastSweep.discoveryDeferred }
+                        : {}),
+                }
+                : {}),
             ...(this.#readinessReconcileLastError ? { lastError: this.#readinessReconcileLastError } : {}),
             ...(this.#readinessReconcileLastErrorClass
                 ? { lastErrorClass: this.#readinessReconcileLastErrorClass }
@@ -6571,7 +6752,7 @@ export class FactoryLoop {
             return [...issuePaths.values()].sort();
         }
         catch (error) {
-            if (relayfileOverload(error))
+            if (isPassWideRelayfileFault(error))
                 throw error;
             this.#githubIssuePathIndexReady = false;
             this.#increment('githubIssueListFailures');
@@ -6587,7 +6768,7 @@ export class FactoryLoop {
             parsed = parseJsonContent(content);
         }
         catch (error) {
-            if (relayfileOverload(error))
+            if (isPassWideRelayfileFault(error))
                 throw error;
             return undefined;
         }
@@ -6684,7 +6865,7 @@ export class FactoryLoop {
             this.#increment('githubIssueMirrorsCreated');
         }
         catch (error) {
-            if (relayfileOverload(error))
+            if (isPassWideRelayfileFault(error))
                 throw error;
             this.#logger.error?.('[factory] failed to ingest GitHub issue', error);
         }
@@ -7134,23 +7315,33 @@ export class FactoryLoop {
             }
         }
     }
+    /**
+     * Why durable dispatch state refuses this issue, or `undefined` to proceed.
+     *
+     * Returns the operator text *and* its #355 code together rather than letting
+     * the sweep re-derive one from the other: these four conditions are the ones
+     * most likely to explain a sweep that saw eligible issues and dispatched
+     * nothing, and two of them (`terminal`, `retry-limit`) never clear on their
+     * own. Deriving the code by matching the message would put that distinction
+     * one rename away from collapsing into `other`.
+     */
     async #dispatchBlockReason(issue) {
         const key = issueStateKey(issue);
         const state = await this.#state.getDispatchAttempts(this.#workspaceId, key);
         if (!state)
             return undefined;
         if (state.terminal)
-            return 'dispatch already terminal';
+            return { reason: 'dispatch already terminal', code: 'dispatch-terminal' };
         if (state.inFlight)
-            return 'dispatch already in-flight';
+            return { reason: 'dispatch already in-flight', code: 'dispatch-in-flight' };
         const now = this.#clock.now();
         if (state.backoffUntilMs > now) {
-            return 'dispatch backoff active';
+            return { reason: 'dispatch backoff active', code: 'dispatch-backoff' };
         }
         if (state.attempts >= this.#config.dispatch.maxAttempts) {
             state.terminal = true;
             await this.#state.recordDispatchAttempt(this.#workspaceId, key, state);
-            return 'dispatch retry limit reached';
+            return { reason: 'dispatch retry limit reached', code: 'dispatch-retry-limit' };
         }
         return undefined;
     }
@@ -7488,7 +7679,7 @@ export class FactoryLoop {
             return resolvedIssue;
         }
         catch (error) {
-            if (relayfileOverload(error))
+            if (isPassWideRelayfileFault(error))
                 throw error;
             if (isMissingIssueFileError(error) && isIssuePathUnderRoot(path)) {
                 this.#increment('phantomSkipped');
@@ -8584,7 +8775,7 @@ export class FactoryLoop {
                 paths = await this.#listRelayfileTree(root, 'exact-head PR confirmation');
             }
             catch (error) {
-                if (relayfileOverload(error))
+                if (isPassWideRelayfileFault(error))
                     throw error;
                 continue;
             }
@@ -8854,7 +9045,7 @@ export class FactoryLoop {
                     return await this.#listRelayfileTree(root, 'published PR confirmation');
                 }
                 catch (error) {
-                    if (relayfileOverload(error))
+                    if (isPassWideRelayfileFault(error))
                         throw error;
                     return [];
                 }
@@ -10436,7 +10627,7 @@ export class FactoryLoop {
                 }
             }
             catch (error) {
-                if (relayfileOverload(error))
+                if (isPassWideRelayfileFault(error))
                     throw error;
                 this.#logger.warn?.('[factory] unable to list GitHub issue comments for replay', { prefix, error });
             }
@@ -12982,7 +13173,7 @@ export class FactoryLoop {
                 found.push(...tree.filter((path) => path.endsWith('.json') && numberSegment.test(path)));
             }
             catch (error) {
-                if (relayfileOverload(error))
+                if (isPassWideRelayfileFault(error))
                     throw error;
                 // try the next root
             }
@@ -14161,7 +14352,7 @@ export class FactoryLoop {
                 return await this.#listRelayfileTree(prefix, 'Slack identity lookup');
             }
             catch (error) {
-                if (relayfileOverload(error))
+                if (isPassWideRelayfileFault(error))
                     throw error;
                 return [];
             }
@@ -17088,7 +17279,7 @@ const resolveIssuePrFromMount = async (mount, config, issue, opts = {}, listTree
                     paths.add(path);
             }
             catch (error) {
-                if (relayfileOverload(error))
+                if (isPassWideRelayfileFault(error))
                     throw error;
                 listErrors.push(error);
             }