@agent-relay/factory 0.1.79 → 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).
  *
@@ -349,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.
@@ -450,6 +472,7 @@ export class FactoryLoop {
     #babysitterWakeUnreachableRetryMs;
     #startupAgentExitDrainTimeoutMs;
     #dispatchLifecycleRetryMs;
+    #dispatchLifecycleRenewMs;
     #state;
     #workspaceId;
     #relayflows;
@@ -896,6 +919,7 @@ export class FactoryLoop {
         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;
@@ -2783,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();
@@ -5019,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
@@ -5437,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.
@@ -6188,7 +6222,7 @@ export class FactoryLoop {
             return;
         this.#dispatchLifecycleRenewTimer = setInterval(() => {
             void this.#renewDispatchLifecycles();
-        }, DISPATCH_LIFECYCLE_RENEW_MS);
+        }, this.#dispatchLifecycleRenewMs);
         this.#dispatchLifecycleRenewTimer.unref?.();
     }
     /**
@@ -6385,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);
@@ -6985,8 +7031,17 @@ export class FactoryLoop {
      * the only thing still running is the spin.
      */
     #chargeReleaseAttempt(record, key, context) {
-        if (this.#dispatchLifecycleReleaseAbandoned.has(key))
+        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)
@@ -6995,6 +7050,19 @@ export class FactoryLoop {
         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
@@ -7009,16 +7077,63 @@ export class FactoryLoop {
             // 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,
+        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,
             });
-        })
-            .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.
@@ -7035,12 +7150,36 @@ export class FactoryLoop {
      * 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) {
-        const batch = await this.#batch();
-        const next = batch.complete(record.issue);
-        this.#uncompensatedDispatchClaims.delete(key);
-        await this.#writeInFlightRegistry();
+        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 });
@@ -9585,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 });
@@ -9601,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, {
@@ -9618,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 {
@@ -9657,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')) {
@@ -9668,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?
      *
@@ -18234,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();
@@ -19125,14 +19428,26 @@ const PULL_INDEX_DECISIVE_SCORE = 20;
  *
  * 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.
+ * 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('/');