@agent-relay/factory 0.1.60 → 0.1.63

package/dist/cli/fleet.js

@@ -1,13 +1,14 @@
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import readline from 'node:readline/promises';
 import { ensureCloudSession } from '@agent-relay/cloud';
 import { stringifyLogValue } from '../logging.js';
 import { resolveLocalFactoryConfig } from '../config/local-clone-paths.js';
 import { initializeFactory } from './init.js';
-import { FileStateStore, RelayfileCloudMountClient, checkFactoryLoopLiveness, closeProbePr, createFactory, createFleet, createFactoryCloudEventV1, ensureRelayBroker, FactoryCloudReporter, FileFactoryCloudEventOutbox, defaultGhRunner, explicitLinkedIssueKey, githubIssuePathParts, githubWatchStatePath, isInFactoryScope, parseGithubFactoryIssue, publishFactoryMountHealth, parseOwnedBrokerAgentExitTimeoutMs, parseStandaloneBabysitTarget, readStandalonePullRequest, readLinearIssueWithCanonicalFallback, reapFactoryOrphansOnce, reapFactoryEnvironmentsOnce, readFactoryLoopHeartbeat, readFactoryInFlightRegistry, resolveFactoryStates, stateResolutionFromIds, standaloneBabysitterAgentName, renderAgentTask, resolveFactoryWorkspace, } from '../index.js';
+import { FACTORY_EXIT, exitCodeForDispatchResult, exitCodeForError, exitCodeForIterationReport, exitCodeForLoopReports, exitCodeForRelayDispatch, } from './exit-codes.js';
+import { FileStateStore, RelayfileCloudMountClient, checkFactoryLoopLiveness, closeProbePr, createFactory, createFleet, createFactoryCloudEventV1, ensureRelayBroker, FactoryCloudReporter, FileFactoryCloudEventOutbox, defaultGhRunner, explicitLinkedIssueKey, githubIssuePathParts, githubWatchStatePath, isAllowedFactoryGithubDraft, isAllowedFactoryGithubArtifactDraft, isInFactoryScope, parseGithubFactoryIssue, publishFactoryMountHealth, heldAgentsFromRegistry, parseOwnedBrokerAgentExitTimeoutMs, parseStandaloneBabysitTarget, readStandalonePullRequest, readLinearIssueWithCanonicalFallback, reapFactoryOrphansOnce, reapFactoryEnvironmentsOnce, readFactoryInFlightRegistry, readFactoryLoopHeartbeat, resolveFactoryStates, stateResolutionFromIds, standaloneBabysitterAgentName, renderAgentTask, resolveFactoryWorkspace, } from '../index.js';
 import { resolveTestGuidance } from '../dispatch/test-guidance.js';
 import { FakeFleetClient, FakeMountClient } from '../testing/index.js';
 import { GitAgentWorktreeManager } from '../git/agent-worktree.js';
@@ -18,7 +19,7 @@ import { checkMountStaleness } from '../mount/relayfile-binary.js';
 import { MountAuthScopeError } from '../mount/mount-auth-error.js';
 import { resolveRelayWorkspaceKey } from '../fleet/relay-workspace-key.js';
 import { isMeaningfullyBehind, readFactoryVersionInfo, } from '../version-info.js';
