@agent-relay/factory 0.1.24 → 0.1.26

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 { factoryWorktreePath } from '../git/agent-worktree.js';
 import { InMemoryStateStore } from '../state/in-memory-state-store.js';
 import { containsExplicitIssueReference, containsIssueKey } from '../issue-key-match.js';
 import { normalizeLogger, normalizeLogValue, setSafeErrorStack, stringifyLogValue } from '../logging.js';
@@ -34,15 +35,6 @@ const GITHUB_ISSUE_ROOT = '/github/repos';
 const READY_EVENTS_LIMIT = 100;
 const LIVE_ISSUE_GLOB = `${ISSUE_ROOT}/**`;
 const LIVE_RELAYFLOW_GLOB = '/**';
-// Subscribe broadly under /github/repos and let isGithubIssueFilePath() /
-// githubPullPathParts() re-validate the exact shape in the callback.
-// globMatchesPath() treats a non-terminal `**` as a single-segment wildcard, so
-// a more specific glob like `.../issues/**/*.json` would miss the two-segment
-// <owner>/<repo> prefix and the nested <number>__<slug>/meta.json (and
-// directory) event shapes this factory accepts. A terminal `**` prefix-matches
-// every descendant, so all supported issue AND pull-request path variants reach
-// the handler — including the PR change events the babysitter reacts to.
-export const LIVE_GITHUB_ISSUE_GLOB = `${GITHUB_ISSUE_ROOT}/**`;
 const LIVE_DEDUPE_LIMIT = 5_000;
 const LIVE_EVENT_DRAIN_BATCH_SIZE = 5;
 const COMPLETION_SWEEP_INTERVAL_MS = 15_000;
@@ -125,6 +117,7 @@ export class FactoryLoop {
     #state;
     #workspaceId;
     #relayflows;
+    #worktrees;
     #batchView;
     #batchReady;
     #listeners = new Map();
@@ -158,6 +151,7 @@ export class FactoryLoop {
     #dispatchTerminalWaiters = new Map();
     #dispatchLifecycleRetryTimers = new Map();
     #dispatchLifecycleDrives = new Set();
+    #localReleaseCheckpoints = new Map();
     #dispatchLifecycleRenewTimer;
     #clarificationSweepTimer;
     #clarificationSweepDueAtMs;
@@ -260,6 +254,7 @@ export class FactoryLoop {
         this.#terminationGraceMs = ports.terminationGraceMs;
         this.#workspaceId = config.workspaceId ?? 'default';
         this.#relayflows = ports.relayflows;
+        this.#worktrees = ports.worktrees;
         this.#state = ports.stateStore ?? new InMemoryStateStore({
             batchSize: config.batchSize,
             agentQuestionDedupeLimit: AGENT_QUESTION_DEDUPE_LIMIT,
@@ -453,7 +448,7 @@ export class FactoryLoop {
         if ((opts.mode ?? 'live') === 'live') {
             this.#started = true;
             try {
-                await this.#startLiveSubscription(opts.liveSubscription);
+                await this.#startLiveSubscription(issueSource, opts.liveSubscription);
                 await this.#rearmSlackReplyWatchers();
                 await this.#drainReadyClarificationWake();
                 await this.#rearmGithubIssueCommentWatchers();
@@ -467,7 +462,7 @@ export class FactoryLoop {
             }
         }
         await this.#backfillReadyIssues();
-        this.#subscription = this.#mount.subscribe(this.#subscriptionGlobs([`${ISSUE_ROOT}/**/*.json`, LIVE_GITHUB_ISSUE_GLOB]), (event) => {
+        this.#subscription = this.#mount.subscribe(this.#subscriptionGlobs(issueSource, [`${ISSUE_ROOT}/**/*.json`]), (event) => {
             void this.#dispatchRelayflowEvent(event);
             // The SDK types `resource` as always-present, but the polling fallback and
             // degraded-sync paths can deliver events without it. Skip those rather
@@ -610,7 +605,7 @@ export class FactoryLoop {
     async dispose() {
         await this.stop();
     }
-    async #startLiveSubscription(overrides = {}) {
+    async #startLiveSubscription(issueSource, overrides = {}) {
         const options = this.#liveOptions(overrides);
         await this.#startLiveHeartbeat();
         this.#liveConnectStartedAtMs = this.#clock.now();
@@ -624,41 +619,51 @@ export class FactoryLoop {
             replaySkewMarginMs: this.#liveReplaySkewMarginMs,
             highWatermarkRouteUnavailable: highWatermark.routeUnavailable,
         });
-        // Register the live subscription BEFORE the startup full pull so an issue
+        // Register the live subscription BEFORE the startup backfill so an issue
         // that becomes Ready *during* the pull is captured, not lost in the window
         // between listTree and subscribe. Events buffer (deferred drain) until the
         // pull finishes; batch dedupe then suppresses any overlap with what the
         // pull already dispatched.
-        if (options.transport !== 'poll') {
-            // LIVE_GITHUB_ISSUE_GLOB is a terminal `${GITHUB_ISSUE_ROOT}/**`, so it
-            // already covers the PR change events the babysitter consumes; pull-event
-            // *processing* is gated on babysitter.enabled in #prepareLiveEventForDrain.
-            this.#subscription = this.#mount.subscribe(this.#subscriptionGlobs([LIVE_ISSUE_GLOB, LIVE_GITHUB_ISSUE_GLOB]), (event) => {
-                this.#enqueueLiveEvent(event);
-            }, { from: 'now', coalesce: 'none' });
-        }
-        if (highWatermark.routeUnavailable) {
-            this.#increment('liveHighWatermarkFullPullFallbacks');
-            this.#logger.info?.('[factory] live subscription high-watermark route unavailable; running startup full pull before draining buffered events');
-            this.#deferLiveEventDrain = true;
+        this.#deferLiveEventDrain = true;
+        try {
+            if (options.transport === 'poll') {
+                // Capture the cursor before the backfill. Events written while listTree
+                // is running are then picked up by the first poll instead of falling
+                // into a cursor-advance gap.
+                this.#liveEventCursor = await this.#currentEventCursor(options.eventLimit);
+            }
+            else {
+                this.#subscription = this.#mount.subscribe(this.#subscriptionGlobs(issueSource, [LIVE_ISSUE_GLOB]), (event) => {
+                    this.#enqueueLiveEvent(event);
+                }, { from: 'now', coalesce: 'none' });
+            }
+            if (highWatermark.routeUnavailable) {
+                this.#increment('liveHighWatermarkFullPullFallbacks');
+            }
+            this.#increment('liveStartupBackfills');
+            this.#logger.info?.('[factory] running startup ready-issue backfill before draining buffered events', {
+                highWatermarkRouteUnavailable: highWatermark.routeUnavailable,
+            });
             try {
                 await this.runOnce();
             }
             catch (error) {
-                // A startup pull failure must not abort the daemon: log it and fall back
-                // to the live event stream (plus any buffered events) instead of leaving
-                // the factory down.
-                this.#increment('liveHighWatermarkFullPullErrors');
+                // A startup backfill failure must not abort the daemon: log it and fall
+                // back to the live event stream (plus any buffered events) instead of
+                // leaving the factory down.
+                this.#increment('liveStartupBackfillErrors');
+                if (highWatermark.routeUnavailable) {
+                    this.#increment('liveHighWatermarkFullPullErrors');
+                }
                 this.#error(error);
             }
-            finally {
-                this.#deferLiveEventDrain = false;
-                this.#scheduleLiveEventDrain();
-            }
-            await this.#refreshLiveHeartbeatIfDue();
         }
