@agent-relay/factory 0.1.14 → 0.1.15

package/dist/orchestrator/factory.js

@@ -41,6 +41,7 @@ const SLACK_REPLY_POLL_INTERVAL_MS = 5_000;
 const AGENT_QUESTION_DEDUPE_LIMIT = 500;
 const AGENT_NEEDS_INPUT_MARKER = '[factory-needs-input]';
 const LEGACY_AGENT_NEEDS_INPUT_MARKER = 'FACTORY_NEEDS_INPUT';
+const GITHUB_ESCALATION_MARKER_PREFIX = 'factory-escalation:';
 // The babysitter DMs `factory` with this marker once it believes the PR is
 // green; the orchestrator confirms readiness with one authoritative gh read
 // before transitioning the issue to Human Review.
@@ -104,6 +105,9 @@ export class FactoryLoop {
     #dispatchInFlight = new Map();
     #slackWatchers = new Map();
     #slackWatcherStarts = new Map();
+    #githubIssueCommentWatchers = new Map();
+    #githubIssueCommentWatchStates = new Map();
+    #githubIssueCommentQueues = new Map();
     #resolvedSlackChannelDir;
     #slackChannelDirRefresh;
     // Agents we've already logged an ambiguous-PID-lookup warning for, so the
@@ -115,6 +119,7 @@ export class FactoryLoop {
     // same notice every cycle. Cleared once the issue dispatches successfully.
     #labelDispatchFailures = new Map();
     #pendingSlackClarifications = new Map();
+    #pendingGithubClarifications = new Map();
     #postMergeDoneAdvances = new Set();
     #slackDegraded = false;
     #slackDegradedReason;
@@ -314,6 +319,7 @@ export class FactoryLoop {
             try {
                 await this.#startLiveSubscription(opts.liveSubscription);
                 await this.#rearmSlackReplyWatchers();
+                await this.#rearmGithubIssueCommentWatchers();
                 this.#scheduleCompletionSweep(0);
                 return;
             }
@@ -345,6 +351,7 @@ export class FactoryLoop {
         });
         this.#started = true;
         await this.#rearmSlackReplyWatchers();
+        await this.#rearmGithubIssueCommentWatchers();
         this.#scheduleCompletionSweep(0);
     }
     async stop() {
@@ -369,6 +376,10 @@ export class FactoryLoop {
             await this.#boundedStopTeardown('factory subscription unsubscribe', () => subscription?.unsubscribe());
             await Promise.all([...this.#slackWatchers.values()].map((watcher) => watcher.stop()));
             this.#slackWatchers.clear();
+            await Promise.all([...this.#githubIssueCommentWatchers.values()].map((watcher) => watcher.stop()));
+            this.#githubIssueCommentWatchers.clear();
+            this.#githubIssueCommentWatchStates.clear();
+            this.#githubIssueCommentQueues.clear();
             await this.#state.clearSlackThreads(this.#workspaceId);
             this.#slackWatcherStarts.clear();
             this.#offAgentExit?.();
@@ -1221,7 +1232,7 @@ export class FactoryLoop {
         }
         const escalationReason = triageEscalationReason(decision);
         if (escalationReason) {
-            const replayedResult = await this.#escalateTriageToSlack(decision, escalationReason, dryRun);
+            const replayedResult = await this.#escalateTriage(decision, escalationReason, dryRun);
             this.#recordTriageEscalation(decision, escalationReason);
             return replayedResult ?? { issue: decision.issue, agents: [], dryRun };
         }
@@ -1322,6 +1333,7 @@ export class FactoryLoop {
                 await this.#sendImplementerTask(record);
                 await this.#sendCriticalReviewerMessage(record);
                 await this.#injectPendingSlackClarification(record);
+                await this.#injectPendingGithubClarification(record);
             }
             return result;
         }
@@ -1416,7 +1428,7 @@ export class FactoryLoop {
             const decision = await this.triageIssue(issue);
             const escalationReason = triageEscalationReason(decision);
             if (escalationReason) {
-                await this.#escalateTriageToSlack(decision, escalationReason, this.#config.dryRun);
+                await this.#escalateTriage(decision, escalationReason, this.#config.dryRun);
                 this.#recordTriageEscalation(decision, escalationReason);
                 return;
             }
@@ -2406,15 +2418,11 @@ export class FactoryLoop {
                 issue: record.issue.key,
             });
         }
-        await this.#postAgentQuestionToSlack(record, question);
+        await this.#postAgentQuestion(record, question);
     }
-    async #postAgentQuestionToSlack(record, question) {
+    async #postAgentQuestion(record, question) {
         if (!this.#slack || !this.#config.slack) {
-            this.#increment('agentQuestionsSkippedNoSlack');
-            this.#logger.warn?.('[factory] agent question has no Slack channel configured', {
-                issue: record.issue,
-                from: question.agentName,
-            });
+            await this.#postAgentQuestionToGithub(record, question);
             return;
         }
         if (await this.#shouldSkipSlackWriteback('agent-question')) {
@@ -2447,6 +2455,401 @@ export class FactoryLoop {
             this.#logger.warn?.(`[factory] failed to post agent question for ${record.issue.key}`, error);
         }
     }
+    async #postAgentQuestionToGithub(record, question) {
+        const correlationId = githubEscalationCorrelationId('agent-question', record.issue, question.question);
+        const issue = await this.#readIssue(record.issue.path);
+        const source = issue ? githubIssueSourceRef(issue) : undefined;
+        const authorizedAuthor = issue ? githubIssueAuthor(issue) : undefined;
+        if (!issue || !source || !authorizedAuthor) {
+            this.#surfaceEscalationDeliveryFailure('agent-question', record.issue, correlationId, 'no Slack channel or GitHub issue write path with an identifiable issue reporter is available');
+            return;
+        }
+        await this.#addGithubIssueCommentWatch(record.issue, source, {
+            correlationId,
+            kind: 'agent-question',
+            authorizedAuthor,
+        });
+        try {
+            await this.#githubWriteback.postComment(issue, [
+                `${record.issue.key}: ${question.agentName} needs input.`,
+                `Question: ${question.question}`,
+                `Authorized responder: @${authorizedAuthor} (the issue reporter).`,
+                `Reply with a comment that starts with \`${githubReplyPrefix(correlationId)}\`.`,
+                '',
+                githubEscalationMarker(correlationId),
+            ].join('\n'));
+            this.#increment('agentQuestionsPostedToGithub');
+        }
+        catch (error) {
+            await this.#removeGithubIssueCommentPending(source, correlationId);
+            this.#surfaceEscalationDeliveryFailure('agent-question', record.issue, correlationId, 'GitHub issue comment writeback failed', error);
+        }
+    }
+    async #addGithubIssueCommentWatch(issue, source, pending) {
+        const key = githubIssueSourceKey(source);
+        let watch = this.#githubIssueCommentWatchStates.get(key);
+        if (!watch) {
+            const persisted = await this.#state.listGithubIssueCommentWatches(this.#workspaceId);
+            watch = persisted.find(([persistedKey]) => persistedKey === key)?.[1];
+        }
+        if (!watch) {
+            const sinceCommentId = await this.#latestGithubIssueCommentId(source);
+            watch = {
+                issue,
+                source,
+                pending: [],
+                sinceCommentId,
+                lastSeenCommentId: sinceCommentId,
+                processedCommentIds: [],
+            };
+        }
+        const added = !watch.pending.some((candidate) => candidate.correlationId === pending.correlationId);
+        if (added) {
+            watch.pending.push(pending);
+        }
+        await this.#watchGithubIssueComments(watch);
+        return added;
+    }
+    async #watchGithubIssueComments(watch) {
+        watch = normalizeGithubIssueCommentWatch(watch);
+        const key = githubIssueSourceKey(watch.source);
+        this.#githubIssueCommentWatchStates.set(key, watch);
+        await this.#state.setGithubIssueCommentWatch(this.#workspaceId, key, watch);
+        if (this.#githubIssueCommentWatchers.has(key)) {
+            await this.#replayGithubIssueComments(key);
+            return false;
+        }
+        const source = watch.source;
+        let stopped = false;
+        const handle = async (event) => {
+            const path = changeEventPath(event);
+            const parts = path ? githubIssueCommentPathParts(path) : undefined;
+            if (stopped ||
+                !path ||
+                !parts ||
+                parts.owner.toLowerCase() !== source.owner.toLowerCase() ||
+                parts.repo.toLowerCase() !== source.repo.toLowerCase() ||
+                parts.number !== source.number) {
+                return;
+            }
+            try {
+                await this.#enqueueGithubIssueComment(key, path);
+            }
+            catch (error) {
+                this.#logger.error?.('[factory] failed to handle GitHub issue comment reply', {
+                    issue: watch.issue,
+                    path,
+                    error,
+                });
+                this.#increment('githubIssueCommentReplyErrors');
+            }
+        };
+        let subscription;
+        try {
+            subscription = this.#mount.subscribe(githubIssueCommentGlobs(source), (event) => {
+                void handle(event);
+            });
+        }
+        catch (error) {
+            this.#githubIssueCommentWatchStates.delete(key);
+            this.#surfaceEscalationDeliveryFailure('github-reply-watcher', watch.issue, githubEscalationCorrelationId('reply-watcher', watch.issue, key), 'GitHub issue comment reply subscription failed', error);
+            return false;
+        }
+        this.#githubIssueCommentWatchers.set(key, {
+            stop: async () => {
+                stopped = true;
+                await this.#boundedStopTeardown('GitHub issue comment subscription unsubscribe', () => subscription.unsubscribe());
+            },
+        });
+        await this.#replayGithubIssueComments(key);
+        return true;
+    }
+    async #stopGithubIssueCommentWatcher(source, clearPersisted = true) {
+        const key = githubIssueSourceKey(source);
+        const watcher = this.#githubIssueCommentWatchers.get(key);
+        this.#githubIssueCommentWatchers.delete(key);
+        this.#githubIssueCommentWatchStates.delete(key);
+        if (clearPersisted) {
+            await this.#state.clearGithubIssueCommentWatch(this.#workspaceId, key);
+        }
+        await watcher?.stop();
+    }
+    async #stopGithubIssueCommentWatcherForIssue(issue) {
+        const keysToStop = [];
+        for (const [key, watch] of this.#githubIssueCommentWatchStates) {
+            if (watch.issue.uuid === issue.uuid || watch.issue.path === issue.path) {
+                keysToStop.push(key);
+            }
+        }
+        for (const key of keysToStop) {
+            const watcher = this.#githubIssueCommentWatchers.get(key);
+            this.#githubIssueCommentWatchers.delete(key);
+            this.#githubIssueCommentWatchStates.delete(key);
+            await this.#state.clearGithubIssueCommentWatch(this.#workspaceId, key);
+            await watcher?.stop();
+        }
+    }
+    async #removeGithubIssueCommentPending(source, correlationId) {
+        const key = githubIssueSourceKey(source);
+        const watch = this.#githubIssueCommentWatchStates.get(key);
+        if (!watch)
+            return;
+        watch.pending = watch.pending.filter((pending) => pending.correlationId !== correlationId);
+        if (watch.pending.length === 0) {
+            await this.#stopGithubIssueCommentWatcher(source);
+            return;
+        }
+        await this.#state.setGithubIssueCommentWatch(this.#workspaceId, key, watch);
+    }
+    async #rearmGithubIssueCommentWatchers() {
+        for (const [, watch] of await this.#state.listGithubIssueCommentWatches(this.#workspaceId)) {
+            if (watch.pending.length === 0)
+                continue;
+            try {
+                await this.#watchGithubIssueComments(watch);
+                this.#increment('githubIssueCommentWatchersRearmed');
+            }
+            catch (error) {
+                this.#logger.warn?.('[factory] failed to re-arm GitHub issue comment watcher', {
+                    issue: watch.issue,
+                    error,
+                });
+            }
+        }
+    }
+    async #replayGithubIssueComments(key) {
+        const watch = this.#githubIssueCommentWatchStates.get(key);
+        if (!watch)
+            return;
+        const comments = [];
+        const sinceCommentId = githubCommentNumericId(watch.sinceCommentId ?? watch.lastSeenCommentId);
+        const processedCommentIds = new Set(watch.processedCommentIds ?? []);
+        for (const path of await this.#githubIssueCommentPaths(watch.source)) {
+            const parts = githubIssueCommentPathParts(path);
+            const id = parts ? githubCommentNumericId(parts.commentId) : undefined;
+            if (id !== undefined && id > sinceCommentId && !processedCommentIds.has(String(id))) {
+                comments.push({ path, id });
+            }
+        }
+        comments.sort((a, b) => a.id - b.id);
+        for (const comment of comments) {
+            await this.#enqueueGithubIssueComment(key, comment.path);
+        }
+    }
+    async #enqueueGithubIssueComment(key, path) {
+        const previous = this.#githubIssueCommentQueues.get(key) ?? Promise.resolve();
+        const current = previous.catch(() => undefined).then(async () => {
+            await this.#handleGithubIssueComment(key, path);
+        });
+        this.#githubIssueCommentQueues.set(key, current);
+        try {
+            await current;
+        }
+        finally {
+            if (this.#githubIssueCommentQueues.get(key) === current) {
+                this.#githubIssueCommentQueues.delete(key);
+            }
+        }
+    }
+    async #githubIssueCommentPaths(source) {
+        const paths = new Set();
+        const owner = encodeURIComponent(source.owner);
+        const repo = encodeURIComponent(source.repo);
+        for (const prefix of [
+            `${GITHUB_ISSUE_ROOT}/${owner}/${repo}/issues`,
+            `${GITHUB_ISSUE_ROOT}/${owner}__${repo}/issues`,
+        ]) {
+            try {
+                for (const path of await this.#mount.listTree(prefix)) {
+                    const parts = githubIssueCommentPathParts(path);
+                    if (parts &&
+                        parts.owner.toLowerCase() === source.owner.toLowerCase() &&
+                        parts.repo.toLowerCase() === source.repo.toLowerCase() &&
+                        parts.number === source.number) {
+                        paths.add(path);
+                    }
+                }
+            }
+            catch (error) {
+                this.#logger.warn?.('[factory] unable to list GitHub issue comments for replay', { prefix, error });
+            }
+        }
+        return [...paths];
+    }
+    async #latestGithubIssueCommentId(source) {
+        let latest = 0;
+        for (const path of await this.#githubIssueCommentPaths(source)) {
+            const id = githubCommentNumericId(githubIssueCommentPathParts(path)?.commentId);
+            if (id > latest)
+                latest = id;
+        }
+        return latest > 0 ? String(latest) : undefined;
+    }
+    async #readGithubIssueComment(path) {
+        try {
+            const { content } = await this.#mount.readFile(path);
+            return parseGithubIssueComment(path, content);
+        }
+        catch (error) {
+            this.#logger.warn?.('[factory] unable to read GitHub issue comment reply', { path, error });
+            return undefined;
+        }
+    }
+    async #handleGithubIssueComment(key, path) {
+        const watch = this.#githubIssueCommentWatchStates.get(key);
+        if (!watch)
+            return;
+        const comment = await this.#readGithubIssueComment(path);
+        if (!comment)
+            return;
+        const commentId = githubCommentNumericId(comment.commentId);
+        const normalizedCommentId = String(commentId);
+        const processedCommentIds = new Set(watch.processedCommentIds ?? []);
+        if (commentId === 0 ||
+            commentId <= githubCommentNumericId(watch.sinceCommentId) ||
+            processedCommentIds.has(normalizedCommentId)) {
+            this.#increment('githubIssueCommentDuplicatesSuppressed');
+            return;
+        }
+        const reply = githubCorrelatedReply(comment.body);
+        const pending = reply
+            ? watch.pending.find((candidate) => candidate.correlationId === reply.correlationId)
+            : undefined;
+        let resolved = false;
+        let discardClaimedPending = false;
+        if (pending?.claimedByCommentId === normalizedCommentId) {
+            this.#increment('githubAnswersClaimedReplaySuppressed');
+            discardClaimedPending = true;
+        }
+        else if (pending && comment.isBot) {
+            this.#increment('githubAnswersIgnoredBot');
+            this.#logger.info?.('[factory] ignored GitHub issue answer from a bot', {
+                issue: watch.issue,
+                commentId: normalizedCommentId,
+                correlationId: pending.correlationId,
+            });
+        }
+        else if (pending && comment.author?.toLowerCase() === pending.authorizedAuthor.toLowerCase()) {
+            pending.claimedByCommentId = normalizedCommentId;
+            await this.#state.setGithubIssueCommentWatch(this.#workspaceId, key, watch);
+            resolved = await this.#routeGithubAnswerToImplementers(watch, pending, comment, reply.text);
+            if (!resolved) {
+                delete pending.claimedByCommentId;
+            }
+        }
+        else if (pending) {
+            this.#increment('githubAnswersIgnoredUnauthorizedAuthor');
+            this.#logger.info?.('[factory] ignored GitHub issue answer from unauthorized author', {
+                issue: watch.issue,
+                commentId: normalizedCommentId,
+                correlationId: pending.correlationId,
+                author: comment.author,
+                authorizedAuthor: pending.authorizedAuthor,
+            });
+        }
+        else if (reply) {
+            this.#increment('githubAnswersIgnoredUnknownCorrelation');
+            this.#logger.info?.('[factory] ignored GitHub issue answer with unknown correlation', {
+                issue: watch.issue,
+                commentId: normalizedCommentId,
+                correlationId: reply.correlationId,
+            });
+        }
+        else if (!reply && comment.body.includes('[factory-reply:')) {
+            this.#increment('githubAnswersIgnoredMissingCorrelationPrefix');
+        }
+        processedCommentIds.add(normalizedCommentId);
+        watch.processedCommentIds = [...processedCommentIds];
+        watch.lastSeenCommentId = String(Math.max(commentId, githubCommentNumericId(watch.lastSeenCommentId)));
+        if ((resolved || discardClaimedPending) && pending) {
+            watch.pending = watch.pending.filter((candidate) => candidate.correlationId !== pending.correlationId);
+        }
+        if (watch.pending.length === 0) {
+            await this.#stopGithubIssueCommentWatcher(watch.source);
+        }
+        else {
+            await this.#state.setGithubIssueCommentWatch(this.#workspaceId, key, watch);
+        }
+    }
+    async #routeGithubAnswerToImplementers(watch, pending, comment, text) {
+        if (pending.kind === 'triage' && pending.decision) {
+            return await this.#handleTriageEscalationGithubAnswer(escalationWatchRecord(pending.decision), text);
+        }
+        const liveRecord = (await this.#batch()).getIssue(watch.issue);
+        if (!liveRecord || liveRecord.dryRun) {
+            this.#increment('githubAnswersIgnoredNoInFlight');
+            return false;
+        }
+        if (!this.#fleet.sendInput)
+            return false;
+        const recipients = [...liveRecord.agents.values()]
+            .filter((agent) => agent.spec.role === 'implementer' || agent.spec.role === 'babysitter')
+            .map((agent) => agent.result?.name ?? agent.spec.name)
+            .filter((name) => Boolean(name));
+        if (recipients.length === 0) {
+            this.#increment('githubAnswersIgnoredNoImplementer');
+            return false;
+        }
+        for (const recipient of new Set(recipients)) {
+            await this.#fleet.sendInput(recipient, githubReplyEvent(liveRecord.issue, text, comment.author));
+            this.#increment('githubAnswersInjected');
+        }
+        return true;
+    }
+    async #handleTriageEscalationGithubAnswer(record, text) {
+        const issue = await this.#readIssue(record.issue.path);
+        if (!issue || !isInFactoryScope(issue, this.#config.safety) || !isDispatchableIssue(issue)) {
+            this.#increment('githubTriageAnswersIgnoredIssueUnavailable');
+            return false;
+        }
+        if (!this.#isIssueReady(issue)) {
+            this.#increment('githubTriageAnswersIgnoredIssueNotReady');
+            return false;
+        }
+        const batch = await this.#batch();
+        if (batch.isInFlight(record.issue) || batch.isQueued(record.issue)) {
+            this.#increment('githubTriageAnswersIgnoredAlreadyActive');
+            return false;
+        }
+        if (await this.#dispatchBlockReason(record.issue)) {
+            this.#increment('githubTriageAnswersIgnoredBlocked');
+            return false;
+        }
+        const clarifiedIssue = issueWithGithubClarification(issue, text);
+        const decision = await this.#triage.triage(clarifiedIssue, {
+            config: this.#config,
+            repoMap: repoMapFromConfig(this.#config),
+        });
+        const escalationReason = triageEscalationReason(decision);
+        if (escalationReason) {
+            if (hasDispatchableRoute(decision)) {
+                this.#pendingGithubClarifications.set(issueKey(decision.issue), text);
+                const result = await this.#startOrQueueGithubClarifiedDecision(dispatchAfterGithubClarification(decision, escalationReason));
+                this.#increment('githubTriageAnswersDispatchedWithRemainingEscalation');
+                return Boolean(result) || (await this.#batch()).isQueued(decision.issue);
+            }
+            this.#increment('githubTriageAnswersStillEscalated');
+            this.#logger.warn?.('[factory] GitHub triage answer still leaves issue escalated', {
+                issue: record.issue,
+                reason: escalationReason,
+            });
+            return false;
+        }
+        this.#pendingGithubClarifications.set(issueKey(decision.issue), text);
+        const result = await this.#startOrQueueGithubClarifiedDecision(decision);
+        this.#increment('githubTriageAnswersDispatched');
+        return Boolean(result) || (await this.#batch()).isQueued(decision.issue);
+    }
+    async #startOrQueueGithubClarifiedDecision(decision) {
+        const batch = await this.#batch();
+        if (batch.canStart()) {
+            return await this.dispatch(decision, { dryRun: this.#config.dryRun });
+        }
+        if (batch.queue(decision, this.#config.dryRun)) {
+            this.#increment('githubTriageAnswersQueued');
+            this.#emit('issue-queued', { issue: decision.issue });
+        }
+    }
     #recordArrivalLatency(event) {
         const occurredAt = Date.parse(event.occurredAt);
         if (!Number.isFinite(occurredAt))
@@ -2990,6 +3393,7 @@ export class FactoryLoop {
             this.#increment(humanReview ? 'humanReview' : 'done');
             this.#emit('issue-done', { issue: record.issue });
             await this.#stopSlackWatcher(record.issue);
+            await this.#stopGithubIssueCommentWatcherForIssue(record.issue);
             await this.#recordDispatchTerminal(record.issue);
             const next = (await this.#batch()).complete(record.issue);
             if (next) {
@@ -3018,6 +3422,22 @@ export class FactoryLoop {
         this.#logger.error?.('[factory] error', error);
         this.#emit('error', { error, ...describeError(error), issue });
     }
+    #surfaceEscalationDeliveryFailure(kind, issue, correlationId, reason, cause) {
+        const error = new Error(`${reason} (${correlationId})`);
+        if (cause !== undefined) {
+            Object.assign(error, { cause });
+        }
+        this.#increment('errors');
+        this.#increment('escalationDeliveryFailures');
+        this.#logger.error?.('[factory] escalation delivery failed', {
+            kind,
+            correlationId,
+            issue,
+            reason,
+            cause,
+        });
+        this.#emit('error', { error, ...describeError(error), issue });
+    }
     #increment(name) {
         this.#counters[name] = (this.#counters[name] ?? 0) + 1;
     }
@@ -3241,16 +3661,12 @@ export class FactoryLoop {
         await this.#watchSlackThread(record, root.threadId);
         this.#recordSlackWritebackSuccess('dispatch-thread');
     }
-    async #escalateTriageToSlack(decision, reason, dryRun) {
+    async #escalateTriage(decision, reason, dryRun) {
         if (dryRun) {
             return;
         }
         if (!this.#slack || !this.#config.slack) {
-            this.#logger.warn?.('[factory] triage escalation has no Slack channel configured', {
-                issue: decision.issue,
-                reason,
-            });
-            return;
+            return await this.#escalateTriageToGithub(decision, reason);
         }
         if (await this.#shouldSkipSlackWriteback('triage-escalation')) {
             return;
@@ -3288,6 +3704,42 @@ export class FactoryLoop {
             this.#slackWatcherStarts.delete(key);
         }
     }
