@agent-relay/factory 0.1.13 → 0.1.15

package/dist/orchestrator/factory.js

@@ -7,10 +7,11 @@ import { GithubMergeGate, closeProbePr } from '../github/index.js';
 import { InMemoryStateStore } from '../state/in-memory-state-store.js';
 import { containsExplicitIssueReference, containsIssueKey } from '../issue-key-match.js';
 import { isInFactoryScope } from '../safety/factory-scope.js';
+import { dispatchRelayflowForChangeEvent } from '../dispatch/relayflow-registry.js';
 import { deriveDescriptorsFromMount, prescriptiveInstructions, } from '@agent-relay/integration-prompts';
 import { renderAgentTask } from '../dispatch/templates.js';
 import { HeuristicTriage, TieredTriage, babysitterSpec, isShapeLabel, scopeFromLabels } from '../triage/index.js';
-import { MountGithubRead, MountLinearWriteback, MountSlackWriteback, slackChannelAliases, slackChannelSegment } from '../writeback/index.js';
+import { GhCliGithubWriteback, MountGithubRead, MountLinearWriteback, MountSlackWriteback, slackChannelAliases, slackChannelSegment } from '../writeback/index.js';
 import { asRecord, parseJsonContent, stableHash, wrappedPayload } from '../writeback/shared.js';
 import { issueKey } from './batch-tracker.js';
 import { findAgentProcessByName, readProcessIdentity } from './process-identity.js';
@@ -19,6 +20,7 @@ const ISSUE_ROOT = '/linear/issues';
 const GITHUB_ISSUE_ROOT = '/github/repos';
 const READY_EVENTS_LIMIT = 100;
 const LIVE_ISSUE_GLOB = `${ISSUE_ROOT}/**`;
+const LIVE_RELAYFLOW_GLOB = '/**';
 // Subscribe broadly under /github/repos and let isGithubIssueFilePath() /
 // githubPullPathParts() re-validate the exact shape in the callback.
 // globMatchesPath() treats a non-terminal `**` as a single-segment wildcard, so
@@ -39,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.
@@ -58,6 +61,7 @@ const DEFAULT_LIVE_HEARTBEAT_INTERVAL_MS = 15_000;
 const REMOTE_OPERATION_PROGRESS_INTERVAL_MS = 15_000;
 const REMOTE_OPERATION_SLOW_WARN_MS = 30_000;
 const GITHUB_FACTORY_LABEL = 'factory';
+const GITHUB_LIFECYCLE_LABELS = new Set(['factory:in-progress', 'factory:human-review']);
 const GITHUB_MIRROR_TITLE_PREFIX = '[factory]';
 const GITHUB_MIRROR_SOURCE_PREFIX = 'Source: ';
 export const DEFAULT_FACTORY_LOOP_HEARTBEAT_PATH = '/tmp/factory-run/factory-loop-heartbeat.json';