+        finally {
+            this.#deferLiveEventDrain = false;
+            this.#scheduleLiveEventDrain();
+        }
+        await this.#refreshLiveHeartbeatIfDue();
         if (options.transport === 'poll') {
-            this.#liveEventCursor = await this.#currentEventCursor(options.eventLimit);
             this.#scheduleLivePoll(0, options);
         }
     }
@@ -873,14 +878,25 @@ export class FactoryLoop {
             return;
         await this.#refreshLiveHeartbeat();
     }
-    #subscriptionGlobs(factoryGlobs) {
-        return this.#relayflows ? [LIVE_RELAYFLOW_GLOB] : factoryGlobs;
+    #subscriptionGlobs(issueSource, linearGlobs) {
+        if (this.#relayflows)
+            return [LIVE_RELAYFLOW_GLOB];
+        return [
+            ...(issueSource === 'linear' ? linearGlobs : []),
+            ...githubRepoSubscriptionGlobs(this.#config),
+        ];
     }
     async #prepareLiveEventForDrain(event, seenIssueKeys) {
         const path = changeEventPath(event);
         if (!path) {
             return { dispatchRelayflow: false };
         }
+        if (!this.#relayflows &&
+            path.startsWith(`${GITHUB_ISSUE_ROOT}/`) &&
+            !isConfiguredGithubRepoPath(path, this.#config)) {
+            this.#increment('liveGithubEventsOutsideConfiguredRepos');
+            return { dispatchRelayflow: false };
+        }
         const isPullPath = isGithubPullFilePath(path);
         const babysitterEvent = this.#config.babysitter.enabled
             ? githubBabysitterEventPathParts(path)
@@ -1169,7 +1185,9 @@ export class FactoryLoop {
             for (const path of paths) {
                 const issue = await this.#readIssue(path);
                 readyIssueReads += 1;
-                lastReadyReadProgressAtMs = this.#logTimedProgress('[factory] Linear ready issue read progress', startedAtMs, lastReadyReadProgressAtMs, { read: readyIssueReads, total: paths.length, path });
+                lastReadyReadProgressAtMs = this.#logTimedProgress(this.#config.issueSource === 'github'
+                    ? '[factory] GitHub ready issue read progress'
+                    : '[factory] Linear ready issue read progress', startedAtMs, lastReadyReadProgressAtMs, { read: readyIssueReads, total: paths.length, path });
                 if (issue && issueSource === 'linear') {
                     await this.#recordCanonicalIssueState(issue);
                 }
@@ -1487,9 +1505,15 @@ export class FactoryLoop {
         // happen before a remote lifecycle is first claimed so takeover cannot
         // recover a persisted minimal triage task after a crash in this gap.
         const durableRemoteDispatch = !dryRun && this.#fleet.placementLocality === 'remote';
-        const lifecycleRunId = durableRemoteDispatch ? randomUUID() : undefined;
+        // Local dispatches need the same deterministic branch identity as remote
+        // ones. Without it, every worker starts in the configured shared checkout
+        // and concurrent issues can switch each other back to the base branch.
+        const isolateLocalWorktree = this.#fleet.placementLocality === 'local' && Boolean(this.#worktrees);
+        const lifecycleRunId = !dryRun && (durableRemoteDispatch || isolateLocalWorktree) ? randomUUID() : undefined;
         if (lifecycleRunId) {
-            dispatchDecision = decisionWithLifecycleBranches(dispatchDecision, lifecycleRunId);
+            dispatchDecision = decisionWithLifecycleBranches(dispatchDecision, lifecycleRunId, {
+                isolateLocalWorktree,
+            });
         }
         dispatchDecision = await this.#withRenderedDispatchTasks(dispatchDecision, liveIssue);
         if (durableRemoteDispatch) {
@@ -1541,6 +1565,7 @@ export class FactoryLoop {
                         name: spawned.name,
                         tracked: cloneTrackedAgent(tracked),
                         persistedAtMs: this.#clock.now(),
+                        worktree: this.#agentWorktree(record, tracked.spec),
                     });
                 }
                 agents.push({ name: spawned.name, role: spec.role });
@@ -1585,7 +1610,12 @@ export class FactoryLoop {
             return result;
         }
         catch (error) {
-            await this.#persistDispatchFailureReaperHandoff(record, spawnedForReaperHandoff);
+            // A spawn can fail after the broker accepted it but before its ack
+            // reached Factory. Include every planned worktree agent, not only the
+            // acknowledged spawns, so cleanup never races a name-only survivor.
+            const failureHandoffs = this.#dispatchFailureHandoffs(record, spawnedForReaperHandoff);
+            await this.#persistDispatchFailureReaperHandoff(record, failureHandoffs);
+            const worktreesTornDown = await this.#teardownFailedDispatchWorktrees(failureHandoffs);
             await this.#recordDispatchFailure(decision.issue);
             const failedState = await this.#state.getDispatchAttempts(this.#workspaceId, decision.issue.key);
             await this.#saveDispatchLifecycle(record, failedState?.terminal ? 'abandoned' : 'retryable');
@@ -1593,6 +1623,20 @@ export class FactoryLoop {
             if (!failedState?.terminal)
                 this.#scheduleDispatchLifecycleRetry(record);
             this.#error(error, decision.issue);
+            // The teardown runs while the record still exists so it can safely
+            // derive every shared checkout. Rewrite the registry only after abandon
+            // removes those agents from the ordinary in-flight view.
+            if (worktreesTornDown) {
+                try {
+                    await this.#writeInFlightRegistry();
+                }
+                catch (registryError) {
+                    this.#logger.warn?.('[factory] failed to rewrite registry after dispatch worktree teardown', {
+                        issue: record.issue,
+                        error: describeError(registryError).errorMessage,
+                    });
+                }
+            }
             throw error;
         }
     }
@@ -1803,6 +1847,31 @@ export class FactoryLoop {
         }, DISPATCH_LIFECYCLE_RETRY_MS);
         this.#dispatchLifecycleRetryTimers.set(key, timer);
     }
