@agent-relay/factory 0.1.49 → 0.1.51

package/README.md

@@ -124,13 +124,15 @@ From a source checkout instead of an npm install, run
 | `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 featuremap check [--base <ref>]` | Validate the repository feature/test manifest and optionally report advisory drift for unchanged entries whose locations changed. |
+| `factory featuremap check [--manifest <path>] [--base <ref>]` | Validate the repository feature/test manifest and optionally report advisory drift for unchanged entries whose locations changed. |
 
 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
 starts one if none is. For self-started brokers, the agent-exit timeout defaults
-to 30 minutes and can also be set with `FACTORY_AGENT_EXIT_TIMEOUT_MS`.
+to 30 minutes and can also be set with `FACTORY_AGENT_EXIT_TIMEOUT_MS`. Set
+`FACTORY_LOG_LEVEL=debug` to include per-checkout details for summarized local
+mount refreshes.
 
 Integration connection prompts only run for commands that need provider data or
 GitHub write access. Maintenance commands such as `status`, `loop-status`,
@@ -146,9 +148,9 @@ instruction to rerun the Factory command in an interactive terminal instead.
 
 Repositories with `.agentworkforce/features/manifest.yaml` can run
 `factory featuremap check` in CI. The command rejects malformed or duplicate
-entries, invalid verification tiers, catalog-summary drift, and locations that
-do not exist. The same checker is published as `@agent-relay/factory/featuremap`
-for programmatic use.
+entries, invalid verification tiers, catalog-summary drift, locations that do
+not exist, and incomplete v1.1 category-to-procedure routing. The same checker
+is published as `@agent-relay/factory/featuremap` for programmatic use.
 
 During review, pass the PR base ref with `--base <ref>`. A changed file named by
 an existing manifest entry produces an advisory when that entry's description,
@@ -156,12 +158,20 @@ verification tier, and locations are unchanged. The reviewer must re-confirm
 that metadata; the advisory does not itself fail the command because a covered
 file can change without changing the feature contract.
 
-An hourly per-repository sweep or Slack confirmation bot is explicitly outside
-this feature's scope. Factory's own guardian cycle is useful for tier-5/6 checks
-that need live or human confirmation, but duplicating it for every customer repo
-would add standing noise and infrastructure without evidence that those entries
-rot between PRs. Revisit that only if usage data demonstrates silent tier-5/6
-drift that PR checks do not catch.
+Factory's agent-facing runbook is `.claude/skills/verify-features.md`. It tells
+an agent how to resolve a manifest category to its named end-to-end procedure,
+run the applicable tier with safe fixtures and cleanup, assert provider/fleet
+state, and report unexercised live tiers explicitly. The deterministic full gate
+is `npm run build && npm run featuremap:check && npm test && npm run verify:e2e`;
+`workflows/verify-features.ts` adds opt-in provider, fleet, and cloud checks.
+
+The checked-in `factory-feature-guardian` proactive persona mirrors Relay's
+guardian operating model. Hourly, it reads the catalog from a scoped Factory
+repository mount, selects one unchecked feature from exact revisioned cycle
+state, posts an idempotent Slack question, requires a provider timestamp, and
+only then checkpoints progress. Manifest/state/delivery ambiguity fails closed
+instead of silently skipping a feature. Configure its Slack channel and deploy
+the persona through the normal Agent Workforce proactive-agent path.
 
 ### Cloud progress and trace correlation
 
@@ -279,6 +289,78 @@ The definition reads its node config from `./factory.node.json` (or
 mapped repo is advertised as a `repo:<label>` tag so placement can route
 repo-scoped spawns to it. Spawns for unadvertised paths are refused on the node.
 
+### Tailnet live previews
+
+Factory can attach an issue-lifetime [Tailscale Serve](https://tailscale.com/docs/features/tailscale-serve)
+route to a repository's local development port. Configure the same service on
+the control plane and execution node (a combined local config needs it only
+once):
+
+```json
+{
+  "preview": {
+    "provider": "tailscale-serve",
+    "access": "tailnet",
+    "services": {
+      "AgentWorkforce/pear": {
+        "port": 3000,
+        "portSpan": 25,
+        "startCommand": "npm ci && exec npm run dev"
+      }
+    }
+  }
+}
+```
+
+The node then advertises `preview:tailscale-serve`; Factory places the preview
+first and pins the issue's agents to that node. The URL is included in agent
+tasks, the Slack dispatch root, and the pull-request description. Factory uses
+Serve—not Funnel—so the URL remains inside the configured tailnet and normal
+tailnet grants/ACLs apply. Factory checks the live Serve status and refuses to
+surface a route marked as Funnel.
+
+`port` is the preferred node-local app port. Factory reserves the first free
+port in `port..port + portSpan - 1` (the span defaults to 100), places that
+allocated port in every agent task, and reserves a separate HTTPS port from
+`preview.httpsPortRange`. Keep that HTTPS range dedicated to Factory previews.
+Preview provisioning happens immediately after Factory creates the isolated
+issue worktree, before an agent has had a chance to install ignored dependencies
+such as `node_modules`. `startCommand` must therefore include any bounded,
+non-interactive bootstrap the fresh checkout needs, followed by a foreground
+development command that honors `PORT` (for example,
+`npm ci && exec npm run dev`).
+The node starts it in the issue checkout, waits for the allocated local HTTP
+port to respond, and verifies on Linux or macOS that the listener belongs to the
+supervised process tree before returning the URL. It persists an exact process
+identity so the command survives agent handoffs and can be safely recovered or
+stopped. The command must not daemonize or bind a different port. Active sweeps
+repeat listener ownership verification and disable the exact Factory route if
+the port is taken over by an unrelated process.
+For safety, preview commands receive only `PORT` plus basic shell, locale, home,
+and temporary-directory variables; they do not inherit arbitrary Factory,
+Relay, or provider credentials from the node process. Load intentional
+application settings through a checkout-local environment mechanism. Do not put
+secrets directly in `startCommand`, because lifecycle recovery persists the
+command as metadata.
+
+Terminal lifecycle completion is withheld until routes and their supervised
+commands have been removed at Human Review or Done. If the source-state
+writeback wins a crash race, startup recovery observes that terminal source
+state and finishes preview teardown before terminalizing the durable lifecycle.
+A startup and periodic sweep reaps only orphaned resources in the current
+Factory workspace whose persisted route and process identities still match.
+See the [provider evaluation](planning/preview-provider-evaluation.md)
+for the decision and lifecycle contract.
+
+To exercise the real provider lifecycle on a signed-in node, build first and
+run `TAILSCALE_BIN=/path/to/tailscale node scripts/verify-tailscale-preview-e2e.mjs`.
+The check drives the node's advertised `preview:tailscale-serve` action to start
+a detached HTTP service, reaches it through Serve, recovers it through a fresh
+node-action instance, tears it down, then proves a startup orphan sweep reaps a
+second abandoned route and process while preserving unrelated Serve
+configuration. Override its dedicated ports with
+`FACTORY_PREVIEW_E2E_HTTPS_PORT` and `FACTORY_PREVIEW_E2E_TARGET_PORT`.
+
 ### Dispatching to nodes (`--backend relay`)
 
 With `--backend relay`, the factory orchestrator dispatches work through the

package/dist/cli/fleet.d.ts

@@ -1,6 +1,6 @@
 import { ensureCloudSession, type CloudSession } from '@agent-relay/cloud';
 import { type LocalClonePathOptions } from '../config/local-clone-paths.js';
-import { createFactory, createFleet, ensureRelayBroker, 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 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';
 interface FleetCliDeps {
@@ -33,6 +33,8 @@ interface FleetCliDeps {
     confirmIntegrationConnect?: (provider: FactoryIntegrationProvider) => Promise<boolean>;
     openIntegrationUrl?: (url: string) => void | Promise<void>;
     featureMapCheck?: (options?: CheckFeatureMapOptions) => Promise<FeatureMapCheckReport>;
+    /** Hermetic verification-environment sweep for CLI tests and alternate runtimes. */
+    reapEnvironments?: typeof reapFactoryEnvironmentsOnce;
 }
 interface GlobalOptions {
     backend: FleetBackend;
@@ -47,6 +49,7 @@ type ParsedCommand = {
         name?: string;
         node?: 'self' | string;
         task?: string;
+        workflow?: string;
         model?: string;
         sessionRef?: string;
         cwd?: string;

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":"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"}

package/dist/cli/fleet.js

@@ -6,13 +6,14 @@ 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 { FileStateStore, RelayfileCloudMountClient, checkFactoryLoopLiveness, closeProbePr, createFactory, createFleet, createFactoryCloudEventV1, ensureRelayBroker, FactoryCloudReporter, FileFactoryCloudEventOutbox, defaultGhRunner, explicitLinkedIssueKey, githubIssuePathParts, githubWatchStatePath, isInFactoryScope, parseGithubFactoryIssue, publishFactoryMountHealth, parseOwnedBrokerAgentExitTimeoutMs, parseStandaloneBabysitTarget, readStandalonePullRequest, readLinearIssueWithCanonicalFallback, reapFactoryOrphansOnce, 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, parseOwnedBrokerAgentExitTimeoutMs, parseStandaloneBabysitTarget, readStandalonePullRequest, readLinearIssueWithCanonicalFallback, reapFactoryOrphansOnce, reapFactoryEnvironmentsOnce, 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';
 import { checkFeatureMap } from '../featuremap/index.js';
 import { loadOrCreateFactoryInstanceId, resolveFactoryInstanceName } from '../observability/instance-identity.js';
 import { ensureFactoryIntegrations, inspectFactoryIntegration, openIntegrationUrl, } from '../mount/relayfile-integration-preflight.js';
+import { checkMountStaleness } from '../mount/relayfile-binary.js';
 const autoDetectedIssueSources = new WeakSet();
 const CLONE_MOUNT_PREFLIGHT_CONCURRENCY = 4;
 export async function runFleetCli(argv, deps = {}) {
@@ -89,6 +90,7 @@ export async function runFleetCli(argv, deps = {}) {
                     capability: command.input.capability,
                     node: command.input.node ?? 'self',
                     task: command.input.task,
+                    workflow: command.input.workflow,
                     model: command.input.model,
                     cwd: command.input.cwd,
                 }));
@@ -109,12 +111,13 @@ export async function runFleetCli(argv, deps = {}) {
                 if (!loaded)
                     throw new Error('factory command requires config');
                 if (command.kind === 'factory' && command.action === 'reap-orphans') {
-                    writeJson(out, await reapFactoryOrphansOnce({
+                    const processes = await reapFactoryOrphansOnce({
                         heartbeatPath: loaded.config.loop.heartbeatPath,
                         registryPath: loaded.config.loop.registryPath,
                         staleMs: loaded.config.loop.heartbeatStaleMs,
                         fleet,
-                    }));
+                    });
+                    writeJson(out, { ...processes, environments: await safeEnvironmentReap(deps.reapEnvironments) });
                     return 0;
                 }
                 // Derive the workspace from the cloud session when it isn't pinned in
@@ -299,6 +302,9 @@ function parseFleetSubcommand(args) {
             throw new Error('factory fleet spawn requires capability spawn:codex, spawn:claude, or workflow:run');
         }
         const parsed = parseFlags(flags);
+        if (capability === 'workflow:run' && !parsed.workflow) {
+            throw new Error('factory fleet spawn workflow:run requires --workflow <path>');
+        }
         return {
             kind: 'spawn',
             input: {
@@ -306,6 +312,7 @@ function parseFleetSubcommand(args) {
                 name: parsed.name,
                 node: parsed.node,
                 task: parsed.task,
+                ...(parsed.workflow ? { workflow: parsed.workflow } : {}),
                 model: parsed.model,
                 sessionRef: parsed.resume,
                 cwd: parsed.cwd,
@@ -361,16 +368,18 @@ export function parseGlobalOptions(argv) {
 }
 async function runFactoryCommand(command, factory, mount, fleet, config, globals, out, deps = {}, workspaceId = config.workspaceId ?? '', acceptableMountIds) {
     const mountFn = resolveLocalMountFn(deps, mount);
+    const mountStderr = deps.stderr ?? process.stderr;
+    const debugMountRefreshes = (deps.env ?? process.env).FACTORY_LOG_LEVEL?.toLowerCase() === 'debug';
     if (command.kind === 'factory') {
         if (command.action === 'start') {
             // Local mirrors are a writeback aid, not the source of truth for remote
             // issue discovery. Start their SDK-backed supervisors immediately, but
             // do not serialize durable recovery behind a stale checkout's readiness
             // timeout. The mount client reports degradation and keeps retrying.
-            void warmStartPathMounts(mountFn, workspaceId, config, acceptableMountIds)
+            void warmStartPathMounts(mountFn, workspaceId, config, acceptableMountIds, mountStderr, debugMountRefreshes)
                 .catch((error) => {
                 const message = error instanceof Error ? error.message : String(error);
-                process.stderr.write(`[factory] warning: background relayfile mount warmup failed: ${message}\n`);
+                mountStderr.write(`[factory] warning: background relayfile mount warmup failed: ${message}\n`);
             });
             const waiter = createStopSignalWaiter();
             let stoppedBySignal = false;
@@ -405,7 +414,7 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
             }
         }
         if (command.action === 'run-once') {
-            await ensureClonePathMounts(mountFn, workspaceId, config, acceptableMountIds);
+            await ensureClonePathMounts(mountFn, workspaceId, config, acceptableMountIds, mountStderr, debugMountRefreshes);
             writeJson(out, await factory.runOnce({ dryRun: globals.dryRun }));
             return 0;
         }
@@ -427,16 +436,7 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
             writeJson(out, { killed: heartbeat.pid, signal: 'SIGTERM' });
             return 0;
         }
-        if (command.action === 'reap-orphans') {
-            writeJson(out, await reapFactoryOrphansOnce({
-                heartbeatPath: config.loop.heartbeatPath,
-                registryPath: config.loop.registryPath,
-                staleMs: config.loop.heartbeatStaleMs,
-                fleet,
-            }));
-            return 0;
-        }
-        await ensureClonePathMounts(mountFn, workspaceId, config, acceptableMountIds);
+        await ensureClonePathMounts(mountFn, workspaceId, config, acceptableMountIds, mountStderr, debugMountRefreshes);
         const removeSignalHandlers = installFactoryStopSignalHandlers(factory, {
             processLike: deps.stopSignalProcessLike,
         });
@@ -480,22 +480,13 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
     writeJson(out, await factory.dispatch(decision, { dryRun: globals.dryRun }));
     return 0;
 }
-async function warmStartPathMounts(mountFn, workspaceId, config, acceptableMountIds) {
-    const daemonMount = (async () => {
-        try {
-            await mountFn(workspaceId, process.cwd(), {
-                acceptableWorkspaceIds: acceptableMountIds,
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            process.stderr.write(`[factory] warning: could not start relayfile mount at ${process.cwd()}: ${message}\n`);
-        }
-    })();
-    await Promise.all([
-        daemonMount,
-        ensureClonePathMounts(mountFn, workspaceId, config, acceptableMountIds),
+async function warmStartPathMounts(mountFn, workspaceId, config, acceptableMountIds, stderr = process.stderr, debug = process.env.FACTORY_LOG_LEVEL?.toLowerCase() === 'debug') {
+    const mountOpts = { acceptableWorkspaceIds: acceptableMountIds };
+    const [daemonRefresh, cloneRefreshes] = await Promise.all([
+        ensureMountPath(mountFn, workspaceId, process.cwd(), mountOpts, stderr),
+        ensureClonePathMounts(mountFn, workspaceId, config, acceptableMountIds, stderr, debug, false),
     ]);
+    writeMountRefreshSummary([...(daemonRefresh ? [daemonRefresh] : []), ...cloneRefreshes], stderr, debug);
 }
 async function runStandaloneBabysitCommand(command, mount, fleet, config, globals, out, deps, workspaceId, acceptableMountIds) {
     const repo = resolveStandaloneBabysitRepo(command.repo, config);
@@ -646,25 +637,60 @@ function standaloneBabysitClonePath(repo, config) {
  * is not automatically accessible from a different directory, and agents need
  * these paths for integration writebacks (Slack, GitHub, etc.).
  */
-async function ensureClonePathMounts(mountFn, workspaceId, config, acceptableMountIds) {
+async function ensureClonePathMounts(mountFn, workspaceId, config, acceptableMountIds, stderr = process.stderr, debug = process.env.FACTORY_LOG_LEVEL?.toLowerCase() === 'debug', reportSummary = true) {
     const mountOpts = { acceptableWorkspaceIds: acceptableMountIds };
     const daemonCwd = resolve(process.cwd());
     const clonePaths = [...new Set(Object.values(config.clonePaths ?? {}).map((clonePath) => resolve(clonePath)))]
         .filter((clonePath) => clonePath !== daemonCwd);
+    const refreshedStaleMounts = [];
     let nextIndex = 0;
     const mountNext = async () => {
         while (nextIndex < clonePaths.length) {
             const resolved = clonePaths[nextIndex++];
-            try {
-                await mountFn(workspaceId, resolved, mountOpts);
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                process.stderr.write(`[factory] warning: could not start relayfile mount at ${resolved}: ${message}\n`);
-            }
+            const refreshed = await ensureMountPath(mountFn, workspaceId, resolved, mountOpts, stderr);
+            if (refreshed)
+                refreshedStaleMounts.push(refreshed);
         }
     };
     await Promise.all(Array.from({ length: Math.min(CLONE_MOUNT_PREFLIGHT_CONCURRENCY, clonePaths.length) }, mountNext));
+    if (reportSummary)
+        writeMountRefreshSummary(refreshedStaleMounts, stderr, debug);
+    return refreshedStaleMounts;
+}
+async function ensureMountPath(mountFn, workspaceId, path, mountOpts, stderr) {
+    const resolved = resolve(path);
+    const statePath = join(resolved, '.integrations', '.relay', 'state.json');
+    const staleBefore = checkMountStaleness(statePath, workspaceId, mountOpts.acceptableWorkspaceIds);
+    try {
+        await mountFn(workspaceId, resolved, {
+            ...mountOpts,
+            ...(staleBefore.stale ? { suppressStaleRefreshLogs: true } : {}),
+        });
+        if (staleBefore.stale && !checkMountStaleness(statePath, workspaceId, mountOpts.acceptableWorkspaceIds).stale) {
+            return { path: resolved, reason: staleBefore.reason };
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stderr.write(`[factory] warning: could not start relayfile mount at ${resolved}: ${message}\n`);
+    }
+    return undefined;
+}
+function writeMountRefreshSummary(refreshedStaleMounts, stderr, debug) {
+    if (debug) {
+        for (const mount of [...refreshedStaleMounts].sort((left, right) => left.path.localeCompare(right.path))) {
+            const suffix = mount.reason ? ` (${mount.reason})` : '';
+            stderr.write(`[factory] debug: refreshed stale local mount at ${mount.path}${suffix}\n`);
+        }
+    }
+    if (refreshedStaleMounts.length > 0) {
+        const ages = refreshedStaleMounts
+            .map(({ reason }) => reason?.match(/^last reconcile (\d+)m ago$/u)?.[1])
+            .filter((age) => age !== undefined)
+            .map(Number);
+        const ageSuffix = ages.length > 0 ? ` (last reconcile ~${Math.max(...ages)}m ago)` : '';
+        stderr.write(`[factory] refreshed ${refreshedStaleMounts.length} stale local mount(s)${ageSuffix}\n`);
+    }
 }
 function resolveLocalMountFn(deps, mount) {
     if (deps.ensureLocalMount)
@@ -860,7 +886,7 @@ async function buildFleet(globals, loaded, deps) {
     // An injected createFleet owns fleet construction entirely (tests), so skip the
     // real broker bootstrap.
     if (deps.createFleet) {
-        return deps.createFleet({ backend: globals.backend, cwd, connectionPath }, { ownedBrokerAgentExitTimeoutMs: globals.agentExitTimeoutMs });
+        return deps.createFleet({ backend: globals.backend, cwd, connectionPath, previewConfig: loaded?.config.preview }, { ownedBrokerAgentExitTimeoutMs: globals.agentExitTimeoutMs });
     }
     // The internal backend talks to a relay broker. Reuse the one already running
     // for this workspace, or start one if none is up, so `factory <run-once|loop>`
@@ -875,7 +901,12 @@ async function buildFleet(globals, loaded, deps) {
             logger,
             env,
         });
-        return createFleet({ backend: 'internal', cwd, connectionPath }, {
+        if (started && connectionPath === undefined) {
+            stderr.write(`[factory] no existing relay broker connection found under ${cwd} (.agentworkforce/relay/connection.json);\n` +
+                'starting a NEW broker. If you expected to attach to an already-running Factory, you are likely running\n' +
+                'from the wrong directory — cd to the checkout that owns .agentworkforce/relay/ and retry.\n');
+        }
+        return createFleet({ backend: 'internal', cwd, connectionPath, previewConfig: loaded?.config.preview }, {
             harnessClient: client,
             ownsBroker: started,
             ownedBrokerAgentExitTimeoutMs: globals.agentExitTimeoutMs,
@@ -883,7 +914,7 @@ async function buildFleet(globals, loaded, deps) {
             logger,
         });
     }
-    return createFleet({ backend: globals.backend, cwd, connectionPath }, { env: deps.env });
+    return createFleet({ backend: globals.backend, cwd, connectionPath, previewConfig: loaded?.config.preview }, { env: deps.env });
 }
 function streamLogger(stream) {
     const write = (message, args) => {
@@ -1274,6 +1305,20 @@ function requireValue(args, index, flag) {
 function writeJson(out, value) {
     out.write(`${JSON.stringify(value, null, 2)}\n`);
 }
+async function safeEnvironmentReap(reap = reapFactoryEnvironmentsOnce) {
+    try {
+        return 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 {
+            reaped: [],
+            retained: [],
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 async function flushProcessOutput() {
     await Promise.all([
         flushWritable(process.stdout),