+    async #escalateTriageToGithub(decision, reason) {
+        const question = triageEscalationQuestion(decision);
+        const correlationId = githubEscalationCorrelationId('triage', decision.issue, question);
+        const issue = await this.#readIssue(decision.issue.path);
+        const source = issue ? githubIssueSourceRef(issue) : undefined;
+        const authorizedAuthor = issue ? githubIssueAuthor(issue) : undefined;
+        if (!issue || !source || !authorizedAuthor) {
+            this.#surfaceEscalationDeliveryFailure('triage', decision.issue, correlationId, 'no Slack channel or GitHub issue write path with an identifiable issue reporter is available');
+            return;
+        }
+        const pendingAdded = await this.#addGithubIssueCommentWatch(decision.issue, source, {
+            correlationId,
+            kind: 'triage',
+            authorizedAuthor,
+            decision,
+        });
+        if (!pendingAdded) {
+            return;
+        }
+        try {
+            await this.#githubWriteback.postComment(issue, [
+                `Factory needs clarification before dispatching ${decision.issue.key}.`,
+                `Reason: ${reason}`,
+                `Question: ${question}`,
+                `Authorized responder: @${authorizedAuthor} (the issue reporter).`,
+                `Reply with a comment that starts with \`${githubReplyPrefix(correlationId)}\`.`,
+                '',
+                githubEscalationMarker(correlationId),
+            ].join('\n'));
+            this.#increment('triageEscalationsPostedToGithub');
+        }
+        catch (error) {
+            await this.#removeGithubIssueCommentPending(source, correlationId);
+            this.#surfaceEscalationDeliveryFailure('triage', decision.issue, correlationId, 'GitHub issue comment writeback failed', error);
+        }
+    }
     async #postAndWatchSlackEscalationThread(decision, reason) {
         if (!this.#slack || !this.#config.slack) {
             return;
@@ -3629,6 +4081,33 @@ export class FactoryLoop {
         }
         this.#pendingSlackClarifications.delete(key);
     }
+    async #injectPendingGithubClarification(record) {
+        const key = issueKey(record.issue);
+        const text = this.#pendingGithubClarifications.get(key);
+        if (!text || !this.#fleet.sendInput) {
+            return;
+        }
+        const recipients = [...record.agents.values()]
+            .filter((agent) => agent.spec.role === 'implementer' ||
+            agent.spec.role === 'workflow' ||
+            agent.spec.role === 'babysitter')
+            .map((agent) => agent.result?.name ?? agent.spec.name)
+            .filter((name) => Boolean(name));
+        for (const recipient of new Set(recipients)) {
+            try {
+                await this.#fleet.sendInput(recipient, githubReplyEvent(record.issue, text));
+                this.#increment('githubTriageAnswersInjectedToAgents');
+            }
+            catch (error) {
+                this.#logger.warn?.('[factory] failed to inject GitHub triage clarification into agent', {
+                    issue: record.issue.key,
+                    recipient,
+                    error,
+                });
+            }
+        }
+        this.#pendingGithubClarifications.delete(key);
+    }
     // Inject the human's Slack reply into the agent framed as the
     // <integration-event> the spawn prompt tells it to expect (not an ambiguous
     // "Slack reply for ..." keystroke), so the agent recognizes it as the awaited
@@ -3906,6 +4385,7 @@ export function parseGithubIssue(path, content) {
         labels: Array.isArray(payload.labels)
             ? payload.labels.map(labelName).filter((label) => Boolean(label))
             : [],
+        author: githubAuthorLogin(payload),
         path,
         raw: asRecord(parsed) ?? payload,
     };