+    #scheduleReleaseRetry(record, reason) {
+        if (this.#fleet.placementLocality === 'remote') {
+            this.#scheduleDispatchLifecycleRetry(record);
+            return;
+        }
+        const key = issueKey(record.issue);
+        if (this.#stopping || this.#dispatchLifecycleRetryTimers.has(key))
+            return;
+        const timer = setTimeout(() => {
+            this.#dispatchLifecycleRetryTimers.delete(key);
+            const drive = this.#finishDurableRelease(record, reason)
+                .then(() => undefined)
+                .catch((error) => {
+                this.#logger.warn?.('[factory] local completion cleanup retry failed', {
+                    issue: record.issue.key,
+                    error: describeError(error).errorMessage,
+                });
+                this.#scheduleReleaseRetry(record, reason);
+            })
+                .finally(() => this.#dispatchLifecycleDrives.delete(drive));
+            this.#dispatchLifecycleDrives.add(drive);
+        }, DISPATCH_LIFECYCLE_RETRY_MS);
+        timer.unref?.();
+        this.#dispatchLifecycleRetryTimers.set(key, timer);
+    }
     async #driveDispatchLifecycle(key) {
         if (this.#stopping)
             return;
@@ -1953,12 +2022,12 @@ export class FactoryLoop {
     }
     async #finishDurableRelease(record, releaseReason) {
         const batch = await this.#batch();
-        const next = this.#fleet.placementLocality === 'remote' ? undefined : batch.complete(record.issue);
         const reason = releaseReason ?? (this.#config.terminalState === 'human-review' ? 'issue-human-review' : 'issue-done');
-        const lifecycle = await this.#state.getDispatchLifecycle(this.#workspaceId, issueKey(record.issue));
+        const releaseKey = issueKey(record.issue);
+        const lifecycle = await this.#state.getDispatchLifecycle(this.#workspaceId, releaseKey);
         const released = new Set(lifecycle?.agents
             .filter((agent) => agent.releasedAtMs !== undefined)
-            .map((agent) => agent.name) ?? []);
+            .map((agent) => agent.name) ?? this.#localReleaseCheckpoints.get(releaseKey) ?? []);
         const failed = [];
         for (const agent of record.agents) {
             if (released.has(agent[0]))
@@ -1969,19 +2038,37 @@ export class FactoryLoop {
                 continue;
             }
             released.add(agent[0]);
+            if (this.#fleet.placementLocality === 'local') {
+                this.#localReleaseCheckpoints.set(releaseKey, new Set(released));
+            }
             // Persist each acknowledged release independently. A takeover retries
             // only agents whose release did not reach a fenced durable checkpoint.
             if (!await this.#saveDispatchLifecycle(record, 'releasing', undefined, reason, released))
                 return false;
         }
-        if (next)
-            await this.dispatch(next.decision, { dryRun: next.dryRun });
         await this.#writeInFlightRegistry();
         if (failed.length > 0) {
             this.#increment('dispatchLifecycleReleaseRetries');
-            this.#scheduleDispatchLifecycleRetry(record);
+            this.#scheduleReleaseRetry(record, reason);
+            return false;
+        }
+        // The PR branch is already pushed and the babysitter has declared the
+        // current PR green with review feedback addressed. Release is now fenced,
+        // so no agent can race cleanup of the shared per-issue worktree.
+        try {
+            await this.#cleanupAgentWorktrees(record);
+        }
+        catch {
+            // Completion remains in-flight until the isolated checkout is gone.
+            // Remote lifecycles retry from their durable `releasing` phase; local
+            // lifecycles retain this record and retry directly from the same fence.
+            this.#scheduleReleaseRetry(record, reason);
             return false;
         }
+        const next = this.#fleet.placementLocality === 'remote' ? undefined : batch.complete(record.issue);
+        this.#localReleaseCheckpoints.delete(releaseKey);
+        if (next)
+            await this.dispatch(next.decision, { dryRun: next.dryRun });
         // Terminal lifecycle saves intentionally relinquish the owner epoch. Clear
         // the babysitter's durable ownership/wake/critical state while that epoch
         // is still valid so a later reopened issue cannot inherit a stale PR owner.
@@ -2458,6 +2545,7 @@ export class FactoryLoop {
         try {
             const protectedPids = await this.#protectedPids();
             let registryChanged = false;
+            const readyToClear = new Set();
             for (const [key, handoff] of handoffs) {
                 const roots = await this.#terminationRoots(handoff.name, handoff.tracked, protectedPids);
                 if (roots.pids.length === 0 && roots.status === 'unresolved') {
@@ -2470,8 +2558,6 @@ export class FactoryLoop {
                         unresolvedAgeMs,
                     });
                     if (unresolvedAgeMs >= DISPATCH_FAILURE_HANDOFF_UNRESOLVED_TTL_MS) {
-                        await this.#state.clearFailureHandoff(this.#workspaceId, key);
-                        registryChanged = true;
                         this.#increment('dispatchFailureReaperHandoffsDroppedStaleUnresolved');
                         this.#logger.warn?.('[factory] dropped stale unresolved dispatch-failed handoff', {
                             agentName: handoff.name,
@@ -2481,6 +2567,7 @@ export class FactoryLoop {
                         });
                         try {
                             await this.#fleet.release(handoff.name, 'dispatch failed');
+                            readyToClear.add(key);
                         }
                         catch (error) {
                             this.#logger.warn?.('[factory] failed to release unresolved dispatch-failure handoff after pruning', {
@@ -2514,16 +2601,55 @@ export class FactoryLoop {
                     }
                 }
                 if (!blockingSkip) {
-                    await this.#state.clearFailureHandoff(this.#workspaceId, key);
-                    registryChanged = true;
                     try {
                         await this.#fleet.release(handoff.name, 'dispatch failed');
+                        readyToClear.add(key);
                     }
                     catch (error) {
                         this.#logger.warn?.(`[factory] failed to release ${handoff.name} after dispatch-failure reap`, error);
                     }
                 }
             }
+            if (readyToClear.size > 0) {
+                const worktreeGroups = new Map();
+                for (const entry of handoffs) {
+                    const worktreePath = entry[1].worktree?.worktreePath;
+                    if (!worktreePath)
+                        continue;
+                    const group = worktreeGroups.get(worktreePath) ?? [];
+                    group.push(entry);
+                    worktreeGroups.set(worktreePath, group);
+                }
+                for (const group of worktreeGroups.values()) {
+                    if (!group.every(([key]) => readyToClear.has(key)))
+                        continue;
+                    try {
+                        await this.#cleanupFailureHandoffWorktrees(group.map(([, handoff]) => handoff));
+                    }
+                    catch (error) {
+                        this.#increment('agentWorktreeCleanupFailures');
+                        this.#logger.warn?.('[factory] retained dispatch-failure handoff after worktree cleanup failed', {
+                            issue: group[0]?.[1].issue,
+                            worktreePath: group[0]?.[1].worktree?.worktreePath,
+                            error: describeError(error).errorMessage,
+                        });
+                        continue;
+                    }
+                    for (const [key] of group) {
+                        await this.#state.clearFailureHandoff(this.#workspaceId, key);
+                        readyToClear.delete(key);
+                        registryChanged = true;
+                    }
+                }
+                // Legacy and non-worktree handoffs can be cleared directly once their
+                // process is gone and the broker accepted the release.
+                for (const [key, handoff] of handoffs) {
+                    if (!readyToClear.has(key) || handoff.worktree)
+                        continue;
+                    await this.#state.clearFailureHandoff(this.#workspaceId, key);
+                    registryChanged = true;
+                }
+            }
             if (registryChanged) {
                 await this.#writeInFlightRegistry(registryPath, heartbeatPath);
             }
@@ -2738,6 +2864,62 @@ export class FactoryLoop {
             this.#error(error, record.issue);
         }
     }
+    #dispatchFailureHandoffs(record, acknowledged) {
+        const handoffs = new Map(acknowledged.map((handoff) => [handoff.name, handoff]));
+        if (!this.#worktrees)
+            return [...handoffs.values()];
+        for (const [name, tracked] of record.agents) {
+            const worktree = this.#agentWorktree(record, tracked.spec);
+            if (!worktree)
+                continue;
+            const existing = handoffs.get(name);
+            handoffs.set(name, {
+                issue: record.issue,
+                name,
+                tracked: cloneTrackedAgent(tracked),
+                persistedAtMs: existing?.persistedAtMs ?? this.#clock.now(),
+                worktree,
+            });
+        }
+        return [...handoffs.values()];
+    }
+    async #teardownFailedDispatchWorktrees(handoffs) {
+        if (!this.#worktrees || !handoffs.some((handoff) => handoff.worktree))
+            return false;
+        const failed = await this.#releaseAndTerminateAgents(handoffs.map((handoff) => [handoff.name, handoff.tracked]), 'dispatch failed', 'completion');
+        if (failed.length > 0)
+            return false;
+        try {
+            await this.#cleanupFailureHandoffWorktrees(handoffs);
+            for (const handoff of handoffs) {
+                await this.#state.clearFailureHandoff(this.#workspaceId, registryHandoffKey(handoff.issue, handoff.name));
+            }
+            return true;
+        }
+        catch (error) {
+            // Keep the durable handoffs. The loop reaper will retry cleanup only
+            // after it has reconfirmed every agent sharing the checkout is gone.
+            this.#increment('agentWorktreeCleanupFailures');
+            this.#logger.warn?.('[factory] retained dispatch-failure handoffs after worktree cleanup failed', {
+                issue: handoffs[0]?.issue,
+                error: describeError(error).errorMessage,
+            });
+            return false;
+        }
+    }
+    async #cleanupFailureHandoffWorktrees(handoffs) {
+        if (!this.#worktrees)
+            return;
+        const unique = new Map();
+        for (const handoff of handoffs) {
+            if (handoff.worktree)
+                unique.set(handoff.worktree.worktreePath, handoff.worktree);
+        }
+        for (const worktree of unique.values()) {
+            await this.#worktrees.cleanup(worktree);
+            this.#increment('agentWorktreesCleaned');
+        }
+    }
     async #writeInFlightRegistry(path = this.#config.loop.registryPath, heartbeatPath = this.#config.loop.heartbeatPath, empty = false) {
         const updatedAtMs = this.#clock.now();
         const agents = [];
@@ -2832,6 +3014,7 @@ export class FactoryLoop {
             }
             return { name: spec.name };
         }
+        await this.#prepareAgentWorktree(record, spec);
         let result;
         try {
             result = await this.#fleet.spawn({
@@ -3049,6 +3232,7 @@ export class FactoryLoop {
             else {
                 const invocationId = `${batch.invocationIdFor(record.issue, tracked.spec)}:restart:${this.#clock.now()}`;
                 try {
+                    await this.#prepareAgentWorktree(record, tracked.spec);
                     const result = await this.#fleet.spawn({
                         name: tracked.spec.name,
                         capability: tracked.spec.capability,
@@ -3178,6 +3362,66 @@ export class FactoryLoop {
         });
         return result;
     }
+    async #prepareAgentWorktree(record, spec) {
+        const worktree = this.#agentWorktree(record, spec);
+        if (!worktree || !this.#worktrees)
+            return;
+        try {
+            await this.#worktrees.prepare(worktree);
+            this.#increment('agentWorktreesPrepared');
+        }
+        catch (error) {
+            throw contextualError(`Unable to prepare isolated worktree for ${record.issue.key}/${spec.repo} at ${worktree.worktreePath}`, error);
+        }
+    }
+    #agentWorktree(record, spec) {
+        if (!spec.baseClonePath || !spec.clonePath || spec.baseClonePath === spec.clonePath)
+            return undefined;
+        const implementer = record.decision.implementers.find((candidate) => candidate.repo === spec.repo && candidate.branch)
+            ?? [...record.agents.values()]
+                .map((tracked) => tracked.spec)
+                .find((candidate) => candidate.repo === spec.repo && candidate.role === 'implementer' && candidate.branch);
+        const branch = spec.branch ?? implementer?.branch;
+        if (!branch)
+            return undefined;
+        return {
+            repo: spec.repo,
+            issueKey: record.issue.key,
+            baseClonePath: spec.baseClonePath,
+            worktreePath: spec.clonePath,
+            branch,
+        };
+    }
+    async #cleanupAgentWorktrees(record) {
+        if (!this.#worktrees)
+            return;
+        const unique = new Map();
+        for (const tracked of record.agents.values()) {
+            const worktree = this.#agentWorktree(record, tracked.spec);
+            if (worktree)
+                unique.set(worktree.worktreePath, worktree);
+        }
+        const failures = [];
+        for (const worktree of unique.values()) {
+            try {
+                await this.#worktrees.cleanup(worktree);
+                this.#increment('agentWorktreesCleaned');
+            }
+            catch (error) {
+                failures.push(`${worktree.worktreePath}: ${describeError(error).errorMessage}`);
+                this.#increment('agentWorktreeCleanupFailures');
+                this.#logger.warn?.('[factory] failed to clean completed issue worktree', {
+                    issue: record.issue.key,
+                    repo: worktree.repo,
+                    worktreePath: worktree.worktreePath,
+                    error: describeError(error).errorMessage,
+                });
+            }
+        }
+        if (failures.length > 0) {
+            throw new Error(`Factory worktree cleanup incomplete for ${record.issue.key}: ${failures.join('; ')}`);
+        }
+    }
     async #confirmPublishedRemotePullRequest(repo, result, expectedHeadRef) {
         const parts = githubRepoParts(repo);
         if (!parts)
