@agent-relay/factory 0.1.77 → 0.1.79

package/dist/orchestrator/factory.js

@@ -167,6 +167,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;
@@ -424,6 +449,7 @@ export class FactoryLoop {
     #babysitterWakeUnreachableEscalateMs;
     #babysitterWakeUnreachableRetryMs;
     #startupAgentExitDrainTimeoutMs;
+    #dispatchLifecycleRetryMs;
     #state;
     #workspaceId;
     #relayflows;
@@ -500,6 +526,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 +895,7 @@ 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.#workspaceId = config.workspaceId ?? 'default';
         this.#relayflows = ports.relayflows;
         this.#worktrees = ports.worktrees;
@@ -4687,11 +4724,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 +4741,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) {
@@ -5637,8 +5685,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 }
                 : {}),
@@ -6912,19 +6975,113 @@ 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))
+            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();
+        // `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,
+        });
+        const drive = 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,
+            });
+        })
+            .finally(() => this.#dispatchLifecycleDrives.delete(drive));
+        this.#dispatchLifecycleDrives.add(drive);
+        return false;
+    }
+    /**
+     * 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.
+     */
+    async #releaseDeadLetteredSlot(record, key) {
+        const batch = await this.#batch();
+        const next = batch.complete(record.issue);
+        this.#uncompensatedDispatchClaims.delete(key);
+        await this.#writeInFlightRegistry();
+        // 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 +7096,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 +7108,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 +7131,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 +7157,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 +7370,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 +7579,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 +7600,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 +7625,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
@@ -18904,28 +19097,47 @@ 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 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. `headRef` was added to
+ * the public GitHub pull index contract in `@relayfile/adapter-github@0.5.7`
+ * and an already-written mount only converges on re-ingest, so mixed indexes
+ * are the expected state, not a corruption. 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.
  */
-const classifyPullIndexFallback = async (mount, repo) => {
+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 +19148,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 };
+};
+/**
+ * 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) };
 };
-const resolveIssuePrFromMount = async (mount, config, issue, opts = {}, listTree = (prefix) => mount.listTree(prefix), observer = {}) => {
+// 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 +19331,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 +19344,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 +19362,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];