@agent-relay/factory 0.1.32 → 0.1.34

package/dist/orchestrator/factory.js

@@ -20,6 +20,7 @@ import { asRecord, parseJsonContent, stableHash, wrappedPayload } from '../write
 import { issueKey } from './batch-tracker.js';
 import { findAgentProcessByName, readProcessIdentity } from './process-identity.js';
 import { readFactoryInFlightRegistry, terminatePids } from './reaper.js';
+import { createFactoryCloudEventV1, factoryCloudReleaseReasonV1, } from '../observability/events.js';
 class ClarificationWakeLeaseLostError extends Error {
 }
 class ClarificationQuestionDeliveryLeaseLostError extends Error {
@@ -119,6 +120,7 @@ export class FactoryLoop {
     #workspaceId;
     #relayflows;
     #worktrees;
+    #reporter;
     #batchView;
     #batchReady;
     #listeners = new Map();
@@ -132,6 +134,8 @@ export class FactoryLoop {
     #githubIssueCommentQueues = new Map();
     #githubIssueAuthors = new Map();
     #githubIssueAuthorLookups = new Map();
+    #githubIssuePreferredPaths = new Map();
+    #githubIssuePathIndexReady = false;
     #slackReporterUserIds = new Map();
     #slackReporterUserIdLookups = new Map();
     #reconciledGithubInProgress = new Set();
@@ -263,6 +267,7 @@ export class FactoryLoop {
         this.#workspaceId = config.workspaceId ?? 'default';
         this.#relayflows = ports.relayflows;
         this.#worktrees = ports.worktrees;
+        this.#reporter = ports.reporter;
         this.#state = ports.stateStore ?? new InMemoryStateStore({
             batchSize: config.batchSize,
             agentQuestionDedupeLimit: AGENT_QUESTION_DEDUPE_LIMIT,
@@ -1362,6 +1367,7 @@ export class FactoryLoop {
             ]);
             const onlineAgents = new Set(roster.agents.map((agent) => agent.name));
             const activeIssueIdentities = new Set();
+            const legacyUnownedAgentsByIssue = new Map();
             for (const [, lifecycle] of lifecycles) {
                 if (isTerminalDispatchLifecycle(lifecycle))
                     continue;
@@ -1378,12 +1384,26 @@ export class FactoryLoop {
                 if (!onlineAgents.has(agent.name) || !agent.issue)
                     continue;
                 const identity = githubIssueRefIdentity(agent.issue);
-                if (identity)
+                if (!identity)
+                    continue;
+                const isLegacyLocalWorker = this.#usesDurableDispatchLifecycle() &&
+                    this.#fleet.placementLocality === 'local' &&
+                    !agent.node &&
+                    !agent.invocationId &&
+                    !activeIssueIdentities.has(identity);
+                if (isLegacyLocalWorker) {
+                    const agents = legacyUnownedAgentsByIssue.get(identity) ?? [];
+                    agents.push(agent);
+                    legacyUnownedAgentsByIssue.set(identity, agents);
+                }
+                else {
                     activeIssueIdentities.add(identity);
+                }
             }
             return {
                 activeIssueIdentities,
                 onlineAgentNames: onlineAgents,
+                legacyUnownedAgentsByIssue,
             };
         }
         catch (error) {
@@ -1405,9 +1425,14 @@ export class FactoryLoop {
             labels.has('factory:human-review'))
             return false;
         const identity = githubIssueRefIdentity(issueRef(issue));
+        const legacyUnownedAgents = identity
+            ? (context.legacyUnownedAgentsByIssue.get(identity) ?? [])
+                .filter((agent) => githubAgentNameMatchesIssue(agent.name, issue))
+            : [];
+        const legacyUnownedAgentNames = new Set(legacyUnownedAgents.map((agent) => agent.name));
         if (!identity ||
             context.activeIssueIdentities.has(identity) ||
-            [...context.onlineAgentNames].some((name) => githubAgentNameMatchesIssue(name, issue))) {
+            [...context.onlineAgentNames].some((name) => githubAgentNameMatchesIssue(name, issue) && !legacyUnownedAgentNames.has(name))) {
             this.#increment('githubOrphanRecoveriesBlockedActive');
             return false;
         }
@@ -1447,7 +1472,7 @@ export class FactoryLoop {
         if (openPr) {
             let adopted = false;
             try {
-                adopted = await this.#adoptOrphanedGithubPullRequest(issue, openPr);
+                adopted = await this.#adoptOrphanedGithubPullRequest(issue, openPr, legacyUnownedAgents);
             }
             catch (error) {
                 this.#increment('githubOrphanedPullRequestAdoptionFailures');
@@ -1468,6 +1493,14 @@ export class FactoryLoop {
             });
             return false;
         }
+        // A pre-durable local Factory may have left live, registry-proven workers
+        // without a lifecycle record. They are safe to adopt only once their open
+        // PR proves which dispatch they own. Without that proof, preserve the issue
+        // and workers instead of redispatching duplicate agents.
+        if (legacyUnownedAgents.length > 0) {
+            this.#increment('githubOrphanRecoveriesBlockedActive');
+            return false;
+        }
         try {
             if (providerStatus === 'in-progress') {
                 await this.#githubWriteback.setStatus(issue, 'ready');
@@ -1504,7 +1537,7 @@ export class FactoryLoop {
             allowLegacyGithubBranch: true,
         });
     }
-    async #adoptOrphanedGithubPullRequest(issue, pr) {
+    async #adoptOrphanedGithubPullRequest(issue, pr, legacyUnownedAgents = []) {
         const headRef = pr.headRef;
         if (!headRef)
             return false;
@@ -1543,14 +1576,14 @@ export class FactoryLoop {
                     : spec),
             };
         }
-        const durableRemoteAdoption = this.#fleet.placementLocality === 'remote';
+        const durableAdoption = this.#usesDurableDispatchLifecycle();
         const publishedPr = {
             repo: pr.repo,
             number: pr.prNumber,
             url: pr.url ?? `https://github.com/${pr.repo}/pull/${pr.prNumber}`,
             headRef,
         };
-        if (durableRemoteAdoption) {
+        if (durableAdoption) {
             const claim = await this.#claimDispatchLifecycle(decision, false, randomUUID(), {
                 phase: 'published',
                 pullRequest: publishedPr,
@@ -1566,7 +1599,7 @@ export class FactoryLoop {
         const batch = await this.#batch();
         const record = batch.start(decision, false);
         if (!record) {
-            if (durableRemoteAdoption) {
+            if (durableAdoption) {
                 const durable = await this.#state.getDispatchLifecycle(this.#workspaceId, issueKey(decision.issue));
                 if (durable) {
                     this.#scheduleDispatchLifecycleRetry(inFlightRecordFromLifecycle(durable));
@@ -1576,6 +1609,48 @@ export class FactoryLoop {
             }
             return false;
         }
+        if (durableAdoption && legacyUnownedAgents.length > 0) {
+            const specsByName = new Map(dispatchSpecs(record.decision).map((spec) => [spec.name, spec]));
+            const initialBabysitter = babysitterSpec(issue, this.#config, route);
+            const sharedCheckout = record.decision.implementers.find((candidate) => candidate.repo === initialBabysitter.repo && candidate.baseClonePath && candidate.clonePath);
+            const legacyBabysitter = {
+                ...initialBabysitter,
+                ...(sharedCheckout
+                    ? {
+                        baseClonePath: sharedCheckout.baseClonePath,
+                        clonePath: sharedCheckout.clonePath,
+                        ...(headRef ? { branch: headRef } : {}),
+                        ...(sharedCheckout.existingPullRequestBranch ? { existingPullRequestBranch: true } : {}),
+                    }
+                    : {}),
+                ownedPullRequest: { repo: pr.repo, number: pr.prNumber, path: pr.path },
+            };
+            specsByName.set(legacyBabysitter.name, legacyBabysitter);
+            const adopted = [];
+            for (const agent of legacyUnownedAgents) {
+                const spec = specsByName.get(agent.name);
+                if (!spec)
+                    continue;
+                const invocationId = batch.invocationIdFor(record.issue, spec);
+                batch.recordSpawn(record, spec, invocationId, {
+                    name: agent.name,
+                    sessionRef: agent.sessionRef,
+                    pids: agent.pids,
+                    locality: 'local',
+                });
+                adopted.push({ name: agent.name, invocationId });
+            }
+            if (adopted.length > 0) {
+                this.#fleet.hydrateTracked?.(adopted);
+                await this.#saveDispatchLifecycle(record, 'published', publishedPr);
+                for (const agent of adopted) {
+                    this.#increment('legacyLocalWorkersAdopted');
+                    const tracked = record.agents.get(agent.name);
+                    if (tracked)
+                        await this.#reportAgent(record, tracked, 'agent.adopted');
+                }
+            }
+        }
         await this.#ensureBabysitter(record, {
             repo: pr.repo,
             prNumber: pr.prNumber,
@@ -1585,7 +1660,7 @@ export class FactoryLoop {
         });
         const babysitter = [...record.agents.values()].find((tracked) => tracked.spec.role === 'babysitter');
         if (!babysitter) {
-            if (durableRemoteAdoption)
+            if (durableAdoption)
                 this.#scheduleDispatchLifecycleRetry(record);
             else
                 batch.abandon(record.issue);
@@ -1593,10 +1668,15 @@ export class FactoryLoop {
         }
         record.result = {
             issue: record.issue,
-            agents: [{ name: babysitter.result?.name ?? babysitter.spec.name, role: 'babysitter' }],
+            agents: [...record.agents.values()].map((tracked) => ({
+                name: tracked.result?.name ?? tracked.spec.name,
+                role: tracked.spec.role,
+            })),
             dryRun: false,
         };
         await this.#writeInFlightRegistry();
+        if (durableAdoption)
+            await this.#saveDispatchLifecycle(record, 'running', publishedPr);
         this.#increment('githubOrphanedPullRequestsAdopted');
         return true;
     }
@@ -1778,7 +1858,7 @@ export class FactoryLoop {
         if (existingRecord?.result) {
             return existingRecord.result;
         }
-        if (!dryRun && this.#fleet.placementLocality === 'remote') {
+        if (!dryRun && this.#usesDurableDispatchLifecycle()) {
             const durable = await this.#state.getDispatchLifecycle(this.#workspaceId, issueKey(decision.issue));
             if (durable && !isTerminalDispatchLifecycle(durable)) {
                 if (durable.result && this.#dispatchLifecycleEpochs.has(issueKey(decision.issue))) {
@@ -1803,6 +1883,9 @@ export class FactoryLoop {
             this.#error(error, decision.issue);
             throw error;
         }
+        if (!this.#isIssueReady(liveIssue)) {
+            throw new LiveDispatchStateChangedError(decision.issue.key);
+        }
         if (!isDispatchableIssue(liveIssue)) {
             const error = new Error(`Refusing to dispatch ${decision.issue.key}: not reconciled real Linear issue`);
             this.#error(error, decision.issue);
@@ -1849,19 +1932,19 @@ export class FactoryLoop {
         // Full task rendering is part of the durable spawn specification. It must
         // 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 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
         // 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;
+        const lifecycleRunId = !dryRun && (durableDispatch || isolateLocalWorktree) ? randomUUID() : undefined;
         if (lifecycleRunId) {
             dispatchDecision = decisionWithLifecycleBranches(dispatchDecision, lifecycleRunId, {
                 isolateLocalWorktree,
             });
         }
         dispatchDecision = await this.#withRenderedDispatchTasks(dispatchDecision, liveIssue);
-        if (durableRemoteDispatch) {
+        if (durableDispatch) {
             const lifecycleClaim = await this.#claimDispatchLifecycle(dispatchDecision, dryRun, lifecycleRunId);
             this.#consumePendingDispatchClarifications(dispatchDecision.issue);
             dispatchDecision = structuredClone(lifecycleClaim.lifecycle.decision);
@@ -1881,7 +1964,7 @@ export class FactoryLoop {
                     return restored.result;
             }
         }
-        if (!durableRemoteDispatch)
+        if (!durableDispatch)
             this.#consumePendingDispatchClarifications(dispatchDecision.issue);
         await this.#recordDispatchAttempt(dispatchDecision.issue);
         const record = batch.start(dispatchDecision, dryRun);
@@ -1899,6 +1982,12 @@ export class FactoryLoop {
             await this.#ensureGithubAgentQuestionWatch(record, liveIssue);
         const spawnedForReaperHandoff = [];
         try {
+            if (!dryRun) {
+                const issue = await this.#readIssue(dispatchDecision.issue.path);
+                if (!issue || !this.#isIssueReady(issue)) {
+                    throw new LiveDispatchStateChangedError(dispatchDecision.issue.key);
+                }
+            }
             const specs = dispatchSpecs(dispatchDecision);
             const agents = [];
             for (const spec of specs) {
@@ -1960,8 +2049,10 @@ export class FactoryLoop {
             // acknowledged spawns, so cleanup never races a name-only survivor.
             const failureHandoffs = this.#dispatchFailureHandoffs(record, spawnedForReaperHandoff);
             await this.#persistDispatchFailureReaperHandoff(record, failureHandoffs);
-            let worktreesTornDown = await this.#teardownFailedDispatchWorktrees(failureHandoffs);
             const liveStateChanged = error instanceof LiveDispatchStateChangedError;
+            const cancellationReason = factoryCloudDispatchCancellationReason(error);
+            const cleanupReason = liveStateChanged ? 'live dispatch state changed' : 'dispatch failed';
+            let worktreesTornDown = await this.#teardownFailedDispatchWorktrees(failureHandoffs, cleanupReason);
             if (liveStateChanged && !failureHandoffs.some((handoff) => handoff.worktree)) {
                 const failed = await this.#releaseAndTerminateAgents(failureHandoffs.map((handoff) => [handoff.name, handoff.tracked]), 'live dispatch state changed', 'completion');
                 if (failed.length === 0) {
@@ -1974,13 +2065,13 @@ export class FactoryLoop {
             let failedState;
             if (liveStateChanged) {
                 await this.#clearDispatchInFlight(decision.issue);
-                await this.#saveDispatchLifecycle(record, 'abandoned');
+                await this.#saveDispatchLifecycle(record, 'abandoned', undefined, undefined, new Set(), { cancellationReason });
                 this.#increment('dispatchLiveStateRaces');
             }
             else {
                 await this.#recordDispatchFailure(decision.issue);
                 failedState = await this.#state.getDispatchAttempts(this.#workspaceId, decision.issue.key);
-                await this.#saveDispatchLifecycle(record, failedState?.terminal ? 'abandoned' : 'retryable');
+                await this.#saveDispatchLifecycle(record, failedState?.terminal ? 'abandoned' : 'retryable', undefined, undefined, new Set(), { cancellationReason: failedState?.terminal ? cancellationReason : undefined });
             }
             batch.abandon(decision.issue);
             if (!liveStateChanged && !failedState?.terminal)
@@ -2057,7 +2148,7 @@ export class FactoryLoop {
             });
         }
     }
-    // Remote backends survive orchestrator restarts: re-adopt the agents recorded
+    // Durable backends survive orchestrator restarts: re-adopt the agents recorded
     // in the durable lifecycle store, restore their full batch/spec association,
     // then reconcile once so exits that happened while this process was down are
     // handled instead of being dropped as unknown agents.
@@ -2097,8 +2188,9 @@ export class FactoryLoop {
                 for (const agent of claim.lifecycle.agents) {
                     const invocationId = agent.tracked.spec.invocationId;
                     const node = agent.tracked.result?.node;
-                    if (invocationId || node)
+                    if (invocationId || node || agent.tracked.result) {
                         agents.push({ name: agent.name, invocationId, node });
+                    }
                 }
             }
             // Migration fallback for registries written before durable lifecycle
@@ -2136,6 +2228,12 @@ export class FactoryLoop {
                 this.#dispatchLifecycleEpochs.delete(key);
                 this.#increment('dispatchLifecycleLeasesLost');
                 const lifecycle = await this.#state.getDispatchLifecycle(this.#workspaceId, key);
+                if (lifecycle) {
+                    await this.#reportLifecycle(lifecycle, 'factory.anomaly', {
+                        level: 'error',
+                        errorCode: 'lease_lost',
+                    });
+                }
                 if (lifecycle && !isTerminalDispatchLifecycle(lifecycle) && lifecycle.phase !== 'waiting-for-human') {
                     this.#scheduleDispatchLifecycleRetry(inFlightRecordFromLifecycle(lifecycle));
                 }
@@ -2171,10 +2269,87 @@ export class FactoryLoop {
         }
         this.#dispatchLifecycleEpochs.set(key, claim.lease.epoch);
         this.#scheduleDispatchLifecycleRenewal();
+        if (claim.created) {
+            await this.#reportLifecycle(claim.lifecycle, 'run.started');
+        }
         return { created: claim.created, lifecycle: claim.lifecycle };
     }
-    async #saveDispatchLifecycle(record, phase, pullRequest, releaseReason, releasedAgentNames = new Set()) {
-        if (record.dryRun || this.#fleet.placementLocality !== 'remote')
+    #usesDurableDispatchLifecycle() {
+        return this.#fleet.durableOwnership ?? this.#fleet.placementLocality === 'remote';
+    }
+    async #report(input) {
+        if (!this.#reporter)
+            return;
+        try {
+            await this.#reporter.report(createFactoryCloudEventV1(input, {
+                now: () => new Date(this.#clock.now()),
+            }));
+        }
+        catch (error) {
+            // A custom reporter is allowed through the public port, so defend the
+            // orchestration path even if it violates the port's no-reject contract.
+            this.#increment('factoryEventReportingFailures');
+            this.#logger.warn?.('[factory] progress reporter rejected an event', {
+                eventType: input.type,
+                errorClass: telemetryErrorClass(error),
+            });
+        }
+    }
+    async #reportLifecycle(lifecycle, type, options = {}) {
+        await this.#report({
+            type,
+            level: options.level ?? (type === 'run.failed' || type === 'factory.anomaly' ? 'error' : 'info'),
+            runId: lifecycle.runId,
+            phase: lifecycle.phase,
+            status: telemetryRunStatus(lifecycle.phase),
+            run: {
+                source: githubIssuePathParts(lifecycle.issue.path) ? 'github' : 'linear',
+                repository: lifecycle.decision.routes[0]?.repo,
+                issueKey: lifecycle.issue.key,
+                recipe: lifecycle.decision.scope,
+            },
+            attributes: {
+                backend: this.#fleet.placementLocality === 'remote' ? 'relay' : 'internal',
+                component: 'orchestrator',
+                operation: 'save_lifecycle',
+                previousPhase: options.previousPhase,
+                errorCode: options.errorCode,
+                cancellationReason: options.cancellationReason,
+                dryRun: lifecycle.dryRun,
+                trackedAgents: lifecycle.agents.length,
+            },
+        });
+    }
+    async #reportAgent(record, tracked, type, options = {}) {
+        const lifecycle = await this.#state
+            .getDispatchLifecycle(this.#workspaceId, issueKey(record.issue))
+            .catch(() => undefined);
+        if (!lifecycle)
+            return;
+        await this.#report({
+            type,
+            runId: lifecycle.runId,
+            phase: lifecycle.phase,
+            status: telemetryRunStatus(lifecycle.phase),
+            run: {
+                source: githubIssuePathParts(record.issue.path) ? 'github' : 'linear',
+                repository: tracked.spec.repo,
+                issueKey: record.issue.key,
+                recipe: record.decision.scope,
+            },
+            attributes: {
+                backend: this.#fleet.placementLocality === 'remote' ? 'relay' : 'internal',
+                component: 'fleet',
+                operation: type.slice('agent.'.length),
+                agentRole: tracked.spec.role,
+                invocationId: tracked.spec.invocationId,
+                locality: tracked.result?.locality ?? this.#fleet.placementLocality,
+                releaseReason: factoryCloudReleaseReasonV1(options.releaseReason),
+            },
+        });
+    }
+    async #saveDispatchLifecycle(record, phase, pullRequest, releaseReason, releasedAgentNames = new Set(), telemetry = {}) {
+        if (record.dryRun || !this.#usesDurableDispatchLifecycle())
             return true;
         const key = issueKey(record.issue);
         const epoch = this.#dispatchLifecycleEpochs.get(key);
@@ -2195,9 +2370,20 @@ export class FactoryLoop {
         if (!saved) {
             this.#dispatchLifecycleEpochs.delete(key);
             this.#increment('dispatchLifecycleFencesRejected');
+            await this.#reportLifecycle(lifecycle, 'factory.anomaly', {
+                level: 'error',
+                errorCode: 'fence_rejected',
+            });
             this.#scheduleDispatchLifecycleRetry(record);
             return false;
         }
+        if (previous?.phase !== lifecycle.phase) {
+            await this.#reportLifecycle(lifecycle, lifecycle.phase === 'complete'
+                ? 'run.succeeded'
+                : lifecycle.phase === 'abandoned'
+                    ? 'run.cancelled'
+                    : 'run.phase_changed', { previousPhase: previous?.phase, cancellationReason: telemetry.cancellationReason });
+        }
         if (isTerminalDispatchLifecycle(lifecycle)) {
             this.#dispatchLifecycleEpochs.delete(key);
         }
@@ -2229,7 +2415,7 @@ export class FactoryLoop {
         this.#dispatchLifecycleRetryTimers.set(key, timer);
     }
     #scheduleReleaseRetry(record, reason) {
-        if (this.#fleet.placementLocality === 'remote') {
+        if (this.#usesDurableDispatchLifecycle()) {
             this.#scheduleDispatchLifecycleRetry(record);
             return;
         }
@@ -2366,6 +2552,16 @@ export class FactoryLoop {
         }
     }
     async #resumeDurableDispatch(record) {
+        if (!record.dryRun) {
+            const issue = await this.#readIssue(record.issue.path);
+            if (!issue) {
+                throw new Error(`Unable to recover durable dispatch ${record.issue.key}: issue is not currently readable`);
+            }
+            if (isGithubIssue(issue) && !this.#isGithubIssueResumable(issue)) {
+                await this.#abandonDurableResume(record, 'live GitHub issue is closed or no longer ready-for-agent');
+                return;
+            }
+        }
         const agents = [];
         const specs = dispatchSpecs(record.decision);
         const plannedNames = new Set(specs.map((spec) => spec.name));
@@ -2413,6 +2609,55 @@ export class FactoryLoop {
             }
         }
     }
+    #isGithubIssueResumable(issue) {
+        if (this.#isIssueReady(issue))
+            return true;
+        if (githubFactoryIssueIsClosed(issue))
+            return false;
+        const labels = new Set(issue.labels.map((label) => label.trim().toLowerCase()));
+        const required = this.#config.safety.requireLabel.trim().toLowerCase();
+        return Boolean(required) &&
+            labels.has(required) &&
+            labels.has('factory:in-progress') &&
+            !labels.has('factory:human-review');
+    }
+    async #abandonDurableResume(record, reason) {
+        const handoffs = this.#dispatchFailureHandoffs(record, [...record.agents].map(([name, tracked]) => ({
+            issue: record.issue,
+            name,
+            tracked: cloneTrackedAgent(tracked),
+            persistedAtMs: this.#clock.now(),
+        })));
+        await this.#persistDispatchFailureReaperHandoff(record, handoffs);
+        if (!await this.#saveDispatchLifecycle(record, 'abandoned', undefined, reason, new Set(), { cancellationReason: 'source_state_changed' }))
+            return;
+        await this.#clearDispatchInFlight(record.issue);
+        const batch = await this.#batch();
+        batch.abandon(record.issue);
+        for (const [name] of record.agents) {
+            this.#fleet.markAgentTerminal?.(name, 'durable-dispatch-abandoned');
+        }
+        if (handoffs.some((handoff) => handoff.worktree)) {
+            await this.#teardownFailedDispatchWorktrees(handoffs, 'live dispatch state changed');
+        }
+        else if (handoffs.length > 0) {
+            const failed = new Set(await this.#releaseAndTerminateAgents(handoffs.map((handoff) => [handoff.name, handoff.tracked]), 'live dispatch state changed', 'completion'));
+            for (const handoff of handoffs) {
+                if (failed.has(handoff.name))
+                    continue;
+                await this.#state.clearFailureHandoff(this.#workspaceId, registryHandoffKey(handoff.issue, handoff.name));
+            }
+        }
+        await this.#stopSlackWatcher(record.issue);
+        await this.#stopGithubIssueCommentWatcherForIssue(record.issue);
+        await this.#writeInFlightRegistry();
+        this.#increment('dispatchLifecycleStaleIssuesAbandoned');
+        this.#resolveDispatchTerminalWaiters(record.issue);
+        this.#logger.info?.('[factory] abandoned durable dispatch whose live issue is no longer ready', {
+            issue: record.issue.key,
+            reason,
+        });
+    }
     async #finishDurableRelease(record, releaseReason) {
         const batch = await this.#batch();
         const reason = releaseReason ?? (this.#config.terminalState === 'human-review' ? 'issue-human-review' : 'issue-done');
@@ -2458,14 +2703,14 @@ export class FactoryLoop {
             this.#scheduleReleaseRetry(record, reason);
             return false;
         }
-        const next = this.#fleet.placementLocality === 'remote' ? undefined : batch.complete(record.issue);
+        const next = this.#usesDurableDispatchLifecycle() ? 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.
-        if (this.#fleet.placementLocality === 'remote' && this.#config.babysitter.enabled) {
+        if (this.#usesDurableDispatchLifecycle() && this.#config.babysitter.enabled) {
             await this.#cancelBabysitterWake(issueKey(record.issue));
         }
         if (!await this.#saveDispatchLifecycle(record, 'complete'))
@@ -2480,7 +2725,7 @@ export class FactoryLoop {
         return await this.#assertIssueDispatchLifecycleOwner(record.issue);
     }
     async #assertIssueDispatchLifecycleOwner(issue) {
-        if (this.#fleet.placementLocality !== 'remote')
+        if (!this.#usesDurableDispatchLifecycle())
             return true;
         const key = issueKey(issue);
         const epoch = this.#dispatchLifecycleEpochs.get(key);
@@ -2580,8 +2825,7 @@ export class FactoryLoop {
         if (!isGithubIssue(issue)) {
             return this.#states.isRole(issue.stateId, 'readyForAgent');
         }
-        const githubState = (issue.state?.name ?? stringValue(wrappedPayload(issue.raw).state) ?? '').trim().toLowerCase();
-        if (githubState === 'closed') {
+        if (githubFactoryIssueIsClosed(issue)) {
             return false;
         }
         const labels = new Set(issue.labels.map((label) => label.trim().toLowerCase()));
@@ -2706,9 +2950,14 @@ export class FactoryLoop {
                     }
                 }
             }
+            for (const [identity, path] of issuePaths) {
+                this.#githubIssuePreferredPaths.set(identity, path);
+            }
+            this.#githubIssuePathIndexReady = true;
             return [...issuePaths.values()].sort();
         }
         catch (error) {
+            this.#githubIssuePathIndexReady = false;
             this.#increment('githubIssueListFailures');
             this.#logger.warn?.('[factory] failed to list GitHub issue source tree', error);
             return [];
@@ -2773,7 +3022,11 @@ export class FactoryLoop {
         }
     }
     async #readGithubIssue(path) {
-        const candidatePaths = githubIssueReadCandidatePaths(path);
+        const preferredPath = await this.#preferredGithubIssuePath(path);
+        const candidatePaths = [...new Set([
+                ...githubIssueReadCandidatePaths(preferredPath),
+                ...githubIssueReadCandidatePaths(path),
+            ])];
         try {
             for (const candidatePath of candidatePaths) {
                 try {
@@ -2797,6 +3050,30 @@ export class FactoryLoop {
             throw error;
         }
     }
+    async #preferredGithubIssuePath(path) {
+        const parts = githubIssuePathParts(path) ?? githubIssueDirectoryPathParts(path);
+        if (!parts)
+            return path;
+        const identity = githubIssueIdentity(parts.owner, parts.repo, parts.number);
+        const cached = this.#githubIssuePreferredPaths.get(identity);
+        if (cached && githubIssuePathPreference(cached) <= githubIssuePathPreference(path))
+            return cached;
+        if (githubIssuePathPreference(path) === 0) {
+            this.#githubIssuePreferredPaths.set(identity, path);
+            return path;
+        }
+        // Normal discovery has already indexed every configured GitHub issue path.
+        // A dispatch-only replacement owner can reach this method before that
+        // backfill, so build the same shared index once instead of traversing both
+        // repository trees separately for every durable issue it recovers.
+        if (!this.#githubIssuePathIndexReady) {
+            await this.#githubIssuePaths();
+        }
+        const indexed = this.#githubIssuePreferredPaths.get(identity);
+        return indexed && githubIssuePathPreference(indexed) < githubIssuePathPreference(path)
+            ? indexed
+            : path;
+    }
     async #findGithubIssueMirror(ghIssue, candidates) {
         const draftPath = githubIssueMirrorDraftPath(ghIssue);
         try {
@@ -2947,6 +3224,19 @@ export class FactoryLoop {
         await mkdir(dirname(path), { recursive: true });
         await writeFile(path, `${JSON.stringify(heartbeat, null, 2)}\n`, 'utf8');
         await this.#writeInFlightRegistry(registryPath, path);
+        const batch = this.#batchView;
+        await this.#report({
+            type: 'instance.heartbeat',
+            attributes: {
+                backend: this.#fleet.placementLocality === 'remote' ? 'relay' : 'internal',
+                mode: status,
+                component: 'orchestrator',
+                operation: 'heartbeat',
+                activeRuns: batch?.inFlight.length,
+                queuedRuns: batch?.queued.length,
+                trackedAgents: batch?.inFlight.reduce((count, record) => count + record.agents.size, 0),
+            },
+        });
     }
     async #reapDispatchFailureHandoffsNow(heartbeatPath, registryPath) {
         const handoffs = await this.#state.listFailureHandoffs(this.#workspaceId);
@@ -3150,7 +3440,9 @@ export class FactoryLoop {
     async #releaseAndTerminateAgents(agents, reason, context) {
         const failed = [];
         const protectedPids = await this.#protectedPids();
+        const batch = this.#batchView;
         for (const [agentName, tracked] of agents) {
+            const record = batch?.getIssueByAgent(agentName);
             if (context === 'stop') {
                 await this.#refreshStoppingHeartbeat();
             }
@@ -3182,10 +3474,23 @@ export class FactoryLoop {
             }
             try {
                 await this.#fleet.release(agentName, reason);
+                if (record)
+                    await this.#reportAgent(record, tracked, 'agent.released', { releaseReason: reason });
             }
             catch (error) {
                 failed.push(agentName);
                 this.#logger.warn?.(`[factory] failed to release ${agentName} during ${context}`, error);
+                if (record) {
+                    const lifecycle = await this.#state
+                        .getDispatchLifecycle(this.#workspaceId, issueKey(record.issue))
+                        .catch(() => undefined);
+                    if (lifecycle) {
+                        await this.#reportLifecycle(lifecycle, 'factory.failure', {
+                            level: 'error',
+                            errorCode: 'release_failed',
+                        });
+                    }
+                }
             }
             if (context === 'stop') {
                 await this.#refreshStoppingHeartbeat();
@@ -3294,10 +3599,10 @@ export class FactoryLoop {
         }
         return [...handoffs.values()];
     }
-    async #teardownFailedDispatchWorktrees(handoffs) {
+    async #teardownFailedDispatchWorktrees(handoffs, releaseReason = 'dispatch failed') {
         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');
+        const failed = await this.#releaseAndTerminateAgents(handoffs.map((handoff) => [handoff.name, handoff.tracked]), releaseReason, 'completion');
         if (failed.length > 0)
             return false;
         try {
@@ -3423,6 +3728,9 @@ export class FactoryLoop {
             if (!await this.#saveDispatchLifecycle(record, 'dispatching')) {
                 throw new Error(`Dispatch lifecycle ownership lost after adopting ${spec.name}`);
             }
+            const adopted = record.agents.get(spec.name);
+            if (adopted)
+                await this.#reportAgent(record, adopted, 'agent.adopted');
             return { name: spec.name };
         }
         await this.#prepareAgentWorktree(record, spec);
@@ -3445,12 +3753,20 @@ export class FactoryLoop {
             });
         }
         catch (error) {
-            throw contextualError(`Dispatch spawn failed for ${record.issue.key}/${spec.name} (${spec.capability}) cwd=${spec.clonePath ?? 'default'}`, error);
+            const wrapped = contextualError(`Dispatch spawn failed for ${record.issue.key}/${spec.name} (${spec.capability}) cwd=${spec.clonePath ?? 'default'}`, error);
+            throw Object.assign(wrapped, {
+                factoryCancellationReason: isDispatchDeliveryError(error)
+                    ? 'agent_delivery_failed'
+                    : 'agent_spawn_failed',
+            });
         }
         batch.recordSpawn(record, spec, invocationId, result);
         if (!await this.#saveDispatchLifecycle(record, 'dispatching')) {
             throw new Error(`Dispatch lifecycle ownership lost after spawning ${spec.name}`);
         }
+        const spawned = record.agents.get(result.name);
+        if (spawned)
+            await this.#reportAgent(record, spawned, 'agent.spawned');
         return { name: result.name };
     }
     async #handleAgentExit(name, reason) {
@@ -3469,6 +3785,19 @@ export class FactoryLoop {
         const batch = await this.#batch();
         const record = batch.getIssueByAgent(name);
         if (!record) {
+            if (/^ar-\d+-/u.test(name)) {
+                await this.#report({
+                    type: 'factory.anomaly',
+                    level: 'error',
+                    attributes: {
+                        backend: this.#fleet.placementLocality === 'remote' ? 'relay' : 'internal',
+                        component: 'fleet',
+                        operation: 'agent_exit',
+                        errorCode: 'unowned_agent',
+                        count: 1,
+                    },
+                });
+            }
             return;
         }
         if (!await this.#assertDispatchLifecycleOwner(record)) {
@@ -3487,7 +3816,9 @@ export class FactoryLoop {
             return;
         }
         const exiting = record.agents.get(name);
-        if (this.#fleet.placementLocality === 'remote') {
+        if (exiting)
+            await this.#reportAgent(record, exiting, 'agent.exited', { releaseReason: reason });
+        if (this.#usesDurableDispatchLifecycle()) {
             const lifecycle = await this.#state.getDispatchLifecycle(this.#workspaceId, issueKey(record.issue));
             if (lifecycle?.phase === 'parking') {
                 this.#increment('clarificationParkingExitsSuppressed');
@@ -4176,6 +4507,7 @@ export class FactoryLoop {
                 await this.#persistBabysitterSession(record.issue, ref, tracked);
             }
         }
+        await this.#reportAgent(record, tracked, 'agent.resumed');
     }
     async #handleDeliveryFailed(info) {
         const critical = await this.#state.consumeCritical(this.#workspaceId, info.msgId ?? '');
@@ -4185,7 +4517,7 @@ export class FactoryLoop {
         }
         const record = (await this.#batch()).getIssueByAgent(info.to);
         const issue = critical.issue ?? record?.issue;
-        const error = new Error(`Critical delivery failed to ${info.to}${info.reason ? `: ${info.reason}` : ''}`);
+        const error = Object.assign(new Error(`Critical delivery failed to ${info.to}${info.reason ? `: ${info.reason}` : ''}`), { code: 'fleet_delivery_failed' });
         this.#error(error, issue);
         if (isTerminalDeliveryFailure(info.reason)) {
             this.#increment('criticalDeliveryTerminalFailures');
@@ -5661,7 +5993,7 @@ export class FactoryLoop {
     }
     async #cancelBabysitterWake(issueIdentity) {
         const issue = this.#babysitterIssueRefs.get(issueIdentity);
-        const mayClearDurable = this.#fleet.placementLocality !== 'remote'
+        const mayClearDurable = !this.#usesDurableDispatchLifecycle()
             || Boolean(issue && await this.#assertIssueDispatchLifecycleOwner(issue));
         for (const [key, state] of this.#babysitterWakeStates) {
             if (issueKey(state.issue) !== issueIdentity)
@@ -5922,19 +6254,7 @@ export class FactoryLoop {
                 },
             };
             let targets;
-            if (this.#fleet.promptDelivery === 'pty') {
-                if (!this.#fleet.sendInput) {
-                    throw new Error('Fleet client advertises PTY prompt delivery without raw input support');
-                }
-                // Internal agents are harness-owned PTYs, not Relaycast identities.
-                // Stage the validated metadata-only wake directly through the broker so
-                // a missing Relaycast registration cannot strand a live babysitter.
-                // The CR remains a separate write: a critical-section begin can arrive
-                // while this write is in flight and must be able to defer submission.
-                await this.#fleet.sendInput(input.to, input.text);
-                targets = [input.to];
-            }
-            else if (!this.#fleet.waitForInjected) {
+            if (!this.#fleet.waitForInjected) {
                 await this.#fleet.sendMessage(input);
                 if (this.#stopping || state.cancelled) {
                     state.deliveringKinds = undefined;
@@ -6403,7 +6723,12 @@ export class FactoryLoop {
                 prNumber: prRef.prNumber,
                 babysitter: spawned.name,
             });
-            if (this.#fleet.waitForInjected) {
+            // Internal PTY spawns receive `task` atomically in spawnPty. Re-sending
+            // the same task through Relaycast before the worker has registered its
+            // messaging identity can fail an otherwise successful spawn and erase
+            // valid babysitter ownership. Remote placement still needs the explicit,
+            // confirmed follow-up injection used by its spawn protocol.
+            if (this.#fleet.waitForInjected && this.#fleet.placementLocality !== 'local') {
                 const input = {
                     to: tracked?.result?.name ?? spawned.name,
                     text: task,
@@ -6637,7 +6962,7 @@ export class FactoryLoop {
             }
             const releaseReason = humanReview ? 'issue-human-review' : 'issue-done';
             releaseReasonForRetry = releaseReason;
-            if (this.#fleet.placementLocality === 'remote') {
+            if (this.#usesDurableDispatchLifecycle()) {
                 // Durable capacity is released as soon as terminal writeback is
                 // acknowledged. Agent cleanup remains fenced/retryable in `releasing`.
                 const batch = await this.#batch();
@@ -6667,7 +6992,7 @@ export class FactoryLoop {
             this.#babysitterPr.delete(completionKey);
             await this.#cancelBabysitterWake(completionKey);
             const durable = await this.#state.getDispatchLifecycle(this.#workspaceId, issueKey(record.issue)).catch(() => undefined);
-            if (this.#fleet.placementLocality !== 'remote' || (durable && isTerminalDispatchLifecycle(durable))) {
+            if (!this.#usesDurableDispatchLifecycle() || (durable && isTerminalDispatchLifecycle(durable))) {
                 for (const publishedKey of this.#publishedPullRequests.keys()) {
                     if (publishedKey.startsWith(`${completionKey}:`))
                         this.#publishedPullRequests.delete(publishedKey);
@@ -6677,7 +7002,16 @@ export class FactoryLoop {
     }
     #emit(event, payload) {
         for (const listener of this.#listeners.get(event) ?? []) {
-            listener(payload);
+            try {
+                listener(payload);
+            }
+            catch (error) {
+                this.#increment('factoryEventListenerFailures');
+                this.#logger.warn?.('[factory] event listener failed', {
+                    event,
+                    errorClass: error instanceof Error ? error.name : 'Error',
+                });
+            }
         }
     }
     #error(error, issue) {
@@ -6692,6 +7026,48 @@ export class FactoryLoop {
             ...details,
             ...(issue ? { issue: issue.key } : {}),
         });
+        const failureCode = telemetryCategory(error && typeof error === 'object' && 'code' in error && typeof error.code === 'string'
+            ? error.code
+            : 'factory_error');
+        const failureClass = telemetryErrorClass(error);
+        void (async () => {
+            try {
+                const lifecycle = issue
+                    ? await this.#state.getDispatchLifecycle(this.#workspaceId, issueKey(issue)).catch(() => undefined)
+                    : undefined;
+                if (lifecycle) {
+                    await this.#reportLifecycle(lifecycle, 'factory.failure', {
+                        level: 'error',
+                        errorCode: failureCode,
+                    });
+                    return;
+                }
+                await this.#report({
+                    type: 'factory.failure',
+                    level: 'error',
+                    attributes: {
+                        backend: this.#fleet.placementLocality === 'remote' ? 'relay' : 'internal',
+                        component: 'orchestrator',
+                        operation: 'error',
+                        errorClass: failureClass,
+                        errorCode: failureCode,
+                    },
+                });
+            }
+            catch (telemetryError) {
+                // This is the terminal guard for the intentionally floating telemetry
+                // task. Never log raw messages or allow a custom logger to turn this
+                // best-effort path into an unhandled rejection.
+                try {
+                    this.#logger.warn?.('[factory] failed to report failure telemetry', {
+                        errorClass: telemetryErrorClass(telemetryError),
+                    });
+                }
+                catch {
+                    // Reporting and logging are both non-critical to orchestration.
+                }
+            }
+        })();
         this.#emit('error', { error, ...details, issue });
     }
     #surfaceEscalationDeliveryFailure(kind, issue, correlationId, reason, cause) {
@@ -7755,7 +8131,7 @@ export class FactoryLoop {
             }
             let lifecycleDecision = waiting.decision;
             let promotedLifecycle;
-            if (!waiting.dryRun && this.#fleet.placementLocality === 'remote') {
+            if (!waiting.dryRun && this.#usesDurableDispatchLifecycle()) {
                 try {
                     const claim = await this.#claimDispatchLifecycle(waiting.decision, false);
                     const lifecycleKey = issueKey(waiting.issue);
@@ -8444,6 +8820,9 @@ export function isDispatchableIssue(issue) {
     if (!isGithubIssue(issue)) {
         return false;
     }
+    if (githubFactoryIssueIsClosed(issue)) {
+        return false;
+    }
     const payload = wrappedPayload(issue.raw);
     const source = asRecord(payload.source);
     const sourceId = stringValue(source?.id);
@@ -8458,6 +8837,7 @@ const isGithubIssue = (issue) => {
     return stringValue(source?.provider)?.toLowerCase() === 'github' &&
         (stringValue(wrapper?.provider)?.toLowerCase() === 'github' || isGithubIssueFilePath(issue.path));
 };
+const githubFactoryIssueIsClosed = (issue) => (issue.state?.name ?? stringValue(wrappedPayload(issue.raw).state) ?? '').trim().toLowerCase() === 'closed';
 const githubIssueSourceRef = (issue) => {
     const source = asRecord(wrappedPayload(issue.raw).source);
     if (stringValue(source?.provider)?.toLowerCase() !== 'github') {
@@ -8906,13 +9286,15 @@ const githubIssueRefIdentity = (issue) => {
     return parts ? githubIssueIdentity(parts.owner, parts.repo, parts.number) : undefined;
 };
 const githubIssuePathPreference = (path) => {
-    if (path.includes('/issues/by-id/'))
-        return 0;
     if (path.endsWith('/meta.json'))
+        return 0;
+    if (path.endsWith('/metadata.json'))
         return 1;
-    if (path.endsWith('.json'))
+    if (path.includes('/issues/by-id/'))
         return 2;
-    return 3;
+    if (path.endsWith('.json'))
+        return 3;
+    return 4;
 };
 const githubAgentNameMatchesIssue = (name, issue) => {
     const parts = githubIssuePathParts(issue.path);
@@ -9228,11 +9610,15 @@ export const githubRepoSubscriptionGlobs = (config) => configuredGithubRepoParts
 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`);
+        for (const root of githubIssueRepoRoots(owner, repo))
+            roots.add(root);
     }
     return [...roots];
 };
+const githubIssueRepoRoots = (owner, repo) => [
+    `${GITHUB_ISSUE_ROOT}/${owner}/${repo}/issues`,
+    `${GITHUB_ISSUE_ROOT}/${owner}__${repo}/issues`,
+];
 const githubRepoPathParts = (path) => {
     const compactSegment = path.match(/^\/github\/repos\/([^/]+)\//u)?.[1];
     const separator = compactSegment?.indexOf('__') ?? -1;
@@ -9981,7 +10367,13 @@ const isAgentAlreadyExistsError = (error) => {
 const defaultRestartPolicy = (spec) => 
 // 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'
+// The reviewer shares the implementer's dispatch lifecycle: it is spawned in
+// the same batch, torn down by the same dispatch-failure/teardown paths, and
+// resumed through the same durable #resumeDurableDispatch flow. Without this
+// opt-out the broker's default restart policy re-registers a torn-down
+// reviewer's name as an orphan (relay#1116-family) while the dashboard only
+// reports dispatch_failed — the exact orphan/restart sequence being audited.
+spec.role === 'implementer' || spec.role === 'reviewer' || spec.role === 'babysitter'
     ? { maxRestarts: 0 }
     : spec.restartPolicy;
 const slackPayloadTs = (threadId) => threadId.replace(/_/g, '.');
@@ -10046,9 +10438,52 @@ const failedIterationReport = (error, dryRun) => {
 };
 const isRegistrationLagInjectionError = (error) => {
     const { errorMessage } = describeError(error);
-    return /recipient unavailable|not registered|unknown recipient|no such (agent|recipient)|timed out waiting for delivery_injected/i
+    return /agent_not_found|recipient unavailable|not registered|unknown recipient|no such (agent|recipient)|timed out waiting for delivery_injected/i
         .test(errorMessage);
 };
+const isDispatchDeliveryError = (error) => {
+    if (isRegistrationLagInjectionError(error))
+        return true;
+    const { errorMessage } = describeError(error);
+    return /delivery[_ -]failed|dead-lettered|max delivery retries exceeded/iu.test(errorMessage);
+};
+const factoryCloudDispatchCancellationReason = (error) => {
+    if (error instanceof LiveDispatchStateChangedError)
+        return 'source_state_changed';
+    if (error && typeof error === 'object' && 'factoryCancellationReason' in error) {
+        const reason = error.factoryCancellationReason;
+        if (reason === 'agent_spawn_failed' || reason === 'agent_delivery_failed')
+            return reason;
+    }
+    return 'dispatch_failed';
+};
+const telemetryRunStatus = (phase) => {
+    switch (phase) {
+        case 'queued':
+            return 'queued';
+        case 'retryable':
+            return 'blocked';
+        case 'parking':
+        case 'waiting-for-human':
+            return 'waiting';
+        case 'complete':
+            return 'succeeded';
+        case 'abandoned':
+            return 'cancelled';
+        default:
+            return 'running';
+    }
+};
+const telemetryCategory = (value) => {
+    if (!value)
+        return undefined;
+    const normalized = value.trim().toLowerCase().replace(/[^a-z0-9._:/-]+/gu, '-');
+    return normalized.slice(0, 120) || undefined;
+};
+const telemetryErrorClass = (error) => {
+    const name = error instanceof Error ? error.name : '';
+    return /^[A-Za-z][A-Za-z0-9]{0,63}(?:Error|Exception)$/u.test(name) ? name : 'Error';
+};
 const isTimeoutError = (error) => error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError');
 const retryOnTimeout = async (fn, opts) => {
     let lastError;