@@ -3365,6 +3609,7 @@ export class FactoryLoop {
         if (!tracked.sessionRef) {
             return;
         }
+        await this.#prepareAgentWorktree(record, tracked.spec);
         const result = await this.#fleet.resume({
             name,
             sessionRef: tracked.sessionRef,
@@ -3607,7 +3852,7 @@ export class FactoryLoop {
         catch {
             // The initiator logs Slack watcher startup failures.
         }
-        const threadId = await this.#state.getSlackThread(this.#workspaceId, key);
+        const threadId = await this.#persistedSlackThread(key);
         if (!threadId) {
             this.#increment('agentQuestionsSkippedMissingThread');
             this.#logger.warn?.('[factory] agent question has no Slack dispatch thread', {
@@ -3835,7 +4080,7 @@ export class FactoryLoop {
             return undefined;
         }
         const key = issueKey(record.issue);
-        const threadId = await this.#state.getSlackThread(this.#workspaceId, key);
+        const threadId = await this.#persistedSlackThread(key);
         if (!threadId) {
             this.#increment('agentQuestionReleaseSkippedMissingThread');
             return undefined;
@@ -3888,7 +4133,7 @@ export class FactoryLoop {
             issue: { ...record.issue },
             decision: structuredClone(record.decision),
             dryRun: record.dryRun,
-            threadId: await this.#state.getSlackThread(this.#workspaceId, key),
+            threadId: await this.#persistedSlackThread(key),
             questionSource: 'github',
             askerName: question.agentName,
             question: question.question,
@@ -3914,7 +4159,7 @@ export class FactoryLoop {
             this.#increment('agentQuestionSlackMirrorsSkippedDegraded');
             return;
         }
-        const threadId = await this.#state.getSlackThread(this.#workspaceId, issueKey(record.issue));
+        const threadId = await this.#persistedSlackThread(issueKey(record.issue));
         if (!threadId) {
             this.#increment('agentQuestionSlackMirrorsSkippedMissingThread');
             return;
@@ -4689,7 +4934,8 @@ export class FactoryLoop {
                 implementerNames,
                 integrationsMountRoot: this.#integrationsMountRoot(),
                 integrationInstructions,
-                branchName: spec.branch,
+                branchName: spec.branch ?? decision.implementers.find((candidate) => candidate.repo === spec.repo)?.branch,
+                branchPrepared: Boolean(spec.baseClonePath && spec.clonePath && spec.baseClonePath !== spec.clonePath),
                 agentName: spec.name,
             }),
         });
@@ -5471,7 +5717,20 @@ export class FactoryLoop {
             }
             const route = record.decision.routes.find((candidate) => candidate.repo === prRef.repo)
                 ?? record.decision.routes[0];
-            const spec = babysitterSpec(issue, this.#config, route);
+            const initialSpec = babysitterSpec(issue, this.#config, route);
+            const sharedCheckout = [...record.agents.values()]
+                .map((agent) => agent.spec)
+                .find((candidate) => candidate.repo === initialSpec.repo && candidate.baseClonePath && candidate.clonePath);
+            const implementerBranch = record.decision.implementers
+                .find((candidate) => candidate.repo === initialSpec.repo && candidate.branch)?.branch;
+            const spec = sharedCheckout
+                ? {
+                    ...initialSpec,
+                    baseClonePath: sharedCheckout.baseClonePath,
+                    clonePath: sharedCheckout.clonePath,
+                    ...(implementerBranch ? { branch: implementerBranch } : {}),
+                }
+                : initialSpec;
             const reviewer = [...record.agents.values()].find((agent) => agent.spec.role === 'reviewer');
             const reviewerName = reviewer?.result?.name ?? reviewer?.spec.name
                 ?? agentNameForRole(issue, 'review', { repo: route?.repo ?? prRef.repo });
@@ -5481,7 +5740,7 @@ export class FactoryLoop {
             const integrationInstructions = await this.#resolveIntegrationInstructions();
             const task = renderAgentTask({
                 issue: templateIssueFromRecord(record, issue),
-                route: route ?? { repo: prRef.repo },
+                route: { ...(route ?? { repo: prRef.repo }), clonePath: spec.clonePath },
                 role: 'babysitter',
                 config: { mergePolicy: this.#config.mergePolicy, terminalState: this.#config.terminalState },
                 reviewerName,
@@ -5490,6 +5749,8 @@ export class FactoryLoop {
                 slackDispatchThread: await this.#slackDispatchThreadFor(record),
                 integrationsMountRoot: this.#integrationsMountRoot(),
                 integrationInstructions,
+                branchName: spec.branch,
+                branchPrepared: Boolean(spec.baseClonePath && spec.clonePath && spec.baseClonePath !== spec.clonePath),
                 agentName: spec.name,
             });
             const spawned = await this.#spawnAgent(record, {
@@ -5658,6 +5919,7 @@ export class FactoryLoop {
             return;
         }
         this.#completionInFlight.add(completionKey);
+        let releaseReasonForRetry;
         try {
             if (!await this.#assertDispatchLifecycleOwner(record))
                 return;
@@ -5743,6 +6005,7 @@ export class FactoryLoop {
                 await this.#runCompletionMergeGate(issue);
             }
             const releaseReason = humanReview ? 'issue-human-review' : 'issue-done';
+            releaseReasonForRetry = releaseReason;
             if (this.#fleet.placementLocality === 'remote') {
                 // Durable capacity is released as soon as terminal writeback is
                 // acknowledged. Agent cleanup remains fenced/retryable in `releasing`.
@@ -5759,7 +6022,10 @@ export class FactoryLoop {
         }
         catch (error) {
             this.#error(error, record.issue);
-            this.#scheduleDispatchLifecycleRetry(record);
+            if (releaseReasonForRetry)
+                this.#scheduleReleaseRetry(record, releaseReasonForRetry);
+            else
+                this.#scheduleDispatchLifecycleRetry(record);
         }
         finally {
             this.#completionInFlight.delete(completionKey);
@@ -6013,6 +6279,19 @@ export class FactoryLoop {
         this.#lastObservedSlackEventAtMs = this.#clock.now();
         this.#increment('slackWebhookEventsObserved');
     }
+    async #persistedSlackThread(key) {
+        const threadId = await this.#state.getSlackThread(this.#workspaceId, key);
+        if (!threadId || /^\d+[._]\d+$/u.test(threadId))
+            return threadId;
+        // Older Factory versions persisted the Relayfile draft client id when the
+        // acknowledged file had not yet reconciled its provider payload. Slack
+        // cannot use that value as thread_ts. Drop it so the caller establishes a
+        // fresh provider-backed root instead of producing invalid_thread_ts.
+        await this.#state.clearSlackThread(this.#workspaceId, key);
+        this.#increment('invalidSlackThreadsCleared');
+        this.#logger.warn?.('[factory] cleared invalid persisted Slack thread id', { issue: key });
+        return undefined;
+    }
     async #ensureSlackDispatchThread(record, result) {
         if (!this.#slack || !this.#config.slack || result.dryRun) {
             return;
@@ -6021,7 +6300,7 @@ export class FactoryLoop {
             return;
         }
         const key = issueKey(record.issue);
-        const existingThread = await this.#state.getSlackThread(this.#workspaceId, key);
+        const existingThread = await this.#persistedSlackThread(key);
         const watcherStart = this.#slackWatcherStarts.get(key);
         if (existingThread || watcherStart) {
             try {
@@ -6074,6 +6353,16 @@ export class FactoryLoop {
         if (dryRun) {
             return;
         }
+        // A source GitHub issue is the durable stakeholder record. Keep both the
+        // question and authorized response there, then mirror the escalation once
+        // to Slack for stakeholder visibility without making Slack a competing
+        // clarification workflow.
+        const sourceIssue = await this.#readIssue(decision.issue.path);
+        if (sourceIssue && githubIssueSourceRef(sourceIssue)) {
+            const result = await this.#escalateTriageToGithub(decision, reason);
+            await this.#mirrorGithubTriageEscalationToSlack(decision, sourceIssue, reason);
+            return result;
+        }
         if (!this.#slack || !this.#config.slack) {
             return await this.#escalateTriageToGithub(decision, reason);
         }
@@ -6081,7 +6370,7 @@ export class FactoryLoop {
             return;
         }
         const key = issueKey(decision.issue);
-        const existingThread = await this.#state.getSlackThread(this.#workspaceId, key);
+        const existingThread = await this.#persistedSlackThread(key);
         const watcherStart = this.#slackWatcherStarts.get(key);
         if (existingThread || watcherStart) {
             try {
@@ -6134,7 +6423,7 @@ export class FactoryLoop {
         }
         try {
             await this.#githubWriteback.postComment(issue, [
-                `Factory needs clarification before dispatching ${decision.issue.key}.`,
+                `@${authorizedAuthor}, Factory needs clarification before dispatching ${decision.issue.key}.`,
                 `Reason: ${reason}`,
                 `Question: ${question}`,
                 `Authorized responder: @${authorizedAuthor} (the issue reporter).`,
@@ -6149,15 +6438,79 @@ export class FactoryLoop {
             this.#surfaceEscalationDeliveryFailure('triage', decision.issue, correlationId, 'GitHub issue comment writeback failed', error);
         }
     }
+    async #mirrorGithubTriageEscalationToSlack(decision, issue, reason) {
+        if (!this.#slack || !this.#config.slack)
+            return;
+        if (await this.#shouldSkipSlackWriteback('triage-escalation-mirror')) {
+            this.#increment('triageEscalationSlackMirrorsSkippedDegraded');
+            return;
+        }
+        const key = issueKey(decision.issue);
+        const existingThread = await this.#persistedSlackThread(key);
+        const inFlight = this.#slackWatcherStarts.get(key);
+        if (existingThread || inFlight) {
+            if (inFlight) {
+                try {
+                    await inFlight;
+                }
+                catch {
+                    // The initiator records the optional mirror failure.
+                }
+            }
+            this.#increment('triageEscalationSlackMirrorDuplicatesSuppressed');
+            return;
+        }
+        const start = this.#postGithubTriageSlackMirror(decision, issue, reason);
+        this.#slackWatcherStarts.set(key, start);
+        try {
+            await start;
+        }
+        catch (error) {
+            this.#markSlackWritebackFailure('triage-escalation-mirror', error);
+            this.#increment('triageEscalationSlackMirrorFailures');
+            this.#logger.warn?.('[factory] optional GitHub triage Slack mirror failed', {
+                issue: decision.issue.key,
+                error: describeError(error).errorMessage,
+            });
+        }
+        finally {
+            this.#slackWatcherStarts.delete(key);
+        }
+    }
+    async #postGithubTriageSlackMirror(decision, issue, reason) {
+        if (!this.#slack || !this.#config.slack)
+            return;
+        const source = githubIssueSourceRef(issue);
+        const stakeholderMentions = slackMentions(this.#config.slack.stakeholderUserIds);
+        const reporter = githubIssueAuthor(issue);
+        const audience = [stakeholderMentions, reporter ? `GitHub reporter: @${reporter}.` : undefined]
+            .filter((part) => Boolean(part))
+            .join(' ');
+        const replyInstruction = source?.url
+            ? `Reply on the GitHub issue so Factory can resume: ${source.url}`
+            : 'Reply on the source GitHub issue so Factory can resume.';
+        const root = await this.#slack.postThread({
+            channel: await this.#slackChannelDir() ?? this.#config.slack.channel,
+            text: [
+                `${audience ? `${audience} ` : ''}${decision.issue.key}: factory triage escalation for ${issue.title}`,
+                `Reason: ${reason}`,
+                `Question: ${triageEscalationQuestion(decision)} ${replyInstruction}`,
+            ].join('\n'),
+        });
+        await this.#state.setSlackThread(this.#workspaceId, issueKey(decision.issue), root.threadId);
+        this.#increment('triageEscalationsMirroredToSlack');
+        this.#recordSlackWritebackSuccess('triage-escalation-mirror');
+    }
     async #postAndWatchSlackEscalationThread(decision, reason) {
         if (!this.#slack || !this.#config.slack) {
             return;
         }
         const issue = await this.#readIssue(decision.issue.path);
+        const stakeholderMentions = slackMentions(this.#config.slack.stakeholderUserIds);
         const root = await this.#slack.postThread({
             channel: await this.#slackChannelDir() ?? this.#config.slack.channel,
             text: [
-                `${decision.issue.key}: factory triage escalation for ${issue?.title ?? decision.issue.key}`,
+                `${stakeholderMentions ? `${stakeholderMentions} ` : ''}${decision.issue.key}: factory triage escalation for ${issue?.title ?? decision.issue.key}`,
                 `Reason: ${reason}`,
                 `Question: ${triageEscalationQuestion(decision)}`,
             ].join('\n'),
@@ -6350,7 +6703,7 @@ export class FactoryLoop {
             }
             let threadId;
             try {
-                threadId = await this.#state.getSlackThread(this.#workspaceId, key);
+                threadId = await this.#persistedSlackThread(key);
             }
             catch (error) {
                 this.#logger.warn?.('[factory] unable to read persisted Slack thread during watcher rehydration', { issue: record.issue.key, error });
@@ -6845,6 +7198,7 @@ export class FactoryLoop {
     }
     async #resumeOrColdStartClarificationAgent(name, tracked, waiting) {
         const task = clarificationResumeTask(tracked.spec.task, waiting);
+        await this.#prepareAgentWorktree(waitingRecord(waiting), tracked.spec);
         if (tracked.sessionRef) {
             try {
                 const resumed = await this.#fleet.resume({
@@ -7054,7 +7408,7 @@ export class FactoryLoop {
         if (!this.#config.slack) {
             return undefined;
         }
-        const threadId = await this.#state.getSlackThread(this.#workspaceId, issueKey(record.issue));
+        const threadId = await this.#persistedSlackThread(issueKey(record.issue));
         const channel = await this.#slackChannelDir() ?? this.#config.slack.channel;
         return threadId
             ? { channel, threadId, mountRoot: this.#integrationsMountRoot() }
@@ -7595,36 +7949,35 @@ function routeImplementerSpec(issue, config, slug, route) {
         node: 'self',
     };
 }
-function decisionWithLifecycleBranches(decision, runId) {
-    const withBranch = (spec) => {
+function decisionWithLifecycleBranches(decision, runId, opts = {}) {
+    const implementerBranch = (spec) => {
+        const runSuffix = `-${runId.slice(0, 8)}`;
+        const stem = `${sanitizeAgentSlug(decision.issue.key)}-${sanitizeAgentSlug(spec.repo)}`
+            .slice(0, 120 - 'factory/'.length - runSuffix.length);
+        return `factory/${stem}${runSuffix}`;
+    };
+    const branchByRepo = new Map(decision.implementers.map((spec) => [spec.repo, implementerBranch(spec)]));
+    const withBranch = (spec, branch) => {
+        const baseClonePath = spec.baseClonePath ?? spec.clonePath;
+        const clonePath = opts.isolateLocalWorktree && baseClonePath && branch
+            ? factoryWorktreePath(baseClonePath, decision.issue.key, spec.repo, runId)
+            : spec.clonePath;
         const lifecycleSpec = {
             ...spec,
+            ...(opts.isolateLocalWorktree && baseClonePath && branch ? { baseClonePath, clonePath } : {}),
             // The same persisted lifecycle reuses this id after takeover, while a
             // genuine reopen gets a new id and cannot replay an old placement ack.
             invocationId: `factory:${decision.issue.key}:${runId}:${spec.role}:${sanitizeAgentSlug(spec.name)}`,
         };
-        if (spec.role !== 'implementer')
-            return lifecycleSpec;
-        const runSuffix = `-${runId.slice(0, 8)}`;
-        const stem = `${sanitizeAgentSlug(decision.issue.key)}-${sanitizeAgentSlug(spec.repo)}`
-            .slice(0, 120 - 'factory/'.length - runSuffix.length);
-        const branch = `factory/${stem}${runSuffix}`;
-        return {
-            ...lifecycleSpec,
-            branch,
-            task: [
-                spec.task,
-                '',
-                `Factory publication branch: ${branch}`,
-                'Before editing, create or reset that exact branch from the repository default branch. Commit and push only that branch.',
-            ].join('\n'),
-        };
+        return branch ? { ...lifecycleSpec, branch } : lifecycleSpec;
     };
     return {
         ...structuredClone(decision),
-        implementers: decision.implementers.map(withBranch),
-        reviewer: withBranch(decision.reviewer),
-        ...(decision.workflow ? { workflow: withBranch(decision.workflow) } : {}),
+        implementers: decision.implementers.map((spec) => withBranch(spec, branchByRepo.get(spec.repo))),
+        reviewer: withBranch(decision.reviewer, branchByRepo.get(decision.reviewer.repo)),
+        ...(decision.workflow
+            ? { workflow: withBranch(decision.workflow, branchByRepo.get(decision.workflow.repo)) }
+            : {}),
     };
 }
 function routeReviewerSpec(issue, config, route, reviewer) {
@@ -7724,12 +8077,21 @@ function taskForDispatch(issue, route, role) {
         issue.description,
     ].join('\n\n');
 }
-const templateIssueFromRecord = (record, issue) => ({
-    key: issue?.key ?? record.issue.key,
-    title: issue?.title ?? record.issue.key,
-    description: issue?.description ?? '',
-    github: issue ? githubIssueSourceRef(issue) : undefined,
-});
+const templateIssueFromRecord = (record, issue) => {
+    const github = issue ? githubIssueSourceRef(issue) : undefined;
+    const reporter = issue ? githubIssueAuthor(issue) : undefined;
+    return {
+        key: issue?.key ?? record.issue.key,
+        title: issue?.title ?? record.issue.key,
+        description: issue?.description ?? '',
+        github: github
+            ? {
+                ...github,
+                ...(reporter ? { reporter } : {}),
+            }
+            : undefined,
+    };
+};
 const routeForSpec = (decision, spec) => {
     const route = decision.routes.find((candidate) => candidate.repo === spec.repo && candidate.clonePath === spec.clonePath) ?? decision.routes.find((candidate) => candidate.repo === spec.repo);
     return {
@@ -8006,24 +8368,69 @@ const reposFromConfig = (config) => {
     ].filter((repo) => Boolean(repo)));
     return [...repos];
 };
-const githubIssueScanRoots = (config) => {
-    const roots = new Set([GITHUB_ISSUE_ROOT]);
-    for (const repo of reposFromConfig(config)) {
-        const parts = githubRepoParts(repo);
+const configuredGithubRepoParts = (config) => {
+    const repos = new Map();
+    for (const configuredRepo of reposFromConfig(config)) {
+        let parts = githubRepoParts(configuredRepo);
+        if (!parts) {
+            try {
+                parts = githubRepoParts(normalizeGithubRepo(configuredRepo, config.repos.org));
+            }
+            catch {
+                continue;
+            }
+        }
         if (!parts)
             continue;
-        roots.add(`/github/repos/${parts.owner}__${parts.repo}/issues/by-id`);
+        repos.set(`${parts.owner.toLowerCase()}/${parts.repo.toLowerCase()}`, parts);
+    }
+    return [...repos.values()];
+};
+// A terminal `**` is intentional: relayfile's matcher treats a non-terminal
+// `**` as a single-segment wildcard. Scoping at the repository root still
+// covers every supported issue, PR, review, comment, and check path without
+// subscribing this factory to other repositories in the workspace.
+export const githubRepoSubscriptionGlobs = (config) => configuredGithubRepoParts(config).flatMap(({ owner, repo }) => [
+    `${GITHUB_ISSUE_ROOT}/${owner}/${repo}/**`,
+    `${GITHUB_ISSUE_ROOT}/${owner}__${repo}/**`,
+]);
+const githubIssueScanRoots = (config) => {
+    const roots = new Set();
+    for (const { owner, repo } of configuredGithubRepoParts(config)) {
+        roots.add(`${GITHUB_ISSUE_ROOT}/${owner}/${repo}/issues`);
+        roots.add(`${GITHUB_ISSUE_ROOT}/${owner}__${repo}/issues`);
     }
     return [...roots];
 };
+const githubRepoPathParts = (path) => {
+    const compactSegment = path.match(/^\/github\/repos\/([^/]+)\//u)?.[1];
+    const separator = compactSegment?.indexOf('__') ?? -1;
+    if (compactSegment && separator > 0 && separator < compactSegment.length - 2) {
+        return {
+            owner: compactSegment.slice(0, separator),
+            repo: compactSegment.slice(separator + 2),
+        };
+    }
+    const nested = path.match(/^\/github\/repos\/([^/]+)\/([^/]+)\//u);
+    if (nested)
+        return { owner: nested[1], repo: nested[2] };
+    return undefined;
+};
+const isConfiguredGithubRepoPath = (path, config) => {
+    const pathParts = githubRepoPathParts(path);
+    if (!pathParts)
+        return false;
+    const pathRepo = `${pathParts.owner.toLowerCase()}/${pathParts.repo.toLowerCase()}`;
+    return configuredGithubRepoParts(config).some(({ owner, repo }) => `${owner.toLowerCase()}/${repo.toLowerCase()}` === pathRepo);
+};
 const githubRepoParts = (repo) => {
     const split = repo.match(/^([^/]+)\/([^/]+)$/u);
     if (split) {
         return { owner: split[1], repo: split[2] };
     }
-    const compact = repo.match(/^([^/]+)__([^/]+)$/u);
-    if (compact) {
-        return { owner: compact[1], repo: compact[2] };
+    const separator = repo.indexOf('__');
+    if (separator > 0 && separator < repo.length - 2 && !repo.includes('/')) {
+        return { owner: repo.slice(0, separator), repo: repo.slice(separator + 2) };
     }
     return undefined;
 };
@@ -8660,12 +9067,10 @@ const isAgentAlreadyExistsError = (error) => {
     return /already exists/iu.test(message);
 };
 const defaultRestartPolicy = (spec) => 
-// Implementers and babysitters are both long-running and resumable — the
-// babysitter shepherds an open PR over many CI/review cycles, so an abnormal
-// exit should resume its session rather than drop the PR. The reviewer is
-// short-lived and keeps the fleet default.
+// Factory owns durable resume/respawn decisions. Broker-level retries race
+// that lifecycle and can re-register the same name before Factory resumes it.
 spec.role === 'implementer' || spec.role === 'babysitter'
-    ? { maxRestarts: 3, strategy: 'resume' }
+    ? { maxRestarts: 0 }
     : spec.restartPolicy;
 const slackPayloadTs = (threadId) => threadId.replace(/_/g, '.');
 const slackChannelMessagesPrefix = (channelDir) => `/slack/channels/${channelDir}/messages/`;