@agent-relay/factory 0.1.56 → 0.1.58

package/dist/orchestrator/factory.js

@@ -27,6 +27,7 @@ import { CoalescedTaskQueue } from './coalesced-task-queue.js';
 import { findAgentProcessByName, readProcessIdentity } from './process-identity.js';
 import { readFactoryInFlightRegistry, terminatePids } from './reaper.js';
 import { createFactoryCloudEventV1, factoryCloudReleaseReasonV1, } from '../observability/events.js';
+import { boundedRunCostTotal, CostLedger } from '../cost/ledger.js';
 class ClarificationWakeLeaseLostError extends Error {
 }
 class ClarificationQuestionDeliveryLeaseLostError extends Error {
@@ -131,6 +132,44 @@ const STALE_LOCAL_AGENT_RECLAIM_MAX_ATTEMPTS = 3;
 const STALE_LOCAL_AGENT_RECLAIM_BACKOFF_MS = 500;
 export const DEFAULT_FACTORY_LOOP_HEARTBEAT_PATH = '/tmp/factory-run/factory-loop-heartbeat.json';
 export const DEFAULT_FACTORY_LOOP_REGISTRY_PATH = '/tmp/factory-run/factory-loop-registry.json';
+// #githubApiFallbackIssues is append-only in memory for the life of the
+// process; bound it so a long-running `factory start --mode live` daemon
+// doesn't accumulate one entry per fallback dispatch forever.
+const GITHUB_API_FALLBACK_ISSUES_MAX = 2_000;
+// A small, separately-bounded record of recently evicted identities, so a
+// later miss can be reported as "eligibility was evicted" rather than
+// silently folded into the same signal as "never was eligible" — an
+// operator investigating a false phantom-skip needs to tell those apart.
+const GITHUB_API_FALLBACK_ISSUES_EVICTED_MAX = 200;
+/**
+ * Adds `identity` to `eligible`, evicting the least-recently-registered
+ * entry once at capacity (Sets preserve insertion order; delete+add
+ * refreshes an existing identity's recency instead of leaving it at its
+ * original position). An evicted identity moves into `evicted` — itself
+ * bounded — so a later caller can tell "eligibility was evicted" apart from
+ * "never was eligible" instead of collapsing both into the same signal.
+ * Exported standalone (pure, no class state) so the bounding and eviction
+ * behavior is directly testable without driving thousands of dispatches
+ * through a full FactoryLoop to fill the production-sized set.
+ */
+export function rememberBoundedFallbackEligibility(eligible, evicted, identity, maxEligible, maxEvicted) {
+    evicted.delete(identity);
+    eligible.delete(identity);
+    eligible.add(identity);
+    if (eligible.size <= maxEligible)
+        return;
+    const oldest = eligible.values().next().value;
+    if (oldest === undefined)
+        return;
+    eligible.delete(oldest);
+    evicted.delete(oldest);
+    evicted.add(oldest);
+    if (evicted.size <= maxEvicted)
+        return;
+    const oldestEvicted = evicted.values().next().value;
+    if (oldestEvicted !== undefined)
+        evicted.delete(oldestEvicted);
+}
 class DispatchLifecycleCapacityError extends Error {
 }
 class DispatchLifecycleOwnedElsewhereError extends Error {
@@ -180,6 +219,7 @@ export class FactoryLoop {
     #relayflows;
     #worktrees;
     #reporter;
+    #costLedger;
     #batchView;
     #batchReady;
     #listeners = new Map();
@@ -197,6 +237,8 @@ export class FactoryLoop {
     #githubIssueAuthors = new Map();
     #githubIssueAuthorLookups = new Map();
     #githubIssuePreferredPaths = new Map();
+    #githubApiFallbackIssues = new Set();
+    #githubApiFallbackIssuesEvicted = new Set();
     #githubIssuePathIndexReady = false;
     #slackReporterUserIds = new Map();
     #slackReporterUserIdLookups = new Map();
@@ -249,6 +291,10 @@ export class FactoryLoop {
     #subscription;
     #livePollTimer;
     #livePollInFlight = false;
+    // The effective transport includes per-start overrides, which can differ
+    // from config.liveSubscription. Persist it so status/heartbeat describes
+    // the listener that was actually registered.
+    #liveTransport;
     #liveEventCursor;
     #liveEventHighWatermark;
     #liveConnectStartedAtMs = 0;
@@ -275,6 +321,9 @@ export class FactoryLoop {
     #reconciledAgentExitsActive = 0;
     #reconciledAgentExitWaiters = [];
     #agentLifecycleSignalsInFlight = new Map();
+    #agentUsageInFlight = new Set();
+    #dispatchLifecyclePersistenceSerial = new Map();
+    #agentUsageGroups = new Set();
     #startupAgentAdoptionActive = false;
     #startupRosterExitSignals;
     // Composite issue + PR identities for which a babysitter has already been spawned, so repeated
@@ -313,6 +362,8 @@ export class FactoryLoop {
     #offDeliveryFailed;
     #offAgentMessage;
     #offAgentLifecycleSignal;
+    #offAgentUsage;
+    #offUnpricedModel;
     // undefined = readiness not yet probed; resolved lazily so the standalone
     // runOnce() path (which skips #start) still ingests when the mount is present.
     #githubIngestionEnabled;
@@ -375,6 +426,10 @@ export class FactoryLoop {
         this.#relayflows = ports.relayflows;
         this.#worktrees = ports.worktrees;
         this.#reporter = ports.reporter;
+        this.#costLedger = ports.costLedger ?? new CostLedger();
+        this.#offUnpricedModel = this.#costLedger.onUnpricedModel((record) => {
+            void this.#reportUnpricedModel(record);
+        });
         this.#state = ports.stateStore ?? new InMemoryStateStore({
             batchSize: config.batchSize,
             agentQuestionDedupeLimit: AGENT_QUESTION_DEDUPE_LIMIT,
@@ -611,6 +666,11 @@ export class FactoryLoop {
             this.#schedulePreviewSweep();
             try {
                 await this.#startLiveSubscription(issueSource, opts.liveSubscription);
+                // The initial live heartbeat is intentionally written before startup
+                // so crash reapers can see a daemon while it bootstraps. Write again
+                // once the listener is actually registered so external `factory
+                // status` can distinguish a quiet feed from no listener.
+                await this.#writeLiveHeartbeat('running');
                 await this.#rearmSlackReplyWatchers();
                 await this.#drainReadyClarificationWake();
                 await this.#rearmGithubIssueCommentWatchers();
@@ -736,12 +796,17 @@ export class FactoryLoop {
             this.#offDeliveryFailed?.();
             this.#offAgentMessage?.();
             this.#offAgentLifecycleSignal?.();
+            this.#offAgentUsage?.();
+            this.#offUnpricedModel?.();
             await Promise.allSettled([...this.#agentLifecycleSignalsInFlight.values()]);
+            await this.#drainAgentUsage();
             await this.#slackConversationTurns.stop();
             this.#offAgentExit = undefined;
             this.#offDeliveryFailed = undefined;
             this.#offAgentMessage = undefined;
             this.#offAgentLifecycleSignal = undefined;
+            this.#offAgentUsage = undefined;
+            this.#offUnpricedModel = undefined;
             await this.#fleet.dispose();
         }
         finally {
@@ -809,6 +874,7 @@ export class FactoryLoop {
     }
     async #startLiveSubscription(issueSource, overrides = {}) {
         const options = this.#liveOptions(overrides);
+        this.#liveTransport = options.transport;
         this.#liveConnectStartedAtMs = this.#clock.now();
         this.#liveReplaySkewMarginMs = options.replaySkewMarginMs;
         const highWatermark = await this.#currentEventHighWatermark();
@@ -2051,7 +2117,10 @@ export class FactoryLoop {
         const dispatched = this.#dispatchUnlocked(decision, opts);
         this.#dispatchInFlight.set(key, dispatched);
         try {
-            return await dispatched;
+            const result = await dispatched;
+            if (decision.issueResolution)
+                result.issueResolution = structuredClone(decision.issueResolution);
+            return result;
         }
         finally {
             if (this.#dispatchInFlight.get(key) === dispatched) {
@@ -2085,7 +2154,11 @@ export class FactoryLoop {
             this.#error(error, decision.issue);
             throw error;
         }
-        const liveIssue = await this.#readIssue(decision.issue.path);
+        // This read runs before `decision` has any tracked record for
+        // #deriveGithubApiFallbackEligibility to find (batch insertion happens
+        // later, once scope/readiness are validated), so pass it directly
+        // rather than registering it into the cache first.
+        const liveIssue = await this.#readIssue(decision.issue.path, decision);
         if (!liveIssue || !isInFactoryScope(liveIssue, this.#config.safety)) {
             const error = new Error(`Refusing to dispatch ${decision.issue.key}: not factory-e2e scope`);
             this.#error(error, decision.issue);
@@ -2440,8 +2513,27 @@ export class FactoryLoop {
             counters: { ...this.#counters },
             slackDegraded: this.#slackDegraded,
             slackDegradedReason: this.#slackDegradedReason,
+            eventListener: this.#eventListenerStatus(),
         };
     }
+    #eventListenerStatus() {
+        if (this.#startMode !== 'live') {
+            return {
+                state: 'not-listening',
+                reason: this.#startMode ? `factory mode is ${this.#startMode}` : 'factory has not started',
+            };
+        }
+        if (!this.#liveHeartbeatActive) {
+            return { state: 'not-listening', reason: 'live daemon heartbeat is inactive' };
+        }
+        if (this.#subscription) {
+            return { state: 'subscribed' };
+        }
+        if (this.#liveTransport === 'poll') {
+            return { state: 'polling' };
+        }
+        return { state: 'starting' };
+    }
     on(event, listener) {
         let listeners = this.#listeners.get(event);
         if (!listeners) {
@@ -2489,6 +2581,9 @@ export class FactoryLoop {
                 return handling;
             });
         }
+        if (!this.#offAgentUsage) {
+            this.#offAgentUsage = this.#fleet.onAgentUsage?.((usage) => this.#queueAgentUsage(usage));
+        }
     }
     #queueAgentExit(name, reason) {
         const startupSignals = this.#startupRosterExitSignals;
@@ -2554,6 +2649,7 @@ export class FactoryLoop {
                     continue;
                 }
                 this.#dispatchLifecycleEpochs.set(claim.key ?? key, claim.lease.epoch);
+                this.#hydrateCostLedger(claim.lifecycle);
                 if (claim.lifecycle.phase === 'waiting-for-human')
                     continue;
                 const durableRecord = inFlightRecordFromLifecycle(claim.lifecycle);
@@ -2844,6 +2940,7 @@ export class FactoryLoop {
             throw new Error(`Refusing to dispatch ${decision.issue.key}: ${reason}`);
         }
         this.#dispatchLifecycleEpochs.set(claim.key ?? key, claim.lease.epoch);
+        this.#hydrateCostLedger(claim.lifecycle);
         this.#scheduleDispatchLifecycleRenewal();
         if (claim.created) {
             await this.#reportLifecycle(claim.lifecycle, 'run.started');
@@ -2924,48 +3021,296 @@ export class FactoryLoop {
             },
         });
     }
-    async #saveDispatchLifecycle(record, phase, pullRequest, releaseReason, releasedAgentNames = new Set(), telemetry = {}) {
-        if (record.dryRun || !this.#usesDurableDispatchLifecycle())
-            return true;
-        const key = issueKey(record.issue);
+    async #handleAgentUsage(usage, key) {
+        const record = (await this.#batch()).getIssueByAgent(usage.name);
+        const activeRecord = record && issueKey(record.issue) === key ? record : undefined;
+        let tracked = activeRecord?.agents.get(usage.name);
+        const lifecycle = await this.#state.getDispatchLifecycle(this.#workspaceId, key);
+        // Completion removes the in-memory batch record immediately after the
+        // terminal lifecycle write. A broker usage snapshot can arrive in that
+        // narrow window; consult durable state so the drop is observable instead
+        // of silently looking like an unknown agent.
+        if (!lifecycle)
+            return;
+        tracked ??= lifecycle.agents.find((agent) => agent.name === usage.name)?.tracked;
+        if (!tracked)
+            return;
+        if (isTerminalDispatchLifecycle(lifecycle)) {
+            await this.#noteDroppedTerminalCostUsage(lifecycle, tracked, usage);
+            return;
+        }
+        const lifecycleRecord = activeRecord ?? inFlightRecordFromLifecycle(lifecycle);
         const epoch = this.#dispatchLifecycleEpochs.get(key);
         if (epoch === undefined) {
-            this.#scheduleDispatchLifecycleRetry(record);
-            return false;
+            this.#increment('costUsagePersistenceUnavailable');
+            this.#logger.warn?.('[factory] unable to persist agent token usage without a durable lifecycle lease', {
+                agentName: usage.name,
+                issue: lifecycle.issue.key,
+            });
+            await this.#reportLifecycle(lifecycle, 'factory.anomaly', {
+                level: 'error',
+                errorCode: 'cost_usage_lease_unavailable',
+            });
+            return;
         }
-        const previous = await this.#state.getDispatchLifecycle(this.#workspaceId, key);
-        const pullRequests = mergePublishedPullRequests(previous, pullRequest);
-        const primaryPullRequest = primaryPublishedPullRequest(previous, pullRequest, pullRequests);
-        const lifecycle = lifecycleFromInFlightRecord(record, previous?.runId ?? randomUUID(), phase, this.#clock.now(), primaryPullRequest, pullRequests, releaseReason ?? previous?.releaseReason);
-        for (const agent of lifecycle.agents) {
-            const previouslyReleasedAtMs = previous?.agents.find((candidate) => candidate.name === agent.name)?.releasedAtMs;
-            if (previouslyReleasedAtMs !== undefined)
-                agent.releasedAtMs = previouslyReleasedAtMs;
-            if (releasedAgentNames.has(agent.name))
-                agent.releasedAtMs ??= this.#clock.now();
+        const lifecycleAgent = lifecycle.agents.find((agent) => agent.name === usage.name);
+        if (!lifecycleAgent) {
+            this.#increment('costUsageLifecycleAgentMissing');
+            this.#logger.warn?.('[factory] unable to persist agent token usage for an untracked durable agent', {
+                agentName: usage.name,
+                issue: lifecycle.issue.key,
+            });
+            return;
         }
-        const saved = await this.#state.saveDispatchLifecycle(this.#workspaceId, key, this.#dispatchLifecycleOwner, epoch, this.#clock.now(), lifecycle);
-        if (!saved) {
-            this.#dispatchLifecycleEpochs.delete(key);
-            this.#increment('dispatchLifecycleFencesRejected');
+        const model = usage.model ?? tracked.spec.model ?? 'unknown';
+        const groupId = costUsageGroupId(lifecycle.runId, tracked);
+        this.#costLedger.record({
+            runId: lifecycle.runId,
+            role: tracked.spec.role,
+            model,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+        }, { entryId: costEntryId(groupId, model) });
+        const nextUsage = mergeDispatchLifecycleAgentUsage(lifecycleAgent.costUsage, {
+            model,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+        });
+        const nextLifecycle = {
+            ...lifecycle,
+            agents: lifecycle.agents.map((agent) => agent.name === usage.name
+                ? { ...agent, costUsage: nextUsage }
+                : agent),
+            cost: boundedRunCostTotal(this.#costLedger.getRunTotal(lifecycle.runId)),
+            updatedAtMs: this.#clock.now(),
+        };
+        let saved;
+        try {
+            saved = await this.#state.saveDispatchLifecycle(this.#workspaceId, key, this.#dispatchLifecycleOwner, epoch, this.#clock.now(), nextLifecycle);
+        }
+        catch (error) {
             await this.#reportLifecycle(lifecycle, 'factory.anomaly', {
                 level: 'error',
-                errorCode: 'fence_rejected',
+                errorCode: 'cost_usage_persistence_failed',
             });
-            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 });
+            throw error;
         }
-        if (isTerminalDispatchLifecycle(lifecycle)) {
+        if (!saved) {
             this.#dispatchLifecycleEpochs.delete(key);
+            const latest = await this.#state.getDispatchLifecycle(this.#workspaceId, key);
+            if (latest && isTerminalDispatchLifecycle(latest)) {
+                await this.#noteDroppedTerminalCostUsage(latest, tracked, usage);
+            }
+            else {
+                this.#increment('costUsagePersistenceFailures');
+                this.#logger.warn?.('[factory] unable to persist agent token usage', {
+                    agentName: usage.name,
+                    issue: lifecycle.issue.key,
+                    reason: 'fence_rejected',
+                });
+                await this.#reportLifecycle(lifecycle, 'factory.anomaly', {
+                    level: 'error',
+                    errorCode: 'cost_usage_persistence_failed',
+                });
+                this.#scheduleDispatchLifecycleRetry(lifecycleRecord);
+            }
+            return;
         }
-        return true;
+        this.#agentUsageGroups.add(groupId);
+    }
+    async #findDispatchLifecycleAgent(name) {
+        let match;
+        for (const [key, lifecycle] of await this.#state.listDispatchLifecycles(this.#workspaceId)) {
+            const agent = lifecycle.agents.find((candidate) => candidate.name === name);
+            if (!agent || (match && match.lifecycle.updatedAtMs >= lifecycle.updatedAtMs))
+                continue;
+            match = { key, lifecycle, tracked: agent.tracked };
+        }
+        return match;
+    }
+    async #dispatchLifecycleKeyForAgent(name) {
+        const record = (await this.#batch()).getIssueByAgent(name);
+        if (record?.agents.has(name))
+            return issueKey(record.issue);
+        return (await this.#findDispatchLifecycleAgent(name))?.key;
+    }
+    #serializeDispatchLifecyclePersistence(key, operation) {
+        const queued = (this.#dispatchLifecyclePersistenceSerial.get(key) ?? Promise.resolve())
+            .catch(() => undefined)
+            .then(operation);
+        const settled = queued.then(() => undefined, () => undefined);
+        this.#dispatchLifecyclePersistenceSerial.set(key, settled);
+        void settled.then(() => {
+            if (this.#dispatchLifecyclePersistenceSerial.get(key) === settled) {
+                this.#dispatchLifecyclePersistenceSerial.delete(key);
+            }
+        });
+        return queued;
+    }
+    #queueAgentUsage(usage) {
+        // Usage reports are cumulative snapshots. Serializing their read/modify/
+        // save cycle with phase changes prevents either mutation from replacing
+        // the other's durable per-agent cost just before an owner restart.
+        const handling = this.#dispatchLifecycleKeyForAgent(usage.name)
+            .then((key) => {
+            return key
+                ? this.#serializeDispatchLifecyclePersistence(key, () => this.#handleAgentUsage(usage, key))
+                : undefined;
+        })
+            .catch(async (error) => {
+            this.#increment('costUsageRecordingFailures');
+            this.#logger.warn?.('[factory] unable to record agent token usage', {
+                agentName: usage.name,
+                errorClass: telemetryErrorClass(error),
+            });
+        })
+            .finally(() => {
+            this.#agentUsageInFlight.delete(handling);
+        });
+        this.#agentUsageInFlight.add(handling);
+        return handling;
+    }
+    async #noteDroppedTerminalCostUsage(lifecycle, tracked, usage) {
+        this.#increment('costUsageDroppedAfterTerminal');
+        await this.#report({
+            type: 'factory.anomaly',
+            level: 'warn',
+            runId: lifecycle.runId,
+            attributes: {
+                errorCode: 'cost_usage_after_terminal',
+                agentRole: tracked.spec.role,
+                model: usage.model ?? tracked.spec.model ?? 'unknown',
+                inputTokens: usage.inputTokens,
+                outputTokens: usage.outputTokens,
+            },
+        });
+    }
+    #hydrateCostLedger(lifecycle) {
+        for (const agent of lifecycle.agents) {
+            const usage = agent.costUsage ?? [];
+            if (usage.length === 0)
+                continue;
+            const groupId = costUsageGroupId(lifecycle.runId, agent.tracked);
+            for (const entry of usage) {
+                this.#costLedger.record({
+                    runId: lifecycle.runId,
+                    role: agent.tracked.spec.role,
+                    model: entry.model,
+                    inputTokens: entry.inputTokens,
+                    outputTokens: entry.outputTokens,
+                }, {
+                    entryId: costEntryId(groupId, entry.model),
+                    notifyUnpriced: false,
+                });
+            }
+            this.#agentUsageGroups.add(groupId);
+        }
+    }
+    async #drainAgentUsage() {
+        while (this.#agentUsageInFlight.size > 0) {
+            await Promise.allSettled([...this.#agentUsageInFlight]);
+        }
+    }
+    async #reportUnpricedModel(record) {
+        await this.#report({
+            type: 'cost.model.unpriced',
+            level: 'warn',
+            runId: record.runId,
+            attributes: {
+                agentRole: record.role,
+                model: record.model,
+                inputTokens: record.inputTokens,
+                outputTokens: record.outputTokens,
+                usd: null,
+            },
+        });
+    }
+    #finalizeRunCost(record, runId) {
+        for (const tracked of record.agents.values()) {
+            const groupId = costUsageGroupId(runId, tracked);
+            if (this.#agentUsageGroups.has(groupId))
+                continue;
+            this.#costLedger.record({
+                runId,
+                role: tracked.spec.role,
+                model: tracked.spec.model ?? 'unknown',
+                inputTokens: null,
+                outputTokens: null,
+            }, { entryId: costEntryId(groupId, 'missing') });
+        }
+        return boundedRunCostTotal(this.#costLedger.getRunTotal(runId));
+    }
+    async #reportRunCost(lifecycle) {
+        if (!lifecycle.cost)
+            return;
+        const { runId: _runId, ...cost } = lifecycle.cost;
+        await this.#report({
+            type: 'run.cost.v1',
+            level: 'info',
+            runId: lifecycle.runId,
+            status: telemetryRunStatus(lifecycle.phase),
+            attributes: {
+                inputTokens: lifecycle.cost.inputTokens,
+                outputTokens: lifecycle.cost.outputTokens,
+                usd: lifecycle.cost.usd,
+            },
+            cost,
+        });
+    }
+    async #saveDispatchLifecycle(record, phase, pullRequest, releaseReason, releasedAgentNames = new Set(), telemetry = {}) {
+        if (record.dryRun || !this.#usesDurableDispatchLifecycle())
+            return true;
+        if (isTerminalDispatchPhase(phase))
+            await this.#drainAgentUsage();
+        const key = issueKey(record.issue);
+        return this.#serializeDispatchLifecyclePersistence(key, async () => {
+            const epoch = this.#dispatchLifecycleEpochs.get(key);
+            if (epoch === undefined) {
+                this.#scheduleDispatchLifecycleRetry(record);
+                return false;
+            }
+            const previous = await this.#state.getDispatchLifecycle(this.#workspaceId, key);
+            const pullRequests = mergePublishedPullRequests(previous, pullRequest);
+            const primaryPullRequest = primaryPublishedPullRequest(previous, pullRequest, pullRequests);
+            const lifecycleRunId = previous?.runId ?? randomUUID();
+            const cost = isTerminalDispatchPhase(phase)
+                ? this.#finalizeRunCost(record, lifecycleRunId)
+                : previous?.cost;
+            const lifecycle = lifecycleFromInFlightRecord(record, lifecycleRunId, phase, this.#clock.now(), primaryPullRequest, pullRequests, releaseReason ?? previous?.releaseReason, cost);
+            for (const agent of lifecycle.agents) {
+                const previousAgent = previous?.agents.find((candidate) => candidate.name === agent.name);
+                if (previousAgent?.releasedAtMs !== undefined)
+                    agent.releasedAtMs = previousAgent.releasedAtMs;
+                if (previousAgent?.costUsage)
+                    agent.costUsage = structuredClone(previousAgent.costUsage);
+                if (releasedAgentNames.has(agent.name))
+                    agent.releasedAtMs ??= this.#clock.now();
+            }
+            const saved = await this.#state.saveDispatchLifecycle(this.#workspaceId, key, this.#dispatchLifecycleOwner, epoch, this.#clock.now(), lifecycle);
+            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))
+                    await this.#reportRunCost(lifecycle);
+            }
+            if (isTerminalDispatchLifecycle(lifecycle)) {
+                this.#dispatchLifecycleEpochs.delete(key);
+            }
+            return true;
+        });
     }
     #resolveDispatchTerminalWaiters(issue) {
         const key = issueKey(issue);