@@ -3947,6 +4427,7 @@ const githubIssueAsFactoryIssue = (issue) => {
                     number: issue.number,
                     url: issue.url,
                     path: issue.path,
+                    ...(issue.author ? { author: issue.author, reporter: issue.author } : {}),
                 },
             },
         },
@@ -4005,6 +4486,28 @@ const isGithubIssue = (issue) => {
     return stringValue(source?.provider)?.toLowerCase() === 'github' &&
         (stringValue(wrapper?.provider)?.toLowerCase() === 'github' || isGithubIssueFilePath(issue.path));
 };
+const githubIssueSourceRef = (issue) => {
+    const source = asRecord(wrappedPayload(issue.raw).source);
+    if (stringValue(source?.provider)?.toLowerCase() !== 'github') {
+        return undefined;
+    }
+    const owner = stringValue(source?.owner)?.trim();
+    const repo = stringValue(source?.repo)?.trim();
+    const number = numberValue(source?.number);
+    const url = stringValue(source?.url)?.trim();
+    if (!owner || !repo || !Number.isInteger(number) || (number ?? 0) <= 0 || !url) {
+        return undefined;
+    }
+    return { owner, repo, number: number, url };
+};
+const githubIssueAuthor = (issue) => {
+    const payload = wrappedPayload(issue.raw);
+    const source = asRecord(payload.source);
+    if (stringValue(source?.provider)?.toLowerCase() === 'github') {
+        return githubAuthorLogin(source ?? {})?.trim() || undefined;
+    }
+    return source ? undefined : githubAuthorLogin(payload)?.trim() || undefined;
+};
 const issueRef = (issue) => ({ uuid: issue.uuid, key: issue.key, path: issue.path });
 const pidsFromSpawnResult = (result) => {
     const pids = new Set();
@@ -4378,6 +4881,73 @@ export const githubIssuePathParts = (path) => {
         slug: match[7],
     };
 };
