@khorsheed/dsh-ankh-guard 0.3.2 → 0.4.1

package/lib/preflight-runner.js

@@ -26,6 +26,13 @@ import { pathToFileURL } from "node:url";
 *   activation — with the webserver port pinned to 0 (OS-assigned) so the
 *   dry-run never collides with the live instance;
 * - every registered client bundle artifact exists on disk;
+* - every registered agent preset is USABLE, not merely loaded: preset rows
+*   mount on the registry's standing scopes beside the profile tree, so a row
+*   whose module stopped resolving (a folded companion's retired package name,
+*   a base version predating its ./tool entry) never fails the boot itself —
+*   it fails every SESSION of that preset later (the picker shows 加载失败,
+*   resume answers "never started"; 3080, 2026-09-28). The audit reads the
+*   preset registry's own `broken` diagnostic back from the dry-run boot;
 * - dispose rolls every effect back.
 *
 * Exit codes (the contract the guard consumes):
@@ -293,6 +300,30 @@ function missingClientArtifacts(ctx) {
 	return missing;
 }
 /**
+* The preset-roster half of the verdict. A profile can boot clean while one
+* of its agent presets is BROKEN: preset rows mount on the registry's
+* standing scopes, not on the profile root the dry-run boots, so a row whose
+* module stopped resolving never fails the boot — it surfaces later as the
+* preset picker's 加载失败 badge and `resume failed … never started` on every
+* session of that preset (3080, 2026-09-28: the dev preset named
+* `@khorsheed/dsh-worktrees/tool` while the installed worktrees predated the
+* entry). The registry already computes this verdict: it activates every
+* registered preset eagerly and records a mount failure as `broken`, and its
+* `list()` re-audits mounted trees after the loader settles, so rows still
+* waiting on a host service report their pending reason instead of passing
+* silently. Fail the dry-run on any broken preset — the restart this gate
+* protects would serve those broken sessions. A host whose registry face is
+* absent or list-less degrades to no findings: the audit never invents one.
+*/
+async function brokenAgentPresets(ctx) {
+	const registry = ctx.get?.("agentPresets");
+	if (registry === void 0 || typeof registry.list !== "function") return [];
+	return (await registry.list()).flatMap((row) => row !== null && typeof row === "object" && typeof row.id === "string" && typeof row.broken === "string" ? [{
+		id: row.id,
+		broken: row.broken
+	}] : []);
+}
+/**
 * Boot the profile's full tree once, tear it down, and report the verdict on
 * the process streams. No HMR, no user-patch watchers, no signal wiring —
 * preflight is one-shot.
@@ -356,9 +387,12 @@ async function runPreflight(profile, patchFiles = [], root = resolveHarnessRoot(
 		});
 		appReady.commit();
 		const missing = missingClientArtifacts(ctx);
+		const brokenPresets = await brokenAgentPresets(ctx);
 		await ctx.fiber.dispose();
-		if (missing.length > 0) {
-			process.stderr.write(`preflight FAIL: profile ${JSON.stringify(profile)} boots but client bundle artifacts are missing or unreadable:\n${missing.map((line) => `  - ${line}`).join("\n")}\nrun \`pnpm run build\` before launch\n`);
+		if (missing.length > 0 || brokenPresets.length > 0) {
+			if (missing.length > 0) process.stderr.write(`preflight FAIL: profile ${JSON.stringify(profile)} boots but client bundle artifacts are missing or unreadable:\n${missing.map((line) => `  - ${line}`).join("\n")}\nrun \`pnpm run build\` before launch\n`);
+			if (brokenPresets.length > 0) process.stderr.write(`preflight FAIL: profile ${JSON.stringify(profile)} boots but ${brokenPresets.length} agent preset(s) are broken — every session on them fails to resume (the preset picker shows 加载失败):\n${brokenPresets.map((preset) => `  - ${preset.id}: ${preset.broken.split("\n").join("\n    ")}`).join("\n")}\nfix the named row (install the package it names, repoint a folded companion row to the core package's ./tool entry, or disable the row) or remove the preset, then re-run preflight
+`);
 			return 1;
 		}
 		process.stdout.write(`preflight PASS: profile ${JSON.stringify(profile)} boots clean\n`);
@@ -425,4 +459,4 @@ if (isDirectInvocation(import.meta.url)) {
 	process.exitCode = await runPreflight(profile, patchFiles, resolveHarnessRoot(), binding);
 }
 //#endregion
-export { composePreflightPatches, parsePreflightArgs, resolveHarnessRoot, runPreflight };
+export { brokenAgentPresets, composePreflightPatches, parsePreflightArgs, resolveHarnessRoot, runPreflight };

package/lib/types/cli.d.ts

@@ -19,6 +19,7 @@ interface CliOptions {
     delayMs: number | undefined;
     stopTimeoutMs: number | undefined;
     supervisorYieldTimeoutMs: number | undefined;
+    bootTimeoutMs: number | undefined;
     log: string | undefined;
     foreground: boolean;
     rollback: boolean;
@@ -61,6 +62,18 @@ export declare function parse(argv: readonly string[]): {
     positionals: readonly string[];
     options: CliOptions;
 };
+/**
+ * How the spawned watchdog should invoke the guard CLI. The executable is
+ * always the ABSOLUTE process.execPath, never a bare `node`: the watchdog runs
+ * under whatever PATH spawned it, and a launcher chain (launchd/systemd) has a
+ * minimal PATH without homebrew — a bare `node` there makes every guard
+ * invocation the watchdog issues (canary, record-proven-deployment, cutover
+ * events) fail with command-not-found (the 2026-09-30 launchd incident). The
+ * source form additionally needs tsx with an absolute path (the watchdog runs
+ * with a deployment cwd that resolves no node_modules).
+ * @returns the command prefix (verb args are appended by the watchdog).
+ */
+export declare function guardInvocation(): string;
 /**
  * How the guard invokes the dsh app's `preflight` mode: the source form runs
  * `node --import <repo>/node_modules/tsx/dist/esm/index.mjs <repo>/apps/cli/src/bin.ts`,

package/lib/types/cli.js

@@ -220,12 +220,14 @@ commands:
           [--home DIR] [--repo DIR] [--harness-root DIR] [--profile NAME] [--browser-handoff required|off]
           --preflight-surface source|built [--preflight-runner FILE] --preflight-install-anchor FILE
           --candidate-probe-command "CMD"
-          [--transition-file FILE] [--delay-ms MS] [--supervisor-yield-timeout-ms MS] [--preflight-timeout-ms MS] [--state-dir DIR]
+          [--transition-file FILE] [--delay-ms MS] [--supervisor-yield-timeout-ms MS] [--preflight-timeout-ms MS]
+          [--boot-timeout-ms MS] [--state-dir DIR]
   restart --port N --start "CMD" [--pid PID] [--timeout-ms MS] [--delay-ms MS] [--stop-timeout-ms MS] [--rollback]
           [--profile NAME] [--harness-root DIR] [--preflight-timeout-ms MS] [--state-dir DIR] [--repo DIR] [--max-age MIN]
   schedule-exit [--port N] --delay-ms MS [--initiator ID] [--log FILE] [--profile NAME]
-          [--harness-root DIR] [--preflight-timeout-ms MS] [--state-dir DIR] [--repo DIR]
+          [--harness-root DIR] [--preflight-timeout-ms MS] [--boot-timeout-ms MS] [--state-dir DIR] [--repo DIR]
   supervise --port N --start "CMD" [--foreground] [--log FILE] [--state-dir DIR] [--repo DIR] [--harness-root DIR] [--home DIR]
+          [--cutover-id ID] [--boot-timeout-ms MS]
 flags:
   --state-dir DIR  state directory (default: $DSH_HOME/state, else <cwd>/.dsh-guard-state)
   --repo DIR       repository the credential binds to (default: cwd)
@@ -252,6 +254,16 @@ flags:
                    (agent-driven graceful self-restart: schedule, complete, then restart);
                    schedule-exit: delay before the detached exit agent kills the host;
                    reconfigure: grace after successor supervisor claim before old-child stop
+  --boot-timeout-ms MS  reconfigure/schedule-exit/supervise: readiness budget for one
+                   boot (the watchdog's WD_BOOT_TIMEOUT, whole seconds, default 60).
+                   reconfigure/supervise hand it to the spawned watchdog's environment;
+                   schedule-exit records it in the restart marker for the respawn's boot
+                   window only (the running watchdog then falls back to its own budget)
+  --cutover-id ID  supervise: resume the durable launch-cutover transaction after its
+                   supervisor chain died (the id is in launch-status / the receipt);
+                   without it a bare supervise on an awaiting-user receipt only holds
+                   the claim and consumes operator control markers, never booting the
+                   rejected side
   --log FILE       supervise (detached only — with --foreground the external supervisor's
                    redirection owns the log) / schedule-exit: log file (default: <state-dir>/*.log)
   --home DIR       supervise: the dsh home the supervised instance boots with (profiles,
@@ -293,6 +305,7 @@ export function parse(argv) {
     const options = {
         stateDir: '', repoDir: '', harnessRoot: '', home: '', maxAgeMinutes: 10, port: undefined, command: undefined, run: false, runArgv: undefined, message: undefined, detail: undefined,
         start: undefined, pid: undefined, timeoutMs: undefined, delayMs: undefined, stopTimeoutMs: undefined, supervisorYieldTimeoutMs: undefined,
+        bootTimeoutMs: undefined,
         log: undefined,
         foreground: false, rollback: false, force: false, sync: false, initiator: undefined, profile: undefined, preflightTimeoutMs: undefined,
         preflightSurface: undefined, preflightRunner: undefined, preflightInstallAnchor: undefined, candidateProbeCommand: undefined,
@@ -418,6 +431,17 @@ export function parse(argv) {
                     i++;
                     break;
                 }
+                case '--boot-timeout-ms': {
+                    const raw = flagValue(arg, true);
+                    const n = Number(raw);
+                    // The wrapper's budget is whole seconds; sub-second values are
+                    // rejected rather than silently rounded away.
+                    if (raw === undefined || !Number.isInteger(n) || n < 1000)
+                        throw new Error('--boot-timeout-ms must be an integer >= 1000');
+                    options.bootTimeoutMs = n;
+                    i++;
+                    break;
+                }
                 case '--foreground':
                     options.foreground = true;
                     break;
@@ -586,12 +610,17 @@ function verifyRepoCredential(stateDir, repoDir, maxAgeMinutes) {
     return verifyCredential(loadState(stateDir), currentHead(repoDir), Date.now(), maxAgeMinutes, isWorkingTreeClean(repoDir));
 }
 /**
- * How the spawned watchdog should invoke the guard CLI: the built form runs
- * `node <cli>`; the source form needs tsx with an absolute path (the watchdog
- * runs with a deployment cwd that resolves no node_modules).
+ * How the spawned watchdog should invoke the guard CLI. The executable is
+ * always the ABSOLUTE process.execPath, never a bare `node`: the watchdog runs
+ * under whatever PATH spawned it, and a launcher chain (launchd/systemd) has a
+ * minimal PATH without homebrew — a bare `node` there makes every guard
+ * invocation the watchdog issues (canary, record-proven-deployment, cutover
+ * events) fail with command-not-found (the 2026-09-30 launchd incident). The
+ * source form additionally needs tsx with an absolute path (the watchdog runs
+ * with a deployment cwd that resolves no node_modules).
  * @returns the command prefix (verb args are appended by the watchdog).
  */
