@agent-relay/factory 0.1.62 → 0.1.63

package/dist/orchestrator/factory.js

@@ -5,6 +5,7 @@ import { FactoryConfigSchema } from '../config/schema.js';
 import { linearByStatePath, linearByIdPath, linearByUuidPath } from '../constants/linear.js';
 import { stateResolutionFromIds } from '../linear/state-resolver.js';
 import { GithubMergeGate, closeProbePr } from '../github/index.js';
+import { factoryGithubIssueCommentDraftName, isFactoryGithubIssueCommentDraftName, isFactoryGithubOperationDraftName, } from '../github/writeback-paths.js';
 import { VerificationPipeline } from '../environments/verification-pipeline.js';
 import { factoryWorktreeIssueSlug, factoryWorktreePath } from '../git/agent-worktree.js';
 import { InMemoryStateStore } from '../state/in-memory-state-store.js';
@@ -12,13 +13,14 @@ import { containsExplicitIssueReference, containsIssueKey, factoryBranchBelongsT
 import { normalizeLogger, normalizeLogValue, setSafeErrorStack, stringifyLogValue } from '../logging.js';
 import { isInFactoryScope } from '../safety/factory-scope.js';
 import { dispatchRelayflowForChangeEvent } from '../dispatch/relayflow-registry.js';
+import { dispatchAgentIdentityKey } from '../dispatch/work-unit-identity.js';
 import { deriveDescriptorsFromMount, prescriptiveInstructions, } from '@agent-relay/integration-prompts';
 import { parseGithubHumanInputRequest, renderAgentTask, } from '../dispatch/templates.js';
 import { resolveTestGuidance } from '../dispatch/test-guidance.js';
-import { HeuristicTriage, TieredTriage, babysitterSpec, isShapeLabel, scopeFromLabels } from '../triage/index.js';
+import { HeuristicTriage, TieredTriage, babysitterSpec, isShapeLabel, scopeFromLabels, swarmChannel, swarmMemberSlugs, swarmTaskFor } from '../triage/index.js';
 import { agentNameForRole, sanitizeAgentSlug } from '../triage/agent-names.js';
 import { isResourceSubscriptionsUnavailable } from '../subscriptions/index.js';
-import { GhCliGithubWriteback, MountGithubRead, MountLinearWriteback, MountSlackWriteback, slackChannelAliases, slackChannelSegment } from '../writeback/index.js';
+import { AppGithubWriteback, FACTORY_GITHUB_STATUS_LABELS, GhCliGithubWriteback, MountGithubRead, MountLinearWriteback, MountSlackWriteback, slackChannelAliases, slackChannelSegment } from '../writeback/index.js';
 import { parseSlackThreadReply, slackThreadReplyGlob } from '../subscriptions/slack-filter.js';
 import { asRecord, parseJsonContent, stableHash, wrappedPayload } from '../writeback/shared.js';
 import { issueKey, } from './batch-tracker.js';
@@ -29,6 +31,7 @@ import { readFactoryInFlightRegistry, terminatePids } from './reaper.js';
 import { createFactoryCloudEventV1, factoryCloudReleaseReasonV1, } from '../observability/events.js';
 import { boundedRunCostTotal, CostLedger } from '../cost/ledger.js';
 import { createTicketDispatchDelivery } from '../delivery/ticket-dispatch.js';
+import { FleetControlPlaneCircuit, FleetControlPlaneCircuitOpenError, guardFleetControlPlane, } from '../fleet/control-plane-circuit.js';
 class ClarificationWakeLeaseLostError extends Error {
 }
 class ClarificationQuestionDeliveryLeaseLostError extends Error {
@@ -224,6 +227,7 @@ export class FactoryLoop {
     #mount;
     #states;
     #fleet;
+    #fleetControlPlane;
     #ticketDispatchDelivery;
     #triage;
     #linear;
@@ -452,7 +456,6 @@ export class FactoryLoop {
         // synced records (state.name but no state.id) without the states catalog.
         this.#states = ports.stateResolution ?? stateResolutionFromIds(config.stateIds, config.linear.states);
         installFactoryDraftPredicate(this.#mount, config);
-        this.#fleet = ports.fleet;
         this.#ticketDispatchDelivery = ports.ticketDispatchDelivery ?? createTicketDispatchDelivery({
             mountRoot: config.localMountRoot,
         });
@@ -461,7 +464,7 @@ export class FactoryLoop {
             safety: config.safety,
         });
         this.#githubWritebackProvided = Boolean(ports.githubWriteback);
-        this.#githubWriteback = ports.githubWriteback ?? new GhCliGithubWriteback();
+        this.#githubWriteback = ports.githubWriteback ?? defaultGithubWriteback(config, ports.mount);
         this.#slack = config.slack ? MountSlackWriteback(ports.mount, config.slack) : ports.slack;
         this.#github = ports.github ?? MountGithubRead(ports.mount);
         this.#mergeGate = ports.mergeGate ?? new GithubMergeGate();
@@ -483,6 +486,13 @@ export class FactoryLoop {
         this.#probePrResolver = ports.probePrResolver ?? ((issue) => this.#resolveIssuePr(issue));
         this.#logger = normalizeLogger(ports.logger ?? console);
         this.#clock = ports.clock ?? realClock;
+        this.#fleetControlPlane = new FleetControlPlaneCircuit({
+            timeoutMs: config.fleetHealth.rosterTimeoutMs,
+            failureThreshold: config.fleetHealth.failureThreshold,
+            resetTimeoutMs: config.fleetHealth.resetTimeoutMs,
+            now: () => this.#clock.now(),
+        });
+        this.#fleet = guardFleetControlPlane(ports.fleet, this.#fleetControlPlane);
         this.#processIdentityReader = ports.processIdentityReader ?? readProcessIdentity;
         this.#processFinder = ports.processFinder ?? ((agentName, opts) => findAgentProcessByName(agentName, {
             readProcessIdentity: this.#processIdentityReader,
@@ -590,11 +600,32 @@ export class FactoryLoop {
         this.#batchView = batch;
         return batch;
     }
+    /**
+     * Resolves once this issue's durable dispatch row reaches a terminal phase,
+     * and reports which one. A caller that turns the run into an exit code needs
+     * the phase: a dispatch that hit capacity returns an empty hold result and
+     * schedules a durable retry, so the pre-wait result says nothing about how
+     * the run actually ended.
+     *
+     * `undefined` means no terminal phase was observed — there was no lifecycle
+     * row to wait on, or the wait ended because Factory is stopping.
+     */
     async waitForDispatchTerminal(issue) {
         const key = issueKey(issue);
         const lifecycle = await this.#state.getDispatchLifecycle(this.#workspaceId, key);
-        if (lifecycle && isTerminalDispatchLifecycle(lifecycle))
-            return;
+        // No durable row means this dispatch never claimed a lifecycle: a
+        // dependency park, a triage escalation, and a label refusal all return
+        // before the claim. Nothing can ever become terminal, so polling would
+        // never stop and the caller would never produce an exit code at all.
+        if (!lifecycle)
+            return undefined;
+        if (isTerminalDispatchLifecycle(lifecycle))
+            return lifecycle.phase;
+        // Capture the phase at the moment this waiter observes it. The waiters are
+        // shared across callers of one row and carry no payload, so a re-read after
+        // the fact can race lifecycle cleanup or a reopened dispatch for the same
+        // issue and report a different run — or none.
+        let observedPhase;
         await new Promise((resolve) => {
             let settled = false;
             let timer;
@@ -603,10 +634,11 @@ export class FactoryLoop {
                 waiters = new Set();
                 this.#dispatchTerminalWaiters.set(key, waiters);
             }
-            const finish = () => {
+            const finish = (phase) => {
                 if (settled)
                     return;
                 settled = true;
+                observedPhase = phase;
                 if (timer)
                     clearTimeout(timer);
                 const current = this.#dispatchTerminalWaiters.get(key);
@@ -629,7 +661,7 @@ export class FactoryLoop {
                 try {
                     const latest = await this.#state.getDispatchLifecycle(this.#workspaceId, key);
                     if (latest && isTerminalDispatchLifecycle(latest)) {
-                        this.#resolveDispatchTerminalWaiters(issue);
+                        this.#resolveDispatchTerminalWaiters(issue, latest.phase);
                         return;
                     }
                     if (latest?.phase === 'waiting-for-human' && this.#startMode === 'dispatch-owner') {
@@ -659,6 +691,10 @@ export class FactoryLoop {
             };
             void poll();
         });
+        // `observedPhase` is whatever resolved THIS waiter. It stays undefined only
+        // when the wait ended without a terminal resolution at all — Factory is
+        // stopping — which is exactly what `undefined` reports.
+        return observedPhase;
     }
     async start(opts = {}) {
         if (this.#started) {
@@ -1831,8 +1867,30 @@ export class FactoryLoop {
             }
         }
     }
+    async #assertFleetControlPlaneAvailable() {
+        try {
+            await this.#fleet.roster();
+            this.#increment('fleetControlPlaneProbeSuccesses');
+        }
+        catch (error) {
+            const health = this.#fleetControlPlane.status();
+            this.#increment('fleetControlPlaneProbeFailures');
+            if (health.state === 'open')
+                this.#increment('fleetControlPlaneCircuitOpen');
+            this.#logger.error?.('[factory] fleet control plane unavailable; dispatch paused', {
+                state: health.state,
+                consecutiveFailures: health.consecutiveFailures,
+                retryAtMs: health.retryAtMs,
+                error: health.lastError ?? 'unknown control-plane failure',
+            });
+            throw contextualError('Factory dispatch paused because the fleet control plane is unavailable', error);
+        }
+    }
     async #runOnceWithDiscoveryFence(opts) {
         const sweepStartedAtMs = this.#clock.now();
+        if (!(opts.dryRun ?? this.#config.dryRun)) {
+            await this.#assertFleetControlPlaneAvailable();
+        }
         let claim = await this.#state.claimDiscoverySweep(this.#workspaceId, this.#discoverySweepOwner, this.#clock.now(), DISCOVERY_SWEEP_LEASE_MS);
         if (!claim.acquired && claim.reason === 'backoff') {
             const delayMs = Math.max(0, claim.state.backoffUntilMs - this.#clock.now());
@@ -2699,7 +2757,7 @@ export class FactoryLoop {
             await this.#state.clearBabysitterSession(this.#workspaceId, issueKey(lifecycle.issue));
             this.#dispatchLifecycleEpochs.delete(key);
             this.#abandonedDispatchReasons.delete(key);
-            this.#resolveDispatchTerminalWaiters(lifecycle.issue);
+            this.#resolveDispatchTerminalWaiters(lifecycle.issue, 'abandoned');
             await this.#writeInFlightRegistry().catch((error) => {
                 this.#logger.warn?.('[factory] failed to rewrite registry after orphaned claim release', {
                     issue: issue.key,
@@ -3054,6 +3112,16 @@ export class FactoryLoop {
                     reports.push(failedIterationReport(error, opts.dryRun ?? this.#config.dryRun));
                     await this.#reapDispatchFailureHandoffsNow(heartbeatPath, registryPath);
                     await this.#writeLoopHeartbeat(heartbeatPath, registryPath, 'running', iteration + 1, maxIterations);
+                    const fleetControlPlane = this.#fleetControlPlane.status();
+                    if (fleetControlPlane.state !== 'closed') {
+                        this.#increment('loopCircuitBreaks');
+                        this.#logger.error?.('[factory] stopping loop because dispatch is paused by the fleet control-plane circuit', {
+                            state: fleetControlPlane.state,
+                            consecutiveFailures: fleetControlPlane.consecutiveFailures,
+                            retryAtMs: fleetControlPlane.retryAtMs,
+                        });
+                        throw new FleetControlPlaneCircuitOpenError(fleetControlPlane.retryAtMs ?? this.#clock.now(), fleetControlPlane.state);
+                    }
                     if (consecutiveFailures >= maxConsecutiveFailures) {
                         this.#increment('loopCircuitBreaks');
                         this.#logger.error?.('[factory] stopping loop after consecutive iteration failures', {
@@ -3209,6 +3277,13 @@ export class FactoryLoop {
             };
         }
         this.#clearDependencyPark(batch, dispatchDecision.issue);
+        // Event-driven and direct dispatches do not necessarily pass through issue
+        // discovery. Admit them before creating previews, claiming a lifecycle, or
+        // 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 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
@@ -3512,6 +3587,7 @@ export class FactoryLoop {
                 capacityBlocked: parked.capacityBlocked,
             })) ?? [],
             counters: { ...this.#counters },
+            fleetControlPlane: this.#fleetControlPlane.status(),
             slackDegraded: this.#slackDegraded,
             slackDegradedReason: this.#slackDegradedReason,
             eventListener: this.#eventListenerStatus(),
@@ -4415,12 +4491,25 @@ export class FactoryLoop {
             }
             for (const agent of lifecycle.agents) {
                 const previousAgent = previous?.agents.find((candidate) => candidate.name === agent.name);
-                if (previousAgent?.releasedAtMs !== undefined)
-                    agent.releasedAtMs = previousAgent.releasedAtMs;
+                // The in-flight record is authoritative for release state: the stamp
+                // now lives on the tracked agent and round-trips through the lifecycle,
+                // so a still-released agent brings its own stamp here. Inheriting the
+                // previous row's stamp instead would refile a respawned worker as
+                // released — a respawn reuses both the agent name and the deterministic
+                // invocation id, so neither can tell the generations apart — and every
+                // consumer that filters on `releasedAtMs` would then treat a live
+                // worker as gone.
                 if (previousAgent?.costUsage)
                     agent.costUsage = structuredClone(previousAgent.costUsage);
-                if (releasedAgentNames.has(agent.name))
-                    agent.releasedAtMs ??= this.#clock.now();
+                if (releasedAgentNames.has(agent.name)) {
+                    const releasedAtMs = agent.releasedAtMs ?? this.#clock.now();
+                    agent.releasedAtMs = releasedAtMs;
+                    // Keep the record the single source of the stamp, so the next save
+                    // carries it without having to read it back off the durable row.
+                    const tracked = record.agents.get(agent.name);
+                    if (tracked)
+                        tracked.releasedAtMs ??= releasedAtMs;
+                }
             }
             const saved = await this.#state.saveDispatchLifecycle(this.#workspaceId, key, this.#dispatchLifecycleOwner, epoch, this.#clock.now(), lifecycle);
             if (!saved) {
@@ -4448,10 +4537,14 @@ export class FactoryLoop {
             return true;
         });
     }
-    #resolveDispatchTerminalWaiters(issue) {
+    // Every caller of this knows the phase the row settled in, and each waiter
+    // must be handed it directly. A waiter that instead re-read the shared row
+    // after release could see it cleared, or see the next dispatch for the same
+    // issue, and classify the wrong run.
+    #resolveDispatchTerminalWaiters(issue, phase) {
         const key = issueKey(issue);
         for (const resolve of this.#dispatchTerminalWaiters.get(key) ?? [])
-            resolve();
+            resolve(phase);
         this.#dispatchTerminalWaiters.delete(key);
     }
     #scheduleDispatchLifecycleRetry(record) {
@@ -4538,7 +4631,7 @@ export class FactoryLoop {
         if (!lifecycle)
             return;
         if (isTerminalDispatchLifecycle(lifecycle)) {
-            this.#resolveDispatchTerminalWaiters(lifecycle.issue);
+            this.#resolveDispatchTerminalWaiters(lifecycle.issue, lifecycle.phase);
             return;
         }
         if (lifecycle.phase === 'waiting-for-human')
@@ -4919,7 +5012,7 @@ export class FactoryLoop {
         await this.#stopGithubIssueCommentWatcherForIssue(record.issue);
         await this.#writeInFlightRegistry();
         this.#increment('dispatchLifecycleStaleIssuesAbandoned');
-        this.#resolveDispatchTerminalWaiters(record.issue);
+        this.#resolveDispatchTerminalWaiters(record.issue, 'abandoned');
         this.#logger.info?.('[factory] abandoned durable dispatch whose live issue is no longer ready', {
             issue: record.issue.key,
             reason,
@@ -4995,7 +5088,7 @@ export class FactoryLoop {
         this.#increment(releaseReason === 'issue-human-review' ? 'humanReview' : 'done');
         this.#emit('issue-done', { issue: record.issue });
         await this.#writeInFlightRegistry();
-        this.#resolveDispatchTerminalWaiters(record.issue);
+        this.#resolveDispatchTerminalWaiters(record.issue, 'complete');
         return true;
     }
     async #assertDispatchLifecycleOwner(record) {
@@ -6019,6 +6112,7 @@ export class FactoryLoop {
             registryPath,
             eventListener: this.#eventListenerStatus(),
             readinessReconcile: this.#readinessReconcileStatus(),
+            fleetControlPlane: this.#fleetControlPlane.status(),
         };
         await mkdir(dirname(path), { recursive: true });
         await writeFile(path, `${JSON.stringify(heartbeat, null, 2)}\n`, 'utf8');
@@ -6277,6 +6371,22 @@ export class FactoryLoop {
             }
             try {
                 await this.#fleet.release(agentName, reason);
+                // Invalidate the spawn memory the moment the release is confirmed, so a
+                // retry for the same deterministic invocation spawns a real worker
+                // instead of inheriting this one's claim. Shutdown is excluded on
+                // purpose: nothing is being retried there, and a takeover must still be
+                // free to adopt agents this process merely stopped supervising.
+                if (record && batch && context !== 'stop') {
+                    const releasedInvocationId = batch.recordRelease(record, agentName, this.#clock.now());
+                    if (releasedInvocationId) {
+                        this.#logger.debug?.('[factory] released agent invocation is no longer dispatchable', {
+                            issue: record.issue.key,
+                            agentName,
+                            reason,
+                            invocationId: releasedInvocationId,
+                        });
+                    }
+                }
                 if (record)
                     await this.#reportAgent(record, tracked, 'agent.released', { releaseReason: reason });
             }
@@ -6506,7 +6616,10 @@ export class FactoryLoop {
         const batch = await this.#batch();
         const invocationId = batch.invocationIdFor(record.issue, spec);
         const existing = record.agents.get(spec.name);
-        if (existing?.result) {
+        // A released placement keeps its bookkeeping entry, but it is not a worker.
+        // Answering with its old spawn result here would report a synthetic success
+        // for a process that no longer exists.
+        if (existing?.result && existing.releasedAtMs === undefined) {
             this.#scheduleHeldAgentDeadline(record);
             return { name: existing.result?.name ?? spec.name };
         }
@@ -6556,6 +6669,7 @@ export class FactoryLoop {
             result = await this.#fleet.spawn({
                 name: spec.name,
                 capability: spec.capability,
+                identityKey: dispatchAgentIdentityKey(record.issue, spec.role),
                 node: spec.node ?? 'self',
                 repo: spec.repo,
                 task: spec.task,
@@ -6657,6 +6771,16 @@ export class FactoryLoop {
                 return;
             }
         }
+        // Swarm workers share the lead's checkout and lifecycle branch. If a worker
+        // exit reached the publication/completion paths below, whichever worker
+        // finished first would publish whatever partial state was on the shared
+        // branch and mark every swarm member "done" via the shared-branch PR probe,
+        // releasing the still-working lead. The lead alone is authoritative for
+        // publication and completion in a swarm.
+        if (exiting?.spec.swarmRole === 'worker') {
+            this.#increment('swarmWorkerExitsSuppressed');
+            return;
+        }
         if (isCompletionReason(reason)) {
             if (exiting?.spec.role === 'implementer' && await this.#issueHasCompletionPr(record, {
                 openOnly: this.#config.babysitter.enabled,
@@ -6901,6 +7025,7 @@ export class FactoryLoop {
                     const result = await this.#fleet.spawn({
                         name: tracked.spec.name,
                         capability: tracked.spec.capability,
+                        identityKey: dispatchAgentIdentityKey(record.issue, tracked.spec.role),
                         node: tracked.result?.node ?? tracked.spec.node ?? 'self',
                         repo: tracked.spec.repo,
                         task: tracked.spec.task,
@@ -7782,6 +7907,7 @@ export class FactoryLoop {
         const result = await this.#fleet.resume({
             name,
             sessionRef: tracked.sessionRef,
+            identityKey: dispatchAgentIdentityKey(record.issue, tracked.spec.role),
             node: tracked.result?.node ?? tracked.spec.node ?? 'self',
             capability: tracked.spec.capability,
             repo: tracked.spec.repo,
@@ -7910,6 +8036,7 @@ export class FactoryLoop {
                 const result = await this.#fleet.spawn({
                     name: replacementSpec.name,
                     capability: replacementSpec.capability,
+                    identityKey: dispatchAgentIdentityKey(record.issue, replacementSpec.role),
                     node: tracked.result?.node ?? replacementSpec.node ?? 'self',
                     repo: replacementSpec.repo,
                     task: replacementSpec.task,
@@ -9377,6 +9504,15 @@ export class FactoryLoop {
                         previewStartCommand: spec.preview?.startCommand,
                     } : {}),
                     ...(this.#fleet.lifecycleActionName ? { lifecycleActionName: this.#fleet.lifecycleActionName } : {}),
+                    ...(spec.swarmRole && spec.channel ? {
+                        swarm: {
+                            role: spec.swarmRole,
+                            channel: spec.channel,
+                            otherMemberNames: decision.implementers
+                                .filter((implementer) => implementer.channel === spec.channel && implementer.name !== spec.name)
+                                .map((implementer) => implementer.name),
+                        },
+                    } : {}),
                 }),
             };
         };
@@ -10897,7 +11033,7 @@ export class FactoryLoop {
             });
             return;
         }
-        const issue = await this.#findMergeAdvanceIssueForPr(snapshot);
+        const issue = await this.#findMergeAdvanceIssueForPr(snapshot, repo);
         if (!issue) {
             this.#increment('mergedPrAdvanceNoIssue');
             return;
@@ -10952,7 +11088,7 @@ export class FactoryLoop {
             this.#error(error, issueRef(issue));
         }
     }
-    async #findMergeAdvanceIssueForPr(snapshot) {
+    async #findMergeAdvanceIssueForPr(snapshot, eventRepo) {
         // An issue is "upstream" of a merge if it sits in the agent-implementing or
         // human-review role for its team. UUIDs are globally unique, so the reverse
         // role lookup covers every team without per-team scoping here.
@@ -10961,16 +11097,34 @@ export class FactoryLoop {
             return role === 'agentImplementing' || role === 'humanReview';
         };
         let best;
+        let ambiguous = false;
         const scanStartedAtMs = this.#clock.now();
         // This no-record path runs after agents are released, so there is no
         // tracked PR identity left. Keep the scan simple and prefer branch identity
         // over title/body references to avoid "related to AR-N" body false positives.
         const githubSource = await this.#issueSource() === 'github';
+        // A GitHub-native issue key is a bare number; the same number exists
+        // independently in every configured repository. Only a same-repo candidate
+        // may complete the merge, so a merged PR in one repo can never close an
+        // unrelated issue that happens to share its number in another. #276.
+        const eventRepoKey = validGithubRepo(eventRepo) ? eventRepo.toLowerCase() : undefined;
+        if (githubSource && !eventRepoKey) {
+            this.#logger.warn?.('[factory] merge advance skipped: event repo is not identifiable', {
+                prNumber: snapshot.number,
+            });
+            return undefined;
+        }
         const paths = githubSource ? await this.#githubIssuePaths() : await this.#listRelayfileTree(ISSUE_ROOT, 'merge advance issue scan');
         for (const path of paths) {
             if (githubSource ? !isGithubIssueFilePath(path) : !isIssueFilePath(path)) {
                 continue;
             }
+            if (githubSource) {
+                const issueParts = githubIssuePathParts(path);
+                if (!issueParts || `${issueParts.owner}/${issueParts.repo}`.toLowerCase() !== eventRepoKey) {
+                    continue;
+                }
+            }
             const issue = await this.#readIssue(path);
             if (!issue || (githubSource
                 ? issue.state?.name?.trim().toLowerCase() === 'closed'
@@ -10983,10 +11137,27 @@ export class FactoryLoop {
             const score = prSnapshotIssueMatchScore(snapshot, issue.key);
             if (score > 0 && (!best || score > best.score)) {
                 best = { issue, score };
+                ambiguous = false;
             }
+            else if (score > 0 && best && score === best.score) {
+                ambiguous = true;
+            }
+        }
+        // Fail-closed on a tie. A silent first-wins on unrelated same-score
+        // candidates is the exact class of quiet corruption we are removing.
+        if (ambiguous) {
+            this.#increment('mergedPrAdvanceAmbiguous');
+            this.#logger.warn?.('[factory] merge advance skipped: multiple candidates tied on match score', {
+                prNumber: snapshot.number,
+                eventRepo,
+                matchedIssue: best?.issue.key,
+                matchScore: best?.score,
+            });
+            return undefined;
         }
         this.#logger.debug?.(`[factory] scanned ${githubSource ? 'GitHub' : 'Linear'} issues for merged PR advance`, {
             prNumber: snapshot.number,
+            eventRepo,
             durationMs: this.#clock.now() - scanStartedAtMs,
             matchedIssue: best?.issue.key,
             matchScore: best?.score,
@@ -12157,6 +12328,7 @@ export class FactoryLoop {
                 const rebound = await this.#state.rebindConversationSession(this.#workspaceId, conversationId, {
                     name: agentName,
                     sessionRef,
+                    role: owned.tracked.spec.role,
                     node: owned.tracked.result?.node ?? owned.tracked.spec.node,
                     capability: owned.tracked.spec.capability,
                     repo: owned.tracked.spec.repo,
@@ -12189,6 +12361,7 @@ export class FactoryLoop {
             agent: {
                 name: agentName,
                 sessionRef,
+                role: owned.tracked.spec.role,
                 node: owned.tracked.result?.node ?? owned.tracked.spec.node,
                 capability: owned.tracked.spec.capability,
                 repo: owned.tracked.spec.repo,
@@ -12252,9 +12425,20 @@ export class FactoryLoop {
         }, Math.max(1_000, Math.floor(SLACK_CONVERSATION_TURN_LEASE_MS / 3)));
         heartbeat.unref?.();
         try {
+            // Sessions bound after this field was introduced carry their role
+            // durably, so resume never depends on a live lookup by the agent's
+            // current name — which a since-completed rename (e.g. babysitter
+            // retarget) can otherwise leave unresolvable forever. Older
+            // already-persisted sessions fall back to the live lookup.
+            const conversationRole = claimed.agent.role
+                ?? (await this.#batch()).getIssueByAgent(claimed.agent.name)?.agents.get(claimed.agent.name)?.spec.role;
+            if (!conversationRole) {
+                throw new Error(`Cannot resume ${claimed.agent.name}: its dispatch role is unavailable for identity proof`);
+            }
             const result = await this.#fleet.resume({
                 name: claimed.agent.name,
                 sessionRef: claimed.agent.sessionRef,
+                identityKey: dispatchAgentIdentityKey(claimed.issue, conversationRole),
                 node: claimed.agent.node ?? 'self',
                 capability: claimed.agent.capability,
                 repo: claimed.agent.repo,
@@ -13414,6 +13598,7 @@ export class FactoryLoop {
                 const resumed = await this.#fleet.resume({
                     name,
                     sessionRef: tracked.sessionRef,
+                    identityKey: dispatchAgentIdentityKey(waiting.issue, tracked.spec.role),
                     node: tracked.result?.node ?? tracked.spec.node ?? 'self',
                     capability: tracked.spec.capability,
                     repo: tracked.spec.repo,
@@ -13444,6 +13629,7 @@ export class FactoryLoop {
         return await this.#fleet.spawn({
             name,
             capability: tracked.spec.capability,
+            identityKey: dispatchAgentIdentityKey(waiting.issue, tracked.spec.role),
             node: tracked.result?.node ?? tracked.spec.node ?? 'self',
             task,
             workflow: tracked.spec.workflow,
@@ -13757,6 +13943,15 @@ export class FactoryLoop {
         return hasTitlePrefix(issue.title, FACTORY_E2E_MARKER);
     }
 }
+const defaultGithubWriteback = (config, mount) => {
+    if (config.github.identity !== 'app') {
+        return new GhCliGithubWriteback();
+    }
+    if (!mount.githubWrite) {
+        throw new Error('GitHub identity "app" requires a connected workspace GitHub App lifecycle write path; refusing to fall back to the local gh user');
+    }
+    return new AppGithubWriteback(mount.githubWrite);
+};
 export function parseLinearIssue(path, content) {
     const parsed = parseJsonContent(content);
     const payload = wrappedPayload(parsed);
@@ -14352,13 +14547,19 @@ function labelDerivedDispatchDecision(liveIssue, decision, config) {
             maxImplementers,
         };
     }
-    const implementers = routesByLabel.routes.map(({ slug, route }) => routeImplementerSpec(liveIssue, config, slug, route));
-    const selectedRoutes = scope === 'single' ? routesByLabel.routes.slice(0, 1) : routesByLabel.routes;
+    // Swarm always shares one checkout (lead + workers collaborate live over a
+    // shared relay channel), so — like single/workflow — only the first matched
+    // label route is used; it is never fanned out across repo labels like team.
+    const selectedRoutes = scope === 'single' || scope === 'swarm'
+        ? routesByLabel.routes.slice(0, 1)
+        : routesByLabel.routes;
     const selectedImplementers = scope === 'team'
-        ? implementers
+        ? routesByLabel.routes.map(({ slug, route }) => routeImplementerSpec(liveIssue, config, slug, route))
         : scope === 'single'
-            ? implementers.slice(0, 1)
-            : [];
+            ? routesByLabel.routes.slice(0, 1).map(({ slug, route }) => routeImplementerSpec(liveIssue, config, slug, route))
+            : scope === 'swarm'
+                ? routeSwarmImplementerSpecs(liveIssue, config, selectedRoutes[0]?.route, maxImplementers)
+                : [];
     const routes = selectedRoutes.map(({ route }) => route);
     const workflow = scope === 'workflow'
         ? routeWorkflowSpec(liveIssue, config, selectedRoutes, decision.workflow)
@@ -14487,6 +14688,24 @@ function routeImplementerSpec(issue, config, slug, route) {
         node: 'self',
     };
 }
+function routeSwarmImplementerSpecs(issue, config, route, maxImplementers) {
+    if (!route) {
+        return [];
+    }
+    const channel = swarmChannel(issue);
+    return swarmMemberSlugs(maxImplementers).map((slug) => ({
+        name: agentNameForRole(issue, 'impl', { repo: route.repo, discriminator: slug }),
+        role: 'implementer',
+        capability: config.agentCapabilities.implementer,
+        model: config.models.implementer,
+        task: swarmTaskFor(issue, route, slug, channel),
+        repo: route.repo,
+        clonePath: route.clonePath,
+        channel,
+        swarmRole: slug === 'lead' ? 'lead' : 'worker',
+        node: 'self',
+    }));
+}
 function decisionWithLifecycleBranches(decision, runId, opts = {}) {
     const implementerBranch = (spec) => {
         const runSuffix = `-${runId.slice(0, 8)}`;
@@ -15633,12 +15852,123 @@ const isAllowedFactoryDraft = async (path, content, opts, mount, config) => {
     if (/^\/slack\/channels\/[^/]+\/messages\/.+/u.test(path)) {
         return true;
     }
-    if (isFactoryGithubWritebackPath(path)) {
+    if (await isAllowedFactoryGithubDraft(path, content, opts, mount, config))
         return true;
+    return false;
+};
+const isFactoryGithubAuthoredArtifactPath = (path) => /^\/github\/repos\/[^/]+\/[^/]+\/(?:pull-requests\/factory-[^/]+\.json|refs\/(?:factory\.json|refs%2Fheads%2Ffactory%2F[^/]+\.json)|pulls\/[1-9]\d*\/close\.json)$/iu.test(path);
+export const isAllowedFactoryGithubArtifactDraft = (path, opts) => opts?.guarded === true && isFactoryGithubAuthoredArtifactPath(path);
+const factoryGithubIssueWriteTarget = (path) => {
+    const match = /^\/github\/repos\/([^/]+)\/([^/]+)\/issues\/([1-9]\d*)(?:\.json|\/(comments|labels)\/([^/]+))$/iu.exec(path);
+    if (!match?.[1] || !match[2] || !match[3])
+        return undefined;
+    const child = match[4];
+    const filename = match[5];
+    if (child === 'comments' && (!filename || !isFactoryGithubIssueCommentDraftName(filename)))
+        return undefined;
+    if (child === 'labels' && (!filename || !isFactoryGithubOperationDraftName(filename)))
+        return undefined;
+    try {
+        return {
+            owner: decodeURIComponent(match[1]),
+            repo: decodeURIComponent(match[2]),
+            number: Number(match[3]),
+            kind: child === 'comments' ? 'comment' : child === 'labels' ? 'label-operation' : 'issue-update',
+        };
+    }
+    catch {
+        return undefined;
+    }
+};
+const factoryGithubRepositoryLabelWriteTarget = (path) => {
+    const match = /^\/github\/repos\/([^/]+)\/([^/]+)\/labels\/([^/]+)$/iu.exec(path);
+    if (!match?.[1] || !match[2] || !match[3] || !isFactoryGithubOperationDraftName(match[3]))
+        return undefined;
+    try {
+        return { owner: decodeURIComponent(match[1]), repo: decodeURIComponent(match[2]) };
+    }
+    catch {
+        return undefined;
+    }
+};
+const githubLifecycleLabel = (name) => Object.values(FACTORY_GITHUB_STATUS_LABELS).find((label) => label.name === name);
+const hasExactKeys = (value, keys) => {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+};
+const isAllowedFactoryGithubIssueWriteContent = (kind, content) => {
+    const value = asRecord(content);
+    if (!value)
+        return false;
+    if (kind === 'issue-update') {
+        return hasExactKeys(value, ['state']) && value.state === 'closed';
+    }
+    if (kind === 'comment') {
+        return hasExactKeys(value, ['body']) && typeof value.body === 'string' && value.body.trim().length > 0;
+    }
+    if (value.operation === 'add') {
+        return hasExactKeys(value, ['labels', 'operation']) &&
+            Array.isArray(value.labels) && value.labels.length === 1 && Boolean(githubLifecycleLabel(value.labels[0]));
+    }
+    return value.operation === 'remove' && hasExactKeys(value, ['label', 'operation']) && Boolean(githubLifecycleLabel(value.label));
+};
+const isAllowedFactoryGithubRepositoryLabelContent = (content) => {
+    const value = asRecord(content);
+    if (!value || !hasExactKeys(value, ['color', 'description', 'name']))
+        return false;
+    const expected = githubLifecycleLabel(value.name);
+    return Boolean(expected && expected.color === value.color && expected.description === value.description);
+};
+/**
+ * Last-resort mount guard for Factory-authored GitHub drafts. PR/ref paths are
+ * intrinsically Factory-owned. Issue mutations additionally require a current
+ * in-scope issue projection in one of Relayfile's supported repository layouts.
+ */
+export const isAllowedFactoryGithubDraft = async (path, content, opts, mount, config) => {
+    if (!opts?.guarded)
+        return false;
+    if (isAllowedFactoryGithubArtifactDraft(path, opts))
+        return true;
+    const repositoryLabelTarget = factoryGithubRepositoryLabelWriteTarget(path);
+    if (repositoryLabelTarget) {
+        const repoPath = `/github/repos/${encodeURIComponent(repositoryLabelTarget.owner)}/${encodeURIComponent(repositoryLabelTarget.repo)}/`;
+        return isConfiguredGithubRepoPath(repoPath, config) && isAllowedFactoryGithubRepositoryLabelContent(content);
+    }
+    const target = factoryGithubIssueWriteTarget(path);
+    if (!target)
+        return false;
+    if (!isAllowedFactoryGithubIssueWriteContent(target.kind, content))
+        return false;
+    if (target.kind === 'comment') {
+        const body = asRecord(content)?.body;
+        const draftName = path.slice(path.lastIndexOf('/') + 1);
+        if (typeof body !== 'string' || draftName !== factoryGithubIssueCommentDraftName(body))
+            return false;
+    }
+    const repoPath = `/github/repos/${encodeURIComponent(target.owner)}/${encodeURIComponent(target.repo)}`;
+    if (!isConfiguredGithubRepoPath(`${repoPath}/`, config))
+        return false;
+    const compactRepo = `${encodeURIComponent(target.owner)}__${encodeURIComponent(target.repo)}`;
+    const candidates = [
+        `${repoPath}/issues/by-id/${target.number}.json`,
+        `/github/repos/${compactRepo}/issues/by-id/${target.number}.json`,
+        `${repoPath}/issues/${target.number}/meta.json`,
+        `/github/repos/${compactRepo}/issues/${target.number}/meta.json`,
+        `${repoPath}/issues/${target.number}.json`,
+        `/github/repos/${compactRepo}/issues/${target.number}.json`,
+    ];
+    for (const candidate of candidates) {
+        try {
+            const issue = parseGithubFactoryIssue(candidate, (await mount.readFile(candidate)).content);
+            return issue.state?.name === 'open' && isInFactoryScope(issue, config.safety);
+        }
+        catch {
+            // Try the next canonical/alias shape. Any total miss fails closed.
+        }
     }
     return false;
 };
-const isFactoryGithubWritebackPath = (path) => /^\/github\/repos\/[^/]+\/[^/]+\/(?:pull-requests\/factory-[^/]+\.json|refs\/(?:factory\.json|refs%2Fheads%2Ffactory%2F[^/]+\.json)|pulls\/[1-9]\d*\/close\.json)$/iu.test(path);
 const isIssuePathInFactoryScope = async (mount, path, config) => {
     try {
         return isInFactoryScope(parseLinearIssue(path, (await mount.readFile(path)).content), config.safety);
@@ -16091,6 +16421,7 @@ const cloneTrackedAgent = (tracked) => ({
     result: tracked.result ? { ...tracked.result } : undefined,
     sessionRef: tracked.sessionRef,
     unreachableWakeResumedSessionRef: tracked.unreachableWakeResumedSessionRef,
+    releasedAtMs: tracked.releasedAtMs,
 });
 const durableBabysitterTrackedAgent = (session, capability = 'spawn:claude') => ({
     spec: {
@@ -16167,7 +16498,11 @@ const lifecycleFromInFlightRecord = (record, runId, phase, updatedAtMs, pullRequ
     decision: structuredClone(record.decision),
     dryRun: record.dryRun,
     phase,
-    agents: [...record.agents].map(([name, tracked]) => ({ name, tracked: cloneTrackedAgent(tracked) })),
+    agents: [...record.agents].map(([name, tracked]) => ({
+        name,
+        tracked: cloneTrackedAgent(tracked),
+        ...(tracked.releasedAtMs !== undefined ? { releasedAtMs: tracked.releasedAtMs } : {}),
+    })),
     invocationIds: [...record.invocationIds],
     result: record.result ? structuredClone(record.result) : undefined,
     ...(record.dispatchClaim ? { dispatchClaim: { ...record.dispatchClaim } } : {}),
@@ -16182,7 +16517,13 @@ const inFlightRecordFromLifecycle = (lifecycle) => ({
     issue: { ...lifecycle.issue },
     decision: structuredClone(lifecycle.decision),
     dryRun: lifecycle.dryRun,
-    agents: new Map(lifecycle.agents.map((agent) => [agent.name, cloneTrackedAgent(agent.tracked)])),
+    // Release state has to survive takeover with the agents themselves. Without
+    // it the rebuilt record reads a released placement as a live worker and the
+    // spawn gate answers for a process that no longer exists.
+    agents: new Map(lifecycle.agents.map((agent) => [agent.name, {
+            ...cloneTrackedAgent(agent.tracked),
+            releasedAtMs: agent.releasedAtMs ?? agent.tracked.releasedAtMs,
+        }])),
     invocationIds: new Set(lifecycle.invocationIds),
     result: lifecycle.result ? structuredClone(lifecycle.result) : undefined,
     ...(lifecycle.dispatchClaim ? { dispatchClaim: { ...lifecycle.dispatchClaim } } : {}),
@@ -16209,7 +16550,14 @@ const triageEscalationReason = (decision) => {
     }
     return `${reasons.join(' and ')}${decision.rationale ? `: ${decision.rationale}` : ''}`;
 };
-class LiveDispatchStateChangedError extends Error {
+/**
+ * The dispatch claim race: another writer changed the issue's live state
+ * between this process reading it and writing back, so the dispatch was
+ * abandoned. Exported so callers outside this module — notably the CLI, which
+ * turns it into a distinct exit code — can recognize it by type rather than by
+ * matching on `error.name`, and so tests can construct a genuine instance.
+ */
+export class LiveDispatchStateChangedError extends Error {
     issueKey;
     constructor(issueKey) {
         super(`Live state changed before writeback for ${issueKey}`);
@@ -16217,6 +16565,10 @@ class LiveDispatchStateChangedError extends Error {
         this.issueKey = issueKey;
     }
 }
+/** Whether a thrown value is a {@link LiveDispatchStateChangedError}. */
+export function isLiveDispatchStateChangedError(error) {
+    return error instanceof LiveDispatchStateChangedError;
+}
 const triageEscalationQuestion = (decision, issue) => {
     const routedRepos = decision.routes.map((route) => route.repo).filter(Boolean);
     const subject = issue?.title?.trim() || decision.issue.key;