@agent-relay/factory 0.1.58 → 0.1.62

package/README.md

@@ -135,14 +135,33 @@ After init, add the `factory` label to an open issue and run a dry run below.
 | `factory run-once` | One discover→triage→dispatch cycle, then exit. Honors `--dry-run`. |
 | `factory loop` | A bounded multi-iteration loop, then exit. |
 | `factory start --mode live` | Long-lived daemon — the production entrypoint. Runs until you stop it. |
-| `factory status` | Print current factory status as JSON. |
+| `factory status` | Print current factory status as JSON, including held agents, lifecycle deadlines, and periodic readiness-reconcile health. |
 | `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. |
+| `factory reap-orphans [--include-held]` | Report stale factory processes and held agents. By default held agents are visible but retained; `--include-held` releases held agents whose configured deadline has elapsed. Kubernetes cleanup is reported as not applicable when no environment provider is configured. |
 | `factory featuremap check [--manifest <path>] [--base <ref>]` | Validate the repository feature/test manifest and optionally report advisory drift for unchanged entries whose locations changed. |
 | `factory intake notion <manifest>` | Normalize ready specs from a read-only Notion mount into GitHub lifecycle issues or exact-path fleet work. Honors `--dry-run`. |
 
+`factory status` includes `inFlightDispatches`, grouped by issue with agent
+names and the provider-claim state (`pending`, `verified`, or `degraded`). This
+view is read from Factory's local in-flight registry, so it remains available
+when GitHub lifecycle writeback is the degraded subsystem.
+
+For a live daemon, `factory status` also includes `readinessReconcile`. Its
+state advances from `retrying` to `degraded` after three consecutive periodic
+discovery failures and returns to `healthy` after a successful checkpoint.
+The same record includes the last error, attempt duration, and failure count.
+
+Dispatch lifecycle writes are claim-critical. Factory applies the
+`factory:in-progress` label/state before the dispatch comment, confirms the
+GitHub label by provider read-back, and retries either write three times. An
+exhausted write is logged at error level as dead-lettered, recorded as a
+degraded claim in the registry, and fails the dispatch instead of reporting a
+clean dispatch with missing GitHub state. Durable lifecycle recovery repeats
+the same label-and-comment claim without respawning acknowledged agents.
+
 Global options work anywhere in the args: `--config <path>`, `--dry-run`,
 `--backend <internal|relay>`, and `--agent-exit-timeout <ms>`. The internal
 backend reuses a relay broker that's already running for your workspace, and
@@ -610,6 +629,22 @@ knobs include issue **routing** (`repos.byLabel` / `byProject` / `keywordRules`
 `mergePolicy` (defaults to `never`), per-role **model** overrides, and an optional
 **Slack** channel for status threads.
 
+Every successfully placed agent team has a wall-clock release backstop. Configure
+the window with `dispatch.agentHoldTimeoutMs`; it defaults to four hours. The
+clock starts at the first successful agent placement, not while a dispatch waits
+for capacity or while a released team waits for human clarification. If the issue
+has not reached its configured `terminalState` before the deadline, Factory
+releases the team with reason `held-past-deadline` and records the lifecycle as
+abandoned so a restart cannot respawn it:
+
+```jsonc
+{
+  "dispatch": {
+    "agentHoldTimeoutMs": 14400000
+  }
+}
+```
+
 The full schema — every field and default — is validated by Zod at load time, so
 an invalid config fails fast with a field-level error. See
 [`src/config/schema.ts`](src/config/schema.ts) for the authoritative reference,

package/dist/cli/fleet.d.ts

@@ -1,8 +1,9 @@
 import { ensureCloudSession, type CloudSession } from '@agent-relay/cloud';
 import { type LocalClonePathOptions } from '../config/local-clone-paths.js';
-import { createFactory, createFleet, ensureRelayBroker, reapFactoryEnvironmentsOnce, type Capability, type Factory, type FactoryEventReporter, type FactoryConfig, type FleetBackend, type FleetClient, type GhRunner, type FactoryStateResolution, type LocalMountOptions, type MountClient, type ProbeCloser, type RelayfileCloudMountClientConfig, type ResolvedFactoryWorkspace } from '../index.js';
+import { createFactory, createFleet, ensureRelayBroker, reapFactoryEnvironmentsOnce, type Capability, type Factory, type FactoryEventReporter, type FactoryConfig, type FleetBackend, type FleetClient, type GhRunner, type FactoryStateResolution, type Logger, type LocalMountOptions, type MountClient, type ProbeCloser, type RelayfileCloudMountClientConfig, type ResolvedFactoryWorkspace } from '../index.js';
 import { type CheckFeatureMapOptions, type FeatureMapCheckReport } from '../featuremap/index.js';
 import type { FactoryIntegrationProvider } from '../ports/index.js';
+import { type FactoryVersionInfo, type FactoryVersionInfoOptions } from '../version-info.js';
 import { type NotionIntakeClaimStore, type NotionContractPublisher } from '../intake/index.js';
 interface FleetCliDeps {
     fleet?: FleetClient;
@@ -40,6 +41,10 @@ interface FleetCliDeps {
     notionClaims?: NotionIntakeClaimStore;
     /** Hermetic verification-environment sweep for CLI tests and alternate runtimes. */
     reapEnvironments?: typeof reapFactoryEnvironmentsOnce;
+    /** Hermetic package/registry metadata for CLI tests and alternate runtimes. */
+    versionInfo?: (options?: FactoryVersionInfoOptions) => Promise<FactoryVersionInfo>;
+    /** Override the six-hour daemon drift check cadence in tests. */
+    versionCheckIntervalMs?: number;
 }
 interface GlobalOptions {
     backend: FleetBackend;
@@ -68,6 +73,7 @@ type ParsedCommand = {
 } | {
     kind: 'factory';
     action: 'run-once' | 'loop' | 'status' | 'loop-status' | 'kill-loop' | 'reap-orphans';
+    includeHeld?: boolean;
 } | {
     kind: 'factory';
     action: 'start';
@@ -109,6 +115,7 @@ export declare function parseGlobalOptions(argv: string[]): {
     globals: GlobalOptions;
     args: string[];
 };
+export declare function reportFactoryVersionDrift(provider: FleetCliDeps['versionInfo'], logger: Logger): Promise<void>;
 export declare function formatLogArgs(args: unknown[]): string;
 export declare function resolveBrokerConnectionPath(startCwd?: string, env?: NodeJS.ProcessEnv): string | undefined;
 export type GithubIssueSelector = {

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

@@ -1 +1 @@
-{"version":3,"file":"fleet.d.ts","sourceRoot":"","sources":["../../src/cli/fleet.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fleet.d.ts","sourceRoot":"","sources":["../../src/cli/fleet.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAG1E,OAAO,EAA6B,KAAK,qBAAqB,EAAE,MAAM,6BAA6B,CAAA;AAEnG,OAAO,EAKL,aAAa,EACb,WAAW,EAEX,iBAAiB,EAiBjB,2BAA2B,EAQ3B,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,oBAAoB,EAGzB,KAAK,aAAa,EAElB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,KAAK,MAAM,EAEX,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAGhB,KAAK,WAAW,EAChB,KAAK,+BAA+B,EACpC,KAAK,wBAAwB,EAC9B,MAAM,UAAU,CAAA;AAIjB,OAAO,EAAmB,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAQxG,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAA;AAI1D,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC/B,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAML,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAE7B,MAAM,WAAW,CAAA;AAElB,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,iBAAiB,KACxB,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,iBAAiB,CAAC,EAAE,QAAQ,CAAA;IAC5B,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;IACvC,gEAAgE;IAChE,qBAAqB,CAAC,EAAE,qBAAqB,CAAA;IAC7C,QAAQ,CAAC,EAAE,oBAAoB,CAAA;IAC/B,oBAAoB,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,CAAA;IACpG,aAAa,CAAC,EAAE,MAAM,OAAO,CAAA;IAC7B,yBAAyB,CAAC,EAAE,CAAC,QAAQ,EAAE,0BAA0B,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACtF,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1D,eAAe,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,sBAAsB,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;IACtF,2FAA2F;IAC3F,eAAe,CAAC,EAAE,uBAAuB,CAAA;IACzC,qFAAqF;IACrF,YAAY,CAAC,EAAE,sBAAsB,CAAA;IACrC,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,OAAO,2BAA2B,CAAA;IACrD,+EAA+E;IAC/E,WAAW,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,yBAAyB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAClF,iEAAiE;IACjE,sBAAsB,CAAC,EAAE,MAAM,CAAA;CAChC;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;AAQD,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,QAAQ,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,GAChL;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,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GACjI;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,iBAAiB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1E;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9E;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACrE;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnD,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqW1F;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAuB/D;AAoED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CA8B7F;AAokBD,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,YAAY,CAAC,aAAa,CAAC,EACrC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAUf;AAiVD,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAGrD;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,SAAgB,EACxB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CA2BpB;AAofD,MAAM,MAAM,mBAAmB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnE,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,mBAAmB,CA6BhG;AA6ND,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;AAyED,wBAAsB,IAAI,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtE"}

package/dist/cli/fleet.js

@@ -1,13 +1,13 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { randomUUID } from 'node:crypto';
+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, resolveFactoryStates, stateResolutionFromIds, standaloneBabysitterAgentName, renderAgentTask, resolveFactoryWorkspace, } from '../index.js';
+import { FileStateStore, RelayfileCloudMountClient, checkFactoryLoopLiveness, closeProbePr, createFactory, createFleet, createFactoryCloudEventV1, ensureRelayBroker, FactoryCloudReporter, FileFactoryCloudEventOutbox, defaultGhRunner, explicitLinkedIssueKey, githubIssuePathParts, githubWatchStatePath, 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';
@@ -17,6 +17,7 @@ import { ensureFactoryIntegrations, inspectFactoryIntegration, openIntegrationUr
 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';
 const autoDetectedIssueSources = new WeakSet();
 export async function runFleetCli(argv, deps = {}) {
@@ -200,8 +201,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
@@ -491,6 +497,18 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
         if (command.action === 'start') {
             const waiter = createStopSignalWaiter();
             let stoppedBySignal = false;
+            const logger = streamLogger(mountStderr);
+            const installedVersion = await safeFactoryVersionInfo(deps.versionInfo, false);
+            logger.info?.('[factory] daemon starting', installedVersion);
+            // The registry lookup is deliberately detached from the startup path.
+            // stop() only joins the bounded in-flight lookup during shutdown.
+            const versionMonitor = deps.versionInfo || !hasInjectedFactoryRuntime(deps)
+                ? startFactoryVersionMonitor({
+                    versionInfo: deps.versionInfo,
+                    intervalMs: deps.versionCheckIntervalMs,
+                    logger,
+                })
+                : { stop: async () => { } };
             const flushAndResolve = async (code) => {
                 try {
                     await (deps.flushDaemonOutput ?? flushProcessOutput)();
@@ -558,6 +576,7 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
                 return typeof code === 'number' ? code : 0;
             }
             finally {
+                await versionMonitor.stop();
                 removeSignalHandlers();
                 if (!stoppedBySignal) {
                     await factory.stop();
@@ -570,7 +589,8 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
             return 0;
         }
         if (command.action === 'status') {
-            writeJson(out, await factoryStatusWithMountHealth(factory, mount, config.loop.heartbeatPath, config.loop.heartbeatStaleMs));
+            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));
             return 0;
         }
         if (command.action === 'loop-status') {
@@ -595,7 +615,7 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
             const reports = await factory.runLoop({ dryRun: globals.dryRun });
             writeJson(out, {
                 reports,
-                status: await factoryStatusWithMountHealth(factory, mount, config.loop.heartbeatPath, config.loop.heartbeatStaleMs),
+                status: await factoryStatusWithMountHealth(factory, mount, config.loop.heartbeatPath, config.loop.registryPath, config.loop.heartbeatStaleMs),
             });
         }
         finally {
@@ -809,10 +829,28 @@ 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, heartbeatStaleMs) {
+async function factoryStatusWithMountHealth(factory, mount, heartbeatPath, registryPath, heartbeatStaleMs, versionInfo) {
     const status = factory.status();
-    const heartbeat = await readFactoryLoopHeartbeat(heartbeatPath);
+    const [heartbeat, registry] = await Promise.all([
+        readFactoryLoopHeartbeat(heartbeatPath),
+        readFactoryInFlightRegistry(registryPath),
+    ]);
+    // 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 eventListener = liveness.ok
         ? heartbeat?.eventListener ?? {
             state: 'unknown',
@@ -824,10 +862,13 @@ async function factoryStatusWithMountHealth(factory, mount, heartbeatPath, heart
         };
     const health = mount.getLocalMountHealth?.();
     if (!health)
-        return { ...status, eventListener };
+        return { ...observableStatus, ...versionInfo, heldAgents, eventListener, readinessReconcile };
     return {
-        ...status,
+        ...observableStatus,
+        ...versionInfo,
+        heldAgents,
         eventListener,
+        readinessReconcile,
         localMountDegraded: health.degraded,
         ...(health.reason ? { localMountDegradedReason: health.reason } : {}),
         ...(health.localDir ? { localMountRoot: health.localDir } : {}),
@@ -839,6 +880,82 @@ async function factoryStatusWithMountHealth(factory, mount, heartbeatPath, heart
         },
     };
 }
+function inFlightDispatchesFromRegistry(registry) {
+    if (!registry)
+        return [];
+    const grouped = new Map();
+    const claimPriority = { verified: 0, pending: 1, degraded: 2 };
+    for (const agent of registry.agents) {
+        if (!agent.issue)
+            continue;
+        const key = `${agent.issue.key}\u0000${agent.issue.uuid}\u0000${agent.issue.path}`;
+        const claim = agent.dispatchClaim ?? {
+            state: 'pending',
+            updatedAtMs: registry.updatedAtMs,
+        };
+        const existing = grouped.get(key);
+        const entry = existing ?? {
+            issue: { ...agent.issue },
+            agents: [],
+            claim: { ...claim },
+        };
+        if (claimPriority[claim.state] > claimPriority[entry.claim.state]) {
+            entry.claim = { ...claim };
+        }
+        if (!entry.agents.some((candidate) => candidate.name === agent.name)) {
+            entry.agents.push({
+                name: agent.name,
+                ...(agent.role ? { role: agent.role } : {}),
+                ...(agent.sessionRef ? { sessionRef: agent.sessionRef } : {}),
+                ...(agent.invocationId ? { invocationId: agent.invocationId } : {}),
+                ...(agent.node ? { node: agent.node } : {}),
+            });
+        }
+        grouped.set(key, entry);
+    }
+    return [...grouped.values()]
+        .map((entry) => ({
+        ...entry,
+        agents: entry.agents.sort((left, right) => left.name.localeCompare(right.name)),
+    }))
+        .sort((left, right) => left.issue.key.localeCompare(right.issue.key));
+}
+const DEFAULT_VERSION_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1_000;
+async function safeFactoryVersionInfo(provider, includeRegistry) {
+    try {
+        return await (provider ?? readFactoryVersionInfo)({ includeRegistry });
+    }
+    catch {
+        return { version: 'unknown' };
+    }
+}
+export async function reportFactoryVersionDrift(provider, logger) {
+    const info = await safeFactoryVersionInfo(provider, true);
+    if (!isMeaningfullyBehind(info) || !info.latestVersion)
+        return;
+    logger.warn?.(`[factory] version drift detected: running ${info.version}; published latest ${info.latestVersion}`, {
+        ...(info.versionsBehind !== undefined ? { versionsBehind: info.versionsBehind } : {}),
+        ...(info.installedAt ? { installedAt: info.installedAt } : {}),
+    });
+}
+function startFactoryVersionMonitor(input) {
+    let pending;
+    const check = () => {
+        if (pending)
+            return;
+        pending = reportFactoryVersionDrift(input.versionInfo, input.logger)
+            .finally(() => { pending = undefined; });
+    };
+    check();
+    const interval = setInterval(check, input.intervalMs ?? DEFAULT_VERSION_CHECK_INTERVAL_MS);
+    interval.unref?.();
+    return {
+        stop: async () => {
+            clearInterval(interval);
+            await pending;
+        },
+    };
+}
 function writeMountRefreshSummary(refreshedStaleMounts, stderr, debug) {
     if (debug) {
         for (const mount of [...refreshedStaleMounts].sort((left, right) => left.path.localeCompare(right.path))) {
@@ -889,7 +1006,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') {
@@ -1059,7 +1187,10 @@ 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;
@@ -1291,7 +1422,7 @@ async function buildMount(loaded, deps, observability = {}) {
     if (deps.mount)
         return deps.mount;
     if (hasExplicitFixtureFiles(loaded))
-        return new FakeMountClient(loaded.fixtureFiles);
+        return new FixtureMountClient(loaded.fixtureFiles);
     let mount;
     mount = await (deps.cloudMountFromConfig ?? RelayfileCloudMountClient.fromConfig)({
         workspaceId: loaded.config.workspaceId,
@@ -1303,6 +1434,21 @@ async function buildMount(loaded, deps, observability = {}) {
     return mount;
 }
 const hasExplicitFixtureFiles = (loaded) => loaded?.fixtureFiles !== undefined;
+/** Hermetic fixture runs have no server event feed, so expose the in-memory
+ * tree shape as their change watermark. The discovery tree cache only
+ * remembers which paths exist under a prefix, not their content, so the
+ * watermark must track path membership only. Hashing full file entries
+ * (as an earlier version of this did) also hashes each file's `revision`,
+ * which FakeMountClient.writeFile bumps on every write — so any factory
+ * writeback mid-sweep (a draft, a confirmed write) would change the digest
+ * with no fixture change-event to explain the gap, and the checkpoint
+ * would never persist across a sweep that actually dispatched anything. */
+class FixtureMountClient extends FakeMountClient {
+    async getEventHighWatermark() {
+        const paths = [...this.files.keys()].sort();
+        return `fixture:${createHash('sha256').update(JSON.stringify(paths)).digest('hex')}`;
+    }
+}
 async function isAllowedFactoryDraft(path, content, opts, mount, config) {
     if (!opts?.guarded)
         return false;
@@ -1481,7 +1627,7 @@ async function findGithubIssueThroughConnection(mount, selector, config, issueAr
     return found[0].issue;
 }
 async function issueProjectionStatus(factory, mount, config) {
-    const status = await factoryStatusWithMountHealth(factory, mount, config.loop.heartbeatPath, config.loop.heartbeatStaleMs);
+    const status = await factoryStatusWithMountHealth(factory, mount, config.loop.heartbeatPath, config.loop.registryPath, config.loop.heartbeatStaleMs);
     const githubConnection = mount.integrationConnections
         ? await mount.integrationConnections.getStatus('github')
         : undefined;
@@ -1664,14 +1810,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),
@@ -1769,7 +1924,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