@agent-relay/factory 0.1.77 → 0.1.80

package/dist/orchestrator/factory.js

@@ -156,6 +156,8 @@ const STOP_REJECTED_DISPATCH_DRAIN_TIMEOUT_MS = 2_500;
 const DISPATCH_LIFECYCLE_LEASE_MS = 5 * 60_000;
 const DISPATCH_LIFECYCLE_RENEW_MS = 60_000;
 const DISPATCH_LIFECYCLE_RETRY_MS = 1_000;
+const REMOTE_AGENT_REGISTRATION_TIMEOUT_MS = 30_000;
+const REMOTE_AGENT_REGISTRATION_POLL_MS = 500;
 /**
  * Ceiling on the durable capacity-wait re-arm (#303).
  *
@@ -167,6 +169,31 @@ const DISPATCH_LIFECYCLE_RETRY_MS = 1_000;
  * multi-hour run holds the slot honestly), so what is bounded is the *rate*.
  */
 const DISPATCH_LIFECYCLE_RETRY_MAX_MS = 30_000;
+/**
+ * How many times a work unit's RELEASE may fail before it is dead-lettered.
+ *
+ * #303 bounded the rate of the capacity-wait re-arm and deliberately left its
+ * count unbounded, because waiting for capacity is legitimate: the slot will
+ * free eventually and abandoning the wait would drop real work. Release is the
+ * opposite shape. It is the last step of a work unit that is already finished
+ * — the issue is closed, the writeback is acknowledged, the batch slot is
+ * gone — so a release that has failed ten times is not waiting for anything.
+ * It is failing, and re-arming it at 1 Hz forever buys nothing.
+ *
+ * What that costs when it happens: `#finishDurableRelease` does not throw on a
+ * failed release, it returns `false` and re-arms itself, so the loop runs
+ * through the *success* path of every `.catch()` that might otherwise have
+ * bounded it. Each pass calls `#terminationRoots` once per agent, and
+ * `#writeInFlightRegistry` calls it once per agent again — each one a process
+ * table scan — plus a durable read and write. Three agents is order ten scans
+ * and several state operations per second, indefinitely, which is the same
+ * serialized-store spin #303 measured at 1477 GETs in 111 s.
+ *
+ * Ten attempts at the 1 Hz floor is ~10 s of genuine retry, which covers the
+ * transient failures release retries exist for (a brief control-plane blip, a
+ * lease handover) without covering a permanent one.
+ */
+const DISPATCH_LIFECYCLE_MAX_RELEASE_ATTEMPTS = 10;
 /** Rate limit for the capacity-wait warning once the backoff has capped. */
 const DISPATCH_LIFECYCLE_CAPACITY_WAIT_LOG_MS = 60_000;
 const DISPATCH_WRITEBACK_MAX_ATTEMPTS = 3;
@@ -324,6 +351,26 @@ class DispatchLifecycleOwnedElsewhereError extends Error {
         this.leaseUntilMs = leaseUntilMs;
     }
 }