@@ -3069,6 +3414,7 @@ export class FactoryLoop {
                 throw new DispatchLifecycleOwnedElsewhereError(claim.lifecycle.lease?.leaseUntilMs);
             }
             this.#dispatchLifecycleEpochs.set(claim.key ?? key, claim.lease.epoch);
+            this.#hydrateCostLedger(claim.lifecycle);
             this.#scheduleDispatchLifecycleRenewal();
             lifecycle = claim.lifecycle;
             acquiredNow = true;
@@ -3254,7 +3600,11 @@ export class FactoryLoop {
     async #resumeDurableDispatch(record) {
         let liveIssue;
         if (!record.dryRun) {
-            liveIssue = await this.#readIssue(record.issue.path);
+            // record is already inserted into the batch by the time any phase
+            // handler runs (BatchTracker.restore, called before this), so
+            // #deriveGithubApiFallbackEligibility would find it there too — the
+            // explicit hint is defense in depth, not a requirement.
+            liveIssue = await this.#readIssue(record.issue.path, record.decision);
             if (!liveIssue) {
                 throw new Error(`Unable to recover durable dispatch ${record.issue.key}: issue is not currently readable`);
             }
@@ -3856,7 +4206,62 @@ export class FactoryLoop {
             this.#logger.error?.('[factory] failed to ingest GitHub issue', error);
         }
     }
-    async #readGithubIssue(path) {
+    #rememberGithubApiFallbackEligible(identity) {
+        rememberBoundedFallbackEligibility(this.#githubApiFallbackIssues, this.#githubApiFallbackIssuesEvicted, identity, GITHUB_API_FALLBACK_ISSUES_MAX, GITHUB_API_FALLBACK_ISSUES_EVICTED_MAX);
+    }
+    /**
+     * `#githubApiFallbackIssues` is a cache, not a source of truth: eligibility
+     * is derived here, not remembered by every caller. A restart (or any read
+     * path added later that never registered anything) still resolves
+     * correctly because this checks the actual current state instead of
+     * requiring every entry point to have called a registration method first.
+     *
+     * A decision can durably outlive the original dispatch call in three
+     * shapes, and this checks all three — a fourth found later means this
+     * enumeration is incomplete, not that the approach is wrong:
+     *   1. `batch.inFlight` — an active live-dispatched or durably-restored
+     *      record (`BatchTracker.restore`/`start` insert it before any phase
+     *      handler runs).
+     *   2. `#state.listWaitingClarifications` — an issue parked awaiting a
+     *      human reply. Restoring it (`#restoreClarifications` et al.)
+     *      rebuilds an `InFlightIssue`-shaped record locally to re-arm the
+     *      watcher and does not insert it into the batch, so (1) alone misses
+     *      it.
+     *   3. `#state.listDispatchLifecycles`, non-terminal — a durably-tracked
+     *      dispatch that is not currently in-memory at all yet (e.g. a
+     *      non-durable-fleet dispatch never reaches the batch either).
+     *
+     * `decisionHint` stays a pure optimization ahead of all three: the one
+     * read that happens before its own record exists anywhere (the initial
+     * live dispatch, validating scope before it is tracked) can skip the
+     * scan entirely, but no read site is required to pass it — omitting it
+     * only costs the scan, never correctness.
+     *
+     * Deliberately scans by GitHub identity (owner/repo/number) against each
+     * candidate's own issue path rather than looking up the durable record by
+     * its composite key (uuid/key/path): the real uuid is built from GitHub's
+     * node_id/id when content is available, which a bare path cannot
+     * reconstruct, so a keyed lookup would not reliably match.
+     */
+    async #deriveGithubApiFallbackEligibility(identity, decisionHint) {
+        if (decisionHint?.issueResolution?.source === 'github-api-fallback' &&
+            githubIssueRefIdentity(decisionHint.issue) === identity) {
+            return true;
+        }
+        const inFlight = (await this.#batch()).inFlight;
+        if (isGithubApiFallbackEligible(inFlight, identity))
+            return true;
+        const [waitingClarifications, dispatchLifecycles] = await Promise.all([
+            this.#state.listWaitingClarifications(this.#workspaceId),
+            this.#state.listDispatchLifecycles(this.#workspaceId),
+        ]);
+        const durable = [
+            ...githubApiFallbackCandidatesFromWaitingClarifications(waitingClarifications),
+            ...githubApiFallbackCandidatesFromDispatchLifecycles(dispatchLifecycles),
+        ];
+        return isGithubApiFallbackEligible(durable, identity);
+    }
+    async #readGithubIssue(path, decisionHint) {
         const preferredPath = await this.#preferredGithubIssuePath(path);
         const candidatePaths = [...new Set([
                 ...githubIssueReadCandidatePaths(preferredPath),
@@ -3880,8 +4285,55 @@ export class FactoryLoop {
         }
         catch (error) {
             if (isMissingIssueFileError(error)) {
+                const parts = githubIssuePathParts(path) ?? githubIssueDirectoryPathParts(path);
+                const identity = parts ? githubIssueIdentity(parts.owner, parts.repo, parts.number) : undefined;
+                const eligible = identity
+                    ? this.#githubApiFallbackIssues.has(identity) ||
+                        await this.#deriveGithubApiFallbackEligibility(identity, decisionHint)
+                    : false;
+                if (eligible && identity)
+                    this.#rememberGithubApiFallbackEligible(identity);
+                if (parts && identity && eligible && this.#mount.githubRead) {
+                    const lookup = await this.#mount.githubRead.getIssue(`${parts.owner}/${parts.repo}`, parts.number);
+                    if (lookup.outcome === 'found') {
+                        const githubIssue = parseGithubIssue(lookup.issue.path, lookup.issue.content);
+                        this.#indexDependencyIssue(githubIssueAsFactoryIssue(githubIssue));
+                        this.#logger.warn?.('[factory] Relayfile projection missed GitHub issue; using GitHub API fallback', {
+                            repo: lookup.issue.repo,
+                            number: lookup.issue.number,
+                            source: 'github-api-fallback',
+                        });
+                        return githubIssue;
+                    }
+                    if (lookup.outcome === 'indeterminate') {
+                        // The provider lookup could not confirm absence (e.g. an
+                        // unauthenticated 404 against a repo it cannot prove is public).
+                        // That is not the same claim as "confirmed gone" — count and log
+                        // it separately so it stays visible instead of being folded into
+                        // the phantom-skip metric.
+                        this.#increment('githubIssueUnverifiable');
+                        this.#logger.warn?.('[factory] GitHub API fallback could not determine issue existence', {
+                            path,
+                            repo: `${parts.owner}/${parts.repo}`,
+                            number: parts.number,
+                            reason: lookup.reason,
+                        });
+                        return undefined;
+                    }
+                }
+                if (identity && this.#githubApiFallbackIssuesEvicted.has(identity)) {
+                    // identity was eligible for the API fallback but aged out of the
+                    // bounded set — a different claim from "never was eligible", and
+                    // one this signal must not silently collapse into a confirmed miss.
+                    this.#increment('githubIssueApiFallbackEligibilityEvicted');
+                    this.#logger.warn?.('[factory] GitHub API fallback eligibility was evicted from the bounded cache before this read', {
+                        path,
+                        identity,
+                    });
+                    return undefined;
+                }
                 this.#increment('githubIssuePhantomSkipped');
-                this.#logger.debug?.('[factory] skipped missing GitHub issue file discovered from issue tree', { path });
+                this.#logger.debug?.('[factory] skipped missing GitHub issue after projection and provider lookup', { path });
                 return undefined;
             }
             throw error;
@@ -4299,6 +4751,7 @@ export class FactoryLoop {
             updatedAt: new Date(updatedAtMs).toISOString(),
             updatedAtMs,
             registryPath,
+            eventListener: this.#eventListenerStatus(),
         };
         await mkdir(dirname(path), { recursive: true });
         await writeFile(path, `${JSON.stringify(heartbeat, null, 2)}\n`, 'utf8');
@@ -4466,10 +4919,10 @@ export class FactoryLoop {
         }
         return [...pathsByKey.values()].sort();
     }
-    async #readIssue(path) {
+    async #readIssue(path, decisionHint) {
         try {
             if (isGithubIssueFilePath(path)) {
-                const githubIssue = await this.#readGithubIssue(path);
+                const githubIssue = await this.#readGithubIssue(path, decisionHint);
                 return githubIssue ? githubIssueAsFactoryIssue(githubIssue) : undefined;
             }
             // Newly-synced issues land as a change-event STUB at the primary
@@ -5334,6 +5787,7 @@ export class FactoryLoop {
             baseRef,
             title: `${issue.key}: ${issue.title}`,
             body: githubPullRequestBody(issue, implementer.spec.preview),
+            ...(implementer.sessionRef ? { sessionRef: implementer.sessionRef } : {}),
         });
         const published = result.author
             ? result
