@agent-relay/factory 0.1.18 → 0.1.20

package/README.md

@@ -116,6 +116,7 @@ From a source checkout instead of an npm install, run
 | `factory status` | Print current factory status as JSON. |
 | `factory triage <KEY\|path>` | Triage one issue and print the decision. |
 | `factory dispatch <KEY\|path>` | Triage + dispatch one issue. Honors `--dry-run`. |
+| `factory babysit <PR\|PR-URL>` | Spawn a one-shot babysitter for an existing open PR, even when it was not created by Factory. |
 | `factory canary <KEY\|path>` | Assert a known "Ready for Agent" issue is dispatch-ready by the real dry-run triage path. Prints `{ok,issue,status,reason}`; exits non-zero (with the skip reason) if it isn't. |
 
 Global options work anywhere in the args: `--config <path>`, `--dry-run`,
@@ -127,6 +128,15 @@ to 30 minutes and can also be set with `FACTORY_AGENT_EXIT_TIMEOUT_MS`.
 (There are a few more operational commands — `loop-status`, `kill-loop`,
 `reap-orphans`, `close-probe` — for running the daemon in production.)
 
+`factory babysit 10` uses `repos.default`; a full URL such as
+`factory babysit https://github.com/org/repo/pull/10` supplies the repository
+directly. The explicit command is opt-in on its own and does not require
+`babysitter.enabled`. It rejects closed, merged, and draft PRs, uses a linked
+issue spec when one can be resolved (otherwise the PR title/body), fixes the
+existing PR branch, and always leaves the final review and merge to a human.
+The command prints a spawn receipt and returns; the PR-keyed task-exit worker
+continues on the relay broker and reports completion or access blockers there.
+
 ### Scheduled sync-fidelity canary
 
 `factory canary` is the regression detector for upstream sync drift: if a synced
@@ -202,6 +212,23 @@ required capability (a named `node` target passes through), the node runs the
 agent in its mapped checkout, and the orchestrator detects exits by reconciling
 its tracked agents against the engine roster.
 
+Relay dispatch is lifecycle-owned, not fire-and-forget. A one-shot `factory
+dispatch --backend relay` keeps a small publisher runtime alive until the
+remote branch has produced a PR, terminal issue writeback is acknowledged, and
+remote agents are released. The lifecycle (including a per-run branch,
+placement results, PR receipt, and a fenced owner lease) is persisted beside
+the configured loop registry so `factory start` or a replacement dispatch
+process on the same control-plane host can take over after a crash. Execution
+nodes never need access to that state file, and remote PIDs are never signalled
+as local processes.
+
+The supported topology is one Factory control-plane host per workspace, with
+any number of relay execution nodes. Multiple Factory processes on that host
+are fenced through the shared `FileStateStore` lock/lease. Active/active Factory
+control planes on different hosts are intentionally unsupported: the current
+Relayfile and Relay messaging APIs do not expose a shared compare-and-set lease,
+so separate local state files cannot provide a truthful cross-host fence.
+
 Tokens involved — set only the first one on the orchestrator host:
 
 | Token | Prefix | Who holds it |
@@ -225,6 +252,31 @@ an invalid config fails fast with a field-level error. See
 and [`test/fixtures/factory.config.json`](test/fixtures/factory.config.json) for a
 worked example (including offline fixture mode).
 
+`cloneRoot` and every `clonePaths` value accept `~` or a leading `~/`, expanded
+against the current user's home directory. Named-user forms such as `~alice`
+are rejected because Node cannot expand them portably.
+
+For a local, single-repository run, the checkout mapping can be omitted:
+
+```json
+{
+  "repos": {
+    "org": "your-org",
+    "names": ["your-repo"],
+    "default": "your-org/your-repo"
+  }
+}
+```
+
+Run Factory from that repository (or one of its subdirectories). When exactly
+one `repos.names` entry is configured and no `cloneRoot` or `clonePaths` field is
+supplied, Factory resolves the checkout's git top-level and uses it only if a
+GitHub remote matches the resolved `org/name`. The inference is logged. Missing,
+unparseable, or mismatched remotes fail with a config-oriented error instead of
+silently dispatching in the wrong directory. Explicit local clone paths are also
+preflighted before commands that can dispatch through the internal backend;
+relay-backend paths are left for their worker nodes to validate.
+
 ## Notes
 
 - The daemon is headless by design; tools like Pear can consume this package and

package/dist/cli/fleet.d.ts

@@ -1,3 +1,4 @@
+import { type LocalClonePathOptions } from '../config/local-clone-paths.js';
 import { createFactory, createFleet, ensureRelayBroker, type Capability, type Factory, type FactoryConfig, type FleetBackend, type FleetClient, type GhRunner, type FactoryStateResolution, type MountClient, type ProbeCloser, type RelayfileCloudMountClientConfig, type ResolvedFactoryWorkspace } from '../index.js';
 interface FleetCliDeps {
     fleet?: FleetClient;
@@ -18,10 +19,13 @@ interface FleetCliDeps {
     stderr?: Pick<NodeJS.WriteStream, 'write'>;
     probeCloser?: ProbeCloser;
     probePrGhRunner?: GhRunner;
+    babysitPrGhRunner?: GhRunner;
     now?: () => number;
     stopSignalProcessLike?: Pick<NodeJS.Process, 'once' | 'off'>;
     daemonExit?: (code: number) => void;
     flushDaemonOutput?: () => Promise<void>;
+    /** Hermetic local-checkout probes for CLI integration tests. */
+    localClonePathOptions?: LocalClonePathOptions;
 }
 interface GlobalOptions {
     backend: FleetBackend;
@@ -62,6 +66,11 @@ type ParsedCommand = {
 } | {
     kind: 'factory-dispatch';
     issue: string;
+} | {
+    kind: 'factory-babysit';
+    prNumber: number;
+    repo?: string;
+    url?: string;
 } | {
     kind: 'factory-close-probe';
     prNumber: number;
@@ -74,6 +83,7 @@ export declare function parseGlobalOptions(argv: string[]): {
     globals: GlobalOptions;
     args: string[];
 };
+export declare function formatLogArgs(args: unknown[]): string;
 export declare function resolveBrokerConnectionPath(startCwd?: string): string | undefined;
 export declare function installFactoryStopSignalHandlers(factory: Factory, opts?: {
     exit?: (code: number) => void;

package/dist/cli/fleet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fleet.d.ts","sourceRoot":"","sources":["../../src/cli/fleet.ts"],"names":[],"mappings":"AAKA,OAAO,EAML,aAAa,EACb,WAAW,EACX,iBAAiB,EAcjB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,aAAa,EAElB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAE3B,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,+BAA+B,EACpC,KAAK,wBAAwB,EAC9B,MAAM,UAAU,CAAA;AAGjB,UAAU,YAAY;IACpB,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,aAAa,CAAC,EAAE,OAAO,aAAa,CAAA;IACpC,WAAW,CAAC,EAAE,OAAO,WAAW,CAAA;IAChC,iBAAiB,CAAC,EAAE,OAAO,iBAAiB,CAAA;IAC5C,oBAAoB,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,+BAA+B,KAAK,OAAO,CAAC,WAAW,CAAC,CAAA;IACzF,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,wBAAwB,CAAC,CAAA;IAC1D,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAA;IAC9F,gBAAgB,CAAC,EAAE,CACjB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QAAE,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,KACrD,OAAO,CAAC,IAAI,CAAC,CAAA;IAClB,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAChD,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;IAC1C,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;IAC1C,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,eAAe,CAAC,EAAE,QAAQ,CAAA;IAC1B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,qBAAqB,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC,CAAA;IAC5D,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACnC,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CACxC;AAED,UAAU,aAAa;IACrB,OAAO,EAAE,YAAY,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAOD,KAAK,aAAa,GACd;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE;QAAE,UAAU,EAAE,UAAU,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC7J;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,GAAG,cAAc,CAAA;CAAE,GAC1G;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAElF,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuH1F;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAe/D;AAyCD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CA8B7F;AA0SD,wBAAgB,2BAA2B,CAAC,QAAQ,SAAgB,GAAG,MAAM,GAAG,SAAS,CAaxF;AAyND,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,OAAO,EAChB,IAAI,GAAE;IACJ,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7B,WAAW,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC,CAAA;CAC9C,GACL,MAAM,IAAI,CA4BZ;AAoDD,wBAAsB,IAAI,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtE"}
+{"version":3,"file":"fleet.d.ts","sourceRoot":"","sources":["../../src/cli/fleet.ts"],"names":[],"mappings":"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"}

package/dist/cli/fleet.js

@@ -1,9 +1,12 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
+import { stringifyLogValue } from '../logging.js';
 import { ensureLocalMount } from '../mount/local-mount-preflight.js';
-import { FactoryConfigSchema, FileStateStore, RelayfileCloudMountClient, checkFactoryLoopLiveness, closeProbePr, createFactory, createFleet, ensureRelayBroker, defaultGhRunner, githubIssuePathParts, githubWatchStatePath, isInFactoryScope, parseGithubFactoryIssue, parseOwnedBrokerAgentExitTimeoutMs, readLinearIssueWithCanonicalFallback, reapFactoryOrphansOnce, readFactoryLoopHeartbeat, resolveFactoryStates, stateResolutionFromIds, resolveFactoryWorkspace, } from '../index.js';
+import { resolveLocalFactoryConfig } from '../config/local-clone-paths.js';
+import { FileStateStore, RelayfileCloudMountClient, checkFactoryLoopLiveness, closeProbePr, createFactory, createFleet, ensureRelayBroker, defaultGhRunner, explicitLinkedIssueKey, githubIssuePathParts, githubWatchStatePath, isInFactoryScope, parseGithubFactoryIssue, parseOwnedBrokerAgentExitTimeoutMs, parseStandaloneBabysitTarget, readStandalonePullRequest, readLinearIssueWithCanonicalFallback, reapFactoryOrphansOnce, readFactoryLoopHeartbeat, resolveFactoryStates, stateResolutionFromIds, standaloneBabysitterAgentName, renderAgentTask, resolveFactoryWorkspace, } from '../index.js';
 import { FakeFleetClient, FakeMountClient } from '../testing/index.js';
+const autoDetectedIssueSources = new WeakSet();
 export async function runFleetCli(argv, deps = {}) {
     const out = deps.stdout ?? process.stdout;
     const err = deps.stderr ?? process.stderr;
@@ -33,7 +36,15 @@ export async function runFleetCli(argv, deps = {}) {
             writeJson(out, result);
             return 0;
         }
-        const loaded = command.kind.startsWith('factory') ? await loadConfig(globals.config) : undefined;
+        const resolvesLocalClonePaths = globals.backend === 'internal' && commandUsesLocalCheckout(command);
+        const loaded = command.kind.startsWith('factory')
+            ? await loadConfig(globals.config, {
+                ...deps.localClonePathOptions,
+                inferFromCwd: resolvesLocalClonePaths,
+                logger: streamLogger(err),
+                validateConfiguredCheckouts: resolvesLocalClonePaths && (deps.localClonePathOptions?.validateConfiguredCheckouts ?? !hasInjectedFactoryRuntime(deps)),
+            })
+            : undefined;
         fleet = await buildFleet(globals, loaded, deps);
         switch (command.kind) {
             case 'spawn': {
@@ -67,7 +78,8 @@ export async function runFleetCli(argv, deps = {}) {
             case 'factory':
             case 'factory-canary':
             case 'factory-triage':
-            case 'factory-dispatch': {
+            case 'factory-dispatch':
+            case 'factory-babysit': {
                 if (!loaded)
                     throw new Error('factory command requires config');
                 if (command.kind === 'factory' && command.action === 'reap-orphans') {
@@ -94,6 +106,9 @@ export async function runFleetCli(argv, deps = {}) {
                 if (!workspaceId)
                     throw new Error('factory command could not resolve a workspaceId');
                 const mount = await buildMount(loaded, deps);
+                if (command.kind === 'factory-babysit') {
+                    return await runStandaloneBabysitCommand(command, mount, fleet, loaded.config, globals, out, deps, workspaceId, acceptableMountIds);
+                }
                 // Resolve Linear workflow states only when Linear is the issue source.
                 // A GitHub-only workspace has no /linear/states catalog and uses labels
                 // for lifecycle state, so it must not depend on that provider at startup.
@@ -304,9 +319,160 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
         writeJson(out, decision);
         return 0;
     }
+    if (command.kind === 'factory-dispatch' && globals.backend === 'relay' && !globals.dryRun) {
+        // A relay dispatch is not placement-only. This process becomes the durable
+        // lifecycle publisher (or attaches to the current owner's durable row),
+        // and stays through takeover/publication/writeback/release to terminal.
+        await factory.start({ mode: 'dispatch-owner' });
+        try {
+            const result = await factory.dispatch(decision, { dryRun: false });
+            writeJson(out, result);
+            await factory.waitForDispatchTerminal(result.issue);
+            return 0;
+        }
+        finally {
+            await factory.stop();
+        }
+    }
     writeJson(out, await factory.dispatch(decision, { dryRun: globals.dryRun }));
     return 0;
 }
+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 = deps.ensureLocalMount ?? ensureLocalMount;
+    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);
+    }
+    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') {
+        throw new Error(`factory babysit requires an open PR; ${repo} PR #${pr.number} is merged`);
+    }
+    if (state !== 'OPEN') {
+        throw new Error(`factory babysit requires an open PR; ${repo} PR #${pr.number} state is ${state ?? 'UNKNOWN'}`);
+    }
+    if (pr.draft) {
+        throw new Error(`factory babysit skips draft PRs; ${repo} PR #${pr.number} is a draft`);
+    }
+    if (pr.crossRepository) {
+        throw new Error(`factory babysit refuses cross-repository PRs by default; ${repo} PR #${pr.number} head is ${pr.headRepo ?? 'unknown'}`);
+    }
+    const linkedIssueKey = explicitLinkedIssueKey(pr.body);
+    let issue = {
+        key: `${repo}#${pr.number}`,
+        title: pr.title,
+        description: pr.body || '(No PR description was provided.)',
+    };
+    let specSource = 'pull-request';
+    if (linkedIssueKey) {
+        try {
+            const linked = await readIssueArg(mount, linkedIssueKey, config);
+            issue = {
+                key: linked.key,
+                title: linked.title,
+                description: linked.description,
+            };
+            specSource = 'linked-issue';
+        }
+        catch {
+            // The PR remains independently babysittable when its referenced issue is
+            // not connected to this workspace. Its own title/body become the spec.
+        }
+    }
+    const agentName = standaloneBabysitterAgentName(repo, pr.number);
+    const task = renderAgentTask({
+        issue,
+        route: { repo, clonePath },
+        role: 'babysitter',
+        config: { mergePolicy: config.mergePolicy, terminalState: config.terminalState },
+        reviewerName: '',
+        pr: {
+            number: pr.number,
+            url: pr.url,
+            headRef: pr.headRef,
+            headSha: pr.headSha,
+            baseRef: pr.baseRef,
+            headRepo: pr.headRepo,
+            crossRepository: pr.crossRepository,
+            maintainerCanModify: pr.maintainerCanModify,
+        },
+        standaloneBabysitter: { specSource },
+        integrationsMountRoot: resolve(process.cwd(), '.integrations'),
+    });
+    const receiptBase = {
+        agent: agentName,
+        repo,
+        prNumber: pr.number,
+        url: pr.url,
+        source: pr.source,
+        specSource,
+        ...(specSource === 'linked-issue' ? { linkedIssue: issue.key } : {}),
+    };
+    if (globals.dryRun) {
+        writeJson(out, { status: 'dry-run', ...receiptBase });
+        return 0;
+    }
+    const roster = await fleet.roster();
+    if (roster.agents.some((agent) => agent.name === agentName)) {
+        writeJson(out, { status: 'already-running', ...receiptBase });
+        return 0;
+    }
+    const spawned = await fleet.spawn({
+        name: agentName,
+        capability: config.agentCapabilities.babysitter,
+        node: 'self',
+        repo,
+        clonePath,
+        task,
+        model: config.models.babysitter,
+        cwd: clonePath,
+        invocationId: `factory-babysit:${repo}#${pr.number}`,
+    });
+    fleet.preserveInfrastructureOnDispose?.();
+    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) {
+        throw new Error('factory babysit <PR-number> requires repos.default; pass a full GitHub PR URL instead');
+    }
+    if (configured.includes('/'))
+        return configured;
+    const exactRoute = config.repos.byLabel[configured];
+    if (exactRoute)
+        return exactRoute;
+    const routed = [...new Set(Object.values(config.repos.byLabel).filter((candidate) => candidate === configured || candidate.endsWith(`/${configured}`)))];
+    if (routed.length === 1)
+        return routed[0];
+    if (routed.length > 1) {
+        throw new Error(`Unable to resolve repository ${configured}: matches multiple configured repos (${routed.sort().join(', ')}); ` +
+            'set repos.default to owner/repo or pass a full GitHub PR URL instead');
+    }
+    if (config.repos.org)
+        return `${config.repos.org}/${configured}`;
+    throw new Error(`Unable to resolve repository ${configured} to owner/repo; pass a full GitHub PR URL instead`);
+}
+function standaloneBabysitClonePath(repo, config) {
+    const configured = Object.entries(config.clonePaths ?? {}).find(([candidate]) => candidate.toLowerCase() === repo.toLowerCase())?.[1]
+        ?? Object.entries(config.repos.clonePaths ?? {}).find(([candidate]) => candidate.toLowerCase() === repo.toLowerCase())?.[1];
+    if (configured && existsSync(configured))
+        return configured;
+    return undefined;
+}
 /**
  * Ensures the relayfile mount is running at each configured clone path so
  * spawned agents can resolve `.integrations` relative to their working
@@ -354,6 +520,11 @@ function parseFactoryCommand(args) {
             throw new Error('factory dispatch requires an issue key or path');
         return { kind: 'factory-dispatch', issue: issueOrPr };
     }
+    if (action === 'babysit') {
+        if (flags.length > 0)
+            throw new Error(`Unexpected argument ${flags[0]}`);
+        return { kind: 'factory-babysit', ...parseStandaloneBabysitTarget(issueOrPr) };
+    }
     if (action === 'close-probe') {
         const prNumber = Number(issueOrPr);
         if (!Number.isInteger(prNumber) || prNumber <= 0)
@@ -416,15 +587,36 @@ function parseFactoryStartFlags(args) {
     }
     return { mode };
 }
-async function loadConfig(path) {
+async function loadConfig(path, options = {}) {
     const configPath = path ?? resolve(process.cwd(), 'factory.config.json');
     const raw = JSON.parse(await readFile(configPath, 'utf8'));
     const record = asRecord(raw);
     return {
-        config: FactoryConfigSchema.parse(record.factoryConfig ?? record),
+        config: await resolveLocalFactoryConfig(raw, {
+            ...options,
+            // fixtureFiles describe a hermetic in-memory run; their checkout paths
+            // are intentionally synthetic and must not be preflighted on the host.
+            validateConfiguredCheckouts: options.validateConfiguredCheckouts && !record.fixtureFiles,
+        }),
         fixtureFiles: record.fixtureFiles ? asRecord(record.fixtureFiles) : undefined,
     };
 }
+function commandUsesLocalCheckout(command) {
+    switch (command.kind) {
+        case 'factory':
+            return command.action === 'run-once' || command.action === 'loop' || command.action === 'start';
+        case 'factory-canary':
+        case 'factory-triage':
+        case 'factory-dispatch':
+        case 'factory-babysit':
+            return true;
+        default:
+            return false;
+    }
+}
+function hasInjectedFactoryRuntime(deps) {
+    return Boolean(deps.fleet || deps.mount || deps.createFactory || deps.createFleet || deps.cloudMountFromConfig);
+}
 async function buildFleet(globals, loaded, deps) {
     if (deps.fleet)
         return deps.fleet;
@@ -466,15 +658,10 @@ function streamLogger(stream) {
         error: (message, ...args) => write(message, args),
     };
 }
-function formatLogArgs(args) {
+export function formatLogArgs(args) {
     if (args.length === 0)
         return '';
-    try {
-        return ` ${args.map((arg) => (typeof arg === 'string' ? arg : JSON.stringify(arg))).join(' ')}`;
-    }
-    catch {
-        return '';
-    }
+    return ` ${args.map((arg) => (typeof arg === 'string' ? arg : stringifyLogValue(arg))).join(' ')}`;
 }
 export function resolveBrokerConnectionPath(startCwd = process.cwd()) {
     let current = resolve(startCwd);
@@ -503,15 +690,37 @@ async function resolveStatesForIssueSource(mount, config, resolveStates) {
         return stateResolutionFromIds(config.stateIds, config.linear.states);
     }
     if (!config.issueSource) {
-        const linearReady = await mount.ensureSubRoot('/linear/issues', { timeoutMs: 90_000 });
-        if (linearReady !== 'ready') {
+        autoDetectedIssueSources.add(config);
+        if (shouldAutoDetectGithubSource(config)) {
             config.issueSource = 'github';
             return stateResolutionFromIds(config.stateIds, config.linear.states);
         }
-        config.issueSource = 'linear';
+        const linearReady = await mount.ensureSubRoot('/linear/issues', { timeoutMs: 90_000 });
+        config.issueSource = linearReady === 'ready' ? 'linear' : 'github';
+        if (config.issueSource === 'github') {
+            return stateResolutionFromIds(config.stateIds, config.linear.states);
+        }
     }
     return (resolveStates ?? defaultResolveStates)(mount, config);
 }
+function shouldAutoDetectGithubSource(config) {
+    if (!config.repos.org || configuredGithubIssueRepos(config).length === 0)
+        return false;
+    return Object.keys(config.stateIds).length === 0 &&
+        hasDefaultLinearStateNames(config.linear.states) &&
+        Object.keys(config.linear.statesByTeam).length === 0 &&
+        Object.keys(config.linear.teamIds).length === 0 &&
+        config.subscription.teams.length === 0 &&
+        config.subscription.projects.length === 0 &&
+        config.subscription.assignees.length === 0;
+}
+function hasDefaultLinearStateNames(states) {
+    return states.readyForAgent === 'Ready for Agent' &&
+        states.agentImplementing === 'Agent Implementing' &&
+        states.inPlanning === 'In Planning' &&
+        states.done === 'Done' &&
+        states.humanReview === 'In Human Review';
+}
 async function buildMount(loaded, deps) {
     if (deps.mount)
         return deps.mount;
@@ -580,20 +789,33 @@ async function findIssuePath(mount, key, config) {
     if (config.issueSource === 'github') {
         const number = Number(key.replace(/^#/, ''));
         if (!Number.isInteger(number) || number <= 0) {
-            throw new Error(`Unable to resolve GitHub issue ${key}: expected a positive issue number`);
+            throw new Error(`${githubIssueResolutionError(config, key)}: expected a positive issue number`);
+        }
+        const configuredRepos = 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');
+        }
+        if (configuredRepos.length === 1) {
+            const directPath = await findDirectGithubIssuePath(mount, configuredRepos[0], number);
+            if (directPath)
+                return directPath;
         }
-        const defaultRepo = config.repos.default?.toLowerCase();
-        const matches = (await mount.listTree('/github/repos'))
+        const roots = configuredRepos.length > 0
+            ? configuredRepos.flatMap(githubIssueRoots)
+            : ['/github/repos'];
+        const matches = (await Promise.all([...new Set(roots)].map((root) => mount.listTree(root))))
+            .flat()
             .filter((path) => path.endsWith('.json'))
             .filter((path) => {
             const parts = githubIssuePathParts(path);
             if (!parts || parts.number !== number)
                 return false;
-            return !defaultRepo || `${parts.owner}/${parts.repo}`.toLowerCase() === defaultRepo;
+            return configuredRepos.length === 0 || configuredRepos.some((repo) => repo.toLowerCase() === `${parts.owner}/${parts.repo}`.toLowerCase());
         })
             .sort((left, right) => githubIssuePathPreference(left) - githubIssuePathPreference(right) || left.localeCompare(right));
         if (matches.length === 0) {
-            throw new Error(`Unable to resolve GitHub issue ${key}: found 0 matches`);
+            throw new Error(`${githubIssueResolutionError(config, key)}: found 0 matches`);
         }
         const matchesByRepo = new Map();
         for (const path of matches) {
@@ -603,9 +825,9 @@ async function findIssuePath(mount, key, config) {
                 matchesByRepo.set(repo.toLowerCase(), { repo, path });
             }
         }
-        if (!defaultRepo && matchesByRepo.size > 1) {
+        if (!config.repos.default && matchesByRepo.size > 1) {
             const repos = [...matchesByRepo.values()].map((match) => match.repo).sort((left, right) => left.localeCompare(right));
-            throw new Error(`Unable to resolve GitHub issue ${key}: matches multiple repositories (${repos.join(', ')}); ` +
+            throw new Error(`${githubIssueResolutionError(config, key)}: matches multiple repositories (${repos.join(', ')}); ` +
                 'set repos.default or pass a repo-qualified argument');
         }
         return matchesByRepo.values().next().value.path;
@@ -613,10 +835,96 @@ async function findIssuePath(mount, key, config) {
     const matches = (await mount.listTree('/linear/issues/'))
         .filter((path) => path.startsWith(`/linear/issues/${key}__`) || path === `/linear/issues/${key}.json`);
     if (matches.length !== 1) {
-        throw new Error(`Unable to resolve issue ${key}: found ${matches.length} matches`);
+        const detected = autoDetectedIssueSources.has(config) ? ', auto-detected' : '';
+        throw new Error(`Unable to resolve issue ${key} in Linear (issueSource=linear${detected}): found ${matches.length} matches; ` +
+            `set issueSource: 'github' if these are GitHub issues`);
     }
     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),
+        ];
+    const repos = new Map();
+    const routedRepos = [
+        ...Object.values(config.repos.byLabel),
+        ...Object.values(config.repos.byProject),
+        ...config.repos.keywordRules.map((rule) => rule.repo),
+    ];
+    for (const candidate of candidates) {
+        const mapped = Object.entries(config.repos.byLabel).find(([label]) => label.toLowerCase() === candidate.toLowerCase())?.[1];
+        const canonicalRoute = routedRepos.find((route) => route.includes('/') && route.toLowerCase() === candidate.toLowerCase());
+        const repo = candidate.includes('/')
+            ? canonicalRoute ?? candidate
+            : mapped?.includes('/')
+                ? mapped
+                : config.repos.org ? `${config.repos.org}/${mapped ?? candidate}` : undefined;
+        if (!repo || !/^[^/]+\/[^/]+$/u.test(repo))
+            continue;
+        repos.set(repo.toLowerCase(), repo);
+    }
+    return [...repos.values()];
+}
+function hasConfiguredGithubIssueRoutes(config) {
+    return Boolean(config.repos.default ||
+        Object.keys(config.repos.byLabel).length > 0 ||
+        Object.keys(config.repos.byProject).length > 0 ||
+        config.repos.keywordRules.length > 0);
+}
+async function findDirectGithubIssuePath(mount, repo, number) {
+    for (const path of githubIssueDirectPaths(repo, number)) {
+        try {
+            await mount.readFile(path);
+            return path;
+        }
+        catch (error) {
+            if (!isMountFileNotFound(error)) {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`Unable to read GitHub issue candidate ${path}: ${message}`, { cause: error });
+            }
+            // Direct reads are an optimization. A scoped tree scan below handles
+            // slugged directories and older mount shapes when these paths are absent.
+        }
+    }
+    return undefined;
+}
+function isMountFileNotFound(error) {
+    const record = asRecord(error);
+    const response = asRecord(record.response);
+    const status = record.status ?? record.statusCode ?? response.status ?? response.statusCode;
+    const code = typeof record.code === 'string' ? record.code.toLowerCase() : undefined;
+    const message = error instanceof Error ? error.message : String(error);
+    return status === 404 || status === '404' ||
+        code === 'not_found' || code === 'file_not_found' ||
+        /(?:file\s+not\s+found|\b404\b)/iu.test(message);
+}
+function githubIssueDirectPaths(repo, number) {
+    const [owner, name] = repo.split('/');
+    const roots = [
+        `/github/repos/${owner}__${name}/issues`,
+        `/github/repos/${owner}/${name}/issues`,
+    ];
+    return [
+        ...roots.map((root) => `${root}/${number}/meta.json`),
+        ...roots.map((root) => `${root}/by-id/${number}.json`),
+        ...roots.map((root) => `${root}/${number}.json`),
+    ];
+}
+function githubIssueRoots(repo) {
+    const [owner, name] = repo.split('/');
+    return [
+        `/github/repos/${owner}__${name}/issues`,
+        `/github/repos/${owner}/${name}/issues`,
+    ];
+}
+function githubIssueResolutionError(config, key) {
+    const detected = autoDetectedIssueSources.has(config) ? ', auto-detected' : '';
+    return `Unable to resolve GitHub issue ${key} (issueSource=github${detected})`;
+}
 const githubIssuePathPreference = (path) => path.endsWith('/meta.json') ? 0 : path.includes('/by-id/') ? 1 : 2;
 function parseFlags(args) {
     const flags = {};
@@ -666,6 +974,7 @@ function isFactoryAction(value) {
         value === 'canary' ||
         value === 'triage' ||
         value === 'dispatch' ||
+        value === 'babysit' ||
         value === 'close-probe';
 }
 function defaultAgentName(capability, now) {
@@ -730,6 +1039,7 @@ Commands:
   canary <KEY|path>     Check that a known issue is dispatch-ready
   triage <KEY|path>     Triage one issue and print the decision
   dispatch <KEY|path>   Triage and dispatch one issue
+  babysit <PR|URL>      Shepherd an existing open PR to green
   close-probe <PR>      Probe/close a PR for an issue
   fleet <command>       Low-level fleet commands: spawn, roster, release