+const githubIssueCommentPathParts = (path) => {
+    const match = path.match(/^\/github\/repos\/(?:([^/]+)\/([^/]+)|([A-Za-z0-9-]+)__([^/]+))\/issues\/(\d+)(?:__[^/]*)?\/comments\/([^/]+?)(?:\.json|\/(?:meta|metadata)\.json)$/u);
+    const owner = match?.[1] ?? match?.[3];
+    const repo = match?.[2] ?? match?.[4];
+    const number = Number(match?.[5]);
+    const commentId = match?.[6];
+    if (!owner || !repo || !Number.isInteger(number) || number <= 0 || !commentId) {
+        return undefined;
+    }
+    return { owner, repo, number, commentId };
+};
+const parseGithubIssueComment = (path, content) => {
+    const parts = githubIssueCommentPathParts(path);
+    if (!parts) {
+        return undefined;
+    }
+    const raw = asRecord(parseJsonContent(content)) ?? {};
+    const payload = wrappedPayload(raw);
+    const comment = asRecord(payload.comment) ?? payload;
+    const author = asRecord(comment.author) ?? asRecord(comment.user);
+    const authorLogin = stringValue(author?.login);
+    const authorType = stringValue(author?.type)?.toLowerCase();
+    return {
+        owner: parts.owner,
+        repo: parts.repo,
+        issueNumber: parts.number,
+        commentId: String(numberValue(comment.id) ?? parts.commentId),
+        body: stringValue(comment.body) ?? '',
+        author: authorLogin,
+        isBot: authorType === 'bot' || Boolean(authorLogin?.toLowerCase().endsWith('[bot]')),
+        raw,
+    };
+};
+const githubIssueSourceKey = (source) => `${source.owner.toLowerCase()}/${source.repo.toLowerCase()}#${source.number}`;
+const githubIssueCommentGlobs = (source) => {
+    const owner = encodeURIComponent(source.owner);
+    const repo = encodeURIComponent(source.repo);
+    const issueSegment = `${source.number}*`;
+    return [
+        `${GITHUB_ISSUE_ROOT}/${owner}/${repo}/issues/${issueSegment}/comments/**`,
+        `${GITHUB_ISSUE_ROOT}/${owner}__${repo}/issues/${issueSegment}/comments/**`,
+    ];
+};
+const githubEscalationCorrelationId = (kind, issue, text) => `factory-${kind}-${stableHash(`${issue.uuid}:${issue.path}:${text}`)}`;
+const githubEscalationMarker = (correlationId) => `<!-- ${GITHUB_ESCALATION_MARKER_PREFIX}${correlationId} -->`;
+const githubReplyPrefix = (correlationId) => `[factory-reply:${correlationId}]`;
+const githubCorrelatedReply = (body) => {
+    if (!body.startsWith('[factory-reply:'))
+        return undefined;
+    const markerEnd = body.indexOf(']');
+    if (markerEnd < 0)
+        return undefined;
+    const correlationId = body.slice('[factory-reply:'.length, markerEnd);
+    if (!/^factory-(?:triage|agent-question)-[a-z0-9]+$/u.test(correlationId))
+        return undefined;
+    const text = body.slice(markerEnd + 1).replace(/^\s*:?\s*/u, '').trim();
+    return text ? { correlationId, text } : undefined;
+};
+const githubCommentNumericId = (value) => {
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : 0;
+};
+const normalizeGithubIssueCommentWatch = (watch) => ({
+    ...watch,
+    sinceCommentId: watch.sinceCommentId ?? watch.lastSeenCommentId,
+    processedCommentIds: [...new Set(watch.processedCommentIds ?? [])],
+});
 const githubIssueReadCandidatePaths = (path) => {
     if (path.endsWith('/')) {
         return [`${path}meta.json`, `${path}metadata.json`];
@@ -4419,6 +4989,7 @@ const githubIssueHasFactoryLabel = (issue, requiredLabel = GITHUB_FACTORY_LABEL)
 const githubIssueIsClosed = (issue) => issue.state === 'closed';
 const githubIssueMirrorPayload = (issue, repoLabel, config, readyForAgentStateId) => {
     const teamId = config.linear.teamIds[config.safety.requireTeamKey];
+    const reporter = issue.author;
     return {
         id: githubIssueMirrorId(issue),
         title: `${GITHUB_MIRROR_TITLE_PREFIX} ${issue.title}`.trim(),
@@ -4434,6 +5005,7 @@ const githubIssueMirrorPayload = (issue, repoLabel, config, readyForAgentStateId
             number: issue.number,
             url: issue.url,
             path: issue.path,
+            ...(reporter ? { author: reporter, reporter } : {}),
         },
     };
 };
@@ -4708,6 +5280,15 @@ const uuidFromPath = (path) => path.split('__')[1]?.replace(/\.json$/, '');
 const stringValue = (value) => typeof value === 'string' ? value : undefined;
 const booleanValue = (value) => typeof value === 'boolean' ? value : undefined;
 const numberValue = (value) => typeof value === 'number' ? value : undefined;
+const githubAuthorLogin = (payload) => {
+    for (const value of [payload.author, payload.user, payload.reporter]) {
+        const login = (stringValue(value) ??
+            stringValue(asRecord(value)?.login))?.trim();
+        if (login)
+            return login;
+    }
+    return undefined;
+};
 const liveHeartbeatIntervalMs = (staleMs) => Math.min(DEFAULT_LIVE_HEARTBEAT_INTERVAL_MS, Math.max(500, Math.floor(staleMs / 4)));
 const installFactoryDraftPredicate = (mount, config) => {
     mount.setDefaultAllowedDraftPredicate?.((path, content, opts) => isAllowedFactoryDraft(path, content, opts, mount, config));
@@ -5070,6 +5651,15 @@ const dispatchAfterSlackClarification = (decision, escalationReason) => ({
         `Human answered the Slack triage escalation (${escalationReason}); dispatching to the matched agent so it can acknowledge the answer and ask follow-up questions if needed.`,
     ].filter(Boolean).join(' '),
 });
+const dispatchAfterGithubClarification = (decision, escalationReason) => ({
+    ...decision,
+    thin: false,
+    confidence: 'high',
+    rationale: [
+        decision.rationale,
+        `Human answered the GitHub triage escalation (${escalationReason}); dispatching to the matched agent so it can acknowledge the answer and ask follow-up questions if needed.`,
+    ].filter(Boolean).join(' '),
+});
 const issueWithSlackClarification = (issue, text) => ({
     ...issue,
     description: [
@@ -5079,11 +5669,21 @@ const issueWithSlackClarification = (issue, text) => ({
         text,
     ].join('\n'),
 });
+const issueWithGithubClarification = (issue, text) => ({
+    ...issue,
+    description: [
+        issue.description,
+        '',
+        'Human clarification from GitHub:',
+        text,
+    ].join('\n'),
+});
 const slackAnswerInput = (issue, text) => `Slack reply for ${issue.key}:\n${text}\r`;
 // The human's Slack-thread reply, framed as an <integration-event> the agent is
 // told (at spawn) to expect — a recognizable injected event, not an ambiguous
 // keystroke. Trailing CR submits it to the agent's PTY.
 const slackReplyEvent = (issue, text) => `<integration-event source="slack" issue="${issue.key}">\nHuman reply in the Slack thread:\n${text}\n</integration-event>\r`;
+const githubReplyEvent = (issue, text, author) => `<integration-event source="github" issue="${issue.key}">\nHuman reply${author ? ` from @${author}` : ''} on the GitHub issue:\n${text}\n</integration-event>\r`;
 const isFactoryQuestionTarget = (target) => {
     const normalized = target.trim().replace(/^@/u, '').toLowerCase();
     return normalized === 'broker' || normalized === 'factory';