@agent-relay/factory 0.1.13 → 0.1.14

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
@@ -58,6 +60,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 +79,7 @@ export class FactoryLoop {
     #fleet;
     #triage;
     #linear;
+    #githubWriteback;
     #slack;
     #mergeGate;
     #probeCloser;
@@ -91,6 +95,7 @@ export class FactoryLoop {
     #terminationGraceMs;
     #state;
     #workspaceId;
+    #relayflows;
     #batchView;
     #batchReady;
     #listeners = new Map();
@@ -158,6 +163,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 +183,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 +202,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,12 +295,19 @@ 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;
@@ -309,7 +324,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).
@@ -415,7 +431,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 +634,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 +671,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 +694,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 +704,7 @@ export class FactoryLoop {
                 highWatermark: this.#liveEventHighWatermark,
                 path,
             });
-            return undefined;
+            return { dispatchRelayflow: false };
         }
         const dedupeKey = liveEventDedupeKey(event);
         if (dedupeKey) {
@@ -691,7 +714,7 @@ export class FactoryLoop {
                     id: event.id,
                     path,
                 });
-                return undefined;
+                return { dispatchRelayflow: false };
             }
             rememberLiveEvent(this.#seenLiveEvents, dedupeKey);
         }
@@ -699,6 +722,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 +733,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 +745,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 +759,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 +770,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 +943,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 +961,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 +978,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 +986,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,7 +1214,7 @@ 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;
@@ -1179,7 +1240,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 +1289,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 = {
@@ -1320,24 +1386,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();
@@ -1367,6 +1433,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 +1583,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 +1605,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 +1883,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 +1911,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
@@ -2525,9 +2640,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 +2661,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 +2693,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 +2713,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 +2878,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 +2914,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 +2959,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,7 +2983,7 @@ 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');
@@ -3373,11 +3550,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;
         }
@@ -3544,27 +3721,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 +3757,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 +3766,7 @@ export class FactoryLoop {
             headSha,
         });
         this.#increment('mergeGateMerged');
+        return true;
     }
     async #closeSyntheticProbeIfPresent(issue) {
         const probe = this.#customProbePrResolver
@@ -3732,6 +3910,48 @@ export function parseGithubIssue(path, content) {
         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,
+                },
+            },
+        },
+    };
+};
 export async function readFactoryLoopHeartbeat(path = DEFAULT_FACTORY_LOOP_HEARTBEAT_PATH) {
     try {
         return parseJsonContent(await readFile(path, 'utf8'));
@@ -3764,6 +3984,27 @@ 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 issueRef = (issue) => ({ uuid: issue.uuid, key: issue.key, path: issue.path });
 const pidsFromSpawnResult = (result) => {
     const pids = new Set();
@@ -3943,7 +4184,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();
@@ -4171,7 +4415,7 @@ 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];