+class FleetPlacementUnavailableError extends Error {
+    capability;
+    constructor(capability) {
+        super(`Refusing remote dispatch: no live fleet node advertises ${capability}`);
+        this.capability = capability;
+        this.name = 'FleetPlacementUnavailableError';
+    }
+}
+class RemoteAgentRegistrationTimeoutError extends Error {
+    agentName;
+    cleanupConfirmed;
+    cleanupError;
+    constructor(agentName, cleanupConfirmed, cleanupError) {
+        super(`Remote agent ${agentName} did not register with the fleet before the startup deadline`);
+        this.agentName = agentName;
+        this.cleanupConfirmed = cleanupConfirmed;
+        this.cleanupError = cleanupError;
+        this.name = 'RemoteAgentRegistrationTimeoutError';
+    }
+}
 /**
  * The durable dispatch-lifecycle claim was refused for one work unit: its
  * record is already terminal, or another publisher currently holds the lease.
@@ -424,6 +471,8 @@ export class FactoryLoop {
     #babysitterWakeUnreachableEscalateMs;
     #babysitterWakeUnreachableRetryMs;
     #startupAgentExitDrainTimeoutMs;
+    #dispatchLifecycleRetryMs;
+    #dispatchLifecycleRenewMs;
     #state;
     #workspaceId;
     #relayflows;
@@ -500,6 +549,16 @@ export class FactoryLoop {
     #dispatchTerminalWaiters = new Map();
     #dispatchLifecycleRetryTimers = new Map();
     #dispatchLifecycleDrives = new Set();
+    /**
+     * Failed release attempts per work unit, and the units that ran out.
+     *
+     * Keyed by `dispatchLifecycleKey`, so it follows the work unit rather than
+     * any one agent, surface or dispatcher — the same identity rule the AR-448
+     * duplicate established for claims. Counted only for release re-arms; a
+     * capacity or ownership wait is not a failure and must not spend the budget.
+     */
+    #dispatchLifecycleReleaseAttempts = new Map();
+    #dispatchLifecycleReleaseAbandoned = new Set();
     #abandonedDispatchReasons = new Map();
     /**
      * Live batch-capacity waits, keyed by issue (#303).
@@ -859,6 +918,8 @@ export class FactoryLoop {
         this.#babysitterWakeUnreachableEscalateMs = ports.babysitterWakeUnreachableEscalateMs ?? BABYSITTER_WAKE_UNREACHABLE_ESCALATE_MS;
         this.#babysitterWakeUnreachableRetryMs = ports.babysitterWakeUnreachableRetryMs ?? BABYSITTER_WAKE_UNREACHABLE_RETRY_MS;
         this.#startupAgentExitDrainTimeoutMs = ports.startupAgentExitDrainTimeoutMs ?? STARTUP_AGENT_EXIT_DRAIN_TIMEOUT_MS;
+        this.#dispatchLifecycleRetryMs = ports.dispatchLifecycleRetryMs ?? DISPATCH_LIFECYCLE_RETRY_MS;
+        this.#dispatchLifecycleRenewMs = ports.dispatchLifecycleRenewMs ?? DISPATCH_LIFECYCLE_RENEW_MS;
         this.#workspaceId = config.workspaceId ?? 'default';
         this.#relayflows = ports.relayflows;
         this.#worktrees = ports.worktrees;
@@ -2746,8 +2807,9 @@ export class FactoryLoop {
     }
     async #assertFleetControlPlaneAvailable() {
         try {
-            await this.#fleet.roster();
+            const roster = await this.#fleet.roster();
             this.#increment('fleetControlPlaneProbeSuccesses');
+            return roster;
         }
         catch (error) {
             const health = this.#fleetControlPlane.status();
@@ -4687,11 +4749,14 @@ export class FactoryLoop {
                     path: progress.path,
                 });
             },
-            // One line per repository saying why the tree walk was necessary. The walk
-            // is a permanent silent fallback today, and a silent permanent fallback is
-            // indistinguishable from a fast path that is working. This makes the day
-            // the index becomes usable (relayfile-adapters#271) show up in the logs
-            // instead of passing unnoticed.
+            // One line per repository saying why the tree walk was necessary. A silent
+            // fallback is indistinguishable from a fast path that is working, and
+            // that is precisely how twelve minutes of sequential reads hid for so
+            // long. Now that the index CAN answer the question, these reasons are the
+            // only way to tell "the index answered" from "the index exists and was
+            // useless" — and on a mount written before
+            // `@relayfile/adapter-github@0.5.7`, `index-without-head-ref` is the
+            // expected reading until a re-ingest converges the rows.
             onIndexFallback: (repo, reason) => {
                 this.#increment('probePrIndexFallbacks');
                 this.#increment(PROBE_PR_INDEX_FALLBACK_COUNTERS[reason]);
@@ -4701,6 +4766,14 @@ export class FactoryLoop {
                     reason,
                 });
             },
+            onIndexHit: (repo, prNumber) => {
+                this.#increment('probePrIndexHits');
+                this.#logger.debug?.('[factory] PR probe resolved from the pull index', {
+                    issue: issue.key,
+                    repo,
+                    prNumber,
+                });
+            },
         };
     }
     #logTimedProgress(message, startedAtMs, lastLoggedAtMs, metadata) {
@@ -4971,8 +5044,10 @@ export class FactoryLoop {
         // consuming a dispatch attempt. The mutation proxy probes again at the
         // actual spawn/resume boundary so a later control-plane fault still fails
         // closed.
-        if (!dryRun)
-            await this.#assertFleetControlPlaneAvailable();
+        const admissionRoster = !dryRun ? await this.#assertFleetControlPlaneAvailable() : undefined;
+        if (admissionRoster && this.#fleet.placementLocality === 'remote') {
+            dispatchDecision = decisionWithVerifiedRemotePlacements(dispatchDecision, admissionRoster);
+        }
         const durableDispatch = !dryRun && this.#usesDurableDispatchLifecycle();
         // Local dispatches need the same deterministic branch identity as remote
         // ones. Without it, every worker starts in the configured shared checkout
@@ -5389,6 +5464,13 @@ export class FactoryLoop {
                 throw error;
             }
             settlePostSpawnIssueObservation(!(error instanceof LiveDispatchStateChangedError));
+            if ((error instanceof FleetPlacementUnavailableError ||
+                (error instanceof RemoteAgentRegistrationTimeoutError && error.cleanupConfirmed)) &&
+                await this.#rollbackUnregisteredRemoteDispatch(record, spawnedForReaperHandoff)) {
+                this.#increment('remoteDispatchAdmissionRollbacks');
+                this.#error(error, decision.issue);
+                throw error;
+            }
             // A spawn can fail after the broker accepted it but before its ack
             // reached Factory. Include every planned worktree agent, not only the
             // acknowledged spawns, so cleanup never races a name-only survivor.
@@ -5637,8 +5719,23 @@ export class FactoryLoop {
             consecutiveFailures,
             failureThreshold: READINESS_RECONCILE_FAILURE_THRESHOLD,
             intervalMs: this.#readinessReconcileIntervalMs,
+            // The two bounds that can actually preempt this pass, published beside
+            // the cadence that cannot. Omitting them made the stanza unreadable in
+            // the one situation it exists for: `intervalMs` next to a climbing
+            // `inFlightMs` looks exactly like an unbounded hang, and has twice been
+            // reported as one. `timeoutMs` ends the wait, `sweepBudgetMs` unwinds
+            // the sweep and hands the lease back — so the second is the one that
+            // answers "when does this recover".
+            timeoutMs: this.#readinessReconcileTimeoutMs,
+            sweepBudgetMs: this.#discoverySweepBudgetMs,
             ...(Number.isFinite(inFlightSinceMs) ? { inFlightSinceMs } : {}),
             ...(inFlightMs !== undefined ? { inFlightMs } : {}),
+            // Derived here rather than left to each reader. The public projection
+            // already computed it (#295/#300); the heartbeat stanza did not, so the
+            // surface an operator actually opens first was the one missing it.
+            ...(inFlightMs !== undefined && this.#readinessReconcileIntervalMs > 0
+                ? { missedPasses: Math.floor(inFlightMs / this.#readinessReconcileIntervalMs) }
+                : {}),
             ...(this.#readinessReconcileLastDurationMs !== undefined
                 ? { lastDurationMs: this.#readinessReconcileLastDurationMs }
                 : {}),
@@ -6125,7 +6222,7 @@ export class FactoryLoop {
             return;
         this.#dispatchLifecycleRenewTimer = setInterval(() => {
             void this.#renewDispatchLifecycles();
-        }, DISPATCH_LIFECYCLE_RENEW_MS);
+        }, this.#dispatchLifecycleRenewMs);
         this.#dispatchLifecycleRenewTimer.unref?.();
     }
     /**
@@ -6322,6 +6419,18 @@ export class FactoryLoop {
     }
     async #renewDispatchLifecycles() {
         for (const [key, epoch] of [...this.#dispatchLifecycleEpochs]) {
+            // The snapshot above can outlive the ownership it records: a relinquish
+            // that runs while this loop is awaiting the store for an earlier key
+            // leaves a stale entry here, and renewing it would re-block a key this
+            // process has already handed back (#391 review, P2). Re-read the live map
+            // rather than trusting the snapshot.
+            //
+            // This narrows the window but does not close it on its own — the delete
+            // can still land after this check and before the renew resolves. Closing
+            // it is `renewDispatchLifecycle`'s expiry fence, which makes a
+            // relinquished lease unrenewable no matter how the two race.
+            if (this.#dispatchLifecycleEpochs.get(key) !== epoch)
+                continue;
             const renewed = await this.#state.renewDispatchLifecycle(this.#workspaceId, key, this.#dispatchLifecycleOwner, epoch, this.#clock.now(), DISPATCH_LIFECYCLE_LEASE_MS);
             if (!renewed) {
                 this.#dispatchLifecycleEpochs.delete(key);
@@ -6912,19 +7021,206 @@ export class FactoryLoop {
         }
         this.#increment('dispatchCapacityBackoffResets');
     }
-    #scheduleDispatchLifecycleRetry(record, delayMs = DISPATCH_LIFECYCLE_RETRY_MS) {
+    /**
+     * Charge one failed release against a work unit's budget.
+     *
+     * Returns `false` once the budget is spent, and the caller must NOT re-arm.
+     * Failing closed here is deliberate and is the opposite of a dispatch gate:
+     * an unrecordable dispatch claim must abort the dispatch, but an unbounded
+     * release must abort the RETRY — the work is already done either way, and
+     * the only thing still running is the spin.
+     */
+    #chargeReleaseAttempt(record, key, context) {
+        if (this.#dispatchLifecycleReleaseAbandoned.has(key)) {
+            // Re-entry, and the reason relinquishing the lease once is not enough.
+            // `#driveDispatchLifecycle` re-claims the lease at the TOP of every
+            // drive, before it has read the phase, so anything that drives an
+            // already-dead-lettered key — the held-agent-deadline sweep, a registry
+            // restore, a takeover — puts the epoch straight back into the renewal
+            // map and re-arms the livelock this bound just escaped. Whenever the
+            // budget declines a re-arm, ownership goes back too.
+            this.#trackDispatchLifecycleDrive(this.#relinquishDispatchLifecycleLease(key, record.issue.key));
+            return false;
+        }
+        const attempts = (this.#dispatchLifecycleReleaseAttempts.get(key) ?? 0) + 1;
+        this.#dispatchLifecycleReleaseAttempts.set(key, attempts);
+        if (attempts <= DISPATCH_LIFECYCLE_MAX_RELEASE_ATTEMPTS)
+            return true;
+        this.#dispatchLifecycleReleaseAbandoned.add(key);
+        this.#dispatchLifecycleReleaseAttempts.delete(key);
+        this.#increment('dispatchLifecycleReleaseAbandoned');
+        const durableLifecycleRetained = this.#usesDurableDispatchLifecycle();
+        // Cleanup is armed BEFORE anything that can throw (#391 review, P1). The
+        // only statements above are set/map writes and a counter, none of which can
+        // reject; `this.#logger.error` below is caller-supplied and can. Ordering
+        // the drive first means nothing between "this unit is abandoned" and "its
+        // lease is handed back" is allowed to fail in a way that skips the handback
+        // — which is precisely the defect shape this whole method exists to fix.
+        this.#trackDispatchLifecycleDrive(this.#releaseDeadLetteredSlot(record, key)
+            .catch((error) => {
+            this.#logger.warn?.('[factory] dead-lettered release could not free its batch slot', {
+                issue: record.issue.key,
+                error: describeError(error).errorMessage,
+            });
+        }));
+        // `error`, not `warn`. Every previous layer of this failure was invisible
+        // until somebody read stderr by hand; a work unit whose cleanup this
+        // process has permanently given up on is exactly the event that must not
+        // be inferable only from the absence of further log lines.
+        this.#logger.error?.('[factory] release retries exhausted; abandoning cleanup for this work unit', {
+            issue: record.issue.key,
+            attempts: attempts - 1,
+            maxAttempts: DISPATCH_LIFECYCLE_MAX_RELEASE_ATTEMPTS,
+            context,
+            // The durable lifecycle is retained on purpose: a takeover or a restart
+            // re-drives it from the persisted phase. This bounds THIS process's
+            // spin, it does not declare the work unit clean.
+            durableLifecycleRetained,
+        });
+        return false;
+    }
+    /** Keeps a lifecycle-side effect awaitable by `stop()` without leaking the set entry. */
+    #trackDispatchLifecycleDrive(promise) {
+        const drive = promise.finally(() => this.#dispatchLifecycleDrives.delete(drive));
+        this.#dispatchLifecycleDrives.add(drive);
+    }
+    /**
+     * Stop asserting durable ownership of a work unit this process will not drive
+     * again.
+     *
+     * `#dispatchLifecycleEpochs` is not merely a cache. `#renewDispatchLifecycles`
+     * walks it every `DISPATCH_LIFECYCLE_RENEW_MS` and re-stamps a full
+     * `DISPATCH_LIFECYCLE_LEASE_MS` onto every key it finds, unconditionally.
+     *
+     * A dead-lettered release deliberately leaves its row in the non-terminal
+     * `releasing` phase so a successor or a restart can re-drive the cleanup with
+     * a fresh budget. That is only a recovery path if the successor can CLAIM the
+     * row — and a lease renewed forever by a process that has permanently given
+     * up driving it is a claim nobody can ever win. #379 bounded the retry and
+     * handed back the batch slot, then kept the key locked for the life of the
+     * process, which is how production reached four issues (a dispatch canary
+     * among them) all logging `durable dispatch is leased by another publisher`
+     * at 1 Hz for three days while the holder logged nothing but 503
+     * `agent_host_unavailable`.
+     *
+     * The epoch is dropped BEFORE the durable release, so a renewal tick that
+     * STARTS after this point finds nothing to renew. That ordering alone is not
+     * sufficient and an earlier version of this comment wrongly claimed it was
+     * (#391 review, P2): `#renewDispatchLifecycles` iterates a snapshot array, so
+     * a tick already in flight still holds this key and would restore the lease
+     * for a full term. The guarantee comes from `renewDispatchLifecycle` fencing
+     * on expiry as well as owner and epoch, which makes a relinquished lease
+     * unrenewable however the two race; the epoch drop and the loop's live re-read
+     * narrow the window ahead of it.
+     *
+     * If the durable release itself fails, the dropped epoch alone still ends the
+     * livelock: nothing renews the lease any more, so it expires within
+     * `DISPATCH_LIFECYCLE_LEASE_MS` instead of never.
+     */
+    async #relinquishDispatchLifecycleLease(key, issueKey) {
+        const epoch = this.#dispatchLifecycleEpochs.get(key);
+        if (epoch === undefined)
+            return;
+        this.#dispatchLifecycleEpochs.delete(key);
+        try {
+            await this.#state.releaseDispatchLifecycleLease(this.#workspaceId, key, this.#dispatchLifecycleOwner, epoch);
+            this.#increment('dispatchLifecycleLeasesRelinquished');
+        }
+        catch (error) {
+            this.#logger.warn?.('[factory] could not relinquish the dispatch lease of an abandoned work unit', {
+                issue: issueKey,
+                // The lease still expires on its own now that nothing renews it.
+                expiresWithinMs: DISPATCH_LIFECYCLE_LEASE_MS,
+                error: describeError(error).errorMessage,
+            });
+        }
+    }
+    /**
+     * Hand back the batch slot of a work unit whose release was dead-lettered.
+     *
+     * Without this the bound trades an unbounded 1 Hz spin for a permanently
+     * leaked slot, which is not obviously the better failure (#379 review, P1):
+     * a spin is loud and self-describing, whereas an in-flight record nobody will
+     * ever complete silently reduces dispatch capacity until the process is
+     * restarted. The slot is process-local accounting and is always freed here.
+     *
+     * What is NOT declared clean is the work itself. On a durable lifecycle the
+     * persisted `releasing` phase is deliberately left in place, so a successor
+     * or a restart re-drives the same cleanup with a fresh budget; freeing the
+     * local slot does not write a terminal phase. On a local lifecycle there is
+     * no durable record to retain, so the batch record is all there is and
+     * completing it is what keeps capacity honest.
+     *
+     * The DURABLE lease has to go back with the slot. Retaining the row for a
+     * successor while renewing the lease that locks the successor out is not a
+     * handoff, it is a permanent block on the key — see
+     * `#relinquishDispatchLifecycleLease`.
+     *
+     * The handback lives in a `finally` for a reason worth stating plainly
+     * (#391 review, P1). The FIRST version of this fix relinquished after
+     * `#writeInFlightRegistry()`, on the happy path only — so a rejecting
+     * registry write would skip it and leave the abandoned key renewing its lease
+     * forever, with nothing but a `warn` to show for it. That is the identical
+     * shape of the bug being fixed (#379 freed the slot but not the lease, on the
+     * failure path), reproduced one level up. Cleanup that only runs when the
+     * rest of cleanup succeeded is not cleanup. `#batch()` and
+     * `#writeInFlightRegistry()` can both reject; neither may strand the key.
+     */
+    async #releaseDeadLetteredSlot(record, key) {
+        let next;
+        try {
+            const batch = await this.#batch();
+            next = batch.complete(record.issue);
+            this.#uncompensatedDispatchClaims.delete(key);
+            await this.#writeInFlightRegistry();
+        }
+        finally {
+            // Unconditional, and safe to put in a `finally` because
+            // `#relinquishDispatchLifecycleLease` handles its own errors and cannot
+            // throw — so it can never mask the failure that brought us here.
+            await this.#relinquishDispatchLifecycleLease(key, record.issue.key);
+        }
+        // A freed slot that nothing is admitted into is only half the repair.
+        if (next && !this.#stopping)
+            await this.dispatch(next.decision, { dryRun: next.dryRun });
+    }
+    /** Clears a work unit's release budget once cleanup actually succeeds. */
+    #clearReleaseAttempts(key) {
+        this.#dispatchLifecycleReleaseAttempts.delete(key);
+        this.#dispatchLifecycleReleaseAbandoned.delete(key);
+    }
+    #scheduleDispatchLifecycleRetry(record, delayMs = this.#dispatchLifecycleRetryMs, opts = {}) {
         const key = dispatchLifecycleKey(record.issue);
         if (this.#stopping || this.#dispatchLifecycleRetryTimers.has(key))
             return;
+        // Only a release re-arm spends the budget. A capacity or ownership wait is
+        // a legitimate wait for someone else to finish (#303) and is bounded by
+        // its rate, not its count — spending the budget on one would abandon work
+        // that was never failing.
+        if (opts.releaseAttempt === true && !this.#chargeReleaseAttempt(record, key, 'durable-lifecycle'))
+            return;
         const timer = setTimeout(() => {
             this.#dispatchLifecycleRetryTimers.delete(key);
             const drive = this.#driveDispatchLifecycle(key)
                 .then(() => {
                 this.#dispatchLifecycleCapacityWaits.delete(key);
                 this.#dispatchLifecycleOwnershipWaitLogged.delete(key);
+                // DELIBERATELY NOT `#clearReleaseAttempts` (#379 review, P1).
+                //
+                // A FAILED release reaches here. `#finishDurableRelease` returns
+                // `false` rather than throwing, and `#driveDispatchLifecycle`
+                // discards that boolean in its `phase === 'releasing'` branch, so
+                // the drive RESOLVES on a failed release and this handler runs on
+                // every re-arm. Clearing the budget here zeroed it once per pass and
+                // the counter could never reach the cap — the same never-fires this
+                // bound exists to avoid, moved from the `.catch()` to the `.then()`.
+                //
+                // The budget is refunded where success is actually known:
+                // `#finishDurableRelease` clears it on real per-agent progress and
+                // again when the work unit completes.
             })
                 .catch((error) => {
-                let nextDelayMs = DISPATCH_LIFECYCLE_RETRY_MS;
+                let nextDelayMs = this.#dispatchLifecycleRetryMs;
                 if (error instanceof DispatchLifecycleCapacityError) {
                     this.#dispatchLifecycleOwnershipWaitLogged.delete(key);
                     nextDelayMs = this.#recordDispatchCapacityWait(record, key);
@@ -6939,7 +7235,7 @@ export class FactoryLoop {
                             leaseRemainingMs: error.leaseUntilMs === undefined
                                 ? undefined
                                 : Math.max(0, error.leaseUntilMs - this.#clock.now()),
-                            retryMs: DISPATCH_LIFECYCLE_RETRY_MS,
+                            retryMs: this.#dispatchLifecycleRetryMs,
                         });
                     }
                 }
@@ -6951,6 +7247,20 @@ export class FactoryLoop {
                         error: describeError(error).errorMessage,
                     });
                 }
+                // Deliberately UNCHARGED (#379 review, P1). This arm re-arms for
+                // dispatch, publishing and recovery failures as well as releases, and
+                // charging all of them would dead-letter a work unit that was never
+                // stuck in a release loop. Charging is confined to
+                // `#scheduleReleaseRetry`, whose every caller is a release failure:
+                // the three inside `#finishDurableRelease` and `#completeIssue`'s
+                // catch once `releaseReasonForRetry` is set.
+                //
+                // The gap this leaves, stated plainly: a release failure that THREW
+                // out of `#finishDurableRelease` instead of returning `false` would
+                // reach here and re-arm unbounded. Every failure path in that method
+                // returns `false` and schedules its own retry, so this is not a
+                // reachable shape today — and if one appears it degrades to the
+                // pre-existing unbounded behaviour rather than to a wrong dead-letter.
                 this.#scheduleDispatchLifecycleRetry(record, nextDelayMs);
             })
                 .finally(() => this.#dispatchLifecycleDrives.delete(drive));
@@ -6960,12 +7270,19 @@ export class FactoryLoop {
     }
     #scheduleReleaseRetry(record, reason) {
         if (this.#usesDurableDispatchLifecycle()) {
-            this.#scheduleDispatchLifecycleRetry(record);
+            this.#scheduleDispatchLifecycleRetry(record, this.#dispatchLifecycleRetryMs, { releaseAttempt: true });
             return;
         }
         const key = dispatchLifecycleKey(record.issue);
         if (this.#stopping || this.#dispatchLifecycleRetryTimers.has(key))
             return;
+        // Charged here rather than in the `.catch()` below, because the loop this
+        // bounds does not go through the `.catch()`: `#finishDurableRelease`
+        // returns `false` on a failed release and re-arms itself, so every re-arm
+        // arrives on the resolved path. A bound on the rejection handler alone
+        // would have been a fix that never fired.
+        if (!this.#chargeReleaseAttempt(record, key, 'local-completion'))
+            return;
         const timer = setTimeout(() => {
             this.#dispatchLifecycleRetryTimers.delete(key);
             const drive = this.#finishDurableRelease(record, reason)
@@ -6979,7 +7296,7 @@ export class FactoryLoop {
             })
                 .finally(() => this.#dispatchLifecycleDrives.delete(drive));
             this.#dispatchLifecycleDrives.add(drive);
-        }, DISPATCH_LIFECYCLE_RETRY_MS);
+        }, this.#dispatchLifecycleRetryMs);
         timer.unref?.();
         this.#dispatchLifecycleRetryTimers.set(key, timer);
     }
@@ -7192,6 +7509,9 @@ export class FactoryLoop {
             return;
         }
         if (lifecycle.phase === 'releasing') {
+            // The boolean is discarded here, as it always was — and that is exactly
+            // why the scheduler's success handler must not refund the release budget
+            // (#379 review, P1). A failed release resolves through this line.
             await this.#finishDurableRelease(record, lifecycle.releaseReason);
         }
     }
@@ -7398,6 +7718,7 @@ export class FactoryLoop {
             .filter((agent) => agent.releasedAtMs !== undefined)
             .map((agent) => agent.name) ?? this.#localReleaseCheckpoints.get(releaseKey) ?? []);
         const failed = [];
+        const releasedOnEntry = released.size;
         for (const agent of record.agents) {
             if (released.has(agent[0]))
                 continue;
@@ -7418,6 +7739,13 @@ export class FactoryLoop {
         await this.#writeInFlightRegistry();
         if (failed.length > 0) {
             this.#increment('dispatchLifecycleReleaseRetries');
+            // Real progress refunds the budget, so the ten attempts bound CONSECUTIVE
+            // no-progress passes rather than capping a slow multi-agent release. This
+            // terminates because an agent released once is checkpointed and skipped
+            // on the next pass, so the remaining set strictly shrinks — a refund can
+            // only be earned a finite number of times.
+            if (released.size > releasedOnEntry)
+                this.#clearReleaseAttempts(releaseKey);
             this.#scheduleReleaseRetry(record, reason);
             return false;
         }
@@ -7436,6 +7764,10 @@ export class FactoryLoop {
         }
         const next = this.#usesDurableDispatchLifecycle() ? undefined : batch.complete(record.issue);
         this.#localReleaseCheckpoints.delete(releaseKey);
+        // Every agent is released. Nothing is left to retry, so the budget goes
+        // back — including the abandoned marker, so a reopened work unit that
+        // reuses this key starts with a full budget rather than a spent one.
+        this.#clearReleaseAttempts(releaseKey);
         if (next)
             await this.dispatch(next.decision, { dryRun: next.dryRun });
         // Terminal lifecycle saves intentionally relinquish the owner epoch. Clear
@@ -9392,13 +9724,6 @@ export class FactoryLoop {
             batch.recordDryRun(record, spec, invocationId);
             return { name: spec.name };
         }
-        // Persist intent before the remote side effect. If the owner crashes after
-        // the spawn ack but before recording its result, takeover retries the same
-        // deterministic invocation id instead of inventing a second worker.
-        batch.recordPlanned(record, { ...spec, invocationId });
-        if (!await this.#saveDispatchLifecycle(record, 'dispatching')) {
-            throw new Error(`Dispatch lifecycle ownership lost before spawning ${spec.name}`);
-        }
         let roster;
         try {
             roster = await retryOnTimeout(() => this.#fleet.roster(), { attempts: 3, delayMs: 2000 });
@@ -9408,6 +9733,15 @@ export class FactoryLoop {
         }
         const rosterAgent = roster.agents.find((agent) => agent.name === spec.name);
         if (rosterAgent) {
+            if (this.#fleet.placementLocality === 'remote') {
+                const host = rosterAgent.node
+                    ? roster.nodes.find((node) => node.name === rosterAgent.node && node.live && node.capabilities.includes(spec.capability))
+                    : undefined;
+                if (!host) {
+                    throw new FleetPlacementUnavailableError(spec.capability);
+                }
+                spec = { ...spec, node: host.name };
+            }
             const trackedPlacement = this.#fleet.trackedAgents?.().get(spec.name);
             record.heldSinceAtMs ??= this.#clock.now();
             batch.recordSpawn(record, spec, invocationId, {
@@ -9425,6 +9759,21 @@ export class FactoryLoop {
                 await this.#reportAgent(record, adopted, 'agent.adopted');
             return { name: spec.name };
         }
+        if (this.#fleet.placementLocality === 'remote') {
+            const loads = new Map();
+            for (const agent of roster.agents) {
+                if (agent.node)
+                    loads.set(agent.node, (loads.get(agent.node) ?? 0) + 1);
+            }
+            spec = { ...spec, node: liveFleetNodeForSpec(spec, roster, loads) };
+        }
+        // Persist intent before the remote side effect. If the owner crashes after
+        // the spawn ack but before recording its result, takeover retries the same
+        // deterministic invocation id instead of inventing a second worker.
+        batch.recordPlanned(record, { ...spec, invocationId });
+        if (!await this.#saveDispatchLifecycle(record, 'dispatching')) {
+            throw new Error(`Dispatch lifecycle ownership lost before spawning ${spec.name}`);
+        }
         await this.#prepareAgentWorktree(record, spec);
         let result;
         try {
@@ -9464,6 +9813,26 @@ export class FactoryLoop {
             await this.#releaseOrphanedLatePlacement(record, spec, result);
             throw new LatePlacementReleasedError(record.issue.key, result.name ?? spec.name);
         }
+        if (this.#fleet.placementLocality === 'remote') {
+            const registered = await this.#awaitRemoteAgentRegistration(result.name, spec.capability, result.node);
+            if (!registered) {
+                try {
+                    await this.#fleet.release(result.name, 'spawn-registration-timeout');
+                    this.#fleet.markAgentTerminal?.(result.name, 'spawn-registration-timeout');
+                    throw new RemoteAgentRegistrationTimeoutError(result.name, true);
+                }
+                catch (error) {
+                    if (error instanceof RemoteAgentRegistrationTimeoutError)
+                        throw error;
+                    // Cleanup is unconfirmed. Persist the placement so a successor can
+                    // retry the release; forgetting it would be worse than retaining a
+                    // nonterminal lifecycle for a worker that may still be alive.
+                    batch.recordSpawn(record, spec, invocationId, result);
+                    await this.#saveDispatchLifecycle(record, 'dispatching');
+                    throw new RemoteAgentRegistrationTimeoutError(result.name, false, error);
+                }
+            }
+        }
         record.heldSinceAtMs ??= this.#clock.now();
         batch.recordSpawn(record, spec, invocationId, result);
         if (!await this.#saveDispatchLifecycle(record, 'dispatching')) {
@@ -9475,6 +9844,89 @@ export class FactoryLoop {
             await this.#reportAgent(record, spawned, 'agent.spawned');
         return { name: result.name };
     }
+    async #awaitRemoteAgentRegistration(name, capability, expectedNode) {
+        const deadlineAtMs = this.#clock.now() + REMOTE_AGENT_REGISTRATION_TIMEOUT_MS;
+        do {
+            try {
+                if (expectedNode) {
+                    if (this.#fleet.isAgentRegistered) {
+                        if (await this.#fleet.isAgentRegistered({ name, node: expectedNode, capability }))
+                            return true;
+                    }
+                    else {
+                        const roster = await this.#fleet.roster();
+                        const agent = roster.agents.find((candidate) => candidate.name === name && candidate.node === expectedNode);
+                        const node = agent
+                            ? roster.nodes.find((candidate) => candidate.name === expectedNode && candidate.live && candidate.capabilities.includes(capability))
+                            : undefined;
+                        if (agent && node)
+                            return true;
+                    }
+                }
+            }
+            catch (error) {
+                this.#logger.warn?.('[factory] remote agent registration probe failed; retrying within startup bound', {
+                    agent: name,
+                    error: describeError(error).errorMessage,
+                });
+            }
+            const remainingMs = deadlineAtMs - this.#clock.now();
+            if (remainingMs <= 0)
+                return false;
+            await this.#clock.sleep(Math.min(REMOTE_AGENT_REGISTRATION_POLL_MS, remainingMs));
+        } while (this.#clock.now() <= deadlineAtMs);
+        return false;
+    }
+    async #rollbackUnregisteredRemoteDispatch(record, acknowledged) {
+        const handoffs = this.#dispatchFailureHandoffs(record, acknowledged);
+        await this.#persistDispatchFailureReaperHandoff(record, handoffs);
+        const hasWorktrees = handoffs.some((handoff) => handoff.worktree);
+        if (hasWorktrees) {
+            if (!await this.#teardownFailedDispatchWorktrees(handoffs, 'spawn-registration-timeout', { skipNeverPlacedAgents: true }))
+                return false;
+        }
+        else {
+            const failed = await this.#releaseAndTerminateAgents(handoffs
+                .filter((handoff) => handoff.tracked.result !== undefined)
+                .map((handoff) => [handoff.name, handoff.tracked]), 'spawn-registration-timeout', 'completion');
+            if (failed.length > 0)
+                return false;
+            for (const handoff of handoffs) {
+                await this.#state.clearFailureHandoff(this.#workspaceId, registryHandoffKey(handoff.issue, handoff.name));
+            }
+        }
+        try {
+            await this.#teardownPreviews(record);
+        }
+        catch (error) {
+            this.#logger.warn?.('[factory] retained unregistered spawn lifecycle after preview rollback failed', {
+                issue: record.issue.key,
+                error: describeError(error).errorMessage,
+            });
+            return false;
+        }
+        const key = dispatchLifecycleKey(record.issue);
+        const epoch = this.#dispatchLifecycleEpochs.get(key);
+        const lifecycle = await this.#state.getDispatchLifecycle(this.#workspaceId, key);
+        const lease = lifecycle?.lease;
+        if (epoch === undefined ||
+            !lease ||
+            lease.owner !== this.#dispatchLifecycleOwner ||
+            lease.epoch !== epoch ||
+            !await this.#state.clearClaimedDispatchLifecycle(this.#workspaceId, key, lease))
+            return false;
+        const retryTimer = this.#dispatchLifecycleRetryTimers.get(key);
+        if (retryTimer)
+            clearTimeout(retryTimer);
+        this.#dispatchLifecycleRetryTimers.delete(key);
+        this.#dispatchLifecycleEpochs.delete(key);
+        this.#abandonedDispatchReasons.delete(key);
+        const batch = await this.#batch();
+        batch.abandon(record.issue);
+        await this.#writeInFlightRegistry();
+        this.#resetDispatchCapacityBackoff();
+        return true;
+    }
     /**
      * Is this process still the owner of a lifecycle that is not already done?
      *
@@ -18041,6 +18493,50 @@ function dispatchSpecs(decision) {
     }
     return [...decision.implementers, decision.reviewer];
 }
+function liveFleetNodeForSpec(spec, roster, assignedLoads) {
+    const eligible = roster.nodes.filter((node) => node.live && node.capabilities.includes(spec.capability));
+    if (eligible.length === 0)
+        throw new FleetPlacementUnavailableError(spec.capability);
+    const explicitlyRequested = spec.node && spec.node !== 'self'
+        ? eligible.find((node) => node.name === spec.node)
+        : undefined;
+    const selected = explicitlyRequested ?? [...eligible].sort((left, right) => {
+        const loadDifference = (assignedLoads.get(left.name) ?? 0) - (assignedLoads.get(right.name) ?? 0);
+        return loadDifference || left.name.localeCompare(right.name);
+    })[0];
+    assignedLoads.set(selected.name, (assignedLoads.get(selected.name) ?? 0) + 1);
+    return selected.name;
+}
+/**
+ * Resolve every remote dispatch spec against one canonical roster snapshot.
+ *
+ * A configured node is a preference, not an entitlement: if it is offline or
+ * no longer advertises the required capability, placement is re-selected from
+ * the live fleet. This runs before durable lifecycle creation, so an empty
+ * eligible set cannot leave a claim or consume a batch slot.
+ */
+function decisionWithVerifiedRemotePlacements(decision, roster) {
+    const assignedLoads = new Map();
+    for (const agent of roster.agents) {
+        if (agent.node)
+            assignedLoads.set(agent.node, (assignedLoads.get(agent.node) ?? 0) + 1);
+    }
+    const place = (spec) => ({
+        ...spec,
+        node: liveFleetNodeForSpec(spec, roster, assignedLoads),
+    });
+    if (decision.scope === 'workflow') {
+        return {
+            ...structuredClone(decision),
+            ...(decision.workflow ? { workflow: place(decision.workflow) } : {}),
+        };
+    }
+    return {
+        ...structuredClone(decision),
+        implementers: decision.implementers.map(place),
+        reviewer: place(decision.reviewer),
+    };
+}
 function dispatchSessionOwner(decision) {
     for (const spec of dispatchSpecs(decision)) {
         const sessionOwner = spec.principal?.trim() || spec.owner?.trim();
@@ -18904,28 +19400,59 @@ const PROBE_PR_INDEX_FALLBACK_COUNTERS = {
     'index-absent': 'probePrIndexAbsent',
     'index-shape-unrecognised': 'probePrIndexShapeUnrecognised',
     'index-without-head-ref': 'probePrIndexWithoutHeadRef',
-    // Not a fallback condition so much as a standing invitation: rows carry
-    // `headRef`, so the walk is now avoidable and this counter going non-zero is
-    // the cue to build the fast path.
-    'index-usable': 'probePrIndexUsableButUnused',
+    'index-row-malformed': 'probePrIndexRowMalformed',
+    'index-incomplete': 'probePrIndexIncomplete',
+    'index-no-match': 'probePrIndexNoMatch',
+    'index-disagreed': 'probePrIndexDisagreed',
 };
 /**
- * Classify the pull index without acting on it.
+ * The lowest `issuePrMatchScore` tier the pull index can compute for itself.
  *
- * Deliberately diagnostic only. Factory's issue-side reader
- * (`#githubIssuePathsFromIndex`) uses its index as a NARROWING FILTER over
- * paths it still reads individually, which is safe because it can only
- * over-select. A pull index cannot be used that way today: it carries no
- * `headRef`, so it cannot exclude any pull request from a branch match, and a
- * title hit alone (score 20) must never be returned as the answer while an
- * unread branch match (score 30) could outrank it. Until the row contract
- * carries `headRef` (relayfile-adapters#271), the only honest thing to do with
- * the index is say out loud why it did not help.
+ * The scores are: branch match 30, issue key in title 20, explicit reference in
+ * body 10. A row carries `headRef` and `title` but NOT `body`, so a row can be
+ * scored exactly at the 30 and 20 tiers and is blind at 10. A pull request the
+ * index scores at 20 or better therefore cannot be beaten by anything the index
+ * could not see, because the best a body-only match can ever earn is 10 — which
+ * makes an index hit of 20 or 30 provably the same winner the full walk would
+ * have chosen. Below that threshold the index proves nothing and the walk is
+ * mandatory.
+ *
+ * Deliberately expressed as a threshold rather than a "highest score wins"
+ * shortcut: the constant is the whole safety argument, and inlining `20` at the
+ * comparison would bury it.
  */
-const classifyPullIndexFallback = async (mount, repo) => {
+const PULL_INDEX_DECISIVE_SCORE = 20;
+/**
+ * Read `pulls/_index.json` and either return rows the probe may rank, or say
+ * why it may not.
+ *
+ * All-or-nothing per repository, and the discipline is copied verbatim from
+ * Factory's issue-side reader (`#githubIssuePathsFromIndex`): fall back for the
+ * ENTIRE repository if any row is legacy or malformed. One legacy row is enough
+ * to poison the whole conclusion: the primary match is a branch match worth 30,
+ * so a row without `headRef` cannot be ruled out as the real winner, and ranking
+ * the remaining rows against each other would answer a different question from
+ * the one the walk answers.
+ *
+ * Mixed indexes are the expected state today, not a corruption. `headRef` landed
+ * in `@relayfile/adapter-github@0.5.7` and there is no pull-side backfill: the
+ * incremental writers replace exactly the row they touched and pass every other
+ * row through verbatim, so a webhook update hydrates one row and leaves the rest
+ * legacy. Only an eager re-ingest converges a repository, because it rebuilds
+ * the file from a list-pulls response in which every row carries `head.ref`.
+ *
+ * Row facts this relies on, from that contract: `state` is GitHub's lowercase
+ * `"open"`/`"closed"` and there is no `"merged"` state — `merged: true` (with
+ * `mergedAt`) is the only merged signal and `merged: false` is never written.
+ * `headRef` is the bare branch name (`head.ref`), matching what
+ * `readProbePrCandidate` reads off a record, NOT the `owner:branch` form of
+ * `head.label`. `id` and `updated` are deliberately not required here: the
+ * oldest legacy rows carry neither.
+ */
+const readPullIndexForProbe = async (mount, repo) => {
     const [owner, name] = repo.split('/');
     if (!owner || !name)
-        return 'index-absent';
+        return { reason: 'index-absent' };
     let parsed;
     try {
         const { content } = await mount.readFile(`${GITHUB_ISSUE_ROOT}/${owner}/${name}/pulls/_index.json`);
@@ -18936,23 +19463,159 @@ const classifyPullIndexFallback = async (mount, repo) => {
         // that is the same convention the tree reads below already follow.
         if (isPassWideRelayfileFault(error))
             throw error;
-        return 'index-absent';
+        return { reason: 'index-absent' };
     }
     if (!Array.isArray(parsed))
-        return 'index-shape-unrecognised';
+        return { reason: 'index-shape-unrecognised' };
     // An empty index proves nothing about the row contract, so it must not read
     // as usable — `[].every(...)` is vacuously true.
-    return parsed.length > 0 && parsed.every((entry) => typeof asRecord(entry)?.headRef === 'string')
-        ? 'index-usable'
-        : 'index-without-head-ref';
+    if (parsed.length === 0)
+        return { reason: 'index-without-head-ref' };
+    const rows = [];
+    for (const entry of parsed) {
+        const row = asRecord(entry);
+        if (typeof row?.headRef !== 'string')
+            return { reason: 'index-without-head-ref' };
+        if (!Number.isSafeInteger(row.number) || Number(row.number) <= 0 ||
+            typeof row.title !== 'string' ||
+            typeof row.state !== 'string' ||
+            (row.merged !== undefined && typeof row.merged !== 'boolean')) {
+            return { reason: 'index-row-malformed' };
+        }
+        rows.push({
+            number: Number(row.number),
+            title: row.title,
+            headRef: row.headRef,
+            state: row.state,
+            merged: row.merged,
+        });
+    }
+    return { rows };
 };
-const resolveIssuePrFromMount = async (mount, config, issue, opts = {}, listTree = (prefix) => mount.listTree(prefix), observer = {}) => {
+/**
+ * Rank index rows exactly as the walk ranks records it has read.
+ *
+ * `body: ''` is a deliberate constant, not a placeholder for a value that
+ * should have been threaded through. The index carries no body, so scoring with
+ * an empty one makes `issuePrMatchScore` return only the tiers the index can
+ * actually justify — 30 for a branch match, 20 for a title match, 0 otherwise —
+ * and never invents the 10 it cannot see. Everything else (`requireTitleMarker`
+ * gating, `allowLegacyGithubBranch`, the marker itself) is the SAME call the
+ * walk makes on the same inputs, so the two paths cannot score differently.
+ *
+ * The tiebreak mirrors `b.score - a.score || b.prNumber - a.prNumber`: highest
+ * score, then highest pull request number.
+ */
+const bestPullIndexRow = (rows, issue, marker, opts) => {
+    let best;
+    for (const row of rows) {
+        // Same derivation `readProbePrCandidate` applies to a record: a merged pull
+        // request reports MERGED regardless of the raw `state` the provider wrote.
+        const state = row.merged === true ? 'MERGED' : row.state;
+        if (opts.openOnly && normalizePrState(state) !== 'OPEN')
+            continue;
+        const score = issuePrMatchScore({ title: row.title, body: '', headRef: row.headRef }, issue, marker, opts);
+        if (score < PULL_INDEX_DECISIVE_SCORE)
+            continue;
+        if (!best || score > best.score || (score === best.score && row.number > best.number)) {
+            best = { number: row.number, score };
+        }
+    }
+    return best;
+};
+/**
+ * Build the resolver's candidate shape from one pull request record.
+ *
+ * Shared by the index fast path and the walk so the two can never disagree on a
+ * field. Differential equivalence is the whole safety property of the fast path
+ * and it should hold structurally, not by two copies staying in sync.
+ */
+const probePrCandidate = (repo, pr, path, score) => ({
+    repo,
+    prNumber: pr.number,
+    draft: pr.draft,
+    headRef: pr.headRef,
+    headRepo: pr.headRepo,
+    crossRepository: pr.crossRepository ?? (pr.headRepo ? pr.headRepo.toLowerCase() !== repo.toLowerCase() : undefined),
+    state: pr.state,
+    url: pr.url,
+    path,
+    score,
+});
+/**
+ * Answer "which pull request belongs to this issue?" from `pulls/_index.json`
+ * instead of reading every mounted pull request record, or say why it could not.
+ *
+ * Reads at most two files: the index, and the one record the index names. That
+ * record read is not an optimisation that was left on the table — it is load
+ * bearing twice over. The index carries no `draft`, `headRepo`, `url` or mount
+ * path, all of which the resolver's result type promises and callers persist as
+ * `ownedPullRequest`; and re-scoring the real record is what turns "the index
+ * said so" into "the record agrees", so a stale row can never decide an answer
+ * on its own.
+ *
+ * The tree listing is NOT avoided, and that is deliberate. It costs two calls
+ * per repository where the record walk cost one call per pull request — 4,000
+ * of them in the live workspace, which is the cost that stalled a sweep for
+ * 11m53s. Keeping it buys two things nothing else can: the exact path spelling
+ * the walk would have reported (the nested layout's slug cannot be constructed,
+ * only listed), and the completeness check below.
+ *
+ * Every condition that still walks:
+ *
+ *  - anything `readPullIndexForProbe` refuses — absent, wrong shape, any row
+ *    without `headRef`, any row whose `number`/`title`/`state` is unusable;
+ *  - a pull request on disk with no row describing it, because an unindexed
+ *    record could hold the score-30 branch match;
+ *  - no row scoring `PULL_INDEX_DECISIVE_SCORE` or better, because a body-only
+ *    reference worth 10 may exist on disk and no index row can see a body;
+ *  - the named record failing to confirm its row — missing, different number,
+ *    different score, or not open when `openOnly` is set.
+ */
+const resolveProbePrFromPullIndex = async (mount, repo, issue, marker, opts, walk, pullNumbersOnDisk, observer) => {
+    const reading = await readPullIndexForProbe(mount, repo);
+    if (!reading.rows)
+        return { reason: reading.reason };
+    const indexed = new Set(reading.rows.map((row) => row.number));
+    for (const number of pullNumbersOnDisk) {
+        if (!indexed.has(number))
+            return { reason: 'index-incomplete' };
+    }
+    const best = bestPullIndexRow(reading.rows, issue, marker, opts);
+    if (!best)
+        return { reason: 'index-no-match' };
+    // The first spelling of this pull request in `walk` is by construction the
+    // one the record loop below would have read: `walk` preserves the listing
+    // order of `githubPullRoots` and has already collapsed the alias spellings,
+    // keeping the first. So the fast path reports the same `path` the walk does.
+    const path = walk.find((candidatePath) => githubPullPathParts(candidatePath)?.number === best.number);
+    if (!path)
+        return { reason: 'index-disagreed' };
+    const pr = await readProbePrCandidate(mount, path);
+    observer.onRead?.({ read: 1, total: 1, path });
+    if (!pr)
+        return { reason: 'index-disagreed' };
+    if (opts.openOnly && normalizePrState(pr.state) !== 'OPEN')
+        return { reason: 'index-disagreed' };
+    // `readProbePrCandidate` takes the number from the PAYLOAD, falling back to
+    // the path, so a record can disagree with the path that addressed it.
+    if (pr.number !== best.number)
+        return { reason: 'index-disagreed' };
+    const score = issuePrMatchScore(pr, issue, marker, opts);
+    if (score !== best.score)
+        return { reason: 'index-disagreed' };
+    observer.onIndexHit?.(repo, pr.number);
+    return { candidate: probePrCandidate(repo, pr, path, score) };
+};
+// Exported for the differential-equivalence suite, which has to invoke the
+// index fast path and the record walk over ONE corpus and compare their two
+// answers field for field. Driving that through the loop's public surface would
+// compare a resolution to itself; the same precedent already exists in this
+// file for `githubIssuePathParts` and `keyFromPath`.
+export const resolveIssuePrFromMount = async (mount, config, issue, opts = {}, listTree = (prefix) => mount.listTree(prefix), observer = {}) => {
     const candidates = [];
     const listErrors = [];
     for (const repo of opts.repo ? [opts.repo] : reposFromConfig(config)) {
-        if (observer.onIndexFallback) {
-            observer.onIndexFallback(repo, await classifyPullIndexFallback(mount, repo));
-        }
         const paths = new Set();
         for (const root of githubPullRoots(repo)) {
             try {
@@ -18983,6 +19646,10 @@ const resolveIssuePrFromMount = async (mount, config, issue, opts = {}, listTree
         // still read exactly as before rather than being filtered on a guess.
         const walk = [];
         const seenPulls = new Set();
+        // The pull request numbers the TREE says exist, which is what makes the
+        // index's completeness checkable below. Built here rather than separately
+        // because `githubPullPathParts` has already been called on every path.
+        const pullNumbersOnDisk = new Set();
         for (const path of paths) {
             if (!path.endsWith('.json'))
                 continue;
@@ -18992,9 +19659,17 @@ const resolveIssuePrFromMount = async (mount, config, issue, opts = {}, listTree
                 if (seenPulls.has(identity))
                     continue;
                 seenPulls.add(identity);
+                pullNumbersOnDisk.add(parts.number);
             }
             walk.push(path);
         }
+        const marker = opts.titleMarker ?? config.safety.requireTitlePrefix;
+        const fromIndex = await resolveProbePrFromPullIndex(mount, repo, issue, marker, opts, walk, pullNumbersOnDisk, observer);
+        if (fromIndex.candidate) {
+            candidates.push(fromIndex.candidate);
+            continue;
+        }
+        observer.onIndexFallback?.(repo, fromIndex.reason);
         let read = 0;
         for (const path of walk) {
             const pr = await readProbePrCandidate(mount, path);
@@ -19002,23 +19677,10 @@ const resolveIssuePrFromMount = async (mount, config, issue, opts = {}, listTree
             observer.onRead?.({ read, total: walk.length, path });
             if (opts.openOnly && normalizePrState(pr?.state) !== 'OPEN')
                 continue;
-            const score = pr
-                ? issuePrMatchScore(pr, issue, opts.titleMarker ?? config.safety.requireTitlePrefix, opts)
-                : 0;
+            const score = pr ? issuePrMatchScore(pr, issue, marker, opts) : 0;
             if (!pr || score <= 0)
                 continue;
-            candidates.push({
-                repo,
-                prNumber: pr.number,
-                draft: pr.draft,
-                headRef: pr.headRef,
-                headRepo: pr.headRepo,
-                crossRepository: pr.crossRepository ?? (pr.headRepo ? pr.headRepo.toLowerCase() !== repo.toLowerCase() : undefined),
-                state: pr.state,
-                url: pr.url,
-                path,
-                score,
-            });
+            candidates.push(probePrCandidate(repo, pr, path, score));
         }
     }
     const resolved = candidates.sort((a, b) => b.score - a.score || b.prNumber - a.prNumber)[0];