@agent-relay/factory 0.1.57 → 0.1.58

package/dist/cli/fleet.js

@@ -15,14 +15,18 @@ import { checkFeatureMap } from '../featuremap/index.js';
 import { loadOrCreateFactoryInstanceId, resolveFactoryInstanceName } from '../observability/instance-identity.js';
 import { ensureFactoryIntegrations, inspectFactoryIntegration, openIntegrationUrl, } from '../mount/relayfile-integration-preflight.js';
 import { checkMountStaleness } from '../mount/relayfile-binary.js';
+import { MountAuthScopeError } from '../mount/mount-auth-error.js';
+import { resolveRelayWorkspaceKey } from '../fleet/relay-workspace-key.js';
+import { GhCliIssuePublisher, RelayChannelNotionClaimStore, RelayChannelNotionContractPublisher, loadNotionIntakeManifest, runNotionIntake, } from '../intake/index.js';
 const autoDetectedIssueSources = new WeakSet();
-const CLONE_MOUNT_PREFLIGHT_CONCURRENCY = 4;
 export async function runFleetCli(argv, deps = {}) {
     const out = deps.stdout ?? process.stdout;
     const err = deps.stderr ?? process.stderr;
     let fleet;
     let mount;
     let reporter;
+    let notionContracts;
+    let notionClaims;
     try {
         if (argv.some(isHelpFlag)) {
             out.write(helpText());
@@ -46,6 +50,81 @@ export async function runFleetCli(argv, deps = {}) {
             await initializeFactory({ repo: command.repo, workspaceId: command.workspaceId, stdout: out, stderr: err });
             return 0;
         }
+        if (command.kind === 'notion-intake') {
+            const manifest = await loadNotionIntakeManifest(command.manifestPath);
+            if (!globals.dryRun) {
+                notionClaims = deps.notionClaims;
+                notionContracts = deps.notionContracts;
+                const needsWorkspaceKey = !notionClaims ||
+                    (manifest.workerMountTransport.kind === 'relay-channel' && !notionContracts);
+                const workspaceKey = needsWorkspaceKey
+                    ? resolveRelayWorkspaceKey({
+                        env: deps.env ?? process.env,
+                        ...(deps.env ? { activeWorkspaceKey: () => undefined } : {}),
+                    })
+                    : undefined;
+                if (needsWorkspaceKey && !workspaceKey) {
+                    throw new Error('Notion dispatch requires an active Agent Relay workspace for its durable shared claim');
+                }
+                notionClaims ??= new RelayChannelNotionClaimStore({ workspaceKey: workspaceKey });
+                if (manifest.workerMountTransport.kind === 'relay-channel') {
+                    notionContracts ??= new RelayChannelNotionContractPublisher({ workspaceKey: workspaceKey });
+                }
+            }
+            const workspace = {
+                find: async (name) => {
+                    fleet ??= await buildFleet(globals, undefined, deps);
+                    const running = (await fleet.roster()).agents.find((agent) => agent.name === name);
+                    return running ? { agent: running.name, node: running.node } : undefined;
+                },
+                dispatch: async (task) => {
+                    fleet ??= await buildFleet(globals, undefined, deps);
+                    const running = (await fleet.roster()).agents.find((agent) => agent.name === task.name);
+                    if (running)
+                        return { agent: running.name, node: running.node, status: 'already-running' };
+                    const spawned = await fleet.spawn({
+                        name: task.name,
+                        capability: 'spawn:codex',
+                        node: task.node ?? 'self',
+                        task: task.task,
+                        cwd: task.projectPath,
+                        invocationId: task.invocationId,
+                    });
+                    fleet.preserveInfrastructureOnDispose?.();
+                    return { agent: spawned.name, node: spawned.node, status: 'spawned' };
+                },
+                redispatch: async (task) => {
+                    fleet ??= await buildFleet(globals, undefined, deps);
+                    const running = (await fleet.roster()).agents.find((agent) => agent.name === task.name);
+                    if (running) {
+                        await fleet.sendMessage({ to: `@${running.name}`, text: task.task, mode: 'steer' });
+                        return { agent: running.name, node: running.node, status: 'updated-running' };
+                    }
+                    const spawned = await fleet.spawn({
+                        name: task.name,
+                        capability: 'spawn:codex',
+                        node: task.node ?? 'self',
+                        task: task.task,
+                        cwd: task.projectPath,
+                        invocationId: task.invocationId,
+                    });
+                    fleet.preserveInfrastructureOnDispose?.();
+                    return { agent: spawned.name, node: spawned.node, status: 'respawned' };
+                },
+            };
+            const report = await runNotionIntake({
+                manifest,
+                dispatch: !globals.dryRun,
+                ...(!globals.dryRun ? {
+                    github: new GhCliIssuePublisher(),
+                    workspace,
+                    ...(notionClaims ? { claims: notionClaims } : {}),
+                    ...(notionContracts ? { contracts: notionContracts } : {}),
+                } : {}),
+            });
+            writeJson(out, report);
+            return report.ok ? 0 : 1;
+        }
         if (command.kind === 'factory-close-probe') {
             // Manual close-probe remains strict; the daemon relaxes the title marker only after issue-synthetic classification.
             let githubWrite;
@@ -238,27 +317,47 @@ export async function runFleetCli(argv, deps = {}) {
     }
     finally {
         try {
-            await mount?.dispose?.();
+            try {
+                await notionClaims?.dispose?.();
+            }
+            catch {
+                err.write('[factory] warning: Notion claim store failed during shutdown\n');
+            }
         }
         finally {
             try {
-                await fleet?.dispose();
+                try {
+                    await notionContracts?.dispose?.();
+                }
+                catch {
+                    err.write('[factory] warning: Notion contract publisher failed during shutdown\n');
+                }
             }
             finally {
-                if (reporter) {
+                try {
+                    await mount?.dispose?.();
+                }
+                finally {
                     try {
-                        await reporter.report(createFactoryCloudEventV1({
-                            type: 'instance.stopping',
-                            attributes: { component: 'cli', operation: 'stop' },
-                        }));
-                        await reporter.report(createFactoryCloudEventV1({
-                            type: 'instance.stopped',
-                            attributes: { component: 'cli', operation: 'stop' },
-                        }));
-                        await reporter.close?.({ deadlineMs: 2_000 });
+                        await fleet?.dispose();
                     }
-                    catch {
-                        err.write('[factory] warning: Cloud progress reporter failed during shutdown\n');
+                    finally {
+                        if (reporter) {
+                            try {
+                                await reporter.report(createFactoryCloudEventV1({
+                                    type: 'instance.stopping',
+                                    attributes: { component: 'cli', operation: 'stop' },
+                                }));
+                                await reporter.report(createFactoryCloudEventV1({
+                                    type: 'instance.stopped',
+                                    attributes: { component: 'cli', operation: 'stop' },
+                                }));
+                                await reporter.close?.({ deadlineMs: 2_000 });
+                            }
+                            catch {
+                                err.write('[factory] warning: Cloud progress reporter failed during shutdown\n');
+                            }
+                        }
                     }
                 }
             }
@@ -279,8 +378,21 @@ export function parseFleetCommand(args) {
     if (verb === 'featuremap') {
         return parseFeatureMapCommand(rest);
     }
+    if (verb === 'intake') {
+        return parseIntakeCommand(rest);
+    }
     throw new Error(`Unknown factory command: ${verb}`);
 }
+function parseIntakeCommand(args) {
+    const [source, manifestPath, ...rest] = args;
+    if (source !== 'notion')
+        throw new Error('factory intake currently requires the notion source');
+    if (!manifestPath)
+        throw new Error('factory intake notion requires a manifest path');
+    if (rest.length > 0)
+        throw new Error(`Unexpected factory intake argument: ${rest[0]}`);
+    return { kind: 'notion-intake', manifestPath };
+}
 function parseFeatureMapCommand(args) {
     const [action, ...flags] = args;
     if (action !== 'check') {
@@ -377,15 +489,6 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
     const debugMountRefreshes = (deps.env ?? process.env).FACTORY_LOG_LEVEL?.toLowerCase() === 'debug';
     if (command.kind === 'factory') {
         if (command.action === 'start') {
-            // Local mirrors are a writeback aid, not the source of truth for remote
-            // issue discovery. Start their SDK-backed supervisors immediately, but
-            // do not serialize durable recovery behind a stale checkout's readiness
-            // timeout. The mount client reports degradation and keeps retrying.
-            void warmStartPathMounts(mountFn, workspaceId, config, acceptableMountIds, mountStderr, debugMountRefreshes)
-                .catch((error) => {
-                const message = error instanceof Error ? error.message : String(error);
-                mountStderr.write(`[factory] warning: background relayfile mount warmup failed: ${message}\n`);
-            });
             const waiter = createStopSignalWaiter();
             let stoppedBySignal = false;
             const flushAndResolve = async (code) => {
@@ -396,6 +499,27 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
                     waiter.resolve(code);
                 }
             };
+            // Once a workspace mirror is known, retain background stale-mount
+            // supervision so durable recovery is not serialized behind a refresh.
+            // If there is no registered root yet, however, wait for the single
+            // mount/admission fallback before Factory can dispatch: agents must not
+            // receive a provisional checkout-local `.integrations` path.
+            //
+            // A MountAuthScopeError is the exception: it is terminal (the cloud
+            // session lacks the filesystem scope the mount needs), so limping on
+            // would only spawn agents against a read-denied mirror. Fail fast with the
+            // remediation and resolve the command with a non-zero code.
+            const warmMount = () => warmStartPathMounts(mount, mountFn, workspaceId, config, acceptableMountIds, mountStderr, debugMountRefreshes);
+            const handleWarmMountError = (error) => {
+                if (error instanceof MountAuthScopeError) {
+                    mountStderr.write(`${error.message}\n`);
+                    mountStderr.write('[factory] aborting startup: local mount cannot obtain its filesystem scopes.\n');
+                    void flushAndResolve(1);
+                    return;
+                }
+                const message = error instanceof Error ? error.message : String(error);
+                mountStderr.write(`[factory] warning: background relayfile mount warmup failed: ${message}\n`);
+            };
             const removeSignalHandlers = installFactoryStopSignalHandlers(factory, {
                 exit: (code) => {
                     stoppedBySignal = true;
@@ -407,6 +531,28 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
                 processLike: deps.stopSignalProcessLike,
             });
             try {
+                if (mount.getLocalMountRoot?.() === undefined) {
+                    try {
+                        const result = await warmMount();
+                        if (!result.mounted) {
+                            mountStderr.write('[factory] aborting startup: Relayfile workspace mirror could not be resolved.\n');
+                            if (stoppedBySignal)
+                                return await waiter.promise;
+                            return 1;
+                        }
+                    }
+                    catch (error) {
+                        handleWarmMountError(error);
+                        if (stoppedBySignal)
+                            return await waiter.promise;
+                        return 1;
+                    }
+                }
+                else {
+                    void warmMount().catch(handleWarmMountError);
+                }
+                if (stoppedBySignal)
+                    return await waiter.promise;
                 await factory.start({ mode: command.mode });
                 const code = await (deps.waitForStopSignal?.() ?? waiter.promise);
                 return typeof code === 'number' ? code : 0;
@@ -419,12 +565,12 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
             }
         }
         if (command.action === 'run-once') {
-            await ensureClonePathMounts(mountFn, workspaceId, config, acceptableMountIds, mountStderr, debugMountRefreshes);
+            await ensureWorkspaceMount(mount, mountFn, workspaceId, acceptableMountIds, mountStderr);
             writeJson(out, await factory.runOnce({ dryRun: globals.dryRun }));
             return 0;
         }
         if (command.action === 'status') {
-            writeJson(out, factory.status());
+            writeJson(out, await factoryStatusWithMountHealth(factory, mount, config.loop.heartbeatPath, config.loop.heartbeatStaleMs));
             return 0;
         }
         if (command.action === 'loop-status') {
@@ -441,13 +587,16 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
             writeJson(out, { killed: heartbeat.pid, signal: 'SIGTERM' });
             return 0;
         }
-        await ensureClonePathMounts(mountFn, workspaceId, config, acceptableMountIds, mountStderr, debugMountRefreshes);
+        await ensureWorkspaceMount(mount, mountFn, workspaceId, acceptableMountIds, mountStderr);
         const removeSignalHandlers = installFactoryStopSignalHandlers(factory, {
             processLike: deps.stopSignalProcessLike,
         });
         try {
             const reports = await factory.runLoop({ dryRun: globals.dryRun });
-            writeJson(out, { reports, status: factory.status() });
+            writeJson(out, {
+                reports,
+                status: await factoryStatusWithMountHealth(factory, mount, config.loop.heartbeatPath, config.loop.heartbeatStaleMs),
+            });
         }
         finally {
             removeSignalHandlers();
@@ -461,8 +610,11 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
         writeJson(out, result);
         return result.ok ? 0 : 1;
     }
-    const issue = await readIssueArg(mount, command.issue, config);
-    const decision = await factory.triageIssue(issue);
+    const resolved = await resolveIssueArg(mount, command.issue, config, async () => issueProjectionStatus(factory, mount, config));
+    const decision = {
+        ...await factory.triageIssue(resolved.issue),
+        issueResolution: resolved.resolution,
+    };
     if (command.kind === 'factory-triage') {
         writeJson(out, decision);
         return 0;
@@ -485,23 +637,18 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
     writeJson(out, await factory.dispatch(decision, { dryRun: globals.dryRun }));
     return 0;
 }
-async function warmStartPathMounts(mountFn, workspaceId, config, acceptableMountIds, stderr = process.stderr, debug = process.env.FACTORY_LOG_LEVEL?.toLowerCase() === 'debug') {
-    const mountOpts = { acceptableWorkspaceIds: acceptableMountIds };
-    const [daemonRefresh, cloneRefreshes] = await Promise.all([
-        ensureMountPath(mountFn, workspaceId, process.cwd(), mountOpts, stderr),
-        ensureClonePathMounts(mountFn, workspaceId, config, acceptableMountIds, stderr, debug, false),
-    ]);
-    writeMountRefreshSummary([...(daemonRefresh ? [daemonRefresh] : []), ...cloneRefreshes], stderr, debug);
+async function warmStartPathMounts(mount, mountFn, workspaceId, config, acceptableMountIds, stderr = process.stderr, debug = process.env.FACTORY_LOG_LEVEL?.toLowerCase() === 'debug') {
+    const result = await ensureWorkspaceMount(mount, mountFn, workspaceId, acceptableMountIds, stderr);
+    writeMountRefreshSummary(result.refreshed ? [result.refreshed] : [], stderr, debug);
+    stderr.write(`[factory] Relayfile workspace mirror preflight: mounted=${result.mounted ? 1 : 0} ` +
+        `failed=${result.mounted ? 0 : 1} routedRepos=${new Set(Object.values(config.repos.byLabel)).size}\n`);
+    return result;
 }
 async function runStandaloneBabysitCommand(command, mount, fleet, config, globals, out, deps, workspaceId, acceptableMountIds) {
     const repo = resolveStandaloneBabysitRepo(command.repo, config);
     const clonePath = standaloneBabysitClonePath(repo, config);
     const mountFn = resolveLocalMountFn(deps, mount);
-    const mountOpts = { acceptableWorkspaceIds: acceptableMountIds };
-    await ensureStandaloneBabysitMount(mountFn, workspaceId, process.cwd(), mountOpts, deps.stderr);
-    if (clonePath && resolve(clonePath) !== resolve(process.cwd())) {
-        await ensureStandaloneBabysitMount(mountFn, workspaceId, clonePath, mountOpts, deps.stderr);
-    }
+    await ensureWorkspaceMount(mount, mountFn, workspaceId, acceptableMountIds, deps.stderr);
     const pr = await readStandalonePullRequest(mount, { repo, prNumber: command.prNumber, url: command.url }, deps.babysitPrGhRunner ?? defaultGhRunner);
     const state = pr.state?.trim().toUpperCase();
     if (pr.merged || state === 'MERGED') {
@@ -561,7 +708,7 @@ async function runStandaloneBabysitCommand(command, mount, fleet, config, global
             maintainerCanModify: pr.maintainerCanModify,
         },
         standaloneBabysitter: { specSource },
-        integrationsMountRoot: resolve(process.cwd(), '.integrations'),
+        integrationsMountRoot: resolveIntegrationsMountRoot(mount),
         testGuidance,
     });
     const receiptBase = {
@@ -597,16 +744,6 @@ async function runStandaloneBabysitCommand(command, mount, fleet, config, global
     writeJson(out, { status: 'spawned', ...receiptBase, agent: spawned.name });
     return 0;
 }
-async function ensureStandaloneBabysitMount(mountFn, workspaceId, startDir, options, stderr = process.stderr) {
-    try {
-        await mountFn(workspaceId, startDir, options);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        stderr.write(`[factory] warning: could not start relayfile mount for standalone babysitter at ${resolve(startDir)}; ` +
-            `the agent will use the GitHub CLI fallback: ${message}\n`);
-    }
-}
 function resolveStandaloneBabysitRepo(repo, config) {
     const configured = repo ?? config.repos.default;
     if (!configured) {
@@ -636,50 +773,71 @@ function standaloneBabysitClonePath(repo, config) {
     return undefined;
 }
 /**
- * Ensures the relayfile mount is running at each configured clone path so
- * spawned agents can resolve `.integrations` relative to their working
- * directory (the checkout path). The mount daemon started at the daemon CWD
- * is not automatically accessible from a different directory, and agents need
- * these paths for integration writebacks (Slack, GitHub, etc.).
+ * Ensures exactly one Relayfile mirror for the workspace.  Agents receive this
+ * absolute path in their tasks, so routing more repositories never asks
+ * Relayfile to re-home the mirror into each checkout.
  */
-async function ensureClonePathMounts(mountFn, workspaceId, config, acceptableMountIds, stderr = process.stderr, debug = process.env.FACTORY_LOG_LEVEL?.toLowerCase() === 'debug', reportSummary = true) {
+async function ensureWorkspaceMount(mount, mountFn, workspaceId, acceptableMountIds, stderr = process.stderr) {
     const mountOpts = { acceptableWorkspaceIds: acceptableMountIds };
-    const daemonCwd = resolve(process.cwd());
-    const clonePaths = [...new Set(Object.values(config.clonePaths ?? {}).map((clonePath) => resolve(clonePath)))]
-        .filter((clonePath) => clonePath !== daemonCwd);
-    const refreshedStaleMounts = [];
-    let nextIndex = 0;
-    const mountNext = async () => {
-        while (nextIndex < clonePaths.length) {
-            const resolved = clonePaths[nextIndex++];
-            const refreshed = await ensureMountPath(mountFn, workspaceId, resolved, mountOpts, stderr);
-            if (refreshed)
-                refreshedStaleMounts.push(refreshed);
-        }
-    };
-    await Promise.all(Array.from({ length: Math.min(CLONE_MOUNT_PREFLIGHT_CONCURRENCY, clonePaths.length) }, mountNext));
-    if (reportSummary)
-        writeMountRefreshSummary(refreshedStaleMounts, stderr, debug);
-    return refreshedStaleMounts;
-}
-async function ensureMountPath(mountFn, workspaceId, path, mountOpts, stderr) {
-    const resolved = resolve(path);
-    const statePath = join(resolved, '.integrations', '.relay', 'state.json');
+    const localDir = mount.getLocalMountRoot?.();
+    return ensureMountPath(mountFn, workspaceId, localDir ? dirname(localDir) : process.cwd(), mountOpts, stderr, localDir);
+}
+async function ensureMountPath(mountFn, workspaceId, path, mountOpts, stderr, localDir = join(resolve(path), '.integrations')) {
+    const statePath = join(localDir, '.relay', 'state.json');
     const staleBefore = checkMountStaleness(statePath, workspaceId, mountOpts.acceptableWorkspaceIds);
     try {
-        await mountFn(workspaceId, resolved, {
+        await mountFn(workspaceId, resolve(path), {
             ...mountOpts,
             ...(staleBefore.stale ? { suppressStaleRefreshLogs: true } : {}),
         });
         if (staleBefore.stale && !checkMountStaleness(statePath, workspaceId, mountOpts.acceptableWorkspaceIds).stale) {
-            return { path: resolved, reason: staleBefore.reason };
+            return { mounted: true, refreshed: { path: localDir, reason: staleBefore.reason } };
         }
+        return { mounted: true };
     }
     catch (error) {
+        // A scope shortfall is terminal and identical across every clone path;
+        // propagate it so startup fails fast with one remediation instead of
+        // logging the same unfixable warning per path.
+        if (error instanceof MountAuthScopeError)
+            throw error;
         const message = error instanceof Error ? error.message : String(error);
-        stderr.write(`[factory] warning: could not start relayfile mount at ${resolved}: ${message}\n`);
+        stderr.write(`[factory] warning: could not start Relayfile workspace mirror at ${localDir}: ${message}\n`);
     }
-    return undefined;
+    return { mounted: false };
+}
+function resolveIntegrationsMountRoot(mount) {
+    return mount.getLocalMountRoot?.() ?? resolve(process.cwd(), '.integrations');
+}
+async function factoryStatusWithMountHealth(factory, mount, heartbeatPath, heartbeatStaleMs) {
+    const status = factory.status();
+    const heartbeat = await readFactoryLoopHeartbeat(heartbeatPath);
+    const liveness = checkFactoryLoopLiveness(heartbeat, { staleMs: heartbeatStaleMs });
+    const eventListener = liveness.ok
+        ? heartbeat?.eventListener ?? {
+            state: 'unknown',
+            reason: 'running daemon heartbeat does not report event listener state',
+        }
+        : {
+            state: 'not-listening',
+            reason: liveness.reason,
+        };
+    const health = mount.getLocalMountHealth?.();
+    if (!health)
+        return { ...status, eventListener };
+    return {
+        ...status,
+        eventListener,
+        localMountDegraded: health.degraded,
+        ...(health.reason ? { localMountDegradedReason: health.reason } : {}),
+        ...(health.localDir ? { localMountRoot: health.localDir } : {}),
+        localMountEventFeed: {
+            state: health.degraded ? 'degraded' : 'healthy',
+            livenessSignal: '.integrations/.relay/state.json',
+            ...(health.reason ? { reason: health.reason } : {}),
+            ...(health.localDir ? { root: health.localDir } : {}),
+        },
+    };
 }
 function writeMountRefreshSummary(refreshedStaleMounts, stderr, debug) {
     if (debug) {
@@ -1018,9 +1176,28 @@ async function prepareFactoryIntegrations(command, mount, config, globals, deps,
     if (providers.length === 0)
         return;
     const dryRun = globals.dryRun || command.kind === 'factory-canary';
+    const providersToEnsure = [];
+    for (const provider of providers) {
+        const observation = observed.get(provider) ?? await inspectFactoryIntegration(connections, provider);
+        observed.set(provider, observation);
+        if (provider === 'github' &&
+            observation.kind === 'connected-not-ready' &&
+            mount.githubRead &&
+            (command.kind === 'factory-triage' || command.kind === 'factory-dispatch')) {
+            const details = [observation.state, observation.initialSyncState]
+                .filter((value) => Boolean(value))
+                .join(', ');
+            err.write(`[factory] warning: GitHub projection is not ready${details ? ` (${details})` : ''}; ` +
+                'targeted resolution remains projection-first and will use the GitHub API fallback only for a miss.\n');
+            continue;
+        }
+        providersToEnsure.push(provider);
+    }
+    if (providersToEnsure.length === 0)
+        return;
     await ensureFactoryIntegrations({
         connections,
-        providers,
+        providers: providersToEnsure,
         workspaceId,
         interactive: !dryRun && (deps.isInteractive?.() ?? Boolean(process.stdin.isTTY && process.stderr.isTTY)),
         dryRun,
@@ -1118,6 +1295,7 @@ async function buildMount(loaded, deps, observability = {}) {
     let mount;
     mount = await (deps.cloudMountFromConfig ?? RelayfileCloudMountClient.fromConfig)({
         workspaceId: loaded.config.workspaceId,
+        localMountRoot: loaded.config.localMountRoot,
         logger: observability.logger,
         onLocalMountHealth: observability.onLocalMountHealth,
         isAllowedDraft: (path, content, opts) => isAllowedFactoryDraft(path, content, opts, mount, loaded.config),
@@ -1170,19 +1348,52 @@ const scopeIssueFromDraftContent = (content) => ({
     raw: asRecord(content),
 });
 async function readIssueArg(mount, issueArg, config) {
-    const path = issueArg.startsWith('/') ? issueArg : await findIssuePath(mount, issueArg, config);
-    if (githubIssuePathParts(path)) {
-        return parseGithubFactoryIssue(path, (await mount.readFile(path)).content);
+    return (await resolveIssueArg(mount, issueArg, config)).issue;
+}
+async function resolveIssueArg(mount, issueArg, config, projectionStatus) {
+    const explicitPath = issueArg.startsWith('/');
+    const path = explicitPath ? issueArg : await findIssuePath(mount, issueArg, config);
+    if (path) {
+        const issue = githubIssuePathParts(path)
+            ? parseGithubFactoryIssue(path, (await mount.readFile(path)).content)
+            : await readLinearIssueWithCanonicalFallback(mount, path);
+        return {
+            issue,
+            resolution: {
+                source: 'relayfile-projection',
+                detail: 'Resolved from the preferred Relayfile projection.',
+                projection: { outcome: 'matched' },
+            },
+        };
     }
-    return readLinearIssueWithCanonicalFallback(mount, path);
+    const selector = parseGithubIssueSelector(issueArg, config);
+    const projection = projectionStatus
+        ? await projectionStatus()
+        : projectionStatusFromMount(mount);
+    const unavailableReason = githubProjectionUnavailableReason(projection);
+    if (!unavailableReason) {
+        throw new Error(`${githubIssueResolutionError(config, issueArg)}: found 0 matches in the healthy Relayfile projection; ` +
+            'the GitHub API fallback was not used');
+    }
+    const fallback = await findGithubIssueThroughConnection(mount, selector, config, issueArg);
+    if (!fallback) {
+        throw new Error(`${githubIssueResolutionError(config, issueArg)}: found 0 matches in the projection and GitHub API`);
+    }
+    return {
+        issue: parseGithubFactoryIssue(fallback.path, fallback.content),
+        resolution: {
+            source: 'github-api-fallback',
+            repo: fallback.repo,
+            detail: `Relayfile projection could not answer (${unavailableReason}); resolved authoritatively through the GitHub API fallback.`,
+            projection,
+        },
+    };
 }
 async function findIssuePath(mount, key, config) {
     if (config.issueSource === 'github') {
-        const number = Number(key.replace(/^#/, ''));
-        if (!Number.isInteger(number) || number <= 0) {
-            throw new Error(`${githubIssueResolutionError(config, key)}: expected a positive issue number`);
-        }
-        const configuredRepos = configuredGithubIssueRepos(config);
+        const selector = parseGithubIssueSelector(key, config);
+        const number = selector.number;
+        const configuredRepos = selector.repo ? [selector.repo] : configuredGithubIssueRepos(config);
         if (configuredRepos.length === 0 && hasConfiguredGithubIssueRoutes(config)) {
             throw new Error(`${githubIssueResolutionError(config, key)}: configured repository routes do not resolve to owner/repo; ` +
                 'set repos.default to owner/repo or map its label in repos.byLabel');
@@ -1206,7 +1417,7 @@ async function findIssuePath(mount, key, config) {
         })
             .sort((left, right) => githubIssuePathPreference(left) - githubIssuePathPreference(right) || left.localeCompare(right));
         if (matches.length === 0) {
-            throw new Error(`${githubIssueResolutionError(config, key)}: found 0 matches`);
+            return undefined;
         }
         const matchesByRepo = new Map();
         for (const path of matches) {
@@ -1232,14 +1443,106 @@ async function findIssuePath(mount, key, config) {
     }
     return matches[0];
 }
-function configuredGithubIssueRepos(config) {
-    const candidates = config.repos.default
-        ? [config.repos.default]
-        : [
-            ...Object.values(config.repos.byLabel),
-            ...Object.values(config.repos.byProject),
-            ...config.repos.keywordRules.map((rule) => rule.repo),
-        ];
+async function findGithubIssueThroughConnection(mount, selector, config, issueArg) {
+    const github = mount.githubRead;
+    if (!github) {
+        throw new Error(`${githubIssueResolutionError(config, issueArg)}: projection cannot answer and the GitHub API fallback is unavailable`);
+    }
+    const repos = selector.repo ? [selector.repo] : configuredGithubIssueRepos(config);
+    if (repos.length === 0) {
+        throw new Error(`${githubIssueResolutionError(config, issueArg)}: projection cannot answer and no configured owner/repo is available for the GitHub API fallback`);
+    }
+    const lookups = await Promise.all(repos.map((repo) => github.getIssue(repo, selector.number)));
+    const found = lookups.filter((lookup) => lookup.outcome === 'found');
+    const indeterminate = lookups.some((lookup) => lookup.outcome === 'indeterminate');
+    if (found.length === 0) {
+        if (indeterminate) {
+            throw new Error(`${githubIssueResolutionError(config, issueArg)}: the projection could not answer and the GitHub API fallback ` +
+                'could not determine whether the issue exists (one or more configured repositories are not visible without authentication)');
+        }
+        return undefined;
+    }
+    if (!selector.repo && !config.repos.default) {
+        if (found.length > 1) {
+            const matchedRepos = found.map((match) => match.issue.repo).sort((left, right) => left.localeCompare(right));
+            throw new Error(`${githubIssueResolutionError(config, issueArg)}: GitHub API matches multiple repositories (${matchedRepos.join(', ')}); ` +
+                'set repos.default or pass a repo-qualified argument');
+        }
+        if (indeterminate) {
+            // A single confirmed match is not the same as a unique one: at least
+            // one other configured repository could not be checked, so a same-
+            // numbered issue could exist there too. Refuse rather than silently
+            // dispatch to whichever repo happened to answer.
+            throw new Error(`${githubIssueResolutionError(config, issueArg)}: GitHub API found a match in ${found[0].issue.repo} but could not ` +
+                'confirm it is unique because one or more other configured repositories could not be checked without authentication; ' +
+                'set repos.default or pass a repo-qualified argument');
+        }
+    }
+    return found[0].issue;
+}
+async function issueProjectionStatus(factory, mount, config) {
+    const status = await factoryStatusWithMountHealth(factory, mount, config.loop.heartbeatPath, config.loop.heartbeatStaleMs);
+    const githubConnection = mount.integrationConnections
+        ? await mount.integrationConnections.getStatus('github')
+        : undefined;
+    return {
+        outcome: 'no-match',
+        ...(status.localMountDegraded !== undefined ? { localMountDegraded: status.localMountDegraded } : {}),
+        ...(status.localMountDegradedReason ? { localMountDegradedReason: status.localMountDegradedReason } : {}),
+        ...(status.eventListener ? { eventListener: status.eventListener } : {}),
+        ...(githubConnection ? { githubConnection } : {}),
+    };
+}
+function projectionStatusFromMount(mount) {
+    const health = mount.getLocalMountHealth?.();
+    return {
+        outcome: 'no-match',
+        ...(health ? { localMountDegraded: health.degraded } : {}),
+        ...(health?.reason ? { localMountDegradedReason: health.reason } : {}),
+    };
+}
+function githubProjectionUnavailableReason(projection) {
+    if (projection.githubConnection && !projection.githubConnection.ready) {
+        const detail = [projection.githubConnection.state, projection.githubConnection.initialSyncState]
+            .filter((value) => Boolean(value))
+            .join(', ');
+        return `GitHub projection connection is not ready${detail ? ` (${detail})` : ''}`;
+    }
+    if (projection.localMountDegraded) {
+        return projection.localMountDegradedReason ?? 'local mount is degraded';
+    }
+    if (projection.eventListener && !['subscribed', 'polling'].includes(projection.eventListener.state)) {
+        return projection.eventListener.reason ?? `event listener is ${projection.eventListener.state}`;
+    }
+    return undefined;
+}
+export function parseGithubIssueSelector(key, config) {
+    const qualified = key.match(/^([^#]+)#([1-9]\d*)$/u);
+    const bare = key.match(/^#?([1-9]\d*)$/u);
+    const number = Number(qualified?.[2] ?? bare?.[1]);
+    if (!Number.isSafeInteger(number) || number <= 0) {
+        throw new Error(`${githubIssueResolutionError(config, key)}: expected a positive issue number or repo-qualified reference (repo#number)`);
+    }
+    if (!qualified)
+        return { number };
+    const requested = qualified[1];
+    const configured = allConfiguredGithubIssueRepos(config);
+    // Resolve what the caller typed through the exact same canonicalization
+    // every configured route already goes through (label mapping, org
+    // prefixing, canonical-route lookup) instead of a second, ad-hoc
+    // expansion — three review rounds each found a different normalization
+    // gap (default-only, org-only, bare-label-vs-normalized) in a hand-rolled
+    // comparison here. Comparison is only ever normalized against normalized.
+    const [resolved] = resolveGithubIssueRepoCandidates(config, [requested]);
+    const repo = resolved
+        ? configured.find((candidate) => candidate.toLowerCase() === resolved.toLowerCase())
+        : undefined;
+    if (!repo) {
+        throw new Error(`${githubIssueResolutionError(config, key)}: repository ${requested} is not one of the configured Factory routes`);
+    }
+    return { number, repo };
+}
+function resolveGithubIssueRepoCandidates(config, candidates) {
     const repos = new Map();
     const routedRepos = [
         ...Object.values(config.repos.byLabel),
@@ -1260,6 +1563,30 @@ function configuredGithubIssueRepos(config) {
     }
     return [...repos.values()];
 }
+/** Bare-number resolution stays default-only: when repos.default is set, a
+ *  bare issue number resolves against that single repo, not every route. */
+function configuredGithubIssueRepos(config) {
+    const candidates = config.repos.default
+        ? [config.repos.default]
+        : [
+            ...Object.values(config.repos.byLabel),
+            ...Object.values(config.repos.byProject),
+            ...config.repos.keywordRules.map((rule) => rule.repo),
+        ];
+    return resolveGithubIssueRepoCandidates(config, candidates);
+}
+/** Qualified `repo#number` selectors must validate against every configured
+ *  route, not just repos.default — a route reachable only through byLabel,
+ *  byProject, or keywordRules is still a valid dispatch target. */
+function allConfiguredGithubIssueRepos(config) {
+    const candidates = [
+        ...(config.repos.default ? [config.repos.default] : []),
+        ...Object.values(config.repos.byLabel),
+        ...Object.values(config.repos.byProject),
+        ...config.repos.keywordRules.map((rule) => rule.repo),
+    ];
+    return resolveGithubIssueRepoCandidates(config, candidates);
+}
 function hasConfiguredGithubIssueRoutes(config) {
     return Boolean(config.repos.default ||
         Object.keys(config.repos.byLabel).length > 0 ||
@@ -1449,6 +1776,7 @@ Commands:
   babysit <PR|URL>      Shepherd an existing open PR to green
   close-probe <PR>      Probe/close a PR for an issue
   featuremap check      Validate .agentworkforce/features/manifest.yaml
+  intake notion <file>  Normalize mounted Notion specs into Factory work
   fleet <command>       Low-level fleet commands: spawn, roster, release
 
 Options: