@agent-relay/factory 0.1.1 → 0.1.3

package/dist/orchestrator/factory.js

@@ -1,19 +1,20 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
-import { FactoryConfigSchema } from '../config/schema';
-import { linearByStatePath } from '../constants/linear';
-import { stateResolutionFromIds } from '../linear/state-resolver';
-import { GithubMergeGate, closeProbePr } from '../github';
-import { InMemoryStateStore } from '../state/in-memory-state-store';
-import { containsExplicitIssueReference, containsIssueKey } from '../issue-key-match';
-import { isInFactoryScope } from '../safety/factory-scope';
-import { renderAgentTask } from '../dispatch/templates';
-import { HeuristicTriage, TieredTriage, babysitterSpec } from '../triage';
-import { MountGithubRead, MountLinearWriteback, MountSlackWriteback } from '../writeback';
-import { asRecord, parseJsonContent, stableHash, wrappedPayload } from '../writeback/shared';
-import { issueKey } from './batch-tracker';
-import { findAgentProcessByName, readProcessIdentity } from './process-identity';
-import { terminatePids } from './reaper';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { FactoryConfigSchema } from '../config/schema.js';
+import { linearByStatePath, linearByIdPath, linearByUuidPath } from '../constants/linear.js';
+import { stateResolutionFromIds } from '../linear/state-resolver.js';
+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 { 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 } 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';
+import { terminatePids } from './reaper.js';
 const ISSUE_ROOT = '/linear/issues';
 const GITHUB_ISSUE_ROOT = '/github/repos';
 const READY_EVENTS_LIMIT = 100;
@@ -95,6 +96,10 @@ export class FactoryLoop {
     #resumeInFlight = new Map();
     #slackWatchers = new Map();
     #slackWatcherStarts = new Map();
+    // Agents we've already logged an ambiguous-PID-lookup warning for, so the
+    // reaper doesn't spam the same benign "ambiguous process lookup" line on every
+    // poll (a joined/cloud agent has no local PID to resolve — expected).
+    #ambiguousLookupWarned = new Set();
     // Last invalid-label failure signature we posted per issue, so a stuck Ready
     // issue (or the comment writeback's own change event) does not re-post the
     // same notice every cycle. Cleared once the issue dispatches successfully.
@@ -147,6 +152,8 @@ 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;
+    #integrationInstructions;
+    #integrationInstructionsRefresh;
     #starting;
     #started = false;
     #stopping = false;
@@ -154,8 +161,10 @@ export class FactoryLoop {
         this.#config = config;
         this.#mount = ports.mount;
         // Resolved role<->state mapping. The CLI injects a name-resolved, per-team
-        // resolution via ports; fall back to one built from explicit stateIds.
-        this.#states = ports.stateResolution ?? stateResolutionFromIds(config.stateIds);
+        // resolution via ports; fall back to one built from explicit stateIds plus
+        // the configured role NAMES so name->UUID backfill still works for sparse
+        // synced records (state.name but no state.id) without the states catalog.
+        this.#states = ports.stateResolution ?? stateResolutionFromIds(config.stateIds, config.linear.states);
         installFactoryDraftPredicate(this.#mount, config);
         this.#fleet = ports.fleet;
         this.#triage = ports.triage ?? new TieredTriage(new HeuristicTriage());
@@ -190,6 +199,63 @@ export class FactoryLoop {
         });
         this.#wireFleetEvents();
     }
+    async #resolveIntegrationInstructions() {
+        if (this.#integrationInstructionsRefresh) {
+            return this.#integrationInstructionsRefresh;
+        }
+        this.#integrationInstructionsRefresh = this.#doResolveIntegrationInstructions();
+        try {
+            return await this.#integrationInstructionsRefresh;
+        }
+        finally {
+            this.#integrationInstructionsRefresh = undefined;
+        }
+    }
+    async #doResolveIntegrationInstructions() {
+        if (this.#integrationInstructions !== undefined) {
+            return this.#integrationInstructions;
+        }
+        try {
+            const reader = {
+                readFile: async (path) => {
+                    try {
+                        const { content } = await this.#mount.readFile(path);
+                        return typeof content === 'string' ? content : undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                },
+                listPaths: async (prefix) => {
+                    return this.#mount.listTree(prefix);
+                },
+            };
+            const descriptors = await deriveDescriptorsFromMount(reader);
+            // The package emits paths relative to the daemon's .integrations mount,
+            // but the agent runs in its repo clonePath — a relative `.integrations/...`
+            // path is unreachable from there. Absolutize every writeback path to the
+            // daemon's mount root so the prescriptive instructions are actionable.
+            const root = this.#integrationsMountRoot();
+            const abs = (p) => (isAbsolute(p) ? p : resolve(root, '..', p));
+            const absoluteDescriptors = descriptors.map((descriptor) => ({
+                ...descriptor,
+                mountRoot: abs(descriptor.mountRoot),
+                ...(descriptor.discoveryRoot ? { discoveryRoot: abs(descriptor.discoveryRoot) } : {}),
+                writableResources: descriptor.writableResources.map((res) => ({
+                    ...res,
+                    path: abs(res.path),
+                    ...(res.createExamplePath ? { createExamplePath: abs(res.createExamplePath) } : {}),
+                    ...(res.schemaPath ? { schemaPath: abs(res.schemaPath) } : {}),
+                })),
+            }));
+            this.#integrationInstructions = prescriptiveInstructions(absoluteDescriptors);
+            return this.#integrationInstructions;
+        }
+        catch {
+            this.#logger.warn?.('[factory] failed to resolve integration instructions from mount');
+            return undefined;
+        }
+    }
     async #batch() {
         if (this.#batchView) {
             return this.#batchView;
@@ -226,6 +292,7 @@ export class FactoryLoop {
             this.#started = true;
             try {
                 await this.#startLiveSubscription(opts.liveSubscription);
+                await this.#rearmSlackReplyWatchers();
                 this.#scheduleCompletionSweep(0);
                 return;
             }
@@ -237,17 +304,25 @@ export class FactoryLoop {
         }
         await this.#backfillReadyIssues();
         this.#subscription = this.#mount.subscribe([`${ISSUE_ROOT}/**/*.json`, LIVE_GITHUB_ISSUE_GLOB], (event) => {
-            if (isGithubPullFilePath(event.resource.path)) {
-                void this.#handlePrChange(event.resource.path);
+            // 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).
+            const path = changeEventPath(event);
+            if (!path) {
                 return;
             }
-            if (isGithubIssueFilePath(event.resource.path)) {
-                void this.#handleGithubIssueChange(event.resource.path, { dryRun: this.#config.dryRun });
+            if (isGithubPullFilePath(path)) {
+                void this.#handlePrChange(path);
                 return;
             }
-            void this.#handleChange(event.resource.path);
+            if (isGithubIssueFilePath(path)) {
+                void this.#handleGithubIssueChange(path, { dryRun: this.#config.dryRun });
+                return;
+            }
+            void this.#handleChange(path);
         });
         this.#started = true;
+        await this.#rearmSlackReplyWatchers();
         this.#scheduleCompletionSweep(0);
     }
     async stop() {
@@ -572,7 +647,10 @@ export class FactoryLoop {
         await this.#refreshLiveHeartbeat();
     }
     async #prepareLiveEventForDrain(event, seenIssueKeys) {
-        const path = event.resource.path;
+        const path = changeEventPath(event);
+        if (!path) {
+            return undefined;
+        }
         const isPullPath = isGithubPullFilePath(path);
         if (!isIssueFilePath(path) && !isGithubIssueFilePath(path) && !isPullPath) {
             return undefined;
@@ -855,6 +933,11 @@ export class FactoryLoop {
         let consecutiveFailures = 0;
         let completed = false;
         try {
+            // Re-arm Slack reply watchers for any issue that is already in-flight with
+            // a persisted dispatch thread before the first iteration runs. The loop
+            // path never calls #start(), so without this a watcher only lives for the
+            // process that originally dispatched — replies after a restart are dropped.
+            await this.#rearmSlackReplyWatchers();
             for (let iteration = 0; iteration < maxIterations; iteration += 1) {
                 await this.#writeLoopHeartbeat(heartbeatPath, registryPath, 'running', iteration, maxIterations);
                 try {
@@ -973,8 +1056,9 @@ export class FactoryLoop {
         }
         const spawnedForReaperHandoff = [];
         try {
+            const specs = dispatchSpecs(dispatchDecision);
             const agents = [];
-            for (const spec of [...dispatchDecision.implementers, dispatchDecision.reviewer]) {
+            for (const spec of specs) {
                 const spawned = await this.#spawnAgent(record, spec, dryRun);
                 const tracked = record.agents.get(spawned.name);
                 if (tracked) {
@@ -1070,8 +1154,9 @@ export class FactoryLoop {
     }
     async #backfillReadyIssues() {
         const page = await this.#mount.getEvents({ limit: READY_EVENTS_LIMIT });
-        const eventPaths = page.events.map((event) => event.resource.path).filter(isIssueFilePath);
-        const githubEventPaths = page.events.map((event) => event.resource.path).filter(isGithubIssueFilePath);
+        const allPaths = page.events.map((event) => changeEventPath(event)).filter((p) => Boolean(p));
+        const eventPaths = allPaths.filter(isIssueFilePath);
+        const githubEventPaths = allPaths.filter(isGithubIssueFilePath);
         for (const path of new Set(githubEventPaths)) {
             await this.#handleGithubIssueChange(path, { dryRun: this.#config.dryRun });
         }
@@ -1537,8 +1622,21 @@ export class FactoryLoop {
     }
     async #readIssue(path) {
         try {
-            const { content } = await this.#mount.readFile(path);
-            return parseLinearIssue(path, content);
+            // 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
+            // when the primary parses empty so triage sees real state.
+            const issue = await readLinearIssueWithCanonicalFallback(this.#mount, path);
+            // Synced Linear records may carry only the state NAME, not the state UUID
+            // (relayfile-adapters#205). The factory matches state by UUID, so backfill
+            // the id from the name when the payload omitted it — otherwise every issue
+            // reads as stateId='' and no role (incl. readyForAgent) ever matches.
+            if (issue && !issue.stateId && issue.state?.name) {
+                const backfilled = this.#states.idForName(issue.state.name, issue.team);
+                if (backfilled)
+                    return { ...issue, stateId: backfilled };
+            }
+            return issue;
         }
         catch (error) {
             if (isMissingIssueFileError(error) && isIssuePathUnderRoot(path)) {
@@ -1619,7 +1717,10 @@ export class FactoryLoop {
             return { pids: [scan.identity.pid], status: 'found' };
         }
         if (scan.status === 'ambiguous') {
-            this.#logger.warn?.(`[factory] ambiguous process lookup for ${agentName}`);
+            if (!this.#ambiguousLookupWarned.has(agentName)) {
+                this.#ambiguousLookupWarned.add(agentName);
+                this.#logger.warn?.(`[factory] ambiguous process lookup for ${agentName} (suppressing repeats)`);
+            }
             return { pids: [], status: 'unresolved' };
         }
         if (pids.length > 0) {
@@ -1760,6 +1861,8 @@ export class FactoryLoop {
                 capability: spec.capability,
                 node: spec.node ?? 'self',
                 task: spec.task,
+                workflow: spec.workflow,
+                inputs: spec.inputs,
                 model: spec.model,
                 cwd: spec.clonePath,
                 sessionRef: spec.sessionRef,
@@ -1817,6 +1920,12 @@ export class FactoryLoop {
             if (tracked.sessionRef) {
                 const resumeKey = `${issueKey(record.issue)}:${name}:${tracked.sessionRef}`;
                 if (await this.#state.isResumed(this.#workspaceId, resumeKey)) {
+                    // Already resumed once and STILL exiting with no completion PR — the
+                    // agent isn't making progress. Escalate so a human notices, instead of
+                    // leaving the issue silently in-flight forever.
+                    if (tracked.spec.role === 'implementer') {
+                        await this.#escalateStalledIssue(record, name);
+                    }
                     return;
                 }
                 const existing = this.#resumeInFlight.get(resumeKey);
@@ -1875,6 +1984,27 @@ export class FactoryLoop {
             this.#error(error, record.issue);
         }
     }
+    // An implementer that exited, was resumed once, and STILL produced no PR is
+    // not making progress. Surface it (counter + a best-effort Slack note to the
+    // dispatch thread) so a human can step in, instead of the issue sitting
+    // silently "in flight" with nothing happening. We do NOT fake a Linear state
+    // change here (the mount may be wedged); the human owns the next step.
+    async #escalateStalledIssue(record, name) {
+        this.#increment('issuesStalledNoPr');
+        this.#logger.warn?.('[factory] implementer exited without a PR after a resume; escalating for human attention', {
+            issue: record.issue.key,
+            agent: name,
+        });
+        try {
+            const thread = await this.#slackDispatchThreadFor(record);
+            if (thread && this.#slack) {
+                await this.#slack.reply(thread.threadId, `:warning: ${record.issue.key}: the implementer exited without opening a PR (after a retry). It needs a human look.`);
+            }
+        }
+        catch (error) {
+            this.#logger.warn?.('[factory] failed to post stalled-issue escalation to Slack', error);
+        }
+    }
     async #issueHasCompletionPr(record) {
         try {
             const issue = await this.#readIssue(record.issue.path);
@@ -2032,7 +2162,7 @@ export class FactoryLoop {
         this.#counters.liveArrivalLatencyMsMax = Math.max(this.#counters.liveArrivalLatencyMsMax ?? 0, latencyMs);
         this.#logger.debug?.('[factory] live issue event latency recorded', {
             eventId: event.id,
-            path: event.resource.path,
+            path: changeEventPath(event),
             latencyMs,
         });
     }
@@ -2065,6 +2195,7 @@ export class FactoryLoop {
         const reviewer = [...record.agents.values()].find((agent) => agent.spec.role === 'reviewer');
         const reviewerName = reviewer?.result?.name ?? reviewer?.spec.name ?? 'reviewer';
         const implementerNames = implementers.map((agent) => agent.result?.name ?? agent.spec.name);
+        const integrationInstructions = await this.#resolveIntegrationInstructions();
         for (const implementer of implementers) {
             const input = {
                 to: implementer.result?.name ?? implementer.spec.name,
@@ -2076,6 +2207,8 @@ export class FactoryLoop {
                     reviewerName,
                     implementerNames,
                     slackDispatchThread: await this.#slackDispatchThreadFor(record),
+                    integrationsMountRoot: this.#integrationsMountRoot(),
+                    integrationInstructions,
                 }),
                 from: 'factory',
                 data: { issue: record.issue },
@@ -2309,6 +2442,7 @@ export class FactoryLoop {
             const implementerNames = [...record.agents.values()]
                 .filter((agent) => agent.spec.role === 'implementer')
                 .map((agent) => agent.result?.name ?? agent.spec.name);
+            const integrationInstructions = await this.#resolveIntegrationInstructions();
             const task = renderAgentTask({
                 issue: templateIssueFromRecord(record, issue),
                 route: route ?? { repo: prRef.repo },
@@ -2318,6 +2452,8 @@ export class FactoryLoop {
                 implementerNames,
                 pr: { number: prRef.prNumber, url: prRef.url },
                 slackDispatchThread: await this.#slackDispatchThreadFor(record),
+                integrationsMountRoot: this.#integrationsMountRoot(),
+                integrationInstructions,
             });
             const spawned = await this.#spawnAgent(record, { ...spec, task }, false);
             await this.#writeInFlightRegistry();
@@ -2674,13 +2810,21 @@ export class FactoryLoop {
             return;
         }
         const key = issueKey(record.issue);
-        if (await this.#state.getSlackThread(this.#workspaceId, key) || this.#slackWatcherStarts.has(key)) {
+        const existingThread = await this.#state.getSlackThread(this.#workspaceId, key);
+        if (existingThread || this.#slackWatcherStarts.has(key)) {
             try {
                 await this.#slackWatcherStarts.get(key);
             }
             catch {
                 // The initiator logs Slack watcher startup failures.
             }
+            // A dispatch thread already exists (often persisted from a previous
+            // process) but the in-process watcher map starts empty on restart. Re-arm
+            // the reply watcher instead of returning early, otherwise human replies in
+            // the existing thread are watched by nobody and silently dropped.
+            if (existingThread) {
+                await this.#rearmSlackWatcher(record, existingThread);
+            }
             return;
         }
         const start = this.#postAndWatchSlackDispatchThread(record, result);
@@ -2727,13 +2871,20 @@ export class FactoryLoop {
             return;
         }
         const key = issueKey(decision.issue);
-        if (await this.#state.getSlackThread(this.#workspaceId, key) || this.#slackWatcherStarts.has(key)) {
+        const existingThread = await this.#state.getSlackThread(this.#workspaceId, key);
+        if (existingThread || this.#slackWatcherStarts.has(key)) {
             try {
                 await this.#slackWatcherStarts.get(key);
             }
             catch {
                 // The initiator logs Slack watcher startup failures.
             }
+            // Re-arm the reply watcher for an escalation thread that already exists but
+            // has no live in-process watcher (e.g. after a restart), matching the
+            // dispatch-thread path.
+            if (existingThread) {
+                await this.#rearmSlackWatcher(escalationWatchRecord(decision), existingThread);
+            }
             return;
         }
         const start = this.#postAndWatchSlackEscalationThread(decision, reason);
@@ -2763,13 +2914,7 @@ export class FactoryLoop {
             ].join('\n'),
         });
         await this.#state.setSlackThread(this.#workspaceId, issueKey(decision.issue), root.threadId);
-        await this.#watchSlackThread({
-            issue: decision.issue,
-            decision,
-            agents: new Map(),
-            invocationIds: new Set(),
-            dryRun: false,
-        }, root.threadId);
+        await this.#watchSlackThread(escalationWatchRecord(decision), root.threadId);
         this.#recordSlackWritebackSuccess('triage-escalation');
     }
     async #watchSlackThread(record, threadId) {
@@ -2794,8 +2939,9 @@ export class FactoryLoop {
                 const page = await this.#mount.getEvents({ limit: SLACK_REPLY_EVENTS_LIMIT });
                 cursor = page.nextCursor ?? undefined;
                 for (const event of page.events) {
-                    if (event.resource.path.startsWith(messagesPrefix)) {
-                        preExistingPaths.add(event.resource.path);
+                    const path = changeEventPath(event);
+                    if (path && path.startsWith(messagesPrefix)) {
+                        preExistingPaths.add(path);
                     }
                 }
             }
@@ -2805,7 +2951,11 @@ export class FactoryLoop {
         };
         const handle = async (event) => {
             try {
-                if (stopped || !event.resource.path.startsWith(messagesPrefix)) {
+                // Polling-fallback / degraded-sync events can lack `resource.path`
+                // despite the SDK type. Skip them quietly so one malformed event never
+                // wedges Slack reply processing (replies that DO carry a path still flow).
+                const path = changeEventPath(event);
+                if (stopped || !path || !path.startsWith(messagesPrefix)) {
                     return;
                 }
                 const eventKey = eventIdentity(event);
@@ -2815,21 +2965,21 @@ export class FactoryLoop {
                         this.#logger.warn?.('[factory] Slack reply event missing stable identity; falling back to path/content dedupe');
                     }
                 }
-                if (preExistingPaths.has(event.resource.path)) {
+                if (preExistingPaths.has(path)) {
                     return;
                 }
-                const reply = await this.#readSlackReply(event.resource.path);
+                const reply = await this.#readSlackReply(path);
                 if (!reply || !reply.isThreadReply || reply.threadTs !== threadId || reply.channelDir !== channelDir) {
                     return;
                 }
                 const replyMessageKey = `${reply.threadTs}:${reply.messageTs}`;
                 if (seenReplyMessages.has(replyMessageKey)) {
-                    this.#logger.debug?.('[factory] suppressed duplicate Slack reply message', { issue: record.issue.key, path: event.resource.path });
+                    this.#logger.debug?.('[factory] suppressed duplicate Slack reply message', { issue: record.issue.key, path });
                     return;
                 }
-                const replyKey = `${eventKey ?? event.resource.path}:${stableHash(JSON.stringify(reply.raw))}`;
+                const replyKey = `${eventKey ?? path}:${stableHash(JSON.stringify(reply.raw))}`;
                 if (seenReplies.has(replyKey)) {
-                    this.#logger.debug?.('[factory] suppressed duplicate Slack reply payload', { issue: record.issue.key, path: event.resource.path });
+                    this.#logger.debug?.('[factory] suppressed duplicate Slack reply payload', { issue: record.issue.key, path });
                     return;
                 }
                 seenReplies.add(replyKey);
@@ -2886,6 +3036,53 @@ export class FactoryLoop {
             },
         });
     }
+    // Re-attach a live reply watcher to a dispatch/escalation thread that already
+    // exists (persisted thread id) but has no in-process watcher. #watchSlackThread
+    // is itself idempotent on #slackWatchers; the guard here keeps the counter (and
+    // the seeding getEvents call) limited to genuine re-arms.
+    async #rearmSlackWatcher(record, threadId) {
+        const key = issueKey(record.issue);
+        if (this.#slackWatchers.has(key) || this.#slackWatcherStarts.has(key)) {
+            return;
+        }
+        try {
+            await this.#watchSlackThread(record, threadId);
+            this.#increment('slackWatchersRearmed');
+        }
+        catch (error) {
+            this.#logger.warn?.('[factory] failed to re-arm Slack reply watcher', { issue: record.issue.key, error });
+        }
+    }
+    // On start()/runLoop() init, re-arm Slack reply watchers for every in-flight
+    // issue that has a persisted dispatch thread. A watcher otherwise only lives as
+    // long as the process that dispatched it, so replies after a restart (or a
+    // run-once exit followed by a loop) would be watched by nobody.
+    async #rearmSlackReplyWatchers() {
+        if (!this.#slack || !this.#config.slack) {
+            return;
+        }
+        for (const record of (await this.#batch()).inFlight) {
+            if (record.dryRun) {
+                continue;
+            }
+            const key = issueKey(record.issue);
+            if (this.#slackWatchers.has(key) || this.#slackWatcherStarts.has(key)) {
+                continue;
+            }
+            let threadId;
+            try {
+                threadId = await this.#state.getSlackThread(this.#workspaceId, key);
+            }
+            catch (error) {
+                this.#logger.warn?.('[factory] unable to read persisted Slack thread during watcher rehydration', { issue: record.issue.key, error });
+                continue;
+            }
+            if (!threadId) {
+                continue;
+            }
+            await this.#rearmSlackWatcher(record, threadId);
+        }
+    }
     async #stopSlackWatcher(issue) {
         const key = issueKey(issue);
         const watcher = this.#slackWatchers.get(key);
@@ -2927,18 +3124,34 @@ export class FactoryLoop {
             this.#increment('slackAnswersIgnoredNoImplementer');
             return;
         }
-        const input = slackAnswerInput(liveRecord.issue, text);
         for (const recipient of new Set(recipients)) {
-            await this.#fleet.sendInput(recipient, input);
+            await this.#injectSlackReplyEvent(recipient, liveRecord.issue, text);
             this.#increment('slackAnswersInjected');
         }
     }
+    // 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
+    // event. (A broker confirmed-delivery path via waitForInjected is a possible
+    // robustness follow-up.)
+    async #injectSlackReplyEvent(recipient, issue, text) {
+        await this.#fleet.sendInput?.(recipient, slackReplyEvent(issue, text));
+    }
+    // Absolute path to the local .integrations mount the daemon manages. The mount
+    // is created at the daemon's cwd (see ensureLocalMount), and spawned agents run
+    // in their repo clonePath, so writeback paths handed to agents must be absolute
+    // against this root rather than a bare relative `.integrations/...`.
+    #integrationsMountRoot() {
+        return resolve(process.cwd(), '.integrations');
+    }
     async #slackDispatchThreadFor(record) {
         if (!this.#config.slack) {
             return undefined;
         }
         const threadId = await this.#state.getSlackThread(this.#workspaceId, issueKey(record.issue));
-        return threadId ? { channel: this.#config.slack.channel, threadId } : undefined;
+        return threadId
+            ? { channel: this.#config.slack.channel, threadId, mountRoot: this.#integrationsMountRoot() }
+            : undefined;
     }
     async #runCompletionMergeGate(issue) {
         if (this.#isSyntheticProbeIssue(issue)) {
@@ -3063,6 +3276,46 @@ export function parseLinearIssue(path, content) {
         raw: asRecord(parsed) ?? payload,
     };
 }
+// A primary issue file that parsed without any usable state is a change-event
+// STUB ({created,path,externalId,ts,id}) — the active-issues sync wrote the full
+// body to the by-id/by-uuid aliases instead. Distinguishes a stub from a real
+// record (which always carries at least a state name from sync).
+const isUsableIssueRecord = (issue) => Boolean(issue.stateId || issue.state?.name);
+// The canonical sibling records for a primary /linear/issues/<key>__<uuid>.json
+// path: by-id keyed on the human key, by-uuid keyed on the Linear UUID.
+const canonicalIssueRecordPaths = (path) => {
+    const key = keyFromPath(path);
+    const uuid = uuidFromPath(path);
+    return [
+        ...(key ? [linearByIdPath(key)] : []),
+        ...(uuid ? [linearByUuidPath(uuid)] : []),
+    ].filter((candidate) => candidate !== path);
+};
+// Read an issue, falling back to the canonical by-id/by-uuid alias when the
+// primary path holds only a stub. The canonical content is re-parsed against
+// the ORIGINAL primary path so issue.path/key/uuid stay primary-anchored (the
+// rest of the factory dedupes and dispatches by the primary path). A missing
+// alias is tolerated; the original (stub) record is returned if no alias helps.
+export async function readLinearIssueWithCanonicalFallback(mount, path) {
+    const { content } = await mount.readFile(path);
+    const issue = parseLinearIssue(path, content);
+    if (isUsableIssueRecord(issue))
+        return issue;
+    for (const candidate of canonicalIssueRecordPaths(path)) {
+        try {
+            const canonical = await mount.readFile(candidate);
+            const parsed = parseLinearIssue(path, canonical.content);
+            if (isUsableIssueRecord(parsed))
+                return parsed;
+        }
+        catch (error) {
+            if (isMissingIssueFileError(error))
+                continue;
+            throw error;
+        }
+    }
+    return issue;
+}
 export function parseGithubIssue(path, content) {
     const parsed = parseJsonContent(content);
     const payload = wrappedPayload(parsed);
@@ -3138,11 +3391,42 @@ const pidsFromSpawnResult = (result) => {
 const dispatchComment = (decision, agents) => [
     `Factory dispatch for ${decision.issue.key}`,
     `Implementers: ${agents.filter((agent) => agent.role === 'implementer').map((agent) => agent.name).join(', ') || 'none'}`,
+    decision.scope === 'workflow' ? `Workflow: ${agents.find((agent) => agent.role === 'workflow')?.name ?? 'none'}` : undefined,
     `Reviewer: ${agents.find((agent) => agent.role === 'reviewer')?.name ?? 'none'}`,
-].join('\n');
+].filter((line) => line !== undefined).join('\n');
+function dispatchSpecs(decision) {
+    if (decision.scope === 'workflow') {
+        return decision.workflow ? [decision.workflow] : [];
+    }
+    return [...decision.implementers, decision.reviewer];
+}
 function labelDerivedDispatchDecision(liveIssue, decision, config) {
     const routesByLabel = labelRoutesForIssue(liveIssue, config);
     if (routesByLabel.labels.length === 0) {
+        // No repo labels — which is also what a label-less sync produces
+        // (relayfile-adapters#205, labels dropped from the synced record). Fall back
+        // to the configured default repo (consistent with triage, which already
+        // routes unlabeled issues to repos.default) rather than refusing to dispatch.
+        const defaultRepo = config.repos.default;
+        if (defaultRepo) {
+            const route = {
+                repo: defaultRepo,
+                clonePath: config.repos.clonePaths[defaultRepo],
+                rationale: 'No repo label present; routed to repos.default.',
+            };
+            const implementer = routeImplementerSpec(liveIssue, config, 'default', route);
+            return {
+                ok: true,
+                decision: {
+                    ...decision,
+                    routes: [route],
+                    scope: 'single',
+                    implementers: [implementer],
+                    workflow: undefined,
+                    reviewer: routeReviewerSpec(liveIssue, config, route, decision.reviewer),
+                },
+            };
+        }
         return {
             ok: false,
             reason: 'no-labels',
@@ -3156,8 +3440,15 @@ function labelDerivedDispatchDecision(liveIssue, decision, config) {
             offendingLabels: routesByLabel.offendingLabels.length > 0 ? routesByLabel.offendingLabels : routesByLabel.labels,
         };
     }
+    const explicitScope = scopeFromLabels(liveIssue.labels);
+    const scope = explicitScope
+        ?? (routesByLabel.routes.length >= 2 || decision.scope === 'team'
+            ? 'team'
+            : decision.scope === 'workflow'
+                ? 'workflow'
+                : 'single');
     const maxImplementers = Math.min(config.triage.maxImplementers, MAX_LABEL_IMPLEMENTERS);
-    if (routesByLabel.routes.length > maxImplementers) {
+    if (scope === 'team' && routesByLabel.routes.length > maxImplementers) {
         return {
             ok: false,
             reason: 'too-many-labels',
@@ -3166,19 +3457,30 @@ function labelDerivedDispatchDecision(liveIssue, decision, config) {
         };
     }
     const implementers = routesByLabel.routes.map(({ slug, route }) => routeImplementerSpec(liveIssue, config, slug, route));
+    const selectedRoutes = scope === 'single' ? routesByLabel.routes.slice(0, 1) : routesByLabel.routes;
+    const selectedImplementers = scope === 'team'
+        ? implementers
+        : scope === 'single'
+            ? implementers.slice(0, 1)
+            : [];
+    const routes = selectedRoutes.map(({ route }) => route);
+    const workflow = scope === 'workflow'
+        ? routeWorkflowSpec(liveIssue, config, selectedRoutes, decision.workflow)
+        : undefined;
     return {
         ok: true,
         decision: {
             ...decision,
-            routes: routesByLabel.routes.map(({ route }) => route),
-            scope: implementers.length >= 2 ? 'team' : 'single',
-            implementers,
-            reviewer: routeReviewerSpec(liveIssue, config, routesByLabel.routes[0].route, decision.reviewer),
+            routes,
+            scope,
+            implementers: selectedImplementers,
+            workflow,
+            reviewer: routeReviewerSpec(liveIssue, config, selectedRoutes[0].route, decision.reviewer),
         },
     };
 }
 function labelRoutesForIssue(issue, config) {
-    const labels = uniqueNormalizedLabels(issue.labels);
+    const labels = uniqueNormalizedLabels(issue.labels).filter((label) => !isShapeLabel(label));
     const routes = [];
     const offendingLabels = [];
     const seenRepos = new Set();
@@ -3229,6 +3531,29 @@ function routeReviewerSpec(issue, config, route, reviewer) {
         node: reviewer.node ?? 'self',
     };
 }
+function routeWorkflowSpec(issue, _config, routesByLabel, workflow) {
+    const route = routesByLabel[0].route;
+    return {
+        ...workflow,
+        name: workflow?.name ?? `${agentBaseName(issue)}-workflow`,
+        role: 'workflow',
+        capability: 'workflow:run',
+        task: workflow?.task ?? taskForDispatch(issue, route, 'workflow'),
+        workflow: workflow?.workflow ?? 'workflows/factory/linear-issue.ts',
+        inputs: {
+            ...workflow?.inputs,
+            issue: { uuid: issue.uuid, key: issue.key, path: issue.path },
+            title: issue.title,
+            description: issue.description,
+            labels: issue.labels,
+            repoLabels: routesByLabel.map(({ slug }) => slug),
+            routes: routesByLabel.map(({ route }) => route),
+        },
+        repo: route.repo,
+        clonePath: route.clonePath,
+        node: workflow?.node ?? 'self',
+    };
+}
 function labelDispatchFailureSignature(resolution) {
     return `${resolution.reason}:${[...resolution.offendingLabels].sort().join(',')}`;
 }
@@ -3276,7 +3601,13 @@ function uniqueNormalizedLabels(labels) {
     return unique;
 }
 function taskForDispatch(issue, route, role) {
-    const verb = role === 'implementer' ? 'Implement' : role === 'babysitter' ? 'Babysit the PR for' : 'Review';
+    const verb = role === 'implementer'
+        ? 'Implement'
+        : role === 'babysitter'
+            ? 'Babysit the PR for'
+            : role === 'workflow'
+                ? 'Run workflow for'
+                : 'Review';
     return [
         `${verb} ${issue.key}: ${issue.title}`,
         `Repo: ${route.repo}`,
@@ -3690,7 +4021,7 @@ const liveEventDedupeKey = (event) => {
     return [
         event.id,
         event.type,
-        event.resource.path,
+        stringValue(resource.path) ?? '',
         stringValue(resource.revision) ?? '',
         event.digest ?? '',
     ].join('\u001f');
@@ -3840,6 +4171,15 @@ const eventIdentity = (event) => {
     const id = typeof rawId === 'string' || typeof rawId === 'number' ? String(rawId) : undefined;
     return id ? `event:${id}` : undefined;
 };
+// Safe accessor for an event's resource path. The SDK types `resource` as
+// always-present, but the HTTP polling fallback and degraded-sync paths can
+// deliver events without it — reading `.path` directly then throws and (in a
+// subscription/poll handler) crash-loops. Returns undefined for such events so
+// callers skip them and keep processing the well-formed ones.
+export const changeEventPath = (event) => {
+    const path = event?.resource?.path;
+    return typeof path === 'string' && path ? path : undefined;
+};
 const describeError = (error) => {
     if (error instanceof Error) {
         return {
@@ -3907,6 +4247,16 @@ const contextualError = (context, error) => {
     return wrapped;
 };
 const registryHandoffKey = (issue, agentName) => `${issueKey(issue)}:${agentName}`;
+// Synthetic in-flight record used to watch an escalation thread. Escalations have
+// no spawned agents; reply routing re-reads the live batch record by issue, so
+// the empty agents/invocations here are only placeholders for the watcher key.
+const escalationWatchRecord = (decision) => ({
+    issue: decision.issue,
+    decision,
+    agents: new Map(),
+    invocationIds: new Set(),
+    dryRun: false,
+});
 const cloneTrackedAgent = (tracked) => ({
     spec: { ...tracked.spec },
     result: tracked.result ? { ...tracked.result } : undefined,
@@ -3948,6 +4298,10 @@ const triageEscalationReason = (decision) => {
     return `${reasons.join(' and ')}${decision.rationale ? `: ${decision.rationale}` : ''}`;
 };
 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 isFactoryQuestionTarget = (target) => {
     const normalized = target.trim().replace(/^@/u, '').toLowerCase();
     return normalized === 'broker' || normalized === 'factory';