-function guardInvocation() {
+export function guardInvocation() {
     const cliPath = fileURLToPath(import.meta.url);
     if (cliPath.includes(`${sep}src${sep}`)) {
         // Source form: locate the tsx loader relative to this file's own
@@ -600,10 +629,10 @@ function guardInvocation() {
         const nodeModules = resolve(dirname(cliPath), '../../../node_modules');
         const tsx = join(nodeModules, 'tsx', 'dist', 'esm', 'index.mjs');
         if (existsSync(tsx))
-            return `node --import ${tsx} ${cliPath}`;
-        return `node ${cliPath}`;
+            return `${process.execPath} --import ${tsx} ${cliPath}`;
+        return `${process.execPath} ${cliPath}`;
     }
-    return `node ${cliPath}`;
+    return `${process.execPath} ${cliPath}`;
 }
 /**
  * argv (after process.execPath) that runs the exit agent, with the same
@@ -1540,7 +1569,7 @@ export async function runCli(argv, io) {
             }
             const watchdogPid = liveWatchdogPid(stateDir);
             if (watchdogPid === null) {
-                io.stderr(`${command} refused: no live watchdog can consume the durable control request\n`);
+                io.stderr(`${command} refused: no live watchdog can consume the durable control request. Start the consumer first: \`supervise --state-dir ${stateDir}\` holds the awaiting-user cutover ${transaction.receipt.id} without launching anything, or \`supervise --cutover-id ${transaction.receipt.id} --state-dir ${stateDir}\` resumes the selected side directly\n`);
                 return 1;
             }
             const requested = command === 'restore-previous' ? 'restore-previous' : 'abort';
@@ -1873,20 +1902,34 @@ export async function runCli(argv, io) {
             const snapshotStartedAt = Date.now();
             let snapshot;
             try {
+                // The copy runs synchronously before any stop; without progress output
+                // a multi-GB prepare looked exactly like a hang (2026-09-27: 848 s of
+                // silence dragging the host checkout's node_modules into the snapshot).
+                let lastProgressAt = 0;
+                const onProgress = (progress) => {
+                    const now = Date.now();
+                    if (now - lastProgressAt < 2000)
+                        return;
+                    lastProgressAt = now;
+                    io.stdout(`preflight snapshot: ${progress.files} files / ${Math.round(progress.bytes / 1024 / 1024)} MB copied…\n`);
+                };
                 snapshot = transitionPlan === undefined
-                    ? createPreflightSnapshot(target.home)
-                    : createTransitionPreflightSnapshot(transitionPlan);
+                    ? createPreflightSnapshot(target.home, { onProgress })
+                    : createTransitionPreflightSnapshot(transitionPlan, { onProgress });
             }
             catch (error) {
                 return refuse('preflight-snapshot', `reconfigure refused: could not prepare an isolated${transitionPlan === undefined ? '' : ' transitioned'} home: ${String(error)}\n`);
             }
             // A large home copy eats the credential's freshness window: the post-boot
             // canary revalidates the same credential, so a slow prepare can expire it
-            // mid-cutover and force a restore (observed with a 24 GB scratch tree —
-            // scratch/ is now excluded; warn early when the remaining copy is slow).
+            // mid-cutover and force a restore (observed with a 24 GB scratch tree).
+            // The snapshot copies only the composition's boot inputs
+            // (SNAPSHOT_INCLUDED_TOP_LEVEL), so size tracks the host's boot surface —
+            // warn when it still comes in slow.
             const snapshotMs = Date.now() - snapshotStartedAt;
+            io.stdout(`isolated home snapshot ready: ${snapshot.copiedFiles} files / ${Math.round(snapshot.copiedBytes / 1024 / 1024)} MB in ${Math.round(snapshotMs / 1000)}s\n`);
             if (snapshotMs > options.maxAgeMinutes * 60_000 / 2) {
-                io.stdout(`note: the isolated-home snapshot took ${Math.round(snapshotMs / 1000)}s — over half the ${options.maxAgeMinutes}min credential window; re-record the credential immediately before reconfigure, and keep the home slim (top-level scratch/ is excluded from the copy)\n`);
+                io.stdout(`note: the isolated-home snapshot took ${Math.round(snapshotMs / 1000)}s — over half the ${options.maxAgeMinutes}min credential window; re-record the credential immediately before reconfigure\n`);
             }
             try {
                 const timeout = options.preflightTimeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS;
@@ -1956,6 +1999,9 @@ export async function runCli(argv, io) {
                     '--takeover-from', String(previousSupervisorPid), '--cutover-id', cutoverId,
                     '--delay-ms', String(options.delayMs ?? 5000),
                     '--supervisor-yield-timeout-ms', String(options.supervisorYieldTimeoutMs ?? 15_000),
+                    // The successor watchdog's readiness budget rides the driver argv;
+                    // the durable spec stays free of per-restart tuning.
+                    ...(options.bootTimeoutMs !== undefined ? ['--boot-timeout-ms', String(options.bootTimeoutMs)] : []),
                     ...(initiator !== undefined ? ['--initiator', initiator] : []),
                 ];
                 const cutoverDriverEnv = { ...process.env };
@@ -2218,10 +2264,21 @@ export async function runCli(argv, io) {
                 io.stderr(`supervise refused: cutover ${options.cutoverId} is not the selected launch transaction\n`);
                 return 1;
             }
+            // A receipt parked in awaiting-user must never auto-boot the rejected
+            // side — but exiting here leaves NO live consumer for the operator
+            // control markers, and abort-cutover/restore-previous then refuse with
+            // "no live watchdog" (the 2026-09-30 mid-cutover wedge). Hold instead:
+            // spawn the watchdog in its parked mode, which claims the pidfile and
+            // consumes those markers without launching anything.
+            let parkedCutover = false;
             if (options.cutoverId === undefined && transaction?.receipt.phase === 'awaiting-user') {
-                io.stderr(`supervise: cutover ${transaction.receipt.id} is waiting for user action; refusing to restart the rejected target automatically (receipt ${stateFile(stateDir, 'launchCutover')})\n`);
-                return 0;
+                parkedCutover = true;
             }
+            // An explicit --cutover-id resume against a live PARKED holder: the
+            // driver-started event below flips the receipt out of awaiting-user,
+            // which is the hold's release signal. Remember the entry phase so the
+            // pidfile branch below knows the live owner is expected to let go.
+            const resumeFromAwaitingUser = options.cutoverId !== undefined && transaction?.receipt.phase === 'awaiting-user';
             // A detached watchdog spawned from a sandboxed turn is reaped with it —
             // refuse before claiming anything. Foreground mode is driven by the
             // external supervisor (launchd/systemd) and stays exempt.
@@ -2277,7 +2334,30 @@ export async function runCli(argv, io) {
                             }
                             if (durable === null)
                                 writeStableLaunchSpec(stateDir, spec);
-                            if (options.foreground) {
+                            if (resumeFromAwaitingUser) {
+                                // The live owner is the awaiting-user hold (or a wrapper still
+                                // parked on its crash page). The hold releases its claim as
+                                // soon as the driver-started event above flips the receipt out
+                                // of awaiting-user — wait for that release, bounded: an owner
+                                // that keeps the claim is not the hold, and waiting behind it
+                                // forever would wedge the explicit resume it never sees.
+                                const existingIdentity = processIdentity(existingPid);
+                                if (existingIdentity === null) {
+                                    io.stderr(`supervise refused: could not capture watchdog ${existingPid} start identity before waiting\n`);
+                                    return 1;
+                                }
+                                io.stdout(`watchdog ${existing} holds the parked cutover — waiting for it to release, then resuming\n`);
+                                const releaseDeadline = Date.now() + 15_000;
+                                while (processIdentityMatches(existingIdentity) && Date.now() < releaseDeadline)
+                                    await sleep(250);
+                                if (processIdentityMatches(existingIdentity)) {
+                                    io.stderr(`supervise refused: watchdog ${existingPid} did not release the parked cutover ${options.cutoverId ?? ''} within 15000 ms — it is not the awaiting-user hold; settle the transaction with \`abort-cutover --state-dir ${stateDir}\` or \`restore-previous --state-dir ${stateDir}\`, or stop that watchdog and retry\n`);
+                                    return 1;
+                                }
+                                waitedForWatchdog = true;
+                                io.stdout(`watchdog ${existing} released the parked cutover — resuming\n`);
+                            }
+                            else if (options.foreground) {
                                 // Foreground = an external supervisor (launchd KeepAlive) runs
                                 // THIS process. Exiting 0 here would read as an intentional stop
                                 // under `KeepAlive SuccessfulExit: false`, so the job would go
@@ -2320,8 +2400,10 @@ export async function runCli(argv, io) {
                     return 1;
                 }
                 if (options.cutoverId === undefined && transaction?.receipt.phase === 'awaiting-user') {
-                    io.stderr(`supervise: cutover ${transaction.receipt.id} settled awaiting-user while this supervisor waited; refusing to restart the rejected target (receipt ${stateFile(stateDir, 'launchCutover')})\n`);
-                    return 0;
+                    // Settled into awaiting-user while this supervisor waited behind the
+                    // old owner: park exactly like the entry check above instead of
+                    // booting the rejected target — or exiting and leaving no consumer.
+                    parkedCutover = true;
                 }
                 io.stdout('launch state refreshed after wait — using the durable selected specification\n');
             }
@@ -2398,6 +2480,11 @@ export async function runCli(argv, io) {
                 // adoption; the detached form waits for the current owner to exit.
                 WD_WAIT_OWNER: options.takeoverFrom !== undefined || !options.foreground ? '1' : '0',
                 WD_GUARD: guardInvocation(),
+                // One boot's readiness budget, in the wrapper's whole-seconds unit.
+                // Ceiling: never round a requested budget DOWN into a tighter window.
+                ...(options.bootTimeoutMs !== undefined
+                    ? { WD_BOOT_TIMEOUT: String(Math.ceil(options.bootTimeoutMs / 1000)) }
+                    : {}),
                 ...(options.takeoverFrom !== undefined ? {
                     WD_TAKEOVER_FROM: String(options.takeoverFrom),
                     WD_TAKEOVER_FROM_START: previousSupervisorStart ?? '',
@@ -2418,11 +2505,18 @@ export async function runCli(argv, io) {
                     WD_PREVIOUS_CHILD_START: previousOwnership.childStartToken,
                     WD_PREVIOUS_LISTENER_PID: String(previousOwnership.listenerPid),
                     WD_PREVIOUS_LISTENER_START: previousOwnership.listenerStartToken,
+                    // Parked hold: claim supervision and consume operator control
+                    // markers, but never launch — the receipt's selected side was
+                    // explicitly rejected and waits for a user decision.
+                    ...(parkedCutover ? { WD_CUTOVER_PARKED: '1' } : {}),
                     ...(transaction.state.transition === undefined ? {} : {
                         WD_TRANSITION_PLAN_SHA256: transaction.state.transition.planSha256,
                     }),
                 } : {}),
             };
+            if (parkedCutover && transaction !== null) {
+                io.stdout(`supervise: cutover ${transaction.receipt.id} is waiting for user action — holding the supervision claim WITHOUT launching the rejected ${transaction.state.selected} side (receipt ${stateFile(stateDir, 'launchCutover')}). The operator verbs now have a live consumer: \`abort-cutover --state-dir ${stateDir}\` applies the pre-approved ${transaction.receipt.recovery.policy} policy, \`restore-previous --state-dir ${stateDir}\` restores the complete previous spec. To end the hold without settling: write the stop marker (\`touch ${stateFile(stateDir, 'watchdogStop')}\`). To resume the rejected side: \`supervise --cutover-id ${transaction.receipt.id} --state-dir ${stateDir}\`\n`);
+            }
             if (options.foreground) {
                 // Run the watchdog inline: the CLI process stays alive as the
                 // watchdog's parent, so an external supervisor (launchd KeepAlive)
@@ -2460,7 +2554,9 @@ export async function runCli(argv, io) {
             const claimDeadline = Date.now() + 5_000;
             while (Date.now() < claimDeadline && spawnError === undefined) {
                 if (liveWatchdogPid(stateDir) === spawnedPid) {
-                    io.stdout(`watchdog spawned and ready (pid ${spawnedPid}) — supervises :${spec.port}, log ${logPath}\n`);
+                    io.stdout(parkedCutover && transaction !== null
+                        ? `watchdog spawned and parked on cutover ${transaction.receipt.id} (pid ${spawnedPid}) — nothing launched; consuming abort-cutover/restore-previous markers; log ${logPath}\n`
+                        : `watchdog spawned and ready (pid ${spawnedPid}) — supervises :${spec.port}, log ${logPath}\n`);
                     return 0;
                 }
                 try {
@@ -2570,6 +2666,10 @@ export async function runCli(argv, io) {
                 writeFileSync(stateFile(stateDir, 'restartRequested'), `${JSON.stringify({
                     reason: 'scheduled self-restart',
                     requestedAt: Date.now(),
+                    // A one-boot readiness budget for the respawn: the live watchdog
+                    // applies it over its own WD_BOOT_TIMEOUT for boots attempted
+                    // while this marker is pending, then falls back to its default.
+                    ...(options.bootTimeoutMs === undefined ? {} : { bootTimeoutMs: options.bootTimeoutMs }),
                     ...(gate.authorization === undefined ? {} : { authorization: gate.authorization }),
                     ...(initiator !== undefined ? { initiator } : {}),
                 })}\n`);

package/lib/types/preflight-runner.d.ts

@@ -19,6 +19,13 @@
  *   activation — with the webserver port pinned to 0 (OS-assigned) so the
  *   dry-run never collides with the live instance;
  * - every registered client bundle artifact exists on disk;
+ * - every registered agent preset is USABLE, not merely loaded: preset rows
+ *   mount on the registry's standing scopes beside the profile tree, so a row
+ *   whose module stopped resolving (a folded companion's retired package name,
+ *   a base version predating its ./tool entry) never fails the boot itself —
+ *   it fails every SESSION of that preset later (the picker shows 加载失败,
+ *   resume answers "never started"; 3080, 2026-09-28). The audit reads the
+ *   preset registry's own `broken` diagnostic back from the dry-run boot;
  * - dispose rolls every effect back.
  *
  * Exit codes (the contract the guard consumes):
@@ -91,6 +98,26 @@ export interface PreflightComposition {
  * @returns the patch stack and composed rows.
  */
 export declare function composePreflightPatches(profile: string, patchFiles: readonly string[], root: string, home?: string, binding?: PreflightHostBinding): Promise<PreflightComposition>;
+/**
+ * The preset-roster half of the verdict. A profile can boot clean while one
+ * of its agent presets is BROKEN: preset rows mount on the registry's
+ * standing scopes, not on the profile root the dry-run boots, so a row whose
+ * module stopped resolving never fails the boot — it surfaces later as the
+ * preset picker's 加载失败 badge and `resume failed … never started` on every
+ * session of that preset (3080, 2026-09-28: the dev preset named
+ * `@khorsheed/dsh-worktrees/tool` while the installed worktrees predated the
+ * entry). The registry already computes this verdict: it activates every
+ * registered preset eagerly and records a mount failure as `broken`, and its
+ * `list()` re-audits mounted trees after the loader settles, so rows still
+ * waiting on a host service report their pending reason instead of passing
+ * silently. Fail the dry-run on any broken preset — the restart this gate
+ * protects would serve those broken sessions. A host whose registry face is
+ * absent or list-less degrades to no findings: the audit never invents one.
+ */
+export declare function brokenAgentPresets(ctx: unknown): Promise<Array<{
+    id: string;
+    broken: string;
+}>>;
 /**
  * Boot the profile's full tree once, tear it down, and report the verdict on
  * the process streams. No HMR, no user-patch watchers, no signal wiring —

package/lib/types/preflight-runner.js

@@ -19,6 +19,13 @@
  *   activation — with the webserver port pinned to 0 (OS-assigned) so the
  *   dry-run never collides with the live instance;
  * - every registered client bundle artifact exists on disk;
+ * - every registered agent preset is USABLE, not merely loaded: preset rows
+ *   mount on the registry's standing scopes beside the profile tree, so a row
+ *   whose module stopped resolving (a folded companion's retired package name,
+ *   a base version predating its ./tool entry) never fails the boot itself —
+ *   it fails every SESSION of that preset later (the picker shows 加载失败,
+ *   resume answers "never started"; 3080, 2026-09-28). The audit reads the
+ *   preset registry's own `broken` diagnostic back from the dry-run boot;
  * - dispose rolls every effect back.
  *
  * Exit codes (the contract the guard consumes):
@@ -377,6 +384,31 @@ function missingClientArtifacts(ctx) {
     }
     return missing;
 }
+/**
+ * The preset-roster half of the verdict. A profile can boot clean while one
+ * of its agent presets is BROKEN: preset rows mount on the registry's
+ * standing scopes, not on the profile root the dry-run boots, so a row whose
+ * module stopped resolving never fails the boot — it surfaces later as the
+ * preset picker's 加载失败 badge and `resume failed … never started` on every
+ * session of that preset (3080, 2026-09-28: the dev preset named
+ * `@khorsheed/dsh-worktrees/tool` while the installed worktrees predated the
+ * entry). The registry already computes this verdict: it activates every
+ * registered preset eagerly and records a mount failure as `broken`, and its
+ * `list()` re-audits mounted trees after the loader settles, so rows still
+ * waiting on a host service report their pending reason instead of passing
+ * silently. Fail the dry-run on any broken preset — the restart this gate
+ * protects would serve those broken sessions. A host whose registry face is
+ * absent or list-less degrades to no findings: the audit never invents one.
+ */
+export async function brokenAgentPresets(ctx) {
+    const registry = ctx.get?.('agentPresets');
+    if (registry === undefined || typeof registry.list !== 'function')
+        return [];
+    const rows = await registry.list();
+    return rows.flatMap(row => row !== null && typeof row === 'object' && typeof row.id === 'string' && typeof row.broken === 'string'
+        ? [{ id: row.id, broken: row.broken }]
+        : []);
+}
 /**
  * Boot the profile's full tree once, tear it down, and report the verdict on
  * the process streams. No HMR, no user-patch watchers, no signal wiring —
@@ -462,11 +494,20 @@ export async function runPreflight(profile, patchFiles = [], root = resolveHarne
         // that point.
         appReady.commit();
         const missing = missingClientArtifacts(ctx);
+        // The registry settles pending rows against the finished loader tree, so
+        // the audit runs after boot completion and before dispose.
+        const brokenPresets = await brokenAgentPresets(ctx);
         // A repeated dispose returns the settled single-shot result when boot
         // already tore the tree down, so this is safe on every path.
         await ctx.fiber.dispose();
-        if (missing.length > 0) {
-            process.stderr.write(`preflight FAIL: profile ${JSON.stringify(profile)} boots but client bundle artifacts are missing or unreadable:\n${missing.map(line => `  - ${line}`).join('\n')}\nrun \`pnpm run build\` before launch\n`);
+        if (missing.length > 0 || brokenPresets.length > 0) {
+            if (missing.length > 0) {
+                process.stderr.write(`preflight FAIL: profile ${JSON.stringify(profile)} boots but client bundle artifacts are missing or unreadable:\n${missing.map(line => `  - ${line}`).join('\n')}\nrun \`pnpm run build\` before launch\n`);
+            }
+            if (brokenPresets.length > 0) {
+                process.stderr.write(`preflight FAIL: profile ${JSON.stringify(profile)} boots but ${brokenPresets.length} agent preset(s) are broken — every session on them fails to resume (the preset picker shows 加载失败):\n${brokenPresets.map(preset => `  - ${preset.id}: ${preset.broken.split('\n').join('\n    ')}`).join('\n')}\n`
+                    + 'fix the named row (install the package it names, repoint a folded companion row to the core package\'s ./tool entry, or disable the row) or remove the preset, then re-run preflight\n');
+            }
             return 1;
         }
         process.stdout.write(`preflight PASS: profile ${JSON.stringify(profile)} boots clean\n`);

package/lib/types/transition.d.ts

@@ -94,24 +94,64 @@ export declare function rollbackTransition(reference: TransitionReference, expec
  */
 export declare function readTransitionRecord(reference: TransitionReference, expectedHome: string, stateDir: string, cutoverId: string): TransitionRecord;
 /**
- * Clone a live home while retaining a contained package-link graph. Internal
- * links are rebuilt against copied nodes; external targets are deduplicated in
- * a snapshot-owned materialization area. No retained link resolves outside the
- * snapshot root, so writes through pnpm/Cordis links cannot reach live bytes.
- * Runtime entries without copyable content (sockets, FIFOs — and links to
- * them) are skipped and counted, never copied; the top-level scratch/ tree is
- * excluded for size. Device nodes still fail closed.
+ * Top-level home entries the preflight snapshot copies — the ALLOWLIST of
+ * inputs the launcher's boot actually reads: the profile trees, the home-level
+ * patch layer, settings, and the credential/identity stores. Everything else
+ * (plugin data: sessions, state, local-agent sub-homes, tarballs, scratch, …)
+ * is excluded BY DEFAULT, so a newly installed plugin's data directory can
+ * never silently join the copy — this list moves only when the HOST's boot
+ * starts reading a new home input, and a miss fails the dry-run loudly with
+ * the missing path rather than degrading into a slow copy. The denylist this
+ * replaced failed twice the other way: a 24 GB scratch tree expired the
+ * credential mid-cutover (canary failed, restored), and on 2026-09-27 the
+ * local-agent sub-home's absolute links dragged the host checkout's entire
+ * node_modules into a ~4 GB / 848 s prepare.
+ */
+export declare const SNAPSHOT_INCLUDED_TOP_LEVEL: readonly string[];
+/** Copy progress, reported from the file branch of {@link copySnapshotNode}. */
+export interface SnapshotProgress {
+    files: number;
+    bytes: number;
+    skippedRuntimeEntries: number;
+}
+export interface PreflightSnapshotOptions {
+    /**
+     * Top-level home entries to copy (default: {@link SNAPSHOT_INCLUDED_TOP_LEVEL}).
+     * `createTransitionPreflightSnapshot` unions its plan's operation roots in.
+     */
+    includeTopLevel?: readonly string[];
+    /** Invoked as the copy advances; the caller throttles its own output. */
+    onProgress?: (progress: SnapshotProgress) => void;
+}
+/**
+ * Clone a live home's BOOT INPUTS while retaining a contained package-link
+ * graph. Only the allowlisted top-level entries are copied (see
+ * {@link SNAPSHOT_INCLUDED_TOP_LEVEL}) — plugin data directories are excluded
+ * by default, so the copy's size is bounded by what the composition's boot
+ * reads, not by whatever the home happens to hold. Internal links are rebuilt
+ * against copied nodes; external targets are deduplicated in a snapshot-owned
+ * materialization area. No retained link resolves outside the snapshot root,
+ * so writes through pnpm/Cordis links cannot reach live bytes. Runtime entries
+ * without copyable content (sockets, FIFOs — and links to them) are skipped
+ * and counted, never copied. Device nodes still fail closed.
  * @param sourceHome - Live dsh home to read.
- * @returns Isolated home, an idempotent cleanup callback, and the count of skipped runtime entries.
+ * @param options - Include-list override and progress callback.
+ * @returns Isolated home, an idempotent cleanup callback, and copy statistics.
  */
-export declare function createPreflightSnapshot(sourceHome: string): {
+export declare function createPreflightSnapshot(sourceHome: string, options?: PreflightSnapshotOptions): {
     home: string;
     root: string;
     skippedRuntimeEntries: number;
+    copiedFiles: number;
+    copiedBytes: number;
     cleanup(): void;
 };
-export declare function createTransitionPreflightSnapshot(plan: TransitionPlan): {
+export declare function createTransitionPreflightSnapshot(plan: TransitionPlan, options?: PreflightSnapshotOptions): {
     home: string;
+    root: string;
+    skippedRuntimeEntries: number;
+    copiedFiles: number;
+    copiedBytes: number;
     cleanup(): void;
 };
 export {};