@@ -76,6 +80,7 @@ export class FactoryLoop {
     #fleet;
     #triage;
     #linear;
+    #githubWriteback;
     #slack;
     #mergeGate;
     #probeCloser;
@@ -91,6 +96,7 @@ export class FactoryLoop {
     #terminationGraceMs;
     #state;
     #workspaceId;
+    #relayflows;
     #batchView;
     #batchReady;
     #listeners = new Map();
@@ -99,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
@@ -110,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;
@@ -158,6 +168,7 @@ export class FactoryLoop {
     // undefined = readiness not yet probed; resolved lazily so the standalone
     // runOnce() path (which skips #start) still ingests when the mount is present.
     #githubIngestionEnabled;
+    #resolvedIssueSource;
     #integrationInstructions;
     #integrationInstructionsRefresh;
     #starting;
@@ -177,6 +188,7 @@ export class FactoryLoop {
         this.#linear = ports.linear ?? MountLinearWriteback(ports.mount, {
             safety: config.safety,
         });
+        this.#githubWriteback = ports.githubWriteback ?? new GhCliGithubWriteback();
         this.#slack = config.slack ? MountSlackWriteback(ports.mount, config.slack) : ports.slack;
         void (ports.github ?? MountGithubRead(ports.mount));
         this.#mergeGate = ports.mergeGate ?? new GithubMergeGate();
@@ -195,6 +207,7 @@ export class FactoryLoop {
         this.#readChildPids = ports.readChildPids;
         this.#terminationGraceMs = ports.terminationGraceMs;
         this.#workspaceId = config.workspaceId ?? 'default';
+        this.#relayflows = ports.relayflows;
         this.#state = ports.stateStore ?? new InMemoryStateStore({
             batchSize: config.batchSize,
             agentQuestionDedupeLimit: AGENT_QUESTION_DEDUPE_LIMIT,
@@ -287,18 +300,26 @@ export class FactoryLoop {
     }
     async #start(opts) {
         this.#stopping = false;
-        const ready = await this.#mount.ensureSubRoot(ISSUE_ROOT, { timeoutMs: 90_000 });
-        if (ready !== 'ready') {
-            this.#error(new Error(`${ISSUE_ROOT} sub-root is not mounted`));
+        const issueSource = await this.#issueSource();
+        if (issueSource === 'linear') {
+            const ready = await this.#mount.ensureSubRoot(ISSUE_ROOT, { timeoutMs: 90_000 });
+            if (ready !== 'ready') {
+                this.#error(new Error(`${ISSUE_ROOT} sub-root is not mounted`));
+                return;
+            }
+        }
+        const githubReady = await this.#ensureGithubIngestionReady();
+        if (issueSource === 'github' && !githubReady) {
+            this.#error(new Error(`${GITHUB_ISSUE_ROOT} sub-root is not mounted`));
             return;
         }
-        await this.#ensureGithubIngestionReady();
         this.#wireFleetEvents();
         if ((opts.mode ?? 'live') === 'live') {
             this.#started = true;
             try {
                 await this.#startLiveSubscription(opts.liveSubscription);
                 await this.#rearmSlackReplyWatchers();
+                await this.#rearmGithubIssueCommentWatchers();
                 this.#scheduleCompletionSweep(0);
                 return;
             }
@@ -309,7 +330,8 @@ export class FactoryLoop {
             }
         }
         await this.#backfillReadyIssues();
-        this.#subscription = this.#mount.subscribe([`${ISSUE_ROOT}/**/*.json`, LIVE_GITHUB_ISSUE_GLOB], (event) => {
+        this.#subscription = this.#mount.subscribe(this.#subscriptionGlobs([`${ISSUE_ROOT}/**/*.json`, LIVE_GITHUB_ISSUE_GLOB]), (event) => {
+            void this.#dispatchRelayflowEvent(event);
             // The SDK types `resource` as always-present, but the polling fallback and
             // degraded-sync paths can deliver events without it. Skip those rather
             // than throwing (which would otherwise crash the subscription handler).
@@ -329,6 +351,7 @@ export class FactoryLoop {
         });
         this.#started = true;
         await this.#rearmSlackReplyWatchers();
+        await this.#rearmGithubIssueCommentWatchers();
         this.#scheduleCompletionSweep(0);
     }
     async stop() {
@@ -353,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?.();
@@ -415,7 +442,7 @@ export class FactoryLoop {
             // LIVE_GITHUB_ISSUE_GLOB is a terminal `${GITHUB_ISSUE_ROOT}/**`, so it
             // already covers the PR change events the babysitter consumes; pull-event
             // *processing* is gated on babysitter.enabled in #prepareLiveEventForDrain.
-            this.#subscription = this.#mount.subscribe([LIVE_ISSUE_GLOB, LIVE_GITHUB_ISSUE_GLOB], (event) => {
+            this.#subscription = this.#mount.subscribe(this.#subscriptionGlobs([LIVE_ISSUE_GLOB, LIVE_GITHUB_ISSUE_GLOB]), (event) => {
                 this.#enqueueLiveEvent(event);
             }, { from: 'now', coalesce: 'none' });
         }
@@ -618,9 +645,12 @@ export class FactoryLoop {
             const batch = events.splice(0, LIVE_EVENT_DRAIN_BATCH_SIZE);
             const paths = [];
             for (const event of batch) {
-                const path = await this.#prepareLiveEventForDrain(event, seenIssueKeys);
-                if (path) {
-                    paths.push(path);
+                const prepared = await this.#prepareLiveEventForDrain(event, seenIssueKeys);
+                if (prepared.dispatchRelayflow) {
+                    void this.#dispatchRelayflowEvent(event);
+                }
+                if (prepared.path) {
+                    paths.push(prepared.path);
                 }
             }
             await Promise.all(paths.map((path) => this.#handlePreparedLiveChange(path)));
@@ -652,14 +682,18 @@ export class FactoryLoop {
             return;
         await this.#refreshLiveHeartbeat();
     }
+    #subscriptionGlobs(factoryGlobs) {
+        return this.#relayflows ? [LIVE_RELAYFLOW_GLOB] : factoryGlobs;
+    }
     async #prepareLiveEventForDrain(event, seenIssueKeys) {
         const path = changeEventPath(event);
         if (!path) {
-            return undefined;
+            return { dispatchRelayflow: false };
         }
         const isPullPath = isGithubPullFilePath(path);
-        if (!isIssueFilePath(path) && !isGithubIssueFilePath(path) && !isPullPath) {
-            return undefined;
+        const isFactoryPath = isIssueFilePath(path) || isGithubIssueFilePath(path) || isPullPath;
+        if (!isFactoryPath && !this.#relayflows) {
+            return { dispatchRelayflow: false };
         }
         if (isBeforeLiveCutoff(event.occurredAt, this.#liveConnectStartedAtMs, this.#liveReplaySkewMarginMs)) {
             this.#increment('liveReplayEventsSuppressed');
@@ -671,7 +705,7 @@ export class FactoryLoop {
                 connectStartedAt: new Date(this.#liveConnectStartedAtMs).toISOString(),
                 replaySkewMarginMs: this.#liveReplaySkewMarginMs,
             });
-            return undefined;
+            return { dispatchRelayflow: false };
         }
         if (isAtOrBeforeHighWatermark(event.id, this.#liveEventHighWatermark)) {
             this.#increment('liveReplayEventsSuppressed');
@@ -681,7 +715,7 @@ export class FactoryLoop {
                 highWatermark: this.#liveEventHighWatermark,
                 path,
             });
-            return undefined;
+            return { dispatchRelayflow: false };
         }
         const dedupeKey = liveEventDedupeKey(event);
         if (dedupeKey) {
@@ -691,7 +725,7 @@ export class FactoryLoop {
                     id: event.id,
                     path,
                 });
-                return undefined;
+                return { dispatchRelayflow: false };
             }
             rememberLiveEvent(this.#seenLiveEvents, dedupeKey);
         }
@@ -699,6 +733,9 @@ export class FactoryLoop {
             this.#increment('liveEventsMissingIdentity');
             this.#logger.warn?.('[factory] live issue event missing stable identity', { path });
         }
+        if (!isFactoryPath) {
+            return { dispatchRelayflow: true };
+        }
         if (isGithubIssueFilePath(path)) {
             const sourceKey = `github:${path}`;
             if (seenIssueKeys.has(sourceKey)) {
@@ -707,11 +744,11 @@ export class FactoryLoop {
                     id: event.id,
                     path,
                 });
-                return undefined;
+                return { dispatchRelayflow: false };
             }
             seenIssueKeys.add(sourceKey);
             this.#recordArrivalLatency(event);
-            return path;
+            return { path, dispatchRelayflow: true };
         }
         if (isPullPath) {
             // Dedupe PR change events by path within a drain; the babysitter routing
@@ -719,11 +756,11 @@ export class FactoryLoop {
             const sourceKey = `pull:${path}`;
             if (seenIssueKeys.has(sourceKey)) {
                 this.#increment('liveDuplicatePrEventsSuppressed');
-                return undefined;
+                return { dispatchRelayflow: false };
             }
             seenIssueKeys.add(sourceKey);
             this.#recordArrivalLatency(event);
-            return path;
+            return { path, dispatchRelayflow: true };
         }
         const issueKey = keyFromPath(path);
         if (seenIssueKeys.has(issueKey)) {
@@ -733,7 +770,7 @@ export class FactoryLoop {
                 path,
                 issue: issueKey,
             });
-            return undefined;
+            return { dispatchRelayflow: false };
         }
         const issueRef = { key: issueKey, uuid: uuidFromPath(path) ?? issueKey, path };
         const batch = await this.#batch();
@@ -744,11 +781,40 @@ export class FactoryLoop {
                 path,
                 issue: issueKey,
             });
-            return undefined;
+            return { dispatchRelayflow: false };
         }
         seenIssueKeys.add(issueKey);
         this.#recordArrivalLatency(event);
-        return path;
+        return { path, dispatchRelayflow: true };
+    }
+    async #dispatchRelayflowEvent(event) {
+        const relayflows = this.#relayflows;
+        if (!relayflows)
+            return;
+        try {
+            const result = await dispatchRelayflowForChangeEvent(event, relayflows.registry, {
+                cwd: relayflows.cwd ?? process.cwd(),
+                mountRoot: relayflows.mountRoot ?? this.#integrationsMountRoot(),
+                workflowRunner: relayflows.workflowRunner,
+            });
+            if (!result)
+                return;
+            this.#increment('relayflowEventsDispatched');
+            this.#logger.info?.('[factory] relayflow dispatched for integration event', {
+                trigger: result.trigger,
+                templatePath: result.templatePath,
+                runId: result.runId,
+                status: result.status,
+            });
+        }
+        catch (error) {
+            this.#increment('relayflowDispatchErrors');
+            this.#logger.warn?.('[factory] relayflow dispatch failed for integration event', {
+                eventId: event.id,
+                path: changeEventPath(event),
+                error,
+            });
+        }
     }
     async #handlePreparedLiveChange(path) {
         if (isGithubPullFilePath(path)) {
@@ -888,7 +954,13 @@ export class FactoryLoop {
         this.#logger.info?.('[factory] run-once started', { dryRun });
         let report;
         try {
-            await this.#ingestGithubIssues({ dryRun });
+            const issueSource = await this.#issueSource();
+            if (issueSource === 'linear') {
+                await this.#ingestGithubIssues({ dryRun });
+            }
+            else {
+                await this.#ensureGithubIngestionReady();
+            }
             const paths = await this.#readyIssuePaths();
             const pulled = [];
             const triaged = [];
@@ -900,7 +972,7 @@ export class FactoryLoop {
                 const issue = await this.#readIssue(path);
                 readyIssueReads += 1;
                 lastReadyReadProgressAtMs = this.#logTimedProgress('[factory] Linear ready issue read progress', startedAtMs, lastReadyReadProgressAtMs, { read: readyIssueReads, total: paths.length, path });
-                if (issue) {
+                if (issue && issueSource === 'linear') {
                     await this.#recordCanonicalIssueState(issue);
                 }
                 if (!issue) {
@@ -917,7 +989,7 @@ export class FactoryLoop {
                     skipped.push({ issue: issueRef(issue), reason: 'already tracked' });
                     continue;
                 }
-                if (!this.#states.isRole(issue.stateId, 'readyForAgent')) {
+                if (!this.#isIssueReady(issue)) {
                     skipped.push({ issue: issueRef(issue), reason: 'live state is not ready-for-agent' });
                     continue;
                 }
@@ -925,7 +997,7 @@ export class FactoryLoop {
                     skipped.push({ issue: issueRef(issue), reason: 'not factory-e2e scope' });
                     continue;
                 }
-                if (!isRealLinearIssue(issue)) {
+                if (!isDispatchableIssue(issue)) {
                     skipped.push({ issue: issueRef(issue), reason: 'not reconciled real Linear issue' });
                     continue;
                 }
@@ -1153,14 +1225,14 @@ export class FactoryLoop {
             this.#error(error, decision.issue);
             throw error;
         }
-        if (!isRealLinearIssue(liveIssue)) {
+        if (!isDispatchableIssue(liveIssue)) {
             const error = new Error(`Refusing to dispatch ${decision.issue.key}: not reconciled real Linear issue`);
             this.#error(error, decision.issue);
             throw error;
         }
         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 };
         }
@@ -1179,7 +1251,7 @@ export class FactoryLoop {
                 const signature = labelDispatchFailureSignature(labelDispatch);
                 if (this.#labelDispatchFailures.get(decision.issue.key) !== signature) {
                     try {
-                        await this.#linear.postComment(liveIssue, comment);
+                        await this.#postIssueComment(liveIssue, comment);
                         // Record only after a successful post so a failed writeback retries
                         // next cycle rather than being suppressed as already-notified.
                         this.#labelDispatchFailures.set(decision.issue.key, signature);
@@ -1228,17 +1300,22 @@ export class FactoryLoop {
             let implementingStateId;
             if (!dryRun) {
                 const issue = await this.#readIssue(dispatchDecision.issue.path);
-                if (!issue || !this.#states.isRole(issue.stateId, 'readyForAgent')) {
+                if (!issue || !this.#isIssueReady(issue)) {
                     throw new Error(`Live state changed before writeback for ${dispatchDecision.issue.key}`);
                 }
-                implementingStateId = this.#states.idFor(issue.team, 'agentImplementing');
                 try {
-                    await this.#linear.postComment(issue, comment);
+                    await this.#postIssueComment(issue, comment);
                 }
                 catch (error) {
                     this.#logger.warn?.('[factory] comment writeback skipped', error);
                 }
-                await this.#linear.setState(issue, implementingStateId);
+                if (isGithubIssue(issue)) {
+                    await this.#githubWriteback.setStatus(issue, 'in-progress');
+                }
+                else {
+                    implementingStateId = this.#states.idFor(issue.team, 'agentImplementing');
+                    await this.#linear.setState(issue, implementingStateId);
+                }
                 this.#emit('writeback-verified', { issue: dispatchDecision.issue, path: issue.path });
             }
             const result = {
@@ -1256,6 +1333,7 @@ export class FactoryLoop {
                 await this.#sendImplementerTask(record);
                 await this.#sendCriticalReviewerMessage(record);
                 await this.#injectPendingSlackClarification(record);
+                await this.#injectPendingGithubClarification(record);
             }
             return result;
         }
@@ -1320,24 +1398,24 @@ export class FactoryLoop {
         }
     }
     async #handleChange(path, opts = {}) {
-        if (!isIssueFilePath(path)) {
+        if (!isIssueFilePath(path) && !isGithubIssueFilePath(path)) {
             return;
         }
         try {
             const issue = await this.#readIssue(path);
-            if (issue) {
+            if (issue && !isGithubIssue(issue)) {
                 await this.#recordCanonicalIssueState(issue);
             }
-            if (!issue || !this.#states.isRole(issue.stateId, 'readyForAgent')) {
+            if (!issue || !this.#isIssueReady(issue)) {
                 return;
             }
-            if (opts.requireRealIssue && !isRealLinearIssue(issue)) {
+            if (opts.requireRealIssue && !isDispatchableIssue(issue)) {
                 return;
             }
             if (!isInFactoryScope(issue, this.#config.safety)) {
                 return;
             }
-            if (!isRealLinearIssue(issue)) {
+            if (!isDispatchableIssue(issue)) {
                 return;
             }
             const batch = await this.#batch();
@@ -1350,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;
             }
@@ -1367,6 +1445,42 @@ export class FactoryLoop {
             this.#logger.error?.('[factory] failed to handle issue change', error);
         }
     }
+    async #issueSource() {
+        if (this.#resolvedIssueSource) {
+            return this.#resolvedIssueSource;
+        }
+        if (this.#config.issueSource) {
+            this.#resolvedIssueSource = this.#config.issueSource;
+            return this.#resolvedIssueSource;
+        }
+        const linearReady = await this.#mount.ensureSubRoot(ISSUE_ROOT, { timeoutMs: 90_000 });
+        this.#resolvedIssueSource = linearReady === 'ready' ? 'linear' : 'github';
+        if (this.#resolvedIssueSource === 'github') {
+            this.#logger.info?.('[factory] Linear issue source is not connected; using GitHub issues');
+        }
+        return this.#resolvedIssueSource;
+    }
+    #isIssueReady(issue) {
+        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') {
+            return false;
+        }
+        if (issue.labels.some((label) => GITHUB_LIFECYCLE_LABELS.has(label.trim().toLowerCase()))) {
+            return false;
+        }
+        const required = this.#config.safety.requireLabel.trim().toLowerCase();
+        return Boolean(required) && issue.labels.some((label) => label.trim().toLowerCase() === required);
+    }
+    async #postIssueComment(issue, body) {
+        if (isGithubIssue(issue)) {
+            await this.#githubWriteback.postComment(issue, body);
+            return;
+        }
+        await this.#linear.postComment(issue, body);
+    }
     // Probes the GitHub issue sub-root at most once and caches the verdict so
     // repeated iterations skip listTree calls when the mount is absent.
     async #ensureGithubIngestionReady() {
@@ -1481,6 +1595,12 @@ export class FactoryLoop {
             if (!ghIssue) {
                 return;
             }
+            if (await this.#issueSource() === 'github') {
+                if (!githubIssueIsClosed(ghIssue) && githubIssueHasFactoryLabel(ghIssue, this.#config.safety.requireLabel)) {
+                    await this.#handleChange(ghIssue.path);
+                }
+                return;
+            }
             if (githubIssueIsClosed(ghIssue)) {
                 const mirror = await this.#findGithubIssueMirror(ghIssue, opts.candidates);
                 if (mirror && !this.#states.isRole(mirror.stateId, 'done')) {
@@ -1497,7 +1617,7 @@ export class FactoryLoop {
                 }
                 return;
             }
-            if (!githubIssueHasFactoryLabel(ghIssue)) {
+            if (!githubIssueHasFactoryLabel(ghIssue, this.#config.safety.requireLabel)) {
                 return;
             }
             const mirror = await this.#findGithubIssueMirror(ghIssue, opts.candidates);
@@ -1775,6 +1895,9 @@ export class FactoryLoop {
         }
     }
     async #readyIssuePaths() {
+        if (await this.#issueSource() === 'github') {
+            return this.#githubIssuePaths();
+        }
         const pathsByKey = new Map();
         const canonicalPathsByKey = new Map();
         for (const path of await this.#listRelayfileTree(ISSUE_ROOT, 'Linear ready issue canonical discovery')) {
@@ -1800,6 +1923,10 @@ export class FactoryLoop {
     }
     async #readIssue(path) {
         try {
+            if (isGithubIssueFilePath(path)) {
+                const githubIssue = await this.#readGithubIssue(path);
+                return githubIssue ? githubIssueAsFactoryIssue(githubIssue) : undefined;
+            }
             // Newly-synced issues land as a change-event STUB at the primary
             // /linear/issues/<key>__<uuid>.json path (no state/url/team); the full
             // record lands at the by-id / by-uuid aliases. Read the canonical sibling
@@ -2291,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')) {
@@ -2332,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))
@@ -2525,9 +3043,15 @@ export class FactoryLoop {
         }
         this.#postMergeDoneAdvances.add(advanceKey);
         try {
-            const doneStateId = this.#states.idFor(issue.team, 'done');
-            await this.#linear.setState(issue, doneStateId);
-            await this.#recordCanonicalIssueState({ key: issue.key, stateId: doneStateId });
+            const githubIssue = isGithubIssue(issue);
+            if (githubIssue) {
+                await this.#githubWriteback.closeIssue(issue, `Factory observed pull request #${snapshot.number} merge and completed this issue.`);
+            }
+            else {
+                const doneStateId = this.#states.idFor(issue.team, 'done');
+                await this.#linear.setState(issue, doneStateId);
+                await this.#recordCanonicalIssueState({ key: issue.key, stateId: doneStateId });
+            }
             this.#emit('writeback-verified', { issue: issueRef(issue), path: issue.path });
             this.#increment('mergedPrAdvancedDone');
             this.#increment('done');
@@ -2540,11 +3064,12 @@ export class FactoryLoop {
                 try {
                     const channel = await this.#slackChannelDir();
                     if (channel) {
+                        const systemOfRecord = githubIssue ? 'GitHub issue closed' : 'Linear state set to Done';
                         const root = await this.#slack.postThread({
                             channel,
-                            text: `${issue.key}: PR merged; Linear state set to Done.`,
+                            text: `${issue.key}: PR merged; ${systemOfRecord}.`,
                         });
-                        await this.#slack.reply(root.threadId, `${issue.key}: Linear state set to Done.`);
+                        await this.#slack.reply(root.threadId, `${issue.key}: ${systemOfRecord}.`);
                         this.#recordSlackWritebackSuccess('merge-done-thread');
                     }
                 }
@@ -2571,15 +3096,19 @@ export class FactoryLoop {
         // This no-record path runs after agents are released, so there is no
         // tracked PR identity left. Keep the scan simple and prefer branch identity
         // over title/body references to avoid "related to AR-N" body false positives.
-        for (const path of await this.#mount.listTree(ISSUE_ROOT)) {
-            if (!isIssueFilePath(path)) {
+        const githubSource = await this.#issueSource() === 'github';
+        const paths = githubSource ? await this.#githubIssuePaths() : await this.#mount.listTree(ISSUE_ROOT);
+        for (const path of paths) {
+            if (githubSource ? !isGithubIssueFilePath(path) : !isIssueFilePath(path)) {
                 continue;
             }
             const issue = await this.#readIssue(path);
-            if (!issue || !isUpstreamState(issue.stateId)) {
+            if (!issue || (githubSource
+                ? issue.state?.name?.trim().toLowerCase() === 'closed'
+                : !isUpstreamState(issue.stateId))) {
                 continue;
             }
-            if (!isRealLinearIssue(issue) || !isInFactoryScope(issue, this.#config.safety)) {
+            if (!isDispatchableIssue(issue) || !isInFactoryScope(issue, this.#config.safety)) {
                 continue;
             }
             const score = prSnapshotIssueMatchScore(snapshot, issue.key);
@@ -2587,7 +3116,7 @@ export class FactoryLoop {
                 best = { issue, score };
             }
         }
-        this.#logger.debug?.('[factory] scanned Linear issues for merged PR advance', {
+        this.#logger.debug?.(`[factory] scanned ${githubSource ? 'GitHub' : 'Linear'} issues for merged PR advance`, {
             prNumber: snapshot.number,
             durationMs: this.#clock.now() - scanStartedAtMs,
             matchedIssue: best?.issue.key,
@@ -2752,6 +3281,28 @@ export class FactoryLoop {
         }
         return found;
     }
+    async #githubPrObservedMerged(record, issue) {
+        const babysatSnapshot = await this.#readBabysatPrSnapshot(record);
+        if (babysatSnapshot && prMetaShowsMerged(babysatSnapshot)) {
+            return true;
+        }
+        const pr = this.#babysitterPr.get(record.issue.key) ?? await this.#completionPrForIssue(issue);
+        if (!pr) {
+            return false;
+        }
+        for (const path of await this.#pullMetaPathsFor(pr.repo, pr.prNumber)) {
+            try {
+                const snapshot = parsePullSnapshot((await this.#mount.readFile(path)).content, pr.prNumber);
+                if (snapshot && prMetaShowsMerged(snapshot)) {
+                    return true;
+                }
+            }
+            catch {
+                // A concurrent mount refresh may remove an alternate path; keep scanning.
+            }
+        }
+        return false;
+    }
     async #completeIssue(record, opts = {}) {
         const completionKey = issueKey(record.issue);
         if (this.#completionInFlight.has(completionKey)) {
@@ -2766,16 +3317,44 @@ export class FactoryLoop {
             // (the legacy terminal) so the issue never gets stuck on an unconfigured
             // state.
             const issueTeam = issue?.team;
-            const humanReview = opts.targetState !== 'done' &&
+            const githubIssue = issue ? isGithubIssue(issue) : false;
+            const configuredHumanReview = opts.targetState !== 'done' &&
                 this.#config.terminalState === 'human-review' &&
-                this.#states.hasHumanReview(issueTeam);
-            const targetState = humanReview
-                ? this.#states.idFor(issueTeam, 'humanReview')
-                : this.#states.idFor(issueTeam, 'done');
+                (githubIssue || this.#states.hasHumanReview(issueTeam));
+            let githubMerged = githubIssue && opts.completionReason === 'pr-merged';
+            if (issue && githubIssue && !configuredHumanReview && !githubMerged) {
+                githubMerged = await this.#githubPrObservedMerged(record, issue);
+                if (!githubMerged && opts.runMergeGate !== false) {
+                    const mergeCommandAccepted = await this.#runCompletionMergeGate(issue);
+                    // A successful merge command can mean queued/auto-merge rather than
+                    // merged. Only mounted PR state or a merged webhook may prove merge.
+                    if (mergeCommandAccepted) {
+                        githubMerged = await this.#githubPrObservedMerged(record, issue);
+                    }
+                }
+            }
+            // A GitHub issue only closes after its PR merges. If a configured done
+            // path cannot merge (including mergePolicy: never), park it for a human
+            // instead of closing the issue while its PR remains open.
+            const humanReview = configuredHumanReview || (githubIssue && !githubMerged);
             const statusLabel = humanReview ? 'In Human Review' : 'Done';
             if (issue) {
-                await this.#linear.setState(issue, targetState);
-                await this.#recordCanonicalIssueState({ key: issue.key, stateId: targetState });
+                if (githubIssue) {
+                    if (humanReview) {
+                        await this.#githubWriteback.setStatus(issue, 'human-review');
+                        await this.#githubWriteback.postComment(issue, `Factory agents completed; this issue is awaiting human review. The pull request remains open.\n\nMerge policy: ${this.#config.mergePolicy}`);
+                    }
+                    else {
+                        await this.#githubWriteback.closeIssue(issue, 'Factory observed the linked pull request merge and completed this issue.');
+                    }
+                }
+                else {
+                    const targetState = humanReview
+                        ? this.#states.idFor(issueTeam, 'humanReview')
+                        : this.#states.idFor(issueTeam, 'done');
+                    await this.#linear.setState(issue, targetState);
+                    await this.#recordCanonicalIssueState({ key: issue.key, stateId: targetState });
+                }
                 this.#emit('writeback-verified', { issue: record.issue, path: issue.path });
             }
             if (this.#slack && this.#config.slack && !await this.#shouldSkipSlackWriteback('completion-thread')) {
@@ -2783,14 +3362,15 @@ export class FactoryLoop {
                     const channel = await this.#slackChannelDir();
                     if (channel) {
                         const merged = opts.completionReason === 'pr-merged';
+                        const systemOfRecord = githubIssue ? 'GitHub status' : 'Linear state';
                         const completionText = merged
-                            ? `${record.issue.key}: PR merged; Linear state set to ${statusLabel}.`
+                            ? `${record.issue.key}: PR merged; ${systemOfRecord} set to ${statusLabel}.`
                             : `${record.issue.key}: factory agents completed${humanReview ? '; awaiting human review' : ''}.\nStatus: ${statusLabel}\nMerge policy: ${this.#config.mergePolicy}`;
                         const stateText = merged
-                            ? `${record.issue.key}: PR merged; Linear state set to ${statusLabel}.`
+                            ? `${record.issue.key}: ${systemOfRecord} set to ${statusLabel}.`
                             : humanReview
-                                ? `${record.issue.key}: awaiting human review; Linear state set to ${statusLabel}.`
-                                : `${record.issue.key}: Linear state set to ${statusLabel}.`;
+                                ? `${record.issue.key}: awaiting human review; ${systemOfRecord} set to ${statusLabel}.`
+                                : `${record.issue.key}: ${systemOfRecord} set to ${statusLabel}.`;
                         const root = await this.#slack.postThread({
                             channel,
                             text: completionText,
@@ -2806,13 +3386,14 @@ export class FactoryLoop {
             // Only auto-merge on the `done` terminal path. Human Review parks the PR
             // for an operator — the merge gate (which requires an APPROVED review)
             // would refuse anyway, and we must not merge before the human has looked.
-            if (issue && !humanReview && opts.runMergeGate !== false) {
+            if (issue && !githubIssue && !humanReview && opts.runMergeGate !== false) {
                 await this.#runCompletionMergeGate(issue);
             }
             await this.#releaseAndTerminateAgents([...record.agents], humanReview ? 'issue-human-review' : 'issue-done', 'completion');
             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) {
@@ -2841,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;
     }
@@ -3064,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;
@@ -3111,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;
@@ -3373,11 +4002,11 @@ export class FactoryLoop {
     }
     async #handleTriageEscalationSlackAnswer(record, text) {
         const issue = await this.#readIssue(record.issue.path);
-        if (!issue || !isInFactoryScope(issue, this.#config.safety) || !isRealLinearIssue(issue)) {
+        if (!issue || !isInFactoryScope(issue, this.#config.safety) || !isDispatchableIssue(issue)) {
             this.#increment('slackTriageAnswersIgnoredIssueUnavailable');
             return;
         }
-        if (!this.#states.isRole(issue.stateId, 'readyForAgent')) {
+        if (!this.#isIssueReady(issue)) {
             this.#increment('slackTriageAnswersIgnoredIssueNotReady');
             return;
         }
@@ -3452,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
@@ -3544,27 +4200,27 @@ export class FactoryLoop {
     async #runCompletionMergeGate(issue) {
         if (this.#isSyntheticProbeIssue(issue)) {
             await this.#closeSyntheticProbeIfPresent(issue);
-            return;
+            return false;
         }
-        if (!isRealLinearIssue(issue)) {
+        if (!isDispatchableIssue(issue)) {
             this.#logger.warn?.('[factory] merge gate skipped non-real Linear issue', { issue: issue.key });
             this.#increment('mergeGateSkippedNonReal');
-            return;
+            return false;
         }
         if (this.#config.mergePolicy !== 'on-green-with-review') {
-            return;
+            return false;
         }
         const pr = await this.#probePrResolver(issue);
         if (!pr) {
             this.#logger.warn?.('[factory] merge gate found no PR for real issue', { issue: issue.key });
             this.#increment('mergeGateMissingPr');
-            return;
+            return false;
         }
         const ready = await this.#waitForMergeReady(pr);
         const headSha = ready?.live.headRefOid;
         if (!ready || !headSha) {
             this.#increment('mergeGateNotMerged');
-            return;
+            return false;
         }
         const result = await this.#mergeGate.merge({
             repo: pr.repo,
@@ -3580,7 +4236,7 @@ export class FactoryLoop {
                 reason: result.reason,
             });
             this.#increment('mergeGateMergeAborted');
-            return;
+            return false;
         }
         this.#logger.info?.('[factory] merge gate merged PR', {
             issue: issue.key,
@@ -3589,6 +4245,7 @@ export class FactoryLoop {
             headSha,
         });
         this.#increment('mergeGateMerged');
+        return true;
     }
     async #closeSyntheticProbeIfPresent(issue) {
         const probe = this.#customProbePrResolver
@@ -3728,10 +4385,54 @@ 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,
     };
 }
+export function parseGithubFactoryIssue(path, content) {
+    return githubIssueAsFactoryIssue(parseGithubIssue(path, content));
+}
+const githubIssueAsFactoryIssue = (issue) => {
+    const wrapper = asRecord(issue.raw) ?? {};
+    const payload = wrappedPayload(wrapper);
+    const objectId = stringValue(wrapper.objectId);
+    const stableId = `${issue.repo}#${objectId ?? issue.number}`;
+    return {
+        uuid: stableId,
+        key: String(issue.number),
+        title: issue.title,
+        description: issue.body,
+        stateId: '',
+        state: issue.state ? { name: issue.state } : undefined,
+        labels: issue.labels,
+        path: issue.path,
+        raw: {
+            ...wrapper,
+            provider: 'github',
+            objectType: 'issue',
+            objectId: stableId,
+            payload: {
+                ...payload,
+                id: stableId,
+                number: issue.number,
+                title: issue.title,
+                description: issue.body,
+                url: issue.url,
+                source: {
+                    provider: 'github',
+                    id: stableId,
+                    owner: issue.owner,
+                    repo: issue.repoName,
+                    number: issue.number,
+                    url: issue.url,
+                    path: issue.path,
+                    ...(issue.author ? { author: issue.author, reporter: issue.author } : {}),
+                },
+            },
+        },
+    };
+};
 export async function readFactoryLoopHeartbeat(path = DEFAULT_FACTORY_LOOP_HEARTBEAT_PATH) {
     try {
         return parseJsonContent(await readFile(path, 'utf8'));
@@ -3764,6 +4465,49 @@ export function isRealLinearIssue(issue) {
         typeof payload.url === 'string' &&
         payload.url.length > 0;
 }
+export function isDispatchableIssue(issue) {
+    if (isRealLinearIssue(issue)) {
+        return true;
+    }
+    if (!isGithubIssue(issue)) {
+        return false;
+    }
+    const payload = wrappedPayload(issue.raw);
+    const source = asRecord(payload.source);
+    const sourceId = stringValue(source?.id);
+    const number = numberValue(source?.number) ?? numberValue(payload.number);
+    const url = stringValue(source?.url) ?? stringValue(payload.url);
+    const hasStableIdentity = Boolean(sourceId?.trim()) || (Number.isInteger(number) && (number ?? 0) > 0);
+    return Boolean(issue.uuid.trim() && issue.key.trim() && hasStableIdentity && url?.trim());
+}
+const isGithubIssue = (issue) => {
+    const wrapper = asRecord(issue.raw);
+    const source = asRecord(wrappedPayload(issue.raw).source);
+    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();
@@ -3943,7 +4687,10 @@ function githubUrlCandidates(value) {
     return [...candidates];
 }
 function labelRoutesForIssue(issue, config) {
-    const labels = uniqueNormalizedLabels(issue.labels).filter((label) => !isShapeLabel(label));
+    const githubReadinessLabel = isGithubIssue(issue) ? config.safety.requireLabel.trim().toLowerCase() : undefined;
+    const labels = uniqueNormalizedLabels(issue.labels).filter((label) => !isShapeLabel(label) &&
+        label.toLowerCase() !== githubReadinessLabel &&
+        (!isGithubIssue(issue) || !GITHUB_LIFECYCLE_LABELS.has(label.toLowerCase())));
     const routes = [];
     const offendingLabels = [];
     const seenRepos = new Set();
@@ -4134,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`];
@@ -4171,10 +4985,11 @@ const githubIssueDirectoryPathParts = (path) => {
         slug: match[6],
     };
 };
-const githubIssueHasFactoryLabel = (issue) => issue.labels.some((label) => label.toLowerCase() === GITHUB_FACTORY_LABEL);
+const githubIssueHasFactoryLabel = (issue, requiredLabel = GITHUB_FACTORY_LABEL) => issue.labels.some((label) => label.trim().toLowerCase() === requiredLabel.trim().toLowerCase());
 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(),
@@ -4190,6 +5005,7 @@ const githubIssueMirrorPayload = (issue, repoLabel, config, readyForAgentStateId
             number: issue.number,
             url: issue.url,
             path: issue.path,
+            ...(reporter ? { author: reporter, reporter } : {}),
         },
     };
 };
@@ -4464,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));
@@ -4826,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: [
@@ -4835,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';