@agent-relay/factory 0.1.37 → 0.1.38

package/dist/orchestrator/factory.js

@@ -85,6 +85,7 @@ const STOP_TEARDOWN_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 STARTUP_AGENT_EXIT_DRAIN_TIMEOUT_MS = 30_000;
 const SLACK_EVENT_WATERMARK_CACHE_MS = 60_000;
 const MERGE_GATE_MAX_ATTEMPTS = 12;
 const MERGE_GATE_POLL_DELAY_MS = 10_000;
@@ -99,6 +100,8 @@ const GITHUB_MIRROR_TITLE_PREFIX = '[factory]';
 const GITHUB_MIRROR_SOURCE_PREFIX = 'Source: ';
 export const DEFAULT_FACTORY_LOOP_HEARTBEAT_PATH = '/tmp/factory-run/factory-loop-heartbeat.json';
 export const DEFAULT_FACTORY_LOOP_REGISTRY_PATH = '/tmp/factory-run/factory-loop-registry.json';
+class DispatchLifecycleCapacityError extends Error {
+}
 const realClock = {
     now: () => Date.now(),
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
@@ -130,6 +133,7 @@ export class FactoryLoop {
     #terminationGraceMs;
     #babysitterWakeUnreachableEscalateMs;
     #babysitterWakeUnreachableRetryMs;
+    #startupAgentExitDrainTimeoutMs;
     #state;
     #workspaceId;
     #relayflows;
@@ -176,6 +180,7 @@ export class FactoryLoop {
     #dispatchTerminalWaiters = new Map();
     #dispatchLifecycleRetryTimers = new Map();
     #dispatchLifecycleDrives = new Set();
+    #dispatchLifecycleCapacityWaitLogged = new Set();
     #localReleaseCheckpoints = new Map();
     #dispatchLifecycleRenewTimer;
     #clarificationSweepTimer;
@@ -286,6 +291,7 @@ export class FactoryLoop {
         this.#terminationGraceMs = ports.terminationGraceMs;
         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.#workspaceId = config.workspaceId ?? 'default';
         this.#relayflows = ports.relayflows;
         this.#worktrees = ports.worktrees;
@@ -480,7 +486,12 @@ export class FactoryLoop {
             this.#wireFleetEvents();
             await this.#adoptInFlightAgents(legacyRegistry);
             this.#startupAgentAdoptionActive = false;
-            await this.#restoreBabysitterOwnership();
+            if (this.#config.babysitter.enabled) {
+                // Re-run the idempotent receipt fold after adoption returns. This
+                // catches records restored by lifecycle work that completed while the
+                // startup roster drain was in progress.
+                await this.#reconcileRestoredBabysitterReceipts();
+            }
         }
         catch (error) {
             this.#startupAgentAdoptionActive = false;
@@ -559,6 +570,12 @@ export class FactoryLoop {
         this.#completionSweepTimer = undefined;
         this.#stoppingHeartbeatRefreshActive = await this.#stopLiveHeartbeat('stopping');
         try {
+            // Relinquish durable ownership before waiting on mount-backed lifecycle
+            // drives. A slow Relayfile scan must not consume the shutdown deadline
+            // while every issue remains fenced to a publisher that is already
+            // stopping. The owner/epoch fence makes any late completion from those
+            // drives harmless; a second sweep below catches claims racing this one.
+            await this.#releaseOwnedDispatchLifecycleLeases();
             await Promise.allSettled([...this.#dispatchLifecycleDrives]);
             // Fence every source of new clarification work before touching the fleet.
             // A wake already past the fence is allowed to unwind, and is awaited
@@ -581,10 +598,7 @@ export class FactoryLoop {
             // non-durable (local/internal) records; terminal completion performs the
             // normal remote release before clearing the lifecycle.
             await this.#releaseInFlightAgents('factory-stopped', { preserveDurable: true });
-            for (const [key, epoch] of [...this.#dispatchLifecycleEpochs]) {
-                await this.#state.releaseDispatchLifecycleLease(this.#workspaceId, key, this.#dispatchLifecycleOwner, epoch);
-            }
-            this.#dispatchLifecycleEpochs.clear();
+            await this.#releaseOwnedDispatchLifecycleLeases();
             if (this.#livePollTimer)
                 clearTimeout(this.#livePollTimer);
             this.#livePollTimer = undefined;
@@ -622,6 +636,14 @@ export class FactoryLoop {
             this.#stoppingHeartbeatRefreshActive = false;
         }
     }
+    async #releaseOwnedDispatchLifecycleLeases() {
+        for (const [key, epoch] of [...this.#dispatchLifecycleEpochs]) {
+            await this.#state.releaseDispatchLifecycleLease(this.#workspaceId, key, this.#dispatchLifecycleOwner, epoch);
+            if (this.#dispatchLifecycleEpochs.get(key) === epoch) {
+                this.#dispatchLifecycleEpochs.delete(key);
+            }
+        }
+    }
     async #drainClarificationWakesForStop() {
         // A wake may add its promise just as the sweep that discovered it settles.
         // Re-snapshot until the map is empty rather than assuming one await is a
@@ -1709,6 +1731,7 @@ export class FactoryLoop {
             url: pr.url ?? `https://github.com/${pr.repo}/pull/${pr.prNumber}`,
             path: pr.path,
             headRef,
+            authoritative: true,
         });
         const babysitter = [...record.agents.values()].find((tracked) => tracked.spec.role === 'babysitter');
         if (!babysitter) {
@@ -2279,6 +2302,14 @@ export class FactoryLoop {
             if (agents.length > 0 && this.#fleet.hydrateTracked) {
                 this.#fleet.hydrateTracked(agents);
             }
+            if (this.#config.babysitter.enabled) {
+                // Restore and reconcile exact PR ownership before asking the fleet to
+                // report missing agents. Otherwise a stale weak-match babysitter from
+                // the lifecycle can be resumed before its independently durable,
+                // metadata-validated replacement session becomes authoritative.
+                await this.#restoreBabysitterOwnership();
+                await this.#reconcileRestoredBabysitterReceipts();
+            }
             this.#scheduleDispatchLifecycleRenewal();
             if (this.#fleet.hydrateTracked) {
                 this.#startupAgentAdoptionActive = false;
@@ -2293,23 +2324,50 @@ export class FactoryLoop {
                 // but recovery work is asynchronous (issue reads, worktree restore,
                 // PR publication). Finish exits discovered by the startup reconcile
                 // before the full ready-issue backfill can monopolize mount I/O.
-                await this.#drainAgentExitsInFlight(new Set(agents.map((agent) => agent.name)));
-                this.#logger.info?.('[factory] durable startup reconciled exits drained');
+                const exitNames = new Set(agents.map((agent) => agent.name));
+                const drained = await this.#drainAgentExitsInFlight(exitNames, this.#startMode === 'live' ? this.#startupAgentExitDrainTimeoutMs : undefined);
+                if (drained) {
+                    this.#logger.info?.('[factory] durable startup reconciled exits drained');
+                }
+                else {
+                    this.#increment('startupAgentExitDrainTimeouts');
+                    this.#logger.warn?.('[factory] startup agent exit reconciliation is still running; continuing ready-issue discovery', {
+                        timeoutMs: this.#startupAgentExitDrainTimeoutMs,
+                        pendingExits: [...this.#agentExitsInFlight.keys()].filter((name) => exitNames.has(name)),
+                    });
+                }
             }
         }
         catch (error) {
             this.#logger.warn?.('[factory] failed to re-adopt durable in-flight agents', { error });
         }
     }
-    async #drainAgentExitsInFlight(names) {
-        for (;;) {
-            const pending = [...this.#agentExitsInFlight]
-                .filter(([name]) => !names || names.has(name))
-                .map(([, handling]) => handling);
-            if (pending.length === 0)
-                return;
-            await Promise.allSettled(pending);
+    async #drainAgentExitsInFlight(names, timeoutMs) {
+        const drain = async () => {
+            for (;;) {
+                const pending = [...this.#agentExitsInFlight]
+                    .filter(([name]) => !names || names.has(name))
+                    .map(([, handling]) => handling);
+                if (pending.length === 0)
+                    return;
+                await Promise.allSettled(pending);
+            }
+        };
+        if (timeoutMs === undefined) {
+            await drain();
+            return true;
         }
+        let timer;
+        const completed = await Promise.race([
+            drain().then(() => true),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs));
+                timer.unref?.();
+            }),
+        ]);
+        if (timer)
+            clearTimeout(timer);
+        return completed;
     }
     #scheduleDispatchLifecycleRenewal() {
         if (this.#dispatchLifecycleRenewTimer || this.#dispatchLifecycleEpochs.size === 0)
@@ -2457,7 +2515,7 @@ export class FactoryLoop {
         }
         const previous = await this.#state.getDispatchLifecycle(this.#workspaceId, key);
         const pullRequests = mergePublishedPullRequests(previous, pullRequest);
-        const primaryPullRequest = previous?.pullRequest ?? pullRequest ?? pullRequests[0];
+        const primaryPullRequest = primaryPublishedPullRequest(previous, pullRequest, pullRequests);
         const lifecycle = lifecycleFromInFlightRecord(record, previous?.runId ?? randomUUID(), phase, this.#clock.now(), primaryPullRequest, pullRequests, releaseReason ?? previous?.releaseReason);
         for (const agent of lifecycle.agents) {
             const previouslyReleasedAtMs = previous?.agents.find((candidate) => candidate.name === agent.name)?.releasedAtMs;
@@ -2502,11 +2560,27 @@ export class FactoryLoop {
         const timer = setTimeout(() => {
             this.#dispatchLifecycleRetryTimers.delete(key);
             const drive = this.#driveDispatchLifecycle(key)
+                .then(() => {
+                this.#dispatchLifecycleCapacityWaitLogged.delete(key);
+            })
                 .catch((error) => {
-                this.#logger.warn?.('[factory] durable dispatch lifecycle retry failed', {
-                    issue: record.issue.key,
-                    error: describeError(error).errorMessage,
-                });
+                if (error instanceof DispatchLifecycleCapacityError) {
+                    if (!this.#dispatchLifecycleCapacityWaitLogged.has(key)) {
+                        this.#dispatchLifecycleCapacityWaitLogged.add(key);
+                        this.#increment('dispatchLifecycleCapacityWaits');
+                        this.#logger.warn?.('[factory] durable dispatch is queued for batch capacity; retries remain active', {
+                            issue: record.issue.key,
+                            retryMs: DISPATCH_LIFECYCLE_RETRY_MS,
+                        });
+                    }
+                }
+                else {
+                    this.#dispatchLifecycleCapacityWaitLogged.delete(key);
+                    this.#logger.warn?.('[factory] durable dispatch lifecycle retry failed', {
+                        issue: record.issue.key,
+                        error: describeError(error).errorMessage,
+                    });
+                }
                 this.#scheduleDispatchLifecycleRetry(record);
             })
                 .finally(() => this.#dispatchLifecycleDrives.delete(drive));
@@ -2565,7 +2639,7 @@ export class FactoryLoop {
         if (lifecycle.phase === 'queued') {
             const epoch = this.#dispatchLifecycleEpochs.get(key);
             if (epoch === undefined || !await this.#state.promoteDispatchLifecycle(this.#workspaceId, key, this.#dispatchLifecycleOwner, epoch, this.#clock.now())) {
-                throw new Error(`durable dispatch ${lifecycle.issue.key} is waiting for batch capacity`);
+                throw new DispatchLifecycleCapacityError(`durable dispatch ${lifecycle.issue.key} is waiting for batch capacity`);
             }
             const promoted = await this.#state.getDispatchLifecycle(this.#workspaceId, key);
             if (!promoted || promoted.phase !== 'dispatching') {
@@ -2601,6 +2675,8 @@ export class FactoryLoop {
                 })));
                 await this.#fleet.reconcileTrackedAgents?.();
             }
+            if (this.#config.babysitter.enabled)
+                await this.#reconcileRestoredBabysitterReceipts(record);
             return;
         }
         if (lifecycle.phase === 'parking') {
@@ -2637,6 +2713,7 @@ export class FactoryLoop {
                         prNumber: receipt.number,
                         url: receipt.url,
                         headRef: receipt.headRef,
+                        authoritative: true,
                     });
                 }
                 return;
@@ -2651,6 +2728,7 @@ export class FactoryLoop {
                     prNumber: receipt.number,
                     url: receipt.url,
                     headRef: receipt.headRef,
+                    authoritative: true,
                 });
             }
             return;
@@ -3040,40 +3118,55 @@ export class FactoryLoop {
     async #githubIssuePaths() {
         try {
             const issuePaths = new Map();
-            for (const root of githubIssueScanRoots(this.#config)) {
-                const paths = await this.#listRelayfileTree(root, 'GitHub issue ingestion');
-                for (let index = 0; index < paths.length; index += 1) {
-                    const path = paths[index];
-                    const parts = githubIssuePathParts(path);
-                    if (parts) {
-                        const identity = githubIssueIdentity(parts.owner, parts.repo, parts.number);
-                        const existing = issuePaths.get(identity);
-                        if (!existing || githubIssuePathPreference(path) < githubIssuePathPreference(existing)) {
-                            if (existing)
+            for (const { owner, repo } of configuredGithubRepoParts(this.#config)) {
+                const indexedPaths = await this.#githubIssuePathsFromIndex(owner, repo);
+                const roots = githubIssueRepoRoots(owner, repo);
+                // Keep the fallback roots as separate batches. Flattening a very large
+                // provider result is synchronous work and can starve the durable loop
+                // heartbeat before the bounded scan below gets a chance to yield.
+                const pathBatches = indexedPaths
+                    ? [indexedPaths]
+                    : await Promise.all(roots.map(async (root) => await this.#listRelayfileTree(root, 'GitHub issue ingestion')));
+                if (indexedPaths) {
+                    this.#increment('githubIssueIndexReposUsed');
+                }
+                else {
+                    this.#increment('githubIssueIndexFallbacks');
+                }
+                for (const paths of pathBatches) {
+                    for (let index = 0; index < paths.length; index += 1) {
+                        const path = paths[index];
+                        const parts = githubIssuePathParts(path);
+                        if (parts) {
+                            const identity = githubIssueIdentity(parts.owner, parts.repo, parts.number);
+                            const existing = issuePaths.get(identity);
+                            if (!existing || githubIssuePathPreference(path) < githubIssuePathPreference(existing)) {
+                                if (existing)
+                                    this.#increment('githubIssueAliasPathsSuppressed');
+                                issuePaths.set(identity, path);
+                            }
+                            else {
                                 this.#increment('githubIssueAliasPathsSuppressed');
-                            issuePaths.set(identity, path);
+                            }
                         }
-                        else {
-                            this.#increment('githubIssueAliasPathsSuppressed');
+                        else if (githubIssueDirectoryPathParts(path) !== undefined) {
+                            // listTree returns the issue directory entry alongside its
+                            // meta.json file; githubIssuePathParts() already collected the
+                            // file, so skip the directory to avoid reading the same issue
+                            // twice in one backfill pass. Directory paths are only meaningful
+                            // for live change events, not the tree scan.
+                            continue;
+                        }
+                        else if (isGithubIssueTreePath(path)) {
+                            this.#increment('githubIssuesIgnoredByPathRegex');
+                        }
+                        if ((index + 1) % LIVE_EVENT_DRAIN_BATCH_SIZE === 0) {
+                            await this.#refreshLiveHeartbeatIfDue();
+                            await liveEventYield();
                         }
                     }
-                    else if (githubIssueDirectoryPathParts(path) !== undefined) {
-                        // listTree returns the issue directory entry alongside its
-                        // meta.json file; githubIssuePathParts() already collected the
-                        // file, so skip the directory to avoid reading the same issue
-                        // twice in one backfill pass. Directory paths are only meaningful
-                        // for live change events, not the tree scan.
-                        continue;
-                    }
-                    else if (isGithubIssueTreePath(path)) {
-                        this.#increment('githubIssuesIgnoredByPathRegex');
-                    }
-                    if ((index + 1) % LIVE_EVENT_DRAIN_BATCH_SIZE === 0) {
-                        await this.#refreshLiveHeartbeatIfDue();
-                        await liveEventYield();
-                    }
+                    await this.#refreshLiveHeartbeatIfDue();
                 }
-                await this.#refreshLiveHeartbeatIfDue();
             }
             for (const [identity, path] of issuePaths) {
                 this.#githubIssuePreferredPaths.set(identity, path);
@@ -3088,6 +3181,41 @@ export class FactoryLoop {
             return [];
         }
     }
+    async #githubIssuePathsFromIndex(owner, repo) {
+        const indexPath = `${GITHUB_ISSUE_ROOT}/${owner}/${repo}/issues/_index.json`;
+        let parsed;
+        try {
+            const { content } = await this.#readRelayfileFile(indexPath, 'GitHub issue index discovery');
+            parsed = parseJsonContent(content);
+        }
+        catch {
+            return undefined;
+        }
+        if (!Array.isArray(parsed))
+            return undefined;
+        const requiredLabel = this.#config.safety.requireLabel.trim().toLowerCase();
+        if (!requiredLabel)
+            return undefined;
+        const paths = [];
+        for (const entry of parsed) {
+            const row = asRecord(entry);
+            const number = row?.number;
+            const state = typeof row?.state === 'string' ? row.state.trim().toLowerCase() : undefined;
+            const labels = row?.labels;
+            // Labels were added to the public GitHub issue index contract after the
+            // first index version. Fall back for the entire repository if any row is
+            // legacy or malformed so an eligible issue can never be filtered out.
+            if (!Number.isSafeInteger(number) || Number(number) <= 0 || !state || !Array.isArray(labels) ||
+                !labels.every((label) => typeof label === 'string')) {
+                return undefined;
+            }
+            if (state !== 'open' || !labels.some((label) => label.trim().toLowerCase() === requiredLabel)) {
+                continue;
+            }
+            paths.push(`${GITHUB_ISSUE_ROOT}/${owner}__${repo}/issues/by-id/${number}.json`);
+        }
+        return paths;
+    }
     async #handleGithubIssueChange(path, opts = {}) {
         if (this.#githubIngestionEnabled === false || !isGithubIssueFilePath(path)) {
             return;
@@ -4003,6 +4131,7 @@ export class FactoryLoop {
                         repo: publishedPr.repo,
                         prNumber: publishedPr.number,
                         url: publishedPr.url,
+                        authoritative: true,
                     });
                 }
                 else {
@@ -4032,8 +4161,42 @@ export class FactoryLoop {
                 });
             }
             if (hasCompletionPr) {
+                let reconciledPr;
+                if (tracingReconciledExit && tracked.spec.role === 'implementer') {
+                    // A restart can discover that the implementer is gone after its PR
+                    // reached GitHub but before the durable receipt was saved. Persist the
+                    // exact existing-branch receipt before handing off to a babysitter;
+                    // otherwise the lifecycle remains `running` forever and consumes a
+                    // batch slot even though useful implementation work has finished.
+                    if (!await this.#saveDispatchLifecycle(record, 'publishing'))
+                        return;
+                    try {
+                        reconciledPr = await this.#publishImplementerPullRequest(record, tracked, {
+                            reconcileExisting: true,
+                        });
+                        if (reconciledPr && !await this.#saveDispatchLifecycle(record, 'published', reconciledPr))
+                            return;
+                    }
+                    catch (error) {
+                        this.#increment('githubPullRequestPublishFailures');
+                        this.#error(error, record.issue);
+                        this.#scheduleDispatchLifecycleRetry(record);
+                        return;
+                    }
+                }
                 if (this.#config.babysitter.enabled) {
-                    await this.#ensureBabysitterForIssue(record);
+                    if (reconciledPr) {
+                        await this.#ensureBabysitter(record, {
+                            repo: reconciledPr.repo,
+                            prNumber: reconciledPr.number,
+                            url: reconciledPr.url,
+                            headRef: reconciledPr.headRef,
+                            authoritative: true,
+                        });
+                    }
+                    else {
+                        await this.#ensureBabysitterForIssue(record);
+                    }
                     return;
                 }
                 if (await this.#allImplementersHaveCompletionPr(record))
@@ -4060,6 +4223,7 @@ export class FactoryLoop {
                             repo: publishedPr.repo,
                             prNumber: publishedPr.number,
                             url: publishedPr.url,
+                            authoritative: true,
                         });
                     }
                     else {
@@ -4236,9 +4400,10 @@ export class FactoryLoop {
             : undefined;
         const repo = normalizeGithubRepo(implementer.spec.repo, this.#config.repos.org ?? sourceOwner);
         const durableReceipt = publishedPullRequests(durable).find((receipt) => receipt.repo.toLowerCase() === repo.toLowerCase());
-        if (durableReceipt)
-            return durableReceipt;
         const expectedHeadRef = implementer.spec.branch ?? remoteBranch;
+        if (durableReceipt &&
+            (!opts.reconcileExisting || !expectedHeadRef || durableReceipt.headRef === expectedHeadRef))
+            return durableReceipt;
         if (opts.reconcileExisting && expectedHeadRef) {
             const existing = await this.#openPullRequestByHead(repo, expectedHeadRef);
             if (existing) {
@@ -4678,7 +4843,17 @@ export class FactoryLoop {
         if (!tracked.sessionRef) {
             return;
         }
+        this.#logger.debug?.('[factory] tracked agent resume preparation started', {
+            issue: record.issue.key,
+            name,
+            role: tracked.spec.role,
+        });
         await this.#prepareAgentWorktree(record, tracked.spec);
+        this.#logger.debug?.('[factory] tracked agent resume spawn started', {
+            issue: record.issue.key,
+            name,
+            role: tracked.spec.role,
+        });
         const result = await this.#fleet.resume({
             name,
             sessionRef: tracked.sessionRef,
@@ -4687,6 +4862,12 @@ export class FactoryLoop {
             repo: tracked.spec.repo,
             clonePath: tracked.spec.clonePath,
         });
+        this.#logger.debug?.('[factory] tracked agent resume spawn completed', {
+            issue: record.issue.key,
+            name,
+            resumedName: result.name,
+            role: tracked.spec.role,
+        });
         tracked.result = {
             ...result,
             node: result.node ?? tracked.result?.node,
@@ -4695,35 +4876,156 @@ export class FactoryLoop {
         tracked.sessionRef = result.sessionRef ?? tracked.sessionRef;
         record.agents.delete(name);
         record.agents.set(result.name, tracked);
-        if (tracked.spec.role === 'babysitter') {
-            this.#babysitterCriticalAgents.delete(name);
-            const ownership = [...this.#babysitterPr.entries()].find(([, candidate]) => candidate.agentName === name);
-            const [ownershipKey, ref] = ownership ?? [];
-            if (ref) {
-                ref.agentName = result.name;
-                for (const [wakeKey, state] of this.#babysitterWakeStates) {
-                    if (state.agentName !== name)
-                        continue;
-                    if (state.timer)
-                        clearTimeout(state.timer);
-                    this.#babysitterWakeStates.delete(wakeKey);
-                    state.timer = undefined;
-                    state.agentName = result.name;
-                    state.tracked = tracked;
-                    if (state.deferredSubmitTargets) {
-                        state.deferredSubmitTargets = undefined;
-                        state.deliveringKinds = undefined;
-                        state.kinds.add('pull-request-state');
-                        await this.#recordPendingBabysitterWake(state);
+        await this.#retargetBabysitterAgent(record, name, tracked);
+        this.#logger.debug?.('[factory] tracked agent resume ownership retargeted', {
+            issue: record.issue.key,
+            name,
+            resumedName: result.name,
+            role: tracked.spec.role,
+        });
+        await this.#reportAgent(record, tracked, 'agent.resumed');
+    }
+    async #retargetBabysitterAgent(record, previousName, tracked) {
+        if (tracked.spec.role !== 'babysitter')
+            return;
+        const currentName = tracked.result?.name ?? tracked.spec.name;
+        this.#babysitterCriticalAgents.delete(previousName);
+        const ownership = [...this.#babysitterPr.entries()]
+            .find(([, candidate]) => candidate.agentName === previousName);
+        const [ownershipKey, ref] = ownership ?? [];
+        if (!ref)
+            return;
+        ref.agentName = currentName;
+        // Resuming a session commonly preserves its Relaycast name. Iterate a
+        // snapshot because deleting and re-inserting that same key while walking
+        // the live Map would append it to the iterator again indefinitely.
+        for (const [wakeKey, state] of [...this.#babysitterWakeStates]) {
+            if (state.agentName !== previousName)
+                continue;
+            if (state.timer)
+                clearTimeout(state.timer);
+            this.#babysitterWakeStates.delete(wakeKey);
+            state.timer = undefined;
+            state.agentName = currentName;
+            state.tracked = tracked;
+            if (state.deferredSubmitTargets) {
+                state.deferredSubmitTargets = undefined;
+                state.deliveringKinds = undefined;
+                state.kinds.add('pull-request-state');
+                await this.#recordPendingBabysitterWake(state);
+            }
+            this.#babysitterWakeStates.set(babysitterWakeKey(record.issue, ref), state);
+            if (state.kinds.size > 0)
+                this.#scheduleBabysitterWake(state, BABYSITTER_EVENT_COALESCE_MS);
+        }
+        await this.#persistBabysitterSession(record.issue, ref, tracked, ownershipKey);
+    }
+    async #recoverUnreachableBabysitter(state) {
+        const batch = await this.#batch();
+        const record = batch.getIssueByAgent(state.agentName);
+        const tracked = record?.agents.get(state.agentName);
+        if (!record || !tracked || tracked.spec.role !== 'babysitter')
+            return false;
+        if (!await this.#assertIssueDispatchLifecycleOwner(record.issue))
+            return false;
+        const previousName = state.agentName;
+        this.#fleet.markAgentTerminal?.(previousName, 'babysitter-unreachable');
+        try {
+            await this.#fleet.release(previousName, 'babysitter-unreachable');
+            this.#logger.debug?.('[factory] unreachable babysitter release completed', {
+                issue: record.issue.key,
+                babysitter: previousName,
+            });
+        }
+        catch (error) {
+            // An unresolvable Relaycast identity is frequently already absent from
+            // placement too. Release is best-effort; the fresh spawn below is the
+            // recovery operation that matters.
+            this.#increment('babysitterUnreachableReleaseFailures');
+            this.#logger.warn?.('[factory] unreachable babysitter release failed; attempting session recovery', {
+                issue: record.issue.key,
+                babysitter: previousName,
+                error: describeError(error).errorMessage,
+            });
+        }
+        try {
+            const configuredCapability = this.#config.agentCapabilities.babysitter;
+            const capabilityChanged = tracked.spec.capability !== configuredCapability;
+            if (tracked.sessionRef && !capabilityChanged) {
+                await this.#resumeTrackedAgent(record, previousName, tracked);
+            }
+            else {
+                const invocationId = `${batch.invocationIdFor(record.issue, tracked.spec)}:unreachable:${this.#clock.now()}`;
+                const { sessionRef: _staleSessionRef, ...persistedSpec } = tracked.spec;
+                const replacementSpec = capabilityChanged
+                    ? {
+                        ...persistedSpec,
+                        capability: configuredCapability,
+                        model: this.#config.models.babysitter,
                     }
-                    this.#babysitterWakeStates.set(babysitterWakeKey(record.issue, ref), state);
-                    if (state.kinds.size > 0)
-                        this.#scheduleBabysitterWake(state, BABYSITTER_EVENT_COALESCE_MS);
+                    : persistedSpec;
+                await this.#prepareAgentWorktree(record, replacementSpec);
+                const result = await this.#fleet.spawn({
+                    name: replacementSpec.name,
+                    capability: replacementSpec.capability,
+                    node: tracked.result?.node ?? replacementSpec.node ?? 'self',
+                    repo: replacementSpec.repo,
+                    task: replacementSpec.task,
+                    model: replacementSpec.model,
+                    cwd: replacementSpec.clonePath,
+                    invocationId,
+                    restartPolicy: defaultRestartPolicy(replacementSpec),
+                    channel: replacementSpec.channel,
+                });
+                batch.recordSpawn(record, replacementSpec, invocationId, result);
+                const restarted = record.agents.get(result.name);
+                if (!restarted)
+                    throw new Error(`Recovered babysitter ${result.name} was not tracked`);
+                await this.#retargetBabysitterAgent(record, previousName, restarted);
+                await this.#reportAgent(record, restarted, 'agent.resumed');
+                if (capabilityChanged) {
+                    this.#increment('babysitterCapabilityMigrations');
+                    this.#logger.info?.('[factory] cold-started unreachable babysitter on configured capability', {
+                        issue: record.issue.key,
+                        babysitter: result.name,
+                        previousCapability: tracked.spec.capability,
+                        capability: configuredCapability,
+                    });
                 }
-                await this.#persistBabysitterSession(record.issue, ref, tracked, ownershipKey);
             }
+            this.#logger.debug?.('[factory] unreachable babysitter replacement started', {
+                issue: record.issue.key,
+                previousBabysitter: previousName,
+                babysitter: state.agentName,
+            });
+            await this.#writeInFlightRegistry();
+            this.#logger.debug?.('[factory] unreachable babysitter registry refreshed', {
+                issue: record.issue.key,
+                babysitter: state.agentName,
+            });
+            if (!await this.#saveDispatchLifecycle(record, 'running'))
+                return false;
+            this.#increment('babysitterEventWakeUnreachableRecoveries');
+            this.#logger.info?.('[factory] restarted unreachable babysitter session', {
+                issue: record.issue.key,
+                repo: state.repo,
+                prNumber: state.prNumber,
+                previousBabysitter: previousName,
+                babysitter: state.agentName,
+            });
+            return true;
+        }
+        catch (error) {
+            this.#increment('babysitterEventWakeUnreachableRecoveryFailures');
+            this.#logger.warn?.('[factory] failed to restart unreachable babysitter session', {
+                issue: record.issue.key,
+                repo: state.repo,
+                prNumber: state.prNumber,
+                babysitter: previousName,
+                error: describeError(error).errorMessage,
+            });
+            return false;
         }
-        await this.#reportAgent(record, tracked, 'agent.resumed');
     }
     async #handleDeliveryFailed(info) {
         const critical = await this.#state.consumeCritical(this.#workspaceId, info.msgId ?? '');
@@ -6195,11 +6497,15 @@ export class FactoryLoop {
                 continue;
             }
             const record = batch.getIssue(session.issue);
-            const tracked = record?.agents.get(session.agentName)
-                ?? [...(record?.agents.values() ?? [])].find((agent) => agent.spec.role === 'babysitter' &&
+            const trackedEntry = record?.agents.has(session.agentName)
+                ? [session.agentName, record.agents.get(session.agentName)]
+                : [...(record?.agents.entries() ?? [])].find(([, agent]) => agent.spec.role === 'babysitter' &&
                     githubPrIdentity(agent.spec.ownedPullRequest?.repo ?? '', agent.spec.ownedPullRequest?.number ?? 0) ===
-                        githubPrIdentity(session.repo, session.prNumber))
+                        githubPrIdentity(session.repo, session.prNumber));
+            const tracked = trackedEntry?.[1]
                 ?? durableBabysitterTrackedAgent(session, this.#config.agentCapabilities.babysitter);
+            if (record && !trackedEntry)
+                record.agents.set(session.agentName, tracked);
             const ref = {
                 repo: session.repo,
                 prNumber: session.prNumber,
@@ -6223,6 +6529,74 @@ export class FactoryLoop {
             }
         }
     }
+    async #reconcileRestoredBabysitterReceipts(onlyRecord) {
+        const records = onlyRecord ? [onlyRecord] : (await this.#batch()).inFlight;
+        for (const record of records) {
+            if (!await this.#assertIssueDispatchLifecycleOwner(record.issue))
+                continue;
+            const lifecycle = await this.#state.getDispatchLifecycle(this.#workspaceId, issueKey(record.issue));
+            // Babysitter sessions are independently durable and restore only after
+            // their mounted PR metadata passes the open/draft/issue-identity guard.
+            // Fold those validated receipts back into the lifecycle on takeover.
+            // This closes the crash gap where the babysitter session persisted but
+            // the lifecycle PR receipt did not, and lets exact ownership retire any
+            // earlier weak-match babysitter for the same repository. The lifecycle's
+            // own exact receipts are authoritative independently of the session
+            // index: session restoration can legitimately be delayed or skipped
+            // while mounted PR metadata converges, but that must never preserve a
+            // superseded weak-match babysitter already disproved by publication.
+            const authoritative = new Map();
+            for (const receipt of lifecycle?.pullRequests ?? (lifecycle?.pullRequest ? [lifecycle.pullRequest] : [])) {
+                if (!receipt.repo || !validPrNumber(receipt.number) || !receipt.url || !receipt.headRef)
+                    continue;
+                const identity = githubPrIdentity(receipt.repo, receipt.number);
+                if (identity)
+                    authoritative.set(identity, { ...receipt });
+            }
+            const restored = [...this.#babysitterPr.entries()]
+                .filter(([ownershipKey, ref]) => ref.agentName && issueKey(this.#babysitterIssueRefs.get(ownershipKey) ?? record.issue) === issueKey(record.issue))
+                .map(([, ref]) => ref);
+            for (const receipt of restored) {
+                if (!receipt.repo || !validPrNumber(receipt.prNumber))
+                    continue;
+                const snapshot = await this.#readPrSnapshot(receipt);
+                const headRef = snapshot?.headRef ?? record.decision.implementers
+                    .find((implementer) => implementer.repo.toLowerCase() === receipt.repo.toLowerCase())?.branch;
+                if (!headRef)
+                    continue;
+                const identity = githubPrIdentity(receipt.repo, receipt.prNumber);
+                if (!identity)
+                    continue;
+                authoritative.set(identity, {
+                    repo: receipt.repo,
+                    number: receipt.prNumber,
+                    url: snapshot?.url ?? `https://github.com/${receipt.repo}/pull/${receipt.prNumber}`,
+                    headRef,
+                    ...(receipt.path ? { path: receipt.path } : {}),
+                });
+            }
+            if (authoritative.size > 0) {
+                this.#logger.debug?.('[factory] reconciling authoritative babysitter receipts', {
+                    issue: record.issue.key,
+                    lifecycleReceipts: lifecycle?.pullRequests?.map((receipt) => receipt.number) ?? [],
+                    restoredReceipts: restored.map((receipt) => receipt.prNumber),
+                    authoritativeReceipts: [...authoritative.values()].map((receipt) => receipt.number),
+                });
+                await this.#retireBabysittersOutsideCurrentRoutes(record);
+            }
+            for (const published of authoritative.values()) {
+                if (!await this.#saveDispatchLifecycle(record, 'running', published))
+                    return;
+                await this.#ensureBabysitter(record, {
+                    repo: published.repo,
+                    prNumber: published.number,
+                    url: published.url,
+                    path: published.path,
+                    authoritative: true,
+                });
+            }
+        }
+    }
     async #drainBabysitterWakesForStop() {
         for (const state of this.#babysitterWakeStates.values()) {
             state.cancelled = true;
@@ -6516,6 +6890,7 @@ export class FactoryLoop {
                 await this.#fleet.sendMessage(input);
                 state.unreachableSinceMs = undefined;
                 state.unreachableEscalated = false;
+                state.unreachableRecoveryAfterMs = undefined;
                 if (this.#stopping || state.cancelled) {
                     state.deliveringKinds = undefined;
                     return;
@@ -6531,6 +6906,7 @@ export class FactoryLoop {
                 // registration-lag backoff state accumulated by prior failures.
                 state.unreachableSinceMs = undefined;
                 state.unreachableEscalated = false;
+                state.unreachableRecoveryAfterMs = undefined;
                 targets = ack.targets.length > 0 ? [...new Set(ack.targets)] : [input.to];
             }
             if (this.#stopping || state.cancelled)
@@ -6586,23 +6962,23 @@ export class FactoryLoop {
                 // unreachable window so a later genuine registration lag starts fresh.
                 state.unreachableSinceMs = undefined;
                 state.unreachableEscalated = false;
+                state.unreachableRecoveryAfterMs = undefined;
             }
             const unreachableMs = state.unreachableSinceMs !== undefined
                 ? this.#clock.now() - state.unreachableSinceMs
                 : 0;
             if (registrationLag && unreachableMs >= this.#babysitterWakeUnreachableEscalateMs) {
                 // The agent is up but its relay identity never became resolvable. Stop
-                // the tight 1s loop: back off to a slow cadence (still eventually
-                // recovering if the agent finally enrolls) and flag it once so an
-                // operator can intervene (e.g. re-spawn / restart) instead of the
-                // failure spinning silently forever.
+                // the tight 1s loop, reconcile once, and restart the session. A recovery
+                // cooldown prevents a still-converging Relaycast registration from
+                // turning that restart into another tight loop.
                 state.nextDelayMs = this.#babysitterWakeUnreachableRetryMs;
                 if (!state.unreachableEscalated) {
                     state.unreachableEscalated = true;
                     await this.#fleet.reconcileTrackedAgents?.();
                     this.#increment('babysitterEventWakeUnreachableReconciliations');
                     this.#increment('babysitterEventWakeUnreachableEscalations');
-                    this.#logger.warn?.('[factory] babysitter unreachable past grace window; slowing wake retries and flagging for human attention', {
+                    this.#logger.warn?.('[factory] babysitter unreachable past grace window; reconciling and restarting its session', {
                         issue: state.issue.key,
                         repo: state.repo,
                         prNumber: state.prNumber,
@@ -6612,6 +6988,19 @@ export class FactoryLoop {
                         error: describeError(error).errorMessage,
                     });
                 }
+                if (state.unreachableRecoveryAfterMs === undefined ||
+                    this.#clock.now() >= state.unreachableRecoveryAfterMs) {
+                    state.unreachableRecoveryAfterMs = this.#clock.now() + this.#babysitterWakeUnreachableRetryMs;
+                    if (await this.#recoverUnreachableBabysitter(state)) {
+                        // Probe the newly registered identity promptly. If Relaycast still
+                        // cannot resolve it, the recovery cooldown above prevents another
+                        // teardown loop and the next attempt uses the slow cadence.
+                        state.nextDelayMs = BABYSITTER_EVENT_RETRY_MS;
+                    }
+                }
+                else {
+                    state.nextDelayMs = Math.max(BABYSITTER_EVENT_RETRY_MS, state.unreachableRecoveryAfterMs - this.#clock.now());
+                }
             }
             else {
                 state.nextDelayMs = BABYSITTER_EVENT_RETRY_MS;
@@ -6910,6 +7299,7 @@ export class FactoryLoop {
                         prNumber: receipt.number,
                         url: receipt.url,
                         headRef: receipt.headRef,
+                        authoritative: true,
                     });
                 }
                 return;
@@ -6931,6 +7321,9 @@ export class FactoryLoop {
             this.#increment('babysitterLifecycleOwnershipRejected');
             return;
         }
+        const replacedSuperseded = prRef.authoritative
+            ? await this.#retireSupersededBabysitters(record, prRef)
+            : false;
         this.#babysitterIssueRefs.set(babysitterKey, { ...record.issue });
         const existing = this.#babysitterPr.get(babysitterKey);
         if (existing && githubPrIdentity(existing.repo, existing.prNumber) !== githubPrIdentity(prRef.repo, prRef.prNumber)) {
@@ -6991,7 +7384,7 @@ export class FactoryLoop {
             const route = record.decision.routes.find((candidate) => candidate.repo === prRef.repo)
                 ?? record.decision.routes[0];
             const initialSpec = babysitterSpec(issue, this.#config, route);
-            if ([...this.#babysitterIssueRefs.entries()].some(([key, candidate]) => key !== babysitterKey && issueKey(candidate) === issueKey(record.issue))) {
+            if (replacedSuperseded || [...this.#babysitterIssueRefs.entries()].some(([key, candidate]) => key !== babysitterKey && issueKey(candidate) === issueKey(record.issue))) {
                 initialSpec.name = agentNameForRole(issue, 'babysit', {
                     repo: prRef.repo,
                     discriminator: `${sanitizeAgentSlug(prRef.repo)}-${prRef.prNumber}`,
@@ -7093,6 +7486,108 @@ export class FactoryLoop {
             }
         }
     }
+    async #retireSupersededBabysitters(record, prRef) {
+        const wanted = githubPrIdentity(prRef.repo, prRef.prNumber);
+        const lifecycle = await this.#state.getDispatchLifecycle(this.#workspaceId, issueKey(record.issue));
+        const trackedAgents = new Map([
+            ...(lifecycle?.agents ?? [])
+                .filter((agent) => agent.releasedAtMs === undefined)
+                .map((agent) => [agent.name, cloneTrackedAgent(agent.tracked)]),
+            ...record.agents,
+        ]);
+        const superseded = [...trackedAgents.entries()].filter(([, tracked]) => {
+            const owned = tracked.spec.ownedPullRequest;
+            return tracked.spec.role === 'babysitter' &&
+                owned?.repo.toLowerCase() === prRef.repo.toLowerCase() &&
+                githubPrIdentity(owned.repo, owned.number) !== wanted;
+        });
+        for (const [agentName, tracked] of superseded) {
+            const owned = tracked.spec.ownedPullRequest;
+            const failed = await this.#releaseAndTerminateAgents([[agentName, tracked]], 'superseded-pr-receipt', 'completion');
+            if (failed.length > 0) {
+                this.#increment('supersededBabysitterReleaseFailures');
+                throw new Error(`Failed to release superseded babysitter ${agentName}`);
+            }
+            if (owned) {
+                const staleKey = babysitterOwnershipKey(record.issue, {
+                    repo: owned.repo,
+                    prNumber: owned.number,
+                });
+                await this.#cancelBabysitterWake(staleKey);
+                if (await this.#assertIssueDispatchLifecycleOwner(record.issue)) {
+                    await this.#state.clearBabysitterSession(this.#workspaceId, staleKey);
+                }
+            }
+            record.agents.delete(agentName);
+            this.#babysitterCriticalAgents.delete(agentName);
+            this.#increment('supersededBabysittersReleased');
+            this.#logger.info?.('[factory] released babysitter superseded by exact PR receipt', {
+                issue: record.issue.key,
+                babysitter: agentName,
+                previousRepo: owned?.repo,
+                previousPrNumber: owned?.number,
+                repo: prRef.repo,
+                prNumber: prRef.prNumber,
+            });
+        }
+        if (superseded.length > 0) {
+            const latest = await this.#state.getDispatchLifecycle(this.#workspaceId, issueKey(record.issue));
+            if (latest && !await this.#saveDispatchLifecycle(record, latest.phase)) {
+                throw new Error(`Failed to persist superseded babysitter cleanup for ${record.issue.key}`);
+            }
+        }
+        return superseded.length > 0;
+    }
+    async #retireBabysittersOutsideCurrentRoutes(record) {
+        const wantedRepos = new Set(record.decision.implementers.map((implementer) => implementer.repo.toLowerCase()));
+        const lifecycle = await this.#state.getDispatchLifecycle(this.#workspaceId, issueKey(record.issue));
+        const trackedAgents = new Map([
+            ...(lifecycle?.agents ?? [])
+                .filter((agent) => agent.releasedAtMs === undefined)
+                .map((agent) => [agent.name, cloneTrackedAgent(agent.tracked)]),
+            ...record.agents,
+        ]);
+        const unrouted = [...trackedAgents.entries()].filter(([, tracked]) => {
+            const owned = tracked.spec.ownedPullRequest;
+            return tracked.spec.role === 'babysitter' &&
+                Boolean(owned) &&
+                !wantedRepos.has(owned.repo.toLowerCase());
+        });
+        for (const [agentName, tracked] of unrouted) {
+            const owned = tracked.spec.ownedPullRequest;
+            const failed = await this.#releaseAndTerminateAgents([[agentName, tracked]], 'superseded-pr-route', 'completion');
+            if (failed.length > 0) {
+                this.#increment('supersededBabysitterReleaseFailures');
+                throw new Error(`Failed to release unrouted babysitter ${agentName}`);
+            }
+            if (owned) {
+                const staleKey = babysitterOwnershipKey(record.issue, {
+                    repo: owned.repo,
+                    prNumber: owned.number,
+                });
+                await this.#cancelBabysitterWake(staleKey);
+                if (await this.#assertIssueDispatchLifecycleOwner(record.issue)) {
+                    await this.#state.clearBabysitterSession(this.#workspaceId, staleKey);
+                }
+            }
+            record.agents.delete(agentName);
+            this.#babysitterCriticalAgents.delete(agentName);
+            this.#increment('supersededBabysittersReleased');
+            this.#logger.info?.('[factory] released babysitter outside the current dispatch routes', {
+                issue: record.issue.key,
+                babysitter: agentName,
+                previousRepo: owned?.repo,
+                previousPrNumber: owned?.number,
+                currentRepos: [...wantedRepos],
+            });
+        }
+        if (unrouted.length > 0) {
+            const latest = await this.#state.getDispatchLifecycle(this.#workspaceId, issueKey(record.issue));
+            if (latest && !await this.#saveDispatchLifecycle(record, latest.phase)) {
+                throw new Error(`Failed to persist unrouted babysitter cleanup for ${record.issue.key}`);
+            }
+        }
+    }
     // The babysitter owns the readiness verdict (CI green + conflicts resolved +
     // review comments addressed) — it sees the per-event PR webhook data in its
     // sandbox, exactly like AgentWorkforce/agents review. It signals readiness by
@@ -10947,6 +11442,12 @@ const mergePublishedPullRequests = (lifecycle, receipt) => {
             { ...candidate },
         ])).values()];
 };
+const primaryPublishedPullRequest = (previous, receipt, receipts) => {
+    if (receipt &&
+        (!previous?.pullRequest || previous.pullRequest.repo.toLowerCase() === receipt.repo.toLowerCase()))
+        return receipt;
+    return previous?.pullRequest ?? receipt ?? receipts[0];
+};
 const lifecycleFromInFlightRecord = (record, runId, phase, updatedAtMs, pullRequest, pullRequests = [], releaseReason) => ({
     runId,
     issue: { ...record.issue },