-import { GhCliIssuePublisher, RelayChannelNotionClaimStore, RelayChannelNotionContractPublisher, loadNotionIntakeManifest, runNotionIntake, } from '../intake/index.js';
+import { GhCliIssuePublisher, NotionApiFactoryTasksClient, RelayChannelNotionClaimStore, RelayChannelNotionContractPublisher, generateFactoryTasksManifest, loadNotionIntakeManifest, runNotionIntake, } from '../intake/index.js';
 const autoDetectedIssueSources = new WeakSet();
 export async function runFleetCli(argv, deps = {}) {
     const out = deps.stdout ?? process.stdout;
@@ -51,6 +52,23 @@ export async function runFleetCli(argv, deps = {}) {
             await initializeFactory({ repo: command.repo, workspaceId: command.workspaceId, stdout: out, stderr: err });
             return 0;
         }
+        if (command.kind === 'notion-manifest') {
+            const notion = deps.notionFactoryTasks ?? new NotionApiFactoryTasksClient({
+                token: (deps.env ?? process.env).NOTION_API_KEY ?? '',
+            });
+            const manifest = await generateFactoryTasksManifest({
+                client: notion,
+                ...(command.dataSourceId ? { dataSourceId: command.dataSourceId } : {}),
+                ...(command.mountRoot ? { mountRoot: command.mountRoot } : {}),
+                ...(command.workerMountRoot ? { workerMountRoot: command.workerMountRoot } : {}),
+                ...(command.workerMountTransport
+                    ? { workerMountTransport: command.workerMountTransport }
+                    : {}),
+                ...(command.statePath ? { statePath: command.statePath } : {}),
+            });
+            writeJson(out, manifest);
+            return 0;
+        }
         if (command.kind === 'notion-intake') {
             const manifest = await loadNotionIntakeManifest(command.manifestPath);
             if (!globals.dryRun) {
@@ -133,7 +151,7 @@ export async function runFleetCli(argv, deps = {}) {
                 const workspaceId = (await (deps.resolveWorkspace ?? resolveFactoryWorkspace)()).workspaceId;
                 mount = deps.mount ?? await (deps.cloudMountFromConfig ?? RelayfileCloudMountClient.fromConfig)({
                     workspaceId,
-                    isAllowedDraft: (path, _content, opts) => isAllowedFactoryGithubDraft(path, opts),
+                    isAllowedDraft: (path, _content, opts) => isAllowedFactoryGithubArtifactDraft(path, opts),
                 });
                 await prepareFactoryIntegrations(command, mount, undefined, globals, deps, workspaceId, err);
                 githubWrite = mount.githubWrite;
@@ -201,8 +219,13 @@ export async function runFleetCli(argv, deps = {}) {
                         registryPath: loaded.config.loop.registryPath,
                         staleMs: loaded.config.loop.heartbeatStaleMs,
                         fleet,
+                        includeHeld: command.includeHeld,
+                        logger: streamLogger(err),
+                    });
+                    writeJson(out, {
+                        ...processes,
+                        environments: await safeEnvironmentReap(Boolean(loaded.config.environments.kubernetes), deps.reapEnvironments),
                     });
-                    writeJson(out, { ...processes, environments: await safeEnvironmentReap(deps.reapEnvironments) });
                     return 0;
                 }
                 // Derive the workspace from the cloud session when it isn't pinned in
@@ -259,10 +282,17 @@ export async function runFleetCli(argv, deps = {}) {
                 // 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.
                 const stateResolution = await resolveStatesForIssueSource(mount, loaded.config, deps.resolveStates);
-                const stateStore = new FileStateStore({
-                    batchSize: loaded.config.batchSize,
-                    watchStatePath: githubWatchStatePath(loaded.config.loop.registryPath),
-                });
+                const stateStore = deps.stateStoreFactory
+                    ? await deps.stateStoreFactory(loaded.config)
+                    : new FileStateStore({
+                        batchSize: loaded.config.batchSize,
+                        watchStatePath: githubWatchStatePath(loaded.config.loop.registryPath),
+                    });
+                // An injected backend is an explicit dispatch-admission dependency.
+                // It must prove readiness before Factory construction; a host adapter
+                // may never turn an unreadable durable store into an empty document.
+                if (deps.stateStoreFactory)
+                    await stateStore.assertReady();
                 reporter = deps.reporter ?? await buildFactoryCloudReporter({
                     config: loaded.config,
                     backend: globals.backend,
@@ -294,7 +324,7 @@ export async function runFleetCli(argv, deps = {}) {
                     reporter,
                     worktrees: globals.backend === 'internal' ? new GitAgentWorktreeManager() : undefined,
                 });
-                return await runFactoryCommand(command, factory, mount, fleet, loaded.config, globals, out, deps, workspaceId, acceptableMountIds);
+                return await runFactoryCommand(command, factory, mount, fleet, loaded.config, globals, out, deps, workspaceId, acceptableMountIds, stateStore.backend ? { backend: stateStore.backend } : undefined);
             }
         }
         return 1;
@@ -314,7 +344,7 @@ export async function runFleetCli(argv, deps = {}) {
             }
         }
         err.write(`${error instanceof Error ? error.message : String(error)}\n`);
-        return 1;
+        return exitCodeForError(error);
     }
     finally {
         try {
@@ -388,6 +418,32 @@ function parseIntakeCommand(args) {
     const [source, manifestPath, ...rest] = args;
     if (source !== 'notion')
         throw new Error('factory intake currently requires the notion source');
+    if (manifestPath === 'generate') {
+        const parsed = parseFlags(rest);
+        const allowed = new Set([
+            'data-source',
+            'mount-root',
+            'worker-mount-root',
+            'worker-mount-transport',
+            'state-path',
+        ]);
+        const unexpected = Object.keys(parsed).find((key) => !allowed.has(key));
+        if (unexpected)
+            throw new Error(`Unknown Factory Tasks manifest option: --${unexpected}`);
+        const workerMountTransport = parsed['worker-mount-transport'];
+        if (workerMountTransport !== undefined &&
+            workerMountTransport !== 'local' && workerMountTransport !== 'relay-channel') {
+            throw new Error('--worker-mount-transport must be local or relay-channel');
+        }
+        return {
+            kind: 'notion-manifest',
+            ...(parsed['data-source'] ? { dataSourceId: parsed['data-source'] } : {}),
+            ...(parsed['mount-root'] ? { mountRoot: parsed['mount-root'] } : {}),
+            ...(parsed['worker-mount-root'] ? { workerMountRoot: parsed['worker-mount-root'] } : {}),
+            ...(workerMountTransport ? { workerMountTransport } : {}),
+            ...(parsed['state-path'] ? { statePath: parsed['state-path'] } : {}),
+        };
+    }
     if (!manifestPath)
         throw new Error('factory intake notion requires a manifest path');
     if (rest.length > 0)
@@ -484,7 +540,7 @@ export function parseGlobalOptions(argv) {
     }
     return { globals, args };
 }
-async function runFactoryCommand(command, factory, mount, fleet, config, globals, out, deps = {}, workspaceId = config.workspaceId ?? '', acceptableMountIds) {
+async function runFactoryCommand(command, factory, mount, fleet, config, globals, out, deps = {}, workspaceId = config.workspaceId ?? '', acceptableMountIds, stateStoreStatus) {
     const mountFn = resolveLocalMountFn(deps, mount);
     const mountStderr = deps.stderr ?? process.stderr;
     const debugMountRefreshes = (deps.env ?? process.env).FACTORY_LOG_LEVEL?.toLowerCase() === 'debug';
@@ -523,15 +579,20 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
             // 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);
+            // Returns the code the failure classifies to, so the inline branch below
+            // can surface it directly. The background branch reads the same value
+            // back off the waiter; both must report one code for one failure.
             const handleWarmMountError = (error) => {
                 if (error instanceof MountAuthScopeError) {
+                    const code = exitCodeForError(error);
                     mountStderr.write(`${error.message}\n`);
                     mountStderr.write('[factory] aborting startup: local mount cannot obtain its filesystem scopes.\n');
-                    void flushAndResolve(1);
-                    return;
+                    void flushAndResolve(code);
+                    return code;
                 }
                 const message = error instanceof Error ? error.message : String(error);
                 mountStderr.write(`[factory] warning: background relayfile mount warmup failed: ${message}\n`);
+                return FACTORY_EXIT.FAILED;
             };
             const removeSignalHandlers = installFactoryStopSignalHandlers(factory, {
                 exit: (code) => {
@@ -551,14 +612,14 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
                             mountStderr.write('[factory] aborting startup: Relayfile workspace mirror could not be resolved.\n');
                             if (stoppedBySignal)
                                 return await waiter.promise;
-                            return 1;
+                            return FACTORY_EXIT.FAILED;
                         }
                     }
                     catch (error) {
-                        handleWarmMountError(error);
+                        const code = handleWarmMountError(error);
                         if (stoppedBySignal)
                             return await waiter.promise;
-                        return 1;
+                        return code;
                     }
                 }
                 else {
@@ -580,12 +641,13 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
         }
         if (command.action === 'run-once') {
             await ensureWorkspaceMount(mount, mountFn, workspaceId, acceptableMountIds, mountStderr);
-            writeJson(out, await factory.runOnce({ dryRun: globals.dryRun }));
-            return 0;
+            const report = await factory.runOnce({ dryRun: globals.dryRun });
+            writeJson(out, report);
+            return exitCodeForIterationReport(report);
         }
         if (command.action === 'status') {
             const versionInfo = await safeFactoryVersionInfo(deps.versionInfo, Boolean(deps.versionInfo) || !hasInjectedFactoryRuntime(deps));
-            writeJson(out, await factoryStatusWithMountHealth(factory, mount, config.loop.heartbeatPath, config.loop.registryPath, config.loop.heartbeatStaleMs, versionInfo));
+            writeJson(out, await factoryStatusWithMountHealth(factory, mount, config.loop.heartbeatPath, config.loop.registryPath, config.loop.heartbeatStaleMs, versionInfo, stateStoreStatus));
             return 0;
         }
         if (command.action === 'loop-status') {
@@ -606,18 +668,20 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
         const removeSignalHandlers = installFactoryStopSignalHandlers(factory, {
             processLike: deps.stopSignalProcessLike,
         });
+        let loopCode = FACTORY_EXIT.OK;
         try {
             const reports = await factory.runLoop({ dryRun: globals.dryRun });
+            loopCode = exitCodeForLoopReports(reports);
             writeJson(out, {
                 reports,
-                status: await factoryStatusWithMountHealth(factory, mount, config.loop.heartbeatPath, config.loop.registryPath, config.loop.heartbeatStaleMs),
+                status: await factoryStatusWithMountHealth(factory, mount, config.loop.heartbeatPath, config.loop.registryPath, config.loop.heartbeatStaleMs, undefined, stateStoreStatus),
             });
         }
         finally {
             removeSignalHandlers();
             await factory.stop();
         }
-        return 0;
+        return loopCode;
     }
     if (command.kind === 'factory-canary') {
         const report = await factory.runOnce({ dryRun: true });
@@ -642,15 +706,16 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
         try {
             const result = await factory.dispatch(decision, { dryRun: false });
             writeJson(out, result);
-            await factory.waitForDispatchTerminal(result.issue);
-            return 0;
+            const terminalPhase = await factory.waitForDispatchTerminal(result.issue);
+            return exitCodeForRelayDispatch(result, terminalPhase);
         }
         finally {
             await factory.stop();
         }
     }
-    writeJson(out, await factory.dispatch(decision, { dryRun: globals.dryRun }));
-    return 0;
+    const dispatched = await factory.dispatch(decision, { dryRun: globals.dryRun });
+    writeJson(out, dispatched);
+    return exitCodeForDispatchResult(dispatched);
 }
 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);
@@ -824,19 +889,31 @@ async function ensureMountPath(mountFn, workspaceId, path, mountOpts, stderr, lo
 function resolveIntegrationsMountRoot(mount) {
     return mount.getLocalMountRoot?.() ?? resolve(process.cwd(), '.integrations');
 }
-async function factoryStatusWithMountHealth(factory, mount, heartbeatPath, registryPath, heartbeatStaleMs, versionInfo) {
+async function factoryStatusWithMountHealth(factory, mount, heartbeatPath, registryPath, heartbeatStaleMs, versionInfo, stateStoreStatus) {
     const status = factory.status();
     const [heartbeat, registry] = await Promise.all([
         readFactoryLoopHeartbeat(heartbeatPath),
         readFactoryInFlightRegistry(registryPath),
     ]);
-    const registryDispatches = registry?.heartbeatPath && registry.heartbeatPath !== heartbeatPath
-        ? []
-        : inFlightDispatchesFromRegistry(registry);
+    // A registry stamped for a different heartbeat file belongs to another
+    // daemon instance; neither its dispatch nor held-agent view applies here.
+    const registryMatchesHeartbeat = !registry?.heartbeatPath || registry.heartbeatPath === heartbeatPath;
+    const registryDispatches = registryMatchesHeartbeat ? inFlightDispatchesFromRegistry(registry) : [];
+    const registryHeldAgents = registryMatchesHeartbeat ? heldAgentsFromRegistry(registry) : [];
+    const heldAgents = registryHeldAgents.length > 0 ? registryHeldAgents : (status.heldAgents ?? []);
     const observableStatus = registryDispatches.length > 0
         ? { ...status, inFlightDispatches: registryDispatches }
         : status;
     const liveness = checkFactoryLoopLiveness(heartbeat, { staleMs: heartbeatStaleMs });
+    // A live heartbeat belongs to the daemon, while `status` is a fresh local
+    // Factory instance. Do not misreport that local instance's `not-running`
+    // state when an older daemon heartbeat predates this health field.
+    const readinessReconcile = liveness.ok
+        ? heartbeat?.readinessReconcile
+        : observableStatus.readinessReconcile;
+    const fleetControlPlane = liveness.ok
+        ? heartbeat?.fleetControlPlane
+        : observableStatus.fleetControlPlane;
     const eventListener = liveness.ok
         ? heartbeat?.eventListener ?? {
             state: 'unknown',
@@ -848,11 +925,23 @@ async function factoryStatusWithMountHealth(factory, mount, heartbeatPath, regis
         };
     const health = mount.getLocalMountHealth?.();
     if (!health)
-        return { ...observableStatus, ...versionInfo, eventListener };
+        return {
+            ...observableStatus,
+            ...versionInfo,
+            ...(stateStoreStatus ? { stateStore: stateStoreStatus } : {}),
+            heldAgents,
+            eventListener,
+            readinessReconcile,
+            fleetControlPlane,
+        };
     return {
         ...observableStatus,
         ...versionInfo,
+        ...(stateStoreStatus ? { stateStore: stateStoreStatus } : {}),
+        heldAgents,
         eventListener,
+        readinessReconcile,
+        fleetControlPlane,
         localMountDegraded: health.degraded,
         ...(health.reason ? { localMountDegradedReason: health.reason } : {}),
         ...(health.localDir ? { localMountRoot: health.localDir } : {}),
@@ -990,7 +1079,18 @@ function parseFactoryCommand(args) {
     if (action === 'start') {
         return { kind: 'factory', action, ...parseFactoryStartFlags([issueOrPr, ...flags]) };
     }
-    if (action === 'run-once' || action === 'loop' || action === 'status' || action === 'loop-status' || action === 'kill-loop' || action === 'reap-orphans') {
+    if (action === 'reap-orphans') {
+        const values = [issueOrPr, ...flags].filter((value) => Boolean(value));
+        const unexpected = values.find((value) => value !== '--include-held');
+        if (unexpected)
+            throw new Error(`Unknown factory reap-orphans option: ${unexpected}`);
+        return {
+            kind: 'factory',
+            action,
+            ...(values.includes('--include-held') ? { includeHeld: true } : {}),
+        };
+    }
+    if (action === 'run-once' || action === 'loop' || action === 'status' || action === 'loop-status' || action === 'kill-loop') {
         return { kind: 'factory', action };
     }
     if (action === 'canary') {
@@ -1160,11 +1260,16 @@ function hasInjectedFactoryRuntime(deps) {
 async function buildFleet(globals, loaded, deps) {
     if (deps.fleet)
         return deps.fleet;
-    if (globals.backend === 'internal' && hasExplicitFixtureFiles(loaded))
+    // fixtureFiles are an explicit hermetic harness opt-in. Keep both backend
+    // command paths off real fleet infrastructure so the durable relay CLI path
+    // can be exercised end-to-end with deterministic fixtures too.
+    if (hasExplicitFixtureFiles(loaded))
         return new FakeFleetClient();
     const cwd = process.cwd();
     const env = deps.env ?? process.env;
-    const connectionPath = resolveBrokerConnectionPath(cwd, env);
+    const connectionPath = globals.backend === 'internal'
+        ? resolveFactoryBrokerConnectionPath(cwd, env, loaded?.config.fleetHealth.requireDedicatedBroker ?? false)
+        : resolveBrokerConnectionPath(cwd, env);
     // An injected createFleet owns fleet construction entirely (tests), so skip the
     // real broker bootstrap.
     if (deps.createFleet) {
@@ -1241,6 +1346,51 @@ export function resolveBrokerConnectionPath(startCwd = process.cwd(), env = proc
         current = parent;
     }
 }
+export function resolveFactoryBrokerConnectionPath(startCwd = process.cwd(), env = process.env, requireDedicatedBroker = false) {
+    const connectionPath = resolveBrokerConnectionPath(startCwd, env);
+    if (!requireDedicatedBroker)
+        return connectionPath;
+    const explicitStateDir = env.AGENT_RELAY_STATE_DIR?.trim();
+    if (!explicitStateDir) {
+        throw new Error('fleetHealth.requireDedicatedBroker requires AGENT_RELAY_STATE_DIR to name Factory\'s isolated relay state directory');
+    }
+    const inheritedConnectionPath = resolveBrokerConnectionPath(startCwd, {
+        ...env,
+        AGENT_RELAY_STATE_DIR: '',
+    });
+    // Always reject the checkout-local path, even if broker discovery currently
+    // walks past it and finds an ancestor connection. An interactive relay
+    // started in this checkout can claim the local path later.
+    const sharedStateDirs = [
+        join(resolve(startCwd), '.agentworkforce', 'relay'),
+        ...(inheritedConnectionPath ? [dirname(inheritedConnectionPath)] : []),
+    ];
+    if (sharedStateDirs.some((stateDir) => sameFilesystemPath(explicitStateDir, stateDir))) {
+        throw new Error('AGENT_RELAY_STATE_DIR resolves to the project broker; choose a separate state directory for Factory');
+    }
+    return connectionPath;
+}
+function sameFilesystemPath(left, right) {
+    return canonicalPath(left) === canonicalPath(right);
+}
+function canonicalPath(path) {
+    const absolute = resolve(path);
+    const missingSegments = [];
+    let existingAncestor = absolute;
+    while (!existsSync(existingAncestor)) {
+        const parent = dirname(existingAncestor);
+        if (parent === existingAncestor)
+            return absolute;
+        missingSegments.unshift(basename(existingAncestor));
+        existingAncestor = parent;
+    }
+    try {
+        return resolve(realpathSync.native(existingAncestor), ...missingSegments);
+    }
+    catch {
+        return absolute;
+    }
+}
 async function prepareFactoryIntegrations(command, mount, config, globals, deps, workspaceId, err) {
     const connections = mount.integrationConnections;
     if (!connections)
@@ -1449,13 +1599,10 @@ async function isAllowedFactoryDraft(path, content, opts, mount, config) {
     if (/^\/slack\/channels\/[^/]+\/messages\/.+/u.test(path)) {
         return true;
     }
-    if (isAllowedFactoryGithubDraft(path, opts)) {
+    if (await isAllowedFactoryGithubDraft(path, content, opts, mount, config))
         return true;
-    }
     return false;
 }
-const isFactoryGithubWritebackPath = (path) => /^\/github\/repos\/[^/]+\/[^/]+\/(?:pull-requests\/factory-[^/]+\.json|refs\/(?:factory\.json|refs%2Fheads%2Ffactory%2F[^/]+\.json)|pulls\/[1-9]\d*\/close\.json)$/iu.test(path);
-const isAllowedFactoryGithubDraft = (path, opts) => opts?.guarded === true && isFactoryGithubWritebackPath(path);
 const scopeIssueFromDraftContent = (content) => ({
     title: typeof asRecord(content)?.title === 'string' ? asRecord(content)?.title : '',
     team: typeof asRecord(asRecord(content)?.team)?.key === 'string'
@@ -1780,14 +1927,23 @@ function requireValue(args, index, flag) {
 function writeJson(out, value) {
     out.write(`${JSON.stringify(value, null, 2)}\n`);
 }
-async function safeEnvironmentReap(reap = reapFactoryEnvironmentsOnce) {
+async function safeEnvironmentReap(configured, reap = reapFactoryEnvironmentsOnce) {
+    if (!configured) {
+        return {
+            applicable: false,
+            reason: 'kubernetes environment provider is not configured',
+            reaped: [],
+            retained: [],
+        };
+    }
     try {
-        return await reap();
+        return { applicable: true, ...await reap() };
     }
     catch (error) {
         // Process cleanup remains useful on hosts without kubectl or an active
         // cluster. Surface the skipped backstop without failing the whole command.
         return {
+            applicable: true,
             reaped: [],
             retained: [],
             error: error instanceof Error ? error.message : String(error),
@@ -1885,7 +2041,8 @@ Commands:
   loop                  Run the bounded loop configured in factory.config.json
   loop-status           Print heartbeat/liveness status for the loop
   kill-loop             Send SIGTERM to the heartbeat pid
-  reap-orphans          Reap stale factory-owned agents
+  reap-orphans [--include-held]
+                        Report stale processes and held agents; opt in to release held agents past deadline
   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
@@ -1893,6 +2050,8 @@ Commands:
   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
+  intake notion generate
+                        Emit a manifest for Ready for Agent Factory Tasks
   fleet <command>       Low-level fleet commands: spawn, roster, release
 
 Options: