@agent-relay/factory 0.1.79 → 0.1.81

package/dist/orchestrator/factory.js

@@ -6,7 +6,7 @@ import { DEFAULT_DISCOVERY_SWEEP_BUDGET_MS, DEFAULT_READINESS_RECONCILE_TIMEOUT_
 import { DEFAULT_RELAYFILE_OPERATION_TIMEOUT_MS, RelayfileOperationTimeoutError, relayfileTimeoutWithPhase, withRelayfileCallDeadline, } from '../mount/relayfile-operation-timeout.js';
 import { linearByStatePath, linearByIdPath, linearByUuidPath } from '../constants/linear.js';
 import { stateResolutionFromIds } from '../linear/state-resolver.js';
-import { GithubMergeGate, closeProbePr } from '../github/index.js';
+import { GhCliGithubMergeGate, MountedGithubMergeGate, 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';
@@ -64,8 +64,7 @@ const LIVE_EVENT_DRAIN_BATCH_SIZE = 5;
 const COMPLETION_SWEEP_INTERVAL_MS = 15_000;
 const COMPLETION_SWEEP_BATCH_SIZE = 2;
 const PREVIEW_SWEEP_INTERVAL_MS = 60_000;
-const PROBE_PR_GH_BACKOFF_MS = 60_000;
-const PROBE_PR_GH_CANDIDATE_LIMIT = 200;
+const PROBE_PR_RESOLVED_CACHE_MS = 60_000;
 const PUBLISHED_PR_CONFIRM_ATTEMPTS = 20;
 const PUBLISHED_PR_CONFIRM_DELAY_MS = 100;
 const SLACK_REPLY_EVENTS_LIMIT = 100;
@@ -119,8 +118,8 @@ const BABYSITTER_PR_SNAPSHOT_DEAD_LETTER_LIMIT = 256;
 const BABYSITTER_PR_SNAPSHOT_DRAIN_PER_SWEEP = 16;
 // A durably faulted mount would otherwise log an error per path per sweep.
 const BABYSITTER_PR_SNAPSHOT_ESCALATED_LOG_EVERY = 20;
-// Adoption probes an issue's open PR through the (already gh-backed-off) probe
-// resolver, so it runs on its own slower cadence than the completion sweep.
+// Adoption probes an issue's open PR through the mounted projection, so its
+// full-tree fallback runs on a slower cadence than the completion sweep.
 const BABYSITTER_ORPHAN_SWEEP_INTERVAL_MS = 60_000;
 // Warn once per PR identity that arrives unowned, then fall back to debug. The
 // counter carries the true volume; the log only has to make it discoverable.
@@ -156,6 +155,8 @@ const STOP_REJECTED_DISPATCH_DRAIN_TIMEOUT_MS = 2_500;
 const DISPATCH_LIFECYCLE_LEASE_MS = 5 * 60_000;
 const DISPATCH_LIFECYCLE_RENEW_MS = 60_000;
 const DISPATCH_LIFECYCLE_RETRY_MS = 1_000;
+const REMOTE_AGENT_REGISTRATION_TIMEOUT_MS = 30_000;
+const REMOTE_AGENT_REGISTRATION_POLL_MS = 500;
 /**
  * Ceiling on the durable capacity-wait re-arm (#303).
  *
@@ -349,6 +350,26 @@ class DispatchLifecycleOwnedElsewhereError extends Error {
         this.leaseUntilMs = leaseUntilMs;
     }
 }
+class FleetPlacementUnavailableError extends Error {
+    capability;
+    constructor(capability) {
+        super(`Refusing remote dispatch: no live fleet node advertises ${capability}`);
+        this.capability = capability;
+        this.name = 'FleetPlacementUnavailableError';
+    }
+}
+class RemoteAgentRegistrationTimeoutError extends Error {
+    agentName;
+    cleanupConfirmed;
+    cleanupError;
+    constructor(agentName, cleanupConfirmed, cleanupError) {
+        super(`Remote agent ${agentName} did not register with the fleet before the startup deadline`);
+        this.agentName = agentName;
+        this.cleanupConfirmed = cleanupConfirmed;
+        this.cleanupError = cleanupError;
+        this.name = 'RemoteAgentRegistrationTimeoutError';
+    }
+}
 /**
  * The durable dispatch-lifecycle claim was refused for one work unit: its
  * record is already terminal, or another publisher currently holds the lease.
@@ -435,10 +456,9 @@ export class FactoryLoop {
     #mergeGate;
     #verificationGate;
     #probeCloser;
+    #defaultProbeCloser;
     #probePrResolver;
     #customProbePrResolver;
-    #hasProbePrGhRunner;
-    #probePrGhRunner;
     #logger;
     #clock;
     #processIdentityReader;
@@ -450,6 +470,7 @@ export class FactoryLoop {
     #babysitterWakeUnreachableRetryMs;
     #startupAgentExitDrainTimeoutMs;
     #dispatchLifecycleRetryMs;
+    #dispatchLifecycleRenewMs;
     #state;
     #workspaceId;
     #relayflows;
@@ -764,7 +785,6 @@ export class FactoryLoop {
     #publishedPullRequests = new Map();
     #previewReferences = new Map();
     #removedPreviewIds = new Set();
-    #probePrGhBackoffUntilMs = new Map();
     #probePrResolvedCache = new Map();
     // GitHub issue mirror-id -> resolved Linear mirror path, so repeat ingestion
     // cycles read the mirror directly instead of re-scanning all Linear issues.
@@ -857,7 +877,7 @@ export class FactoryLoop {
         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();
+        this.#mergeGate = ports.mergeGate ?? defaultMergeGate(config, ports.mount);
         this.#verificationGate = ports.verificationGate ?? (config.verification.enabled
             ? new VerificationPipeline({
                 descriptorPath: config.verification.descriptorPath,
@@ -869,10 +889,9 @@ export class FactoryLoop {
                 maxTeardownTimeoutMs: config.verification.maxTeardownTimeoutMs,
             })
             : undefined);
+        this.#defaultProbeCloser = !ports.probeCloser;
         this.#probeCloser = ports.probeCloser ?? closeProbePr;
         this.#customProbePrResolver = Boolean(ports.probePrResolver);
-        this.#hasProbePrGhRunner = Boolean(ports.probePrGhRunner);
-        this.#probePrGhRunner = ports.probePrGhRunner ?? failClosedGhRunner;
         this.#probePrResolver = ports.probePrResolver ??
             ((issue) => this.#resolveIssuePr(issue, { repo: this.#probeRepoForIssue(issue) }));
         this.#logger = normalizeLogger(ports.logger ?? console);
@@ -896,6 +915,7 @@ export class FactoryLoop {
         this.#babysitterWakeUnreachableRetryMs = ports.babysitterWakeUnreachableRetryMs ?? BABYSITTER_WAKE_UNREACHABLE_RETRY_MS;
         this.#startupAgentExitDrainTimeoutMs = ports.startupAgentExitDrainTimeoutMs ?? STARTUP_AGENT_EXIT_DRAIN_TIMEOUT_MS;
         this.#dispatchLifecycleRetryMs = ports.dispatchLifecycleRetryMs ?? DISPATCH_LIFECYCLE_RETRY_MS;
+        this.#dispatchLifecycleRenewMs = ports.dispatchLifecycleRenewMs ?? DISPATCH_LIFECYCLE_RENEW_MS;
         this.#workspaceId = config.workspaceId ?? 'default';
         this.#relayflows = ports.relayflows;
         this.#worktrees = ports.worktrees;
@@ -2397,11 +2417,6 @@ export class FactoryLoop {
                     }
                     if (pr.draft) {
                         this.#increment('completionSweepDraftPr');
-                        // Must match the key `#completionPrForIssue` resolves under —
-                        // same options, same repo scope — or this backoff is written
-                        // under a name nothing reads and the draft PR is re-fetched from
-                        // gh on every pass.
-                        this.#probePrGhBackoffUntilMs.set(this.#probePrCacheKey(issue, { repo: this.#probeRepoForIssue(issue) }), this.#clock.now() + PROBE_PR_GH_BACKOFF_MS);
                         return undefined;
                     }
                     if (record.decision.implementers.length > 1 && !await this.#allImplementersHaveCompletionPr(record)) {
@@ -2533,9 +2548,7 @@ export class FactoryLoop {
         }
     }
     // Candidate PR meta paths for an ownerless record, newest PR first. Resolution
-    // reuses the durable dispatch receipts and then the probe resolver (which
-    // carries its own gh backoff, so a record whose implementer has not opened a
-    // PR yet costs no more than a cached miss).
+    // reuses the durable dispatch receipts and then the mounted probe resolver.
     async #orphanedPrMetaPaths(record) {
         const wanted = [];
         if (this.#usesDurableDispatchLifecycle()) {
@@ -2684,19 +2697,13 @@ export class FactoryLoop {
         return dependencyRepoForIssue(issue, undefined, this.#config, { allowDefault: false });
     }
     /**
-     * The key for BOTH `#probePrResolvedCache` and `#probePrGhBackoffUntilMs`.
-     *
-     * Shared rather than inlined because those two maps are written from more than
-     * one place: `#resolveIssuePr` writes both, and the completion sweep writes a
-     * draft-PR backoff directly. Those writes must agree on the key or the backoff
-     * is set under a name nothing reads, which silently costs a gh call per pass.
+     * The key for `#probePrResolvedCache`.
      *
      * `repo` is part of the key because it narrows which pull requests the
      * resolution can even see — an issue whose route changes must not be served
-     * the previous repository's PR, or held off gh by the previous repository's
-     * negative backoff, because the completion path probes and CLOSES what this
-     * returns. `*` marks the unscoped walk, a genuinely different resolution that
-     * must not share an entry with any single-repo one.
+     * the previous repository's PR, because the completion path probes and
+     * CLOSES what this returns. `*` marks the unscoped walk, a genuinely
+     * different resolution that must not share an entry with any single-repo one.
      *
      * Every dimension is a trailing `:`-prefixed segment so the completion
      * invalidation — which clears `stateKey` plus everything starting
@@ -2721,31 +2728,13 @@ export class FactoryLoop {
             // method. The cache had a reader and no writer on the hot path, so the
             // full tree walk repeated for every caller, on every sweep, forever.
             //
-            // Cached on the same terms as the gh branch below — same key, same TTL,
-            // same draft exclusion — because the reason to keep a draft uncached is a
-            // property of the PR (its state is about to flip and the caller wants to
-            // see that promptly), not of which resolver observed it.
+            // Keep drafts uncached because their state is expected to flip and callers
+            // need to observe that promptly.
             if (!mountPr.draft) {
-                this.#probePrResolvedCache.set(key, { pr: mountPr, expiresAtMs: now + PROBE_PR_GH_BACKOFF_MS });
+                this.#probePrResolvedCache.set(key, { pr: mountPr, expiresAtMs: now + PROBE_PR_RESOLVED_CACHE_MS });
             }
             return mountPr;
         }
-        const backoffUntil = this.#probePrGhBackoffUntilMs.get(key) ?? 0;
-        if (backoffUntil > now) {
-            this.#increment('probePrGhBackoffSkips');
-            return undefined;
-        }
-        const ghPr = await resolveIssuePrFromGh(this.#probePrGhRunner, this.#config, issue, opts, this.#logger);
-        this.#increment('probePrGhResolveAttempts');
-        if (ghPr) {
-            this.#probePrGhBackoffUntilMs.delete(key);
-            if (!ghPr.draft) {
-                this.#probePrResolvedCache.set(key, { pr: ghPr, expiresAtMs: now + PROBE_PR_GH_BACKOFF_MS });
-            }
-            this.#increment('probePrGhResolveHits');
-            return ghPr;
-        }
-        this.#probePrGhBackoffUntilMs.set(key, now + PROBE_PR_GH_BACKOFF_MS);
         return undefined;
     }
     async runOnce(opts = {}) {
@@ -2783,8 +2772,9 @@ export class FactoryLoop {
     }
     async #assertFleetControlPlaneAvailable() {
         try {
-            await this.#fleet.roster();
+            const roster = await this.#fleet.roster();
             this.#increment('fleetControlPlaneProbeSuccesses');
+            return roster;
         }
         catch (error) {
             const health = this.#fleetControlPlane.status();
@@ -5019,8 +5009,10 @@ export class FactoryLoop {
         // consuming a dispatch attempt. The mutation proxy probes again at the
         // actual spawn/resume boundary so a later control-plane fault still fails
         // closed.
-        if (!dryRun)
-            await this.#assertFleetControlPlaneAvailable();
+        const admissionRoster = !dryRun ? await this.#assertFleetControlPlaneAvailable() : undefined;
+        if (admissionRoster && this.#fleet.placementLocality === 'remote') {
+            dispatchDecision = decisionWithVerifiedRemotePlacements(dispatchDecision, admissionRoster);
+        }
         const durableDispatch = !dryRun && this.#usesDurableDispatchLifecycle();
         // Local dispatches need the same deterministic branch identity as remote
         // ones. Without it, every worker starts in the configured shared checkout
@@ -5437,6 +5429,13 @@ export class FactoryLoop {
                 throw error;
             }
             settlePostSpawnIssueObservation(!(error instanceof LiveDispatchStateChangedError));
+            if ((error instanceof FleetPlacementUnavailableError ||
+                (error instanceof RemoteAgentRegistrationTimeoutError && error.cleanupConfirmed)) &&
+                await this.#rollbackUnregisteredRemoteDispatch(record, spawnedForReaperHandoff)) {
+                this.#increment('remoteDispatchAdmissionRollbacks');
+                this.#error(error, decision.issue);
+                throw error;
+            }
             // A spawn can fail after the broker accepted it but before its ack
             // reached Factory. Include every planned worktree agent, not only the
             // acknowledged spawns, so cleanup never races a name-only survivor.
@@ -6188,7 +6187,7 @@ export class FactoryLoop {
             return;
         this.#dispatchLifecycleRenewTimer = setInterval(() => {
             void this.#renewDispatchLifecycles();
-        }, DISPATCH_LIFECYCLE_RENEW_MS);
+        }, this.#dispatchLifecycleRenewMs);
         this.#dispatchLifecycleRenewTimer.unref?.();
     }
     /**
@@ -6385,6 +6384,18 @@ export class FactoryLoop {
     }
     async #renewDispatchLifecycles() {
         for (const [key, epoch] of [...this.#dispatchLifecycleEpochs]) {
+            // The snapshot above can outlive the ownership it records: a relinquish
+            // that runs while this loop is awaiting the store for an earlier key
+            // leaves a stale entry here, and renewing it would re-block a key this
+            // process has already handed back (#391 review, P2). Re-read the live map
+            // rather than trusting the snapshot.
+            //
+            // This narrows the window but does not close it on its own — the delete
+            // can still land after this check and before the renew resolves. Closing
+            // it is `renewDispatchLifecycle`'s expiry fence, which makes a
+            // relinquished lease unrenewable no matter how the two race.
+            if (this.#dispatchLifecycleEpochs.get(key) !== epoch)
+                continue;
             const renewed = await this.#state.renewDispatchLifecycle(this.#workspaceId, key, this.#dispatchLifecycleOwner, epoch, this.#clock.now(), DISPATCH_LIFECYCLE_LEASE_MS);
             if (!renewed) {
                 this.#dispatchLifecycleEpochs.delete(key);
@@ -6985,8 +6996,17 @@ export class FactoryLoop {
      * the only thing still running is the spin.
      */
     #chargeReleaseAttempt(record, key, context) {
-        if (this.#dispatchLifecycleReleaseAbandoned.has(key))
+        if (this.#dispatchLifecycleReleaseAbandoned.has(key)) {
+            // Re-entry, and the reason relinquishing the lease once is not enough.
+            // `#driveDispatchLifecycle` re-claims the lease at the TOP of every
+            // drive, before it has read the phase, so anything that drives an
+            // already-dead-lettered key — the held-agent-deadline sweep, a registry
+            // restore, a takeover — puts the epoch straight back into the renewal
+            // map and re-arms the livelock this bound just escaped. Whenever the
+            // budget declines a re-arm, ownership goes back too.
+            this.#trackDispatchLifecycleDrive(this.#relinquishDispatchLifecycleLease(key, record.issue.key));
             return false;
+        }
         const attempts = (this.#dispatchLifecycleReleaseAttempts.get(key) ?? 0) + 1;
         this.#dispatchLifecycleReleaseAttempts.set(key, attempts);
         if (attempts <= DISPATCH_LIFECYCLE_MAX_RELEASE_ATTEMPTS)
@@ -6995,6 +7015,19 @@ export class FactoryLoop {
         this.#dispatchLifecycleReleaseAttempts.delete(key);
         this.#increment('dispatchLifecycleReleaseAbandoned');
         const durableLifecycleRetained = this.#usesDurableDispatchLifecycle();
+        // Cleanup is armed BEFORE anything that can throw (#391 review, P1). The
+        // only statements above are set/map writes and a counter, none of which can
+        // reject; `this.#logger.error` below is caller-supplied and can. Ordering
+        // the drive first means nothing between "this unit is abandoned" and "its
+        // lease is handed back" is allowed to fail in a way that skips the handback
+        // — which is precisely the defect shape this whole method exists to fix.
+        this.#trackDispatchLifecycleDrive(this.#releaseDeadLetteredSlot(record, key)
+            .catch((error) => {
+            this.#logger.warn?.('[factory] dead-lettered release could not free its batch slot', {
+                issue: record.issue.key,
+                error: describeError(error).errorMessage,
+            });
+        }));
         // `error`, not `warn`. Every previous layer of this failure was invisible
         // until somebody read stderr by hand; a work unit whose cleanup this
         // process has permanently given up on is exactly the event that must not
@@ -7009,16 +7042,63 @@ export class FactoryLoop {
             // spin, it does not declare the work unit clean.
             durableLifecycleRetained,
         });
-        const drive = this.#releaseDeadLetteredSlot(record, key)
-            .catch((error) => {
-            this.#logger.warn?.('[factory] dead-lettered release could not free its batch slot', {
-                issue: record.issue.key,
+        return false;
+    }
+    /** Keeps a lifecycle-side effect awaitable by `stop()` without leaking the set entry. */
+    #trackDispatchLifecycleDrive(promise) {
+        const drive = promise.finally(() => this.#dispatchLifecycleDrives.delete(drive));
+        this.#dispatchLifecycleDrives.add(drive);
+    }
+    /**
+     * Stop asserting durable ownership of a work unit this process will not drive
+     * again.
+     *
+     * `#dispatchLifecycleEpochs` is not merely a cache. `#renewDispatchLifecycles`
+     * walks it every `DISPATCH_LIFECYCLE_RENEW_MS` and re-stamps a full
+     * `DISPATCH_LIFECYCLE_LEASE_MS` onto every key it finds, unconditionally.
+     *
+     * A dead-lettered release deliberately leaves its row in the non-terminal
+     * `releasing` phase so a successor or a restart can re-drive the cleanup with
+     * a fresh budget. That is only a recovery path if the successor can CLAIM the
+     * row — and a lease renewed forever by a process that has permanently given
+     * up driving it is a claim nobody can ever win. #379 bounded the retry and
+     * handed back the batch slot, then kept the key locked for the life of the
+     * process, which is how production reached four issues (a dispatch canary
+     * among them) all logging `durable dispatch is leased by another publisher`
+     * at 1 Hz for three days while the holder logged nothing but 503
+     * `agent_host_unavailable`.
+     *
+     * The epoch is dropped BEFORE the durable release, so a renewal tick that
+     * STARTS after this point finds nothing to renew. That ordering alone is not
+     * sufficient and an earlier version of this comment wrongly claimed it was
+     * (#391 review, P2): `#renewDispatchLifecycles` iterates a snapshot array, so
+     * a tick already in flight still holds this key and would restore the lease
+     * for a full term. The guarantee comes from `renewDispatchLifecycle` fencing
+     * on expiry as well as owner and epoch, which makes a relinquished lease
+     * unrenewable however the two race; the epoch drop and the loop's live re-read
+     * narrow the window ahead of it.
+     *
+     * If the durable release itself fails, the dropped epoch alone still ends the
+     * livelock: nothing renews the lease any more, so it expires within
+     * `DISPATCH_LIFECYCLE_LEASE_MS` instead of never.
+     */
+    async #relinquishDispatchLifecycleLease(key, issueKey) {
+        const epoch = this.#dispatchLifecycleEpochs.get(key);
+        if (epoch === undefined)
+            return;
+        this.#dispatchLifecycleEpochs.delete(key);
+        try {
+            await this.#state.releaseDispatchLifecycleLease(this.#workspaceId, key, this.#dispatchLifecycleOwner, epoch);
+            this.#increment('dispatchLifecycleLeasesRelinquished');
+        }
+        catch (error) {
+            this.#logger.warn?.('[factory] could not relinquish the dispatch lease of an abandoned work unit', {
+                issue: issueKey,
+                // The lease still expires on its own now that nothing renews it.
+                expiresWithinMs: DISPATCH_LIFECYCLE_LEASE_MS,
                 error: describeError(error).errorMessage,
             });
-        })
-            .finally(() => this.#dispatchLifecycleDrives.delete(drive));
-        this.#dispatchLifecycleDrives.add(drive);
-        return false;
+        }
     }
     /**
      * Hand back the batch slot of a work unit whose release was dead-lettered.
@@ -7035,12 +7115,36 @@ export class FactoryLoop {
      * local slot does not write a terminal phase. On a local lifecycle there is
      * no durable record to retain, so the batch record is all there is and
      * completing it is what keeps capacity honest.
+     *
+     * The DURABLE lease has to go back with the slot. Retaining the row for a
+     * successor while renewing the lease that locks the successor out is not a
+     * handoff, it is a permanent block on the key — see
+     * `#relinquishDispatchLifecycleLease`.
+     *
+     * The handback lives in a `finally` for a reason worth stating plainly
+     * (#391 review, P1). The FIRST version of this fix relinquished after
+     * `#writeInFlightRegistry()`, on the happy path only — so a rejecting
+     * registry write would skip it and leave the abandoned key renewing its lease
+     * forever, with nothing but a `warn` to show for it. That is the identical
+     * shape of the bug being fixed (#379 freed the slot but not the lease, on the
+     * failure path), reproduced one level up. Cleanup that only runs when the
+     * rest of cleanup succeeded is not cleanup. `#batch()` and
+     * `#writeInFlightRegistry()` can both reject; neither may strand the key.
      */
     async #releaseDeadLetteredSlot(record, key) {
-        const batch = await this.#batch();
-        const next = batch.complete(record.issue);
-        this.#uncompensatedDispatchClaims.delete(key);
-        await this.#writeInFlightRegistry();
+        let next;
+        try {
+            const batch = await this.#batch();
+            next = batch.complete(record.issue);
+            this.#uncompensatedDispatchClaims.delete(key);
+            await this.#writeInFlightRegistry();
+        }
+        finally {
+            // Unconditional, and safe to put in a `finally` because
+            // `#relinquishDispatchLifecycleLease` handles its own errors and cannot
+            // throw — so it can never mask the failure that brought us here.
+            await this.#relinquishDispatchLifecycleLease(key, record.issue.key);
+        }
         // A freed slot that nothing is admitted into is only half the repair.
         if (next && !this.#stopping)
             await this.dispatch(next.decision, { dryRun: next.dryRun });
@@ -8084,18 +8188,18 @@ export class FactoryLoop {
                 const roots = githubIssueRepoRoots(owner, repo);
                 const cachedBatches = roots.map((root) => this.#cachedDiscoveryTree(root));
                 const allRootsCached = cachedBatches.every((paths) => paths !== undefined);
-                const indexedPaths = allRootsCached
-                    ? undefined
-                    : await this.#githubIssuePathsFromIndex(owner, repo);
+                // The issue index is the current eligibility authority, while the
+                // durable trees are only an incremental fallback for mounts whose
+                // index is absent or malformed. A checkpoint can legitimately retain
+                // stale membership (for example across an older cache format or a
+                // missed change window); letting two cached roots bypass a healthy
+                // index makes that stale snapshot self-validating forever.
+                const indexedPaths = await this.#githubIssuePathsFromIndex(owner, repo);
                 // Keep the fallback roots as separate batches. Flattening a very large
                 // provider result is synchronous work and can starve the durable loop
                 // heartbeat before the bounded scan below gets a chance to yield.
                 let pathBatches;
-                if (allRootsCached) {
-                    pathBatches = cachedBatches;
-                    this.#increment('githubIssueDiscoveryCacheReposUsed');
-                }
-                else if (indexedPaths) {
+                if (indexedPaths) {
                     // Do not feed this into the discovery cache: the index only covers
                     // open, labeled issues, so it is a filtered subset of the real
                     // tree (and an empty result for whichever root form the index
@@ -8105,6 +8209,10 @@ export class FactoryLoop {
                     pathBatches = [indexedPaths];
                     this.#increment('githubIssueIndexReposUsed');
                 }
+                else if (allRootsCached) {
+                    pathBatches = cachedBatches;
+                    this.#increment('githubIssueDiscoveryCacheReposUsed');
+                }
                 else {
                     pathBatches = [];
                     for (const root of roots) {
@@ -8642,9 +8750,9 @@ export class FactoryLoop {
         const repo = dependencyRepoForIssue(issue, undefined, this.#config);
         if (!repo)
             return false;
-        // This probe does NOT go through `#resolveIssuePr` — it must not fall back to
-        // gh — so it never saw that method's cache, and `#terminalDependencyIdentities`
-        // only ever memoises the TRUE answer. A dependency that is not merged was
+        // This specialized probe does not go through `#resolveIssuePr`, so it never
+        // saw that method's cache, and `#terminalDependencyIdentities` only ever
+        // memoises the TRUE answer. A dependency that is not merged was
         // therefore re-walked in full for every issue declaring it, on every sweep;
         // several issues blocked on one dependency multiplied a single tree walk by
         // the number of blocked issues. Memoise the negative answer too, on exactly
@@ -9585,13 +9693,6 @@ export class FactoryLoop {
             batch.recordDryRun(record, spec, invocationId);
             return { name: spec.name };
         }
-        // Persist intent before the remote side effect. If the owner crashes after
-        // the spawn ack but before recording its result, takeover retries the same
-        // deterministic invocation id instead of inventing a second worker.
-        batch.recordPlanned(record, { ...spec, invocationId });
-        if (!await this.#saveDispatchLifecycle(record, 'dispatching')) {
-            throw new Error(`Dispatch lifecycle ownership lost before spawning ${spec.name}`);
-        }
         let roster;
         try {
             roster = await retryOnTimeout(() => this.#fleet.roster(), { attempts: 3, delayMs: 2000 });
@@ -9601,6 +9702,15 @@ export class FactoryLoop {
         }
         const rosterAgent = roster.agents.find((agent) => agent.name === spec.name);
         if (rosterAgent) {
+            if (this.#fleet.placementLocality === 'remote') {
+                const host = rosterAgent.node
+                    ? roster.nodes.find((node) => node.name === rosterAgent.node && node.live && node.capabilities.includes(spec.capability))
+                    : undefined;
+                if (!host) {
+                    throw new FleetPlacementUnavailableError(spec.capability);
+                }
+                spec = { ...spec, node: host.name };
+            }
             const trackedPlacement = this.#fleet.trackedAgents?.().get(spec.name);
             record.heldSinceAtMs ??= this.#clock.now();
             batch.recordSpawn(record, spec, invocationId, {
@@ -9618,6 +9728,21 @@ export class FactoryLoop {
                 await this.#reportAgent(record, adopted, 'agent.adopted');
             return { name: spec.name };
         }
+        if (this.#fleet.placementLocality === 'remote') {
+            const loads = new Map();
+            for (const agent of roster.agents) {
+                if (agent.node)
+                    loads.set(agent.node, (loads.get(agent.node) ?? 0) + 1);
+            }
+            spec = { ...spec, node: liveFleetNodeForSpec(spec, roster, loads) };
+        }
+        // Persist intent before the remote side effect. If the owner crashes after
+        // the spawn ack but before recording its result, takeover retries the same
+        // deterministic invocation id instead of inventing a second worker.
+        batch.recordPlanned(record, { ...spec, invocationId });
+        if (!await this.#saveDispatchLifecycle(record, 'dispatching')) {
+            throw new Error(`Dispatch lifecycle ownership lost before spawning ${spec.name}`);
+        }
         await this.#prepareAgentWorktree(record, spec);
         let result;
         try {
@@ -9657,6 +9782,26 @@ export class FactoryLoop {
             await this.#releaseOrphanedLatePlacement(record, spec, result);
             throw new LatePlacementReleasedError(record.issue.key, result.name ?? spec.name);
         }
+        if (this.#fleet.placementLocality === 'remote') {
+            const registered = await this.#awaitRemoteAgentRegistration(result.name, spec.capability, result.node);
+            if (!registered) {
+                try {
+                    await this.#fleet.release(result.name, 'spawn-registration-timeout');
+                    this.#fleet.markAgentTerminal?.(result.name, 'spawn-registration-timeout');
+                    throw new RemoteAgentRegistrationTimeoutError(result.name, true);
+                }
+                catch (error) {
+                    if (error instanceof RemoteAgentRegistrationTimeoutError)
+                        throw error;
+                    // Cleanup is unconfirmed. Persist the placement so a successor can
+                    // retry the release; forgetting it would be worse than retaining a
+                    // nonterminal lifecycle for a worker that may still be alive.
+                    batch.recordSpawn(record, spec, invocationId, result);
+                    await this.#saveDispatchLifecycle(record, 'dispatching');
+                    throw new RemoteAgentRegistrationTimeoutError(result.name, false, error);
+                }
+            }
+        }
         record.heldSinceAtMs ??= this.#clock.now();
         batch.recordSpawn(record, spec, invocationId, result);
         if (!await this.#saveDispatchLifecycle(record, 'dispatching')) {
@@ -9668,6 +9813,89 @@ export class FactoryLoop {
             await this.#reportAgent(record, spawned, 'agent.spawned');
         return { name: result.name };
     }
+    async #awaitRemoteAgentRegistration(name, capability, expectedNode) {
+        const deadlineAtMs = this.#clock.now() + REMOTE_AGENT_REGISTRATION_TIMEOUT_MS;
+        do {
+            try {
+                if (expectedNode) {
+                    if (this.#fleet.isAgentRegistered) {
+                        if (await this.#fleet.isAgentRegistered({ name, node: expectedNode, capability }))
+                            return true;
+                    }
+                    else {
+                        const roster = await this.#fleet.roster();
+                        const agent = roster.agents.find((candidate) => candidate.name === name && candidate.node === expectedNode);
+                        const node = agent
+                            ? roster.nodes.find((candidate) => candidate.name === expectedNode && candidate.live && candidate.capabilities.includes(capability))
+                            : undefined;
+                        if (agent && node)
+                            return true;
+                    }
+                }
+            }
+            catch (error) {
+                this.#logger.warn?.('[factory] remote agent registration probe failed; retrying within startup bound', {
+                    agent: name,
+                    error: describeError(error).errorMessage,
+                });
+            }
+            const remainingMs = deadlineAtMs - this.#clock.now();
+            if (remainingMs <= 0)
+                return false;
+            await this.#clock.sleep(Math.min(REMOTE_AGENT_REGISTRATION_POLL_MS, remainingMs));
+        } while (this.#clock.now() <= deadlineAtMs);
+        return false;
+    }
+    async #rollbackUnregisteredRemoteDispatch(record, acknowledged) {
+        const handoffs = this.#dispatchFailureHandoffs(record, acknowledged);
+        await this.#persistDispatchFailureReaperHandoff(record, handoffs);
+        const hasWorktrees = handoffs.some((handoff) => handoff.worktree);
+        if (hasWorktrees) {
+            if (!await this.#teardownFailedDispatchWorktrees(handoffs, 'spawn-registration-timeout', { skipNeverPlacedAgents: true }))
+                return false;
+        }
+        else {
+            const failed = await this.#releaseAndTerminateAgents(handoffs
+                .filter((handoff) => handoff.tracked.result !== undefined)
+                .map((handoff) => [handoff.name, handoff.tracked]), 'spawn-registration-timeout', 'completion');
+            if (failed.length > 0)
+                return false;
+            for (const handoff of handoffs) {
+                await this.#state.clearFailureHandoff(this.#workspaceId, registryHandoffKey(handoff.issue, handoff.name));
+            }
+        }
+        try {
+            await this.#teardownPreviews(record);
+        }
+        catch (error) {
+            this.#logger.warn?.('[factory] retained unregistered spawn lifecycle after preview rollback failed', {
+                issue: record.issue.key,
+                error: describeError(error).errorMessage,
+            });
+            return false;
+        }
+        const key = dispatchLifecycleKey(record.issue);
+        const epoch = this.#dispatchLifecycleEpochs.get(key);
+        const lifecycle = await this.#state.getDispatchLifecycle(this.#workspaceId, key);
+        const lease = lifecycle?.lease;
+        if (epoch === undefined ||
+            !lease ||
+            lease.owner !== this.#dispatchLifecycleOwner ||
+            lease.epoch !== epoch ||
+            !await this.#state.clearClaimedDispatchLifecycle(this.#workspaceId, key, lease))
+            return false;
+        const retryTimer = this.#dispatchLifecycleRetryTimers.get(key);
+        if (retryTimer)
+            clearTimeout(retryTimer);
+        this.#dispatchLifecycleRetryTimers.delete(key);
+        this.#dispatchLifecycleEpochs.delete(key);
+        this.#abandonedDispatchReasons.delete(key);
+        const batch = await this.#batch();
+        batch.abandon(record.issue);
+        await this.#writeInFlightRegistry();
+        this.#resetDispatchCapacityBackoff();
+        return true;
+    }
     /**
      * Is this process still the owner of a lifecycle that is not already done?
      *
@@ -10302,44 +10530,6 @@ export class FactoryLoop {
         return true;
     }
     async #openPullRequestByHead(repo, expectedHeadRef) {
-        if (this.#hasProbePrGhRunner) {
-            try {
-                const result = await this.#probePrGhRunner([
-                    'pr',
-                    'list',
-                    '--repo',
-                    repo,
-                    '--head',
-                    expectedHeadRef,
-                    '--state',
-                    'open',
-                    '--json',
-                    'number,url,headRefName,isDraft',
-                    '--limit',
-                    '10',
-                ]);
-                const payload = parseJsonContent(result.stdout);
-                if (Array.isArray(payload)) {
-                    const candidates = payload.flatMap((entry) => {
-                        const candidate = asRecord(entry);
-                        const number = numberValue(candidate?.number);
-                        const url = stringValue(candidate?.url);
-                        const headRef = stringValue(candidate?.headRefName);
-                        if (!number || !url || headRef !== expectedHeadRef || candidate?.isDraft !== false)
-                            return [];
-                        return [{ repo, number, url, headRef }];
-                    });
-                    return candidates.sort((a, b) => b.number - a.number)[0];
-                }
-            }
-            catch (error) {
-                this.#logger.warn?.('[factory] exact-head gh PR lookup failed; falling back to mounted metadata', {
-                    repo,
-                    headRef: expectedHeadRef,
-                    error: describeError(error).errorMessage,
-                });
-            }
-        }
         const parts = githubRepoParts(repo);
         if (!parts)
             return undefined;
@@ -15111,11 +15301,6 @@ export class FactoryLoop {
                     this.#probePrResolvedCache.delete(cacheKey);
                 }
             }
-            for (const backoffKey of [...this.#probePrGhBackoffUntilMs.keys()]) {
-                if (backoffKey === stateKey || backoffKey.startsWith(`${stateKey}:`)) {
-                    this.#probePrGhBackoffUntilMs.delete(backoffKey);
-                }
-            }
             // Cancellation must see the subscription identity so it can issue the
             // idempotent Relayfile DELETE before clearing the local owner maps.
             await this.#cancelBabysittersForIssue(record.issue);
@@ -17788,19 +17973,29 @@ export class FactoryLoop {
         if (!probe) {
             return;
         }
-        await this.#probeCloser({
+        const closeInput = {
             repo: probe.repo,
             prNumber: probe.prNumber,
             expectedIssueKey: issue.key,
             requireTitleMarker: false,
-            ...(this.#mount.githubWrite ? { githubWrite: this.#mount.githubWrite } : {}),
-        });
+        };
+        if (this.#defaultProbeCloser) {
+            await closeProbePr({
+                ...closeInput,
+                ...(probe.path ? { path: probe.path } : {}),
+                mount: this.#mount,
+                ...(this.#mount.githubWrite ? { githubWrite: this.#mount.githubWrite } : {}),
+            });
+        }
+        else {
+            await this.#probeCloser(closeInput);
+        }
         this.#increment('mergeGateSyntheticClosed');
     }
     async #waitForMergeReady(pr) {
         let lastReason = 'not checked';
         for (let attempt = 1; attempt <= MERGE_GATE_MAX_ATTEMPTS; attempt += 1) {
-            const verdict = await this.#mergeGate.check({ repo: pr.repo, number: pr.prNumber });
+            const verdict = await this.#mergeGate.check({ repo: pr.repo, number: pr.prNumber, ...(pr.path ? { path: pr.path } : {}) });
             lastReason = verdict.reason;
             if (verdict.ready && verdict.live.headRefOid) {
                 return verdict;
@@ -17821,14 +18016,44 @@ export class FactoryLoop {
         return hasTitlePrefix(issue.title, FACTORY_E2E_MARKER);
     }
 }
+/**
+ * The guarded merge is a GitHub mutation, so it answers to the same identity
+ * policy as the lifecycle writeback. Under exact `github.identity: "app"` the
+ * gate refuses the merge instead of squash-merging as the operator's local
+ * `gh` user; `auto` and `user` keep today's behavior.
+ *
+ * Exported so the selection itself is testable rather than buried in the
+ * constructor — the same shape as `defaultGithubWriteback` below. `run` is a
+ * test seam only: production passes nothing and gets `defaultGhRunner`. No
+ * test may reach the real `gh` binary here, because the operation it would
+ * perform is an irreversible merge.
+ */
+export const defaultMergeGate = (config, mount, run) => new MountedGithubMergeGate(mount, new GhCliGithubMergeGate(run, config.github.identity));
+const hasAppGithubLifecycleWrite = (write) => Boolean(write?.postIssueComment &&
+    write.ensureRepositoryLabel &&
+    write.mutateIssueLabel &&
+    write.updateIssue);
 const defaultGithubWriteback = (config, mount) => {
-    if (config.github.identity !== 'app') {
+    const identity = config.github.identity;
+    const cloudContainer = mount.writebackTransport === 'relayfile-cloud';
+    if (identity === 'user') {
+        if (cloudContainer) {
+            throw new Error('GitHub identity "user" requires lifecycle writes through local gh, but the Factory cloud container does not contain gh. ' +
+                'Use identity "auto" or "app" with a connected workspace GitHub App lifecycle write path.');
+        }
         return new GhCliGithubWriteback();
     }
-    if (!mount.githubWrite) {
+    if (hasAppGithubLifecycleWrite(mount.githubWrite)) {
+        return new AppGithubWriteback(mount.githubWrite, mount.githubRead);
+    }
+    if (identity === 'app') {
         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, mount.githubRead);
+    if (cloudContainer) {
+        throw new Error('GitHub identity "auto" cannot select lifecycle writeback in the Factory cloud container: no connected workspace GitHub App lifecycle write path is available, ' +
+            'and the container does not contain gh.');
+    }
+    return new GhCliGithubWriteback();
 };
 export function parseLinearIssue(path, content) {
     const parsed = parseJsonContent(content);
@@ -18234,6 +18459,50 @@ function dispatchSpecs(decision) {
     }
     return [...decision.implementers, decision.reviewer];
 }
+function liveFleetNodeForSpec(spec, roster, assignedLoads) {
+    const eligible = roster.nodes.filter((node) => node.live && node.capabilities.includes(spec.capability));
+    if (eligible.length === 0)
+        throw new FleetPlacementUnavailableError(spec.capability);
+    const explicitlyRequested = spec.node && spec.node !== 'self'
+        ? eligible.find((node) => node.name === spec.node)
+        : undefined;
+    const selected = explicitlyRequested ?? [...eligible].sort((left, right) => {
+        const loadDifference = (assignedLoads.get(left.name) ?? 0) - (assignedLoads.get(right.name) ?? 0);
+        return loadDifference || left.name.localeCompare(right.name);
+    })[0];
+    assignedLoads.set(selected.name, (assignedLoads.get(selected.name) ?? 0) + 1);
+    return selected.name;
+}
+/**
+ * Resolve every remote dispatch spec against one canonical roster snapshot.
+ *
+ * A configured node is a preference, not an entitlement: if it is offline or
+ * no longer advertises the required capability, placement is re-selected from
+ * the live fleet. This runs before durable lifecycle creation, so an empty
+ * eligible set cannot leave a claim or consume a batch slot.
+ */
+function decisionWithVerifiedRemotePlacements(decision, roster) {
+    const assignedLoads = new Map();
+    for (const agent of roster.agents) {
+        if (agent.node)
+            assignedLoads.set(agent.node, (assignedLoads.get(agent.node) ?? 0) + 1);
+    }
+    const place = (spec) => ({
+        ...spec,
+        node: liveFleetNodeForSpec(spec, roster, assignedLoads),
+    });
+    if (decision.scope === 'workflow') {
+        return {
+            ...structuredClone(decision),
+            ...(decision.workflow ? { workflow: place(decision.workflow) } : {}),
+        };
+    }
+    return {
+        ...structuredClone(decision),
+        implementers: decision.implementers.map(place),
+        reviewer: place(decision.reviewer),
+    };
+}
 function dispatchSessionOwner(decision) {
     for (const spec of dispatchSpecs(decision)) {
         const sessionOwner = spec.principal?.trim() || spec.owner?.trim();
@@ -19125,14 +19394,26 @@ const PULL_INDEX_DECISIVE_SCORE = 20;
  *
  * All-or-nothing per repository, and the discipline is copied verbatim from
  * Factory's issue-side reader (`#githubIssuePathsFromIndex`): fall back for the
- * ENTIRE repository if any row is legacy or malformed. `headRef` was added to
- * the public GitHub pull index contract in `@relayfile/adapter-github@0.5.7`
- * and an already-written mount only converges on re-ingest, so mixed indexes
- * are the expected state, not a corruption. One legacy row is enough to poison
- * the whole conclusion: the primary match is a branch match worth 30, so a row
- * without `headRef` cannot be ruled out as the real winner, and ranking the
- * remaining rows against each other would answer a different question from the
- * one the walk answers.
+ * ENTIRE repository if any row is legacy or malformed. One legacy row is enough
+ * to poison the whole conclusion: the primary match is a branch match worth 30,
+ * so a row without `headRef` cannot be ruled out as the real winner, and ranking
+ * the remaining rows against each other would answer a different question from
+ * the one the walk answers.
+ *
+ * Mixed indexes are the expected state today, not a corruption. `headRef` landed
+ * in `@relayfile/adapter-github@0.5.7` and there is no pull-side backfill: the
+ * incremental writers replace exactly the row they touched and pass every other
+ * row through verbatim, so a webhook update hydrates one row and leaves the rest
+ * legacy. Only an eager re-ingest converges a repository, because it rebuilds
+ * the file from a list-pulls response in which every row carries `head.ref`.
+ *
+ * Row facts this relies on, from that contract: `state` is GitHub's lowercase
+ * `"open"`/`"closed"` and there is no `"merged"` state — `merged: true` (with
+ * `mergedAt`) is the only merged signal and `merged: false` is never written.
+ * `headRef` is the bare branch name (`head.ref`), matching what
+ * `readProbePrCandidate` reads off a record, NOT the `owner:branch` form of
+ * `head.label`. `id` and `updated` are deliberately not required here: the
+ * oldest legacy rows carry neither.
  */
 const readPullIndexForProbe = async (mount, repo) => {
     const [owner, name] = repo.split('/');
@@ -19374,79 +19655,6 @@ export const resolveIssuePrFromMount = async (mount, config, issue, opts = {}, l
     }
     return resolved;
 };
-const resolveIssuePrFromGh = async (run, config, issue, opts = {}, logger) => {
-    const candidates = [];
-    let lookupFailures = 0;
-    for (const repo of reposFromConfig(config)) {
-        let payload;
-        try {
-            const result = await run([
-                'pr',
-                'list',
-                '--repo',
-                repo,
-                '--state',
-                'all',
-                '--json',
-                'number,title,body,headRefName,headRepository,headRepositoryOwner,isCrossRepository,isDraft,state,url',
-                '--limit',
-                String(PROBE_PR_GH_CANDIDATE_LIMIT),
-            ]);
-            if (!result.stdout.trim()) {
-                lookupFailures += 1;
-                logger?.warn?.('[factory] gh PR resolver returned empty output', { issue: issue.key, repo });
-                continue;
-            }
-            payload = parseJsonContent(result.stdout);
-        }
-        catch (error) {
-            lookupFailures += 1;
-            logger?.warn?.('[factory] gh PR resolver failed', { issue: issue.key, repo, error });
-            continue;
-        }
-        if (!Array.isArray(payload)) {
-            lookupFailures += 1;
-            logger?.warn?.('[factory] gh PR resolver returned non-array payload', { issue: issue.key, repo });
-            continue;
-        }
-        if (payload.length >= PROBE_PR_GH_CANDIDATE_LIMIT) {
-            logger?.warn?.('[factory] gh PR resolver hit candidate limit', { issue: issue.key, repo, limit: PROBE_PR_GH_CANDIDATE_LIMIT });
-            if (opts.failOnLookupError)
-                lookupFailures += 1;
-        }
-        for (const entry of payload) {
-            const pr = ghProbePrCandidate(entry);
-            if (!pr ||
-                (!factoryBranchMatchesIssue(pr.headRef, issue.key) &&
-                    !(opts.allowLegacyGithubBranch && legacyGithubBranchMatchesIssue(pr.headRef, issue))))
-                continue;
-            if (opts.openOnly && normalizePrState(pr.state) !== 'OPEN')
-                continue;
-            const score = issuePrMatchScore(pr, issue, opts.titleMarker ?? config.safety.requireTitlePrefix, opts);
-            if (score <= 0)
-                continue;
-            candidates.push({
-                repo,
-                prNumber: pr.number,
-                draft: pr.draft,
-                headRef: pr.headRef,
-                headRepo: pr.headRepo,
-                crossRepository: pr.crossRepository ?? (pr.headRepo ? pr.headRepo.toLowerCase() !== repo.toLowerCase() : undefined),
-                state: pr.state,
-                url: pr.url,
-                score,
-                open: normalizePrState(pr.state) === 'OPEN',
-            });
-        }
-    }
-    const resolved = candidates.sort((a, b) => b.score - a.score ||
-        Number(b.open) - Number(a.open) ||
-        b.prNumber - a.prNumber)[0];
-    if (!resolved && opts.failOnLookupError && lookupFailures > 0) {
-        throw new Error(`Unable to confirm open pull request state for ${issue.key} in ${lookupFailures} configured repository lookup(s)`);
-    }
-    return resolved;
-};
 const reposFromConfig = (config) => {
     const repos = new Set([
         ...Object.values(config.repos.byLabel),
@@ -19565,32 +19773,6 @@ const readProbePrCandidate = async (mount, path) => {
         return undefined;
     }
 };
-const ghProbePrCandidate = (value) => {
-    const payload = asRecord(value);
-    if (!payload)
-        return undefined;
-    const number = numberValue(payload.number);
-    if (typeof number !== 'number' || !Number.isInteger(number) || number <= 0)
-        return undefined;
-    const headRepository = asRecord(payload.headRepository);
-    const headRepositoryOwner = asRecord(payload.headRepositoryOwner);
-    const headRepo = githubRepositoryFullName(payload.headRepository) ?? (() => {
-        const name = stringValue(headRepository?.name);
-        const owner = stringValue(headRepositoryOwner?.login) ?? stringValue(headRepositoryOwner?.name);
-        return name && owner ? `${owner}/${name}` : undefined;
-    })();
-    return {
-        number,
-        title: stringValue(payload.title) ?? '',
-        body: stringValue(payload.body) ?? '',
-        headRef: stringValue(payload.headRefName) ?? '',
-        headRepo,
-        crossRepository: booleanValue(payload.isCrossRepository),
-        draft: booleanValue(payload.isDraft),
-        state: stringValue(payload.state),
-        url: stringValue(payload.url),
-    };
-};
 const issuePrMatchScore = (pr, issue, marker, opts = {}) => {
     if (opts.requireTitleMarker && !hasTitlePrefix(pr.title, marker))
         return 0;
@@ -19633,7 +19815,6 @@ const legacyGithubPrCanBeAdopted = (issue, pr) => {
     return pr.crossRepository === false || pr.headRepo?.toLowerCase() === pr.repo.toLowerCase();
 };
 const normalizePrState = (state) => state?.toUpperCase();
-const failClosedGhRunner = async () => ({ stdout: '[]' });
 const ISSUE_KEY_PATTERN = /^[A-Z]+-\d+$/u;
 const isIssuePathUnderRoot = (path) => path.startsWith(`${ISSUE_ROOT}/`) && path.endsWith('.json');
 const isIssueFilePath = (path) => isIssuePathUnderRoot(path) &&