@@ -5988,6 +6442,20 @@ export class FactoryLoop {
         if (!tracked.sessionRef) {
             return;
         }
+        // Never resume an agent against a read-denied mirror: the mount lacks the
+        // filesystem scope it needs, so the spawn would fail opaquely (roster PID
+        // never resolves) and risk operating on stale integration state. Skip with
+        // one clear message; a later attempt succeeds once the session is re-authed
+        // and Factory restarted.
+        if (this.#mount.isLocalMountAuthDegraded?.()) {
+            this.#increment('resumeSkippedMountAuthDegraded');
+            this.#logger.warn?.('[factory] tracked agent resume skipped: local mount is auth-degraded (cloud session missing relayfile fs scope); re-authenticate and restart Factory', {
+                issue: record.issue.key,
+                name,
+                role: tracked.spec.role,
+            });
+            return;
+        }
         this.#logger.debug?.('[factory] tracked agent resume preparation started', {
             issue: record.issue.key,
             name,
@@ -11133,7 +11601,7 @@ export class FactoryLoop {
         }, Math.max(1_000, Math.floor(CLARIFICATION_WAKE_LEASE_MS / 3)));
         heartbeat.unref?.();
         try {
-            if (!await this.#clarificationIssueStillActive(waiting.issue)) {
+            if (!await this.#clarificationIssueStillActive(waiting.issue, waiting.decision)) {
                 this.#assertClarificationWakeRunning();
                 await renewLease();
                 const completed = await this.#state.completeClarificationWake(this.#workspaceId, key, this.#clarificationWakeOwner);
@@ -11309,8 +11777,8 @@ export class FactoryLoop {
         if (this.#stopping)
             throw new ClarificationWakeStoppedError('factory is stopping');
     }
-    async #clarificationIssueStillActive(issueRef) {
-        const issue = await this.#readIssue(issueRef.path);
+    async #clarificationIssueStillActive(issueRef, decisionHint) {
+        const issue = await this.#readIssue(issueRef.path, decisionHint);
         if (!issue || !isInFactoryScope(issue, this.#config.safety) || !isDispatchableIssue(issue)) {
             this.#logger.info?.('[factory] clarification wake cancelled because issue left factory scope', {
                 issue: issueRef.key,
@@ -11476,12 +11944,11 @@ export class FactoryLoop {
             this.#emit('issue-queued', { issue: decision.issue });
         }
     }
-    // Absolute path to the local .integrations mount the daemon manages. The mount
-    // is created at the daemon's cwd (see ensureLocalMount), and spawned agents run
-    // in their repo clonePath, so writeback paths handed to agents must be absolute
-    // against this root rather than a bare relative `.integrations/...`.
+    // Absolute path to the one registered workspace mirror. Spawned agents run in
+    // repo clone paths, so writeback instructions must name the shared mirror,
+    // not a relative `.integrations` path or a per-repository re-home attempt.
     #integrationsMountRoot() {
-        return resolve(process.cwd(), '.integrations');
+        return this.#mount.getLocalMountRoot?.() ?? resolve(process.cwd(), '.integrations');
     }
     async #slackChannelDir() {
         if (!this.#config.slack) {
@@ -11999,8 +12466,17 @@ const pidsFromSpawnResult = (result) => {
     }
     return [...pids].sort((a, b) => a - b);
 };
-const dispatchComment = (decision, agents) => [
+// `issueResolution.detail` and `projection.localMountDegradedReason` are
+// free text that can carry an absolute local filesystem path (e.g. "mount
+// state is missing at /Users/<name>/...") — safe in the JSON result and in
+// logs, but this comment is posted to a public GitHub issue. Emit only
+// `source`, a closed enum, rather than trying to scrub paths out of free
+// text; free text is not a safe thing to scrub, only a safe thing to omit.
+export const dispatchComment = (decision, agents) => [
     `Factory dispatch for ${decision.issue.key}`,
+    decision.issueResolution
+        ? `Issue resolution: ${decision.issueResolution.source}`
+        : undefined,
     `Implementers: ${agents.filter((agent) => agent.role === 'implementer').map((agent) => agent.name).join(', ') || 'none'}`,
     decision.scope === 'workflow' ? `Workflow: ${agents.find((agent) => agent.role === 'workflow')?.name ?? 'none'}` : undefined,
     `Reviewer: ${agents.find((agent) => agent.role === 'reviewer')?.name ?? 'none'}`,
@@ -12518,11 +12994,51 @@ export const githubIssuePathParts = (path) => {
         slug: match[7],
     };
 };
-const githubIssueIdentity = (owner, repo, number) => `${owner.toLowerCase()}/${repo.toLowerCase()}#${number}`;
+export const githubIssueIdentity = (owner, repo, number) => `${owner.toLowerCase()}/${repo.toLowerCase()}#${number}`;
 const githubIssueRefIdentity = (issue) => {
     const parts = githubIssuePathParts(issue.path);
     return parts ? githubIssueIdentity(parts.owner, parts.repo, parts.number) : undefined;
 };
+/**
+ * Whether a GitHub API fallback read is eligible for `identity`, derived
+ * from currently-tracked state rather than a separately-remembered flag:
+ * `decisionHint` (the one read that happens before its own record is
+ * tracked anywhere) or any `{issue, decision}` candidate — drawn from
+ * whichever durable or in-memory store the caller has gathered — whose
+ * decision was resolved through the fallback. Exported standalone so this
+ * is directly testable — no caller has to have registered anything for
+ * this to return true for a candidate that is genuinely present, which is
+ * the property that keeps a future read call site from silently
+ * reintroducing the restart-eligibility bug by omission.
+ *
+ * A decision durably outlives the in-memory batch in more than one shape
+ * (in-flight dispatch, a parked clarification, a durable dispatch
+ * lifecycle — see #deriveGithubApiFallbackEligibility for the full list
+ * this class gathers); this function does not care which shape a
+ * candidate came from, only whether one matches.
+ */
+export function isGithubApiFallbackEligible(candidates, identity, decisionHint) {
+    if (decisionHint?.issueResolution?.source === 'github-api-fallback' &&
+        githubIssueRefIdentity(decisionHint.issue) === identity) {
+        return true;
+    }
+    return candidates.some((candidate) => candidate.decision.issueResolution?.source === 'github-api-fallback' &&
+        githubIssueRefIdentity(candidate.issue) === identity);
+}
+/** Maps durable waiting-clarification records to isGithubApiFallbackEligible candidates. */
+export function githubApiFallbackCandidatesFromWaitingClarifications(waitingClarifications) {
+    return waitingClarifications.map(([, waiting]) => ({ issue: waiting.issue, decision: waiting.decision }));
+}
+/**
+ * Maps durable dispatch-lifecycle records to isGithubApiFallbackEligible
+ * candidates, excluding terminal ones — a completed or abandoned dispatch's
+ * decision is no longer a reason to trust a live read for that issue.
+ */
+export function githubApiFallbackCandidatesFromDispatchLifecycles(dispatchLifecycles) {
+    return dispatchLifecycles
+        .filter(([, lifecycle]) => !isTerminalDispatchLifecycle(lifecycle))
+        .map(([, lifecycle]) => ({ issue: lifecycle.issue, decision: lifecycle.decision }));
+}
 const githubIssuePathPreference = (path) => {
     if (path.endsWith('/meta.json'))
         return 0;
@@ -13833,6 +14349,9 @@ const durableBabysitterTrackedAgent = (session, capability = 'spawn:claude') =>
     result: { name: session.agentName },
 });
 const isTerminalDispatchLifecycle = (lifecycle) => lifecycle.phase === 'complete' || lifecycle.phase === 'abandoned';
+const isTerminalDispatchPhase = (phase) => phase === 'complete' || phase === 'abandoned';
+const costUsageGroupId = (runId, tracked) => JSON.stringify([runId, tracked.spec.invocationId ?? tracked.spec.name]);
+const costEntryId = (groupId, model) => JSON.stringify([groupId, model]);
 const publishedPullRequests = (lifecycle) => {
     const receipts = [
         ...(lifecycle?.pullRequests ?? []).filter(Boolean),
@@ -13858,7 +14377,11 @@ const primaryPublishedPullRequest = (previous, receipt, receipts) => {
         return receipt;
     return previous?.pullRequest ?? receipt ?? receipts[0];
 };
-const lifecycleFromInFlightRecord = (record, runId, phase, updatedAtMs, pullRequest, pullRequests = [], releaseReason) => ({
+const mergeDispatchLifecycleAgentUsage = (current, next) => [
+    ...(current ?? []).filter((entry) => entry.model !== next.model),
+    structuredClone(next),
+].sort((left, right) => left.model.localeCompare(right.model));
+const lifecycleFromInFlightRecord = (record, runId, phase, updatedAtMs, pullRequest, pullRequests = [], releaseReason, cost) => ({
     runId,
     issue: { ...record.issue },
     decision: structuredClone(record.decision),
@@ -13870,6 +14393,7 @@ const lifecycleFromInFlightRecord = (record, runId, phase, updatedAtMs, pullRequ
     ...(pullRequests.length > 0 ? { pullRequests: pullRequests.map((receipt) => ({ ...receipt })) } : {}),
     ...(pullRequest ? { pullRequest: { ...pullRequest } } : {}),
     ...(releaseReason ? { releaseReason } : {}),
+    ...(cost ? { cost: structuredClone(cost) } : {}),
     updatedAtMs,
 });
 const inFlightRecordFromLifecycle = (lifecycle) => ({