@khorsheed/dsh-ankh-guard 0.3.2 → 0.4.0

package/README.en.md

@@ -6,7 +6,7 @@ Let an agent change its own code and restart its own service — without taking
 
 When the agent wants to restart after editing code, this plugin asks one question first: did the build and tests pass? Yes, go ahead. No, blocked — so broken code can't take the service, and the conversation running inside it, down with it.
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/ankh-guard.JPG" width="640" alt="a guarded restart: the agent announces its verification plan beforehand, and the canary reactivates the session afterwards to keep verifying">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/ankh-guard.JPG" width="640" alt="a guarded restart: the agent announces its verification plan beforehand, and the canary reactivates the session afterwards to keep verifying">
 
 ## How it works
 
@@ -79,7 +79,7 @@ Full commands: `verify`, `record`, `status`, `clear`, `checkpoint`, `reset`, `ca
 
 ### preflight: the composition gate
 
-`preflight` deep-dry-runs the exact composition a restart would boot: it composes the profile's full patch stack through the same path as the real launcher (bundle layers, user layers, overlays), boots the **whole plugin tree** in a subprocess through the same engine — every plugin's apply runs, because apply is activation — with an overlay pinning the webserver port to 0 (OS-assigned, so it never collides with the live instance), checks every registered client bundle artifact exists, and disposes (registrations are effects, so dispose rolls the dry-run back). Exit codes are the contract:
+`preflight` deep-dry-runs the exact composition a restart would boot: it composes the profile's full patch stack through the same path as the real launcher (bundle layers, user layers, overlays), boots the **whole plugin tree** in a subprocess through the same engine — every plugin's apply runs, because apply is activation — with an overlay pinning the webserver port to 0 (OS-assigned, so it never collides with the live instance), checks every registered client bundle artifact exists, and reads back the agent preset registry's `broken` diagnostic (preset rows mount on the registry's standing scopes, not the profile root, so **a clean boot does not imply a usable preset**: a broken preset shows 加载失败 in the picker and its sessions fail resume with `never started` — 3080 hit exactly that on 2026-09-28 with the dry-run green all the way), and disposes (registrations are effects, so dispose rolls the dry-run back). Exit codes are the contract:
 
 - `0` — the composition boots clean.
 - `1` — a composition verdict: the tree a restart would boot is broken; the output names the failing layer.
@@ -139,7 +139,7 @@ For a protected target, the watchdog accepts a launch URL only from the final pr
 
 When a candidate cannot read a reconstructible projection or cache left by the previous host, `--transition-file` can submit a reviewed schema-v1 quarantine plan. A plan accepts only non-overlapping, symlink-free paths below `home` that exclude guard state, with an explicit `quarantine` operation; it contains no host-version or filename knowledge. Example: `{"schemaVersion":1,"home":"/absolute/dsh-home","operations":[{"kind":"quarantine","path":"storages/<reconstructible-cache>","expect":"present"}]}`. Each `expect` is `present` or `absent`; isolated preflight and live apply must observe that same state or refuse before previous stops or target starts. The plan must cover both old paths that need to leave before target starts and new output paths that must leave before previous can recover after a target failure; list the latter explicitly with `expect: "absent"` even when they do not exist at preparation. Do not use this mechanism for authoritative logs, credentials, or irreplaceable data. Formats that require content transformation need a separate reversible migration tool and review.
 
-The guard first copies the live home's physical files with copy-on-write preference, then rebuilds pnpm/Cordis links as relative links whose targets are snapshot-owned copies; legitimate internal dependency cycles remain intact. External targets enter a hash-named, deduplicated materialization area inside the snapshot. A linked `node_modules` target brings its ancestor resolution layer once so Node's package lookup semantics survive. A post-copy `realpath` audit requires every writable link target to remain under the snapshot root. Runtime entries without copyable semantics (sockets, FIFOs, and links to them) are skipped and counted, and the top-level `scratch/` tree never joins the copy; dangling or unresolvable links, any other special files, writable escapes, and read/copy failures make `reconfigure` fail closed before it runs the candidate, creates a cutover, or stops previous. It then applies the same quarantine and runs target composition preflight in that safe copy. If the copy cannot be prepared or the target does not boot, previous keeps serving and the live home stays unchanged. Only after the successor owns supervision and has stopped and revalidated the previous process tree does it apply the hash-bound durable plan with same-filesystem renames. If the target is rejected, the watchdog first stops its proven process, retains replacements it created at transitioned paths under `launch-transitions/<cutover>/rejected-target/`, restores the exact previous bytes and records the result, and only then permits previous to start. Any unproven step parks at `awaiting-user` instead of exposing previous to mixed state. After target success, the quarantined previous content remains in the cutover directory for operator disposition; it is never deleted automatically.
+The guard first copies the live home's boot inputs with copy-on-write preference — the allowlist is `profiles/`, the home-level `cordis.patch.yml`, `settings.yaml`, `.credentials.yaml`, and `.anonymous-user-id`; plugin data directories (sessions, state, local-agent sub-homes, tarballs, scratch, …) are excluded by default, so a newly installed plugin's data never silently grows the snapshot, and the list only moves when the host's boot starts reading a new home input (a miss fails the preflight loudly instead of slowing the copy down). It then rebuilds pnpm/Cordis links as relative links whose targets are snapshot-owned copies; legitimate internal dependency cycles remain intact. External targets enter a hash-named, deduplicated materialization area inside the snapshot. A linked `node_modules` target anchors at the package's own parent `node_modules` — the tightest scope that preserves Node's ancestor lookup — rather than the whole store root. A post-copy `realpath` audit requires every writable link target to remain under the snapshot root. Runtime entries without copyable semantics (sockets, FIFOs, and links to them) are skipped and counted; dangling or unresolvable links, any other special files, writable escapes, and read/copy failures make `reconfigure` fail closed before it runs the candidate, creates a cutover, or stops previous. It then applies the same quarantine and runs target composition preflight in that safe copy. If the copy cannot be prepared or the target does not boot, previous keeps serving and the live home stays unchanged. Only after the successor owns supervision and has stopped and revalidated the previous process tree does it apply the hash-bound durable plan with same-filesystem renames. If the target is rejected, the watchdog first stops its proven process, retains replacements it created at transitioned paths under `launch-transitions/<cutover>/rejected-target/`, restores the exact previous bytes and records the result, and only then permits previous to start. Any unproven step parks at `awaiting-user` instead of exposing previous to mixed state. After target success, the quarantined previous content remains in the cutover directory for operator disposition; it is never deleted automatically.
 
 **The restart report reaches the model by itself — and waits for its owner.** After a scheduled restart (a pending `last-restart.json` record), the plugin queues the report as the next turn via `agent.followup` — the official wake-the-agent seam the schedule system uses for reminders — so the agent reports the restart result without any user message. Session restore after a restart is lazy (an agent is created only when the UI or an RPC touches the session), so the report goes ONLY to the session that scheduled the exit (`schedule-exit` records `$DSH_SESSION_ID` as the initiator), whenever it resumes — no other session is ever woken for reporting, and the record stays pending until its owner resumes or the next restart replaces it (new `exitAt`). A record without an initiator is claimed by the first root agent created. Only root agents, once (acknowledged on delivery). Config `reportRestartContext`: `followup` (default, autonomous), `step` (ride the first step of whatever turn comes next), or `off`.
 

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # last confirmed-consistent state. Both languages carry equal authority; after
 # editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/ankh-guard/README.en.md
-packages/ankh-guard/README.en.md: 1503f247dbba22fb64d0d5988225a06ee2e49c9d
-packages/ankh-guard/README.md: 90693789e64935abff5fb1d7fbbf5d4807c19a99
+packages/ankh-guard/README.en.md: 998372daf4877938983f5272038b236957dbd964
+packages/ankh-guard/README.md: 6fc053dfb906a7875e5172d40b972d16b8578216

package/README.md

@@ -6,7 +6,7 @@
 
 agent 改完代码想重启的时候，这个插件会先问一句：这次改动，构建和测试都过了吗？过了才放行，没过就拦下来——免得改坏的代码把整个服务、连同正在进行的对话一起带走。
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/ankh-guard.JPG" width="640" alt="一次受守护的重启:重启前告知验证项,重启后金丝雀自动激活会话并注入上下文继续验证">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/ankh-guard.JPG" width="640" alt="一次受守护的重启:重启前告知验证项,重启后金丝雀自动激活会话并注入上下文继续验证">
 
 ## 工作原理
 
@@ -79,7 +79,7 @@ dsh-ankh-guard reconfigure --start "NEW CMD" --repo "<credential repo>" \
 
 ### preflight: the composition gate
 
-`preflight` 对重启将要 boot 的组合做完全一致的深度干跑：走与真实 launcher 相同的路径组装 profile 的全部 patch 层（bundle 层、用户层、overlay），在子进程里用同一个引擎 boot **整棵插件树**——每个插件的 apply 都真实执行，因为 apply 即激活——同时用 overlay 把 webserver 端口钉到 0（操作系统分配，绝不与在跑实例抢端口），检查每个已注册 client bundle 产物存在，然后 dispose（注册即 effect，dispose 即回滚这次干跑）。退出码即契约：
+`preflight` 对重启将要 boot 的组合做完全一致的深度干跑：走与真实 launcher 相同的路径组装 profile 的全部 patch 层（bundle 层、用户层、overlay），在子进程里用同一个引擎 boot **整棵插件树**——每个插件的 apply 都真实执行，因为 apply 即激活——同时用 overlay 把 webserver 端口钉到 0（操作系统分配，绝不与在跑实例抢端口），检查每个已注册 client bundle 产物存在，并回读 agent preset 注册表的 `broken` 诊断（preset 行挂在注册表的 standing scope 上而不是 profile 根，**boot 干净不代表 preset 可用**：坏 preset 的选择器卡片显示「加载失败」、其会话 resume 报 `never started`——3080 在 2026-09-28 撞过一次，干跑一路全绿），然后 dispose（注册即 effect，dispose 即回滚这次干跑）。退出码即契约：
 
 - `0`——组合干净通过。
 - `1`——组合结论：重启将要 boot 的树是坏的；输出会指明坏在哪一层。
@@ -139,7 +139,7 @@ dsh-ankh-guard reconfigure \
 
 candidate 无法读取旧宿主留下的可重建投影或缓存时，`--transition-file` 可以提交一份经过评审的 schema-v1 隔离计划。计划只接受 `home` 下互不重叠、没有符号链接且不包含 guard state 的相对路径，以及显式的 `quarantine` 操作；它不内置任何宿主版本或文件名知识。示例：`{"schemaVersion":1,"home":"/absolute/dsh-home","operations":[{"kind":"quarantine","path":"storages/<可重建缓存>","expect":"present"}]}`。每项 `expect` 必须是 `present` 或 `absent`，副本 preflight 与 live apply 都必须观察到相同状态，否则在停 previous 前或启动 target 前拒绝。计划既要覆盖 target 启动前必须移开的旧路径，也要覆盖 target 失败后 previous 启动前必须清走的新输出路径；后者即使准备时不存在也必须用 `expect: "absent"` 显式列出。权威日志、凭据或不可重建数据不得借此移出；需要内容转换的格式应使用独立、可逆且另行评审的迁移工具。
 
-guard 先以 copy-on-write 优先方式复制 live home 的物理文件，再把 pnpm/Cordis 链接重建为只指向 snapshot 内副本的相对链接；合法的内部依赖循环保留。外部目标进入 snapshot 自己的哈希命名去重物化区，`node_modules` 目标连同其祖先解析层一次复制，避免破坏 Node 模块查找语义。复制后逐链接 `realpath` 审计，任何可写目标都必须仍在 snapshot 根内；无可复制语义的运行时条目（socket、FIFO 及指向它们的链接）跳过并计数，顶层 `scratch/` 不进复制；悬空或不可解析链接、其余特殊文件、可写逃逸及读取/复制失败都会让 `reconfigure` 在运行 candidate、创建 cutover 或停止 previous 前 fail closed。在安全副本中执行相同隔离后才运行 target composition preflight；副本无法准备或 target 无法 boot 时，previous 继续运行且 live home 不变。successor 取得监督所有权、停止并复核 previous 进程树以后，才按照哈希绑定的耐久计划用同文件系统 rename 隔离原路径。target 被拒绝时，watchdog 必须先停止其已证明的进程，再把它在同路径产生的替代内容保留到 `launch-transitions/<cutover>/rejected-target/`，恢复 previous 原字节并写入回执，最后才允许 previous 启动；任一步无法证明完成都会停在 `awaiting-user`，不会让旧宿主读取混合状态。target 成功后，旧内容仍保存在 cutover 目录，等待 operator 后续处置，不会自动删除。
+guard 先以 copy-on-write 优先方式复制 live home 的启动输入——白名单为 `profiles/`、home 级 `cordis.patch.yml`、`settings.yaml`、`.credentials.yaml`、`.anonymous-user-id`；插件数据目录（sessions、state、local-agent 子 home、tarballs、scratch 等）默认不进复制，新插件的数据目录不会悄悄扩大快照，名单只在宿主启动读取范围变化时才需要更新（漏项会以预检 FAIL 显形，而不是慢慢变大）。再把 pnpm/Cordis 链接重建为只指向 snapshot 内副本的相对链接；合法的内部依赖循环保留。外部目标进入 snapshot 自己的哈希命名去重物化区，`node_modules` 目标锚定在包自身的父 `node_modules`（保留 Node 祖先查找语义的最小范围），而不是整个 store 根。复制后逐链接 `realpath` 审计，任何可写目标都必须仍在 snapshot 根内；无可复制语义的运行时条目（socket、FIFO 及指向它们的链接）跳过并计数；悬空或不可解析链接、其余特殊文件、可写逃逸及读取/复制失败都会让 `reconfigure` 在运行 candidate、创建 cutover 或停止 previous 前 fail closed。在安全副本中执行相同隔离后才运行 target composition preflight；副本无法准备或 target 无法 boot 时，previous 继续运行且 live home 不变。successor 取得监督所有权、停止并复核 previous 进程树以后，才按照哈希绑定的耐久计划用同文件系统 rename 隔离原路径。target 被拒绝时，watchdog 必须先停止其已证明的进程，再把它在同路径产生的替代内容保留到 `launch-transitions/<cutover>/rejected-target/`，恢复 previous 原字节并写入回执，最后才允许 previous 启动；任一步无法证明完成都会停在 `awaiting-user`，不会让旧宿主读取混合状态。target 成功后，旧内容仍保存在 cutover 目录，等待 operator 后续处置，不会自动删除。
 
 **重启报告自动到达模型——并只等它的主人。** 计划重启后（存在未确认的 `last-restart.json` 记录），插件通过 `agent.followup` 把报告排入下一回合，agent 无需任何用户消息即可回报重启结果。重启后的会话恢复是 lazy 的（只有 UI 或 RPC 碰到某个会话，它的 agent 才会被创建），所以完整报告只发给发起重启的会话（`schedule-exit` 把 `$DSH_SESSION_ID` 记为 initiator），等它何时恢复何时送达——其他会话永远不会为了报告被唤醒；记录保持未确认，直到发起会话恢复或下一次重启替换它（新 `exitAt`）。没有 initiator 的记录由首个创建的根 agent 领走。仅根 agent、仅一次（送达即确认）。配置 `reportRestartContext`：`followup`（默认，自主）、`step`（骑在下一次回合的第一步上）、或 `off`。
 

package/lib/cli.js

@@ -805,12 +805,26 @@ function snapshotCopyError(source, error) {
 	return /* @__PURE__ */ new Error(`preflight snapshot could not safely copy ${source}: ${String(error)}`);
 }
 /**
-* Top-level home entries that never join a preflight snapshot: scratch is
-* ephemeral by definition, and copying it can push prepare+canary past the
-* credential's freshness window (observed: a 24 GB scratch expired the
-* credential mid-cutover, the target canary then failed and restored).
+* 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.
 */
-const SNAPSHOT_SKIPPED_TOP_LEVEL = /* @__PURE__ */ new Set(["scratch"]);
+const SNAPSHOT_INCLUDED_TOP_LEVEL = [
+	"profiles",
+	"settings.yaml",
+	"cordis.patch.yml",
+	".credentials.yaml",
+	".anonymous-user-id"
+];
 function canonicalSnapshotSource(source) {
 	try {
 		return realpathSync(source);
@@ -859,7 +873,7 @@ function copySnapshotNode(source, destination, context) {
 		});
 		try {
 			for (const name of readdirSync(canonical)) {
-				if (canonical === context.rootCanonical && SNAPSHOT_SKIPPED_TOP_LEVEL.has(name)) continue;
+				if (canonical === context.rootCanonical && !context.includeTopLevel.has(name)) continue;
 				copySnapshotNode(join(canonical, name), join(destination, name), context);
 			}
 		} catch (error) {
@@ -872,18 +886,32 @@ function copySnapshotNode(source, destination, context) {
 		copyFileSync(canonical, destination, constants.COPYFILE_FICLONE);
 		chmodSync(destination, linkMetadata.mode & 4095);
 		utimesSync(destination, linkMetadata.atime, linkMetadata.mtime);
+		context.copiedFiles++;
+		context.copiedBytes += linkMetadata.size;
+		context.onProgress?.({
+			files: context.copiedFiles,
+			bytes: context.copiedBytes,
+			skippedRuntimeEntries: context.skippedRuntimeEntries
+		});
 	} catch (error) {
 		throw snapshotCopyError(source, error);
 	}
 }
 /**
 * Preserve Node's ancestor node_modules lookup for an external package while
-* avoiding one copy per package link. Other external targets are materialized
-* individually and still deduplicated by canonical path.
+* avoiding one copy per package link. The anchor is the package's OWN parent
+* node_modules — the LAST node_modules segment in the resolved target: pnpm
+* store links resolve to …/.pnpm/<name>@<version>/node_modules/<name>, where
+* that parent already holds the package's dependency siblings, so the lookup
+* survives at the tightest scope. Anchoring the FIRST segment instead dragged
+* the whole multi-GB store root into the snapshot (observed 2026-09-27: 32
+* profile links pulled in the host checkout's entire root node_modules).
+* Other external targets are materialized individually and still deduplicated
+* by canonical path.
 */
 function externalMaterializationAnchor(target) {
 	const parsed = resolve(target).split(sep);
-	const nodeModulesIndex = parsed.indexOf("node_modules");
+	const nodeModulesIndex = parsed.lastIndexOf("node_modules");
 	if (nodeModulesIndex >= 0) return {
 		source: parsed.slice(0, nodeModulesIndex + 1).join(sep) || sep,
 		destination: "node_modules"
@@ -958,17 +986,21 @@ function finalizeSnapshotDirectories(context) {
 	}
 }
 /**
-* 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.
+* 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.
 */
-function createPreflightSnapshot(sourceHome) {
+function createPreflightSnapshot(sourceHome, options = {}) {
 	const root = mkdtempSync(join(tmpdir(), "ankh-transition-preflight-"));
 	const home = join(root, "home");
 	try {
@@ -977,10 +1009,14 @@ function createPreflightSnapshot(sourceHome) {
 		const context = {
 			externalRoot: join(root, "materialized"),
 			rootCanonical: source,
+			includeTopLevel: new Set(options.includeTopLevel ?? SNAPSHOT_INCLUDED_TOP_LEVEL),
 			destinations: /* @__PURE__ */ new Map(),
 			pendingLinks: [],
 			directories: [],
-			skippedRuntimeEntries: 0
+			skippedRuntimeEntries: 0,
+			copiedFiles: 0,
+			copiedBytes: 0,
+			...options.onProgress === void 0 ? {} : { onProgress: options.onProgress }
 		};
 		copySnapshotNode(source, home, context);
 		resolveSnapshotLinks(context);
@@ -990,6 +1026,8 @@ function createPreflightSnapshot(sourceHome) {
 			home,
 			root,
 			skippedRuntimeEntries: context.skippedRuntimeEntries,
+			copiedFiles: context.copiedFiles,
+			copiedBytes: context.copiedBytes,
 			cleanup: () => {
 				rmSync(root, {
 					recursive: true,
@@ -1005,8 +1043,12 @@ function createPreflightSnapshot(sourceHome) {
 		throw error;
 	}
 }
-function createTransitionPreflightSnapshot(plan) {
-	const snapshot = createPreflightSnapshot(plan.home);
+function createTransitionPreflightSnapshot(plan, options = {}) {
+	const operationRoots = plan.operations.map((operation) => operation.path.split(sep)[0]);
+	const snapshot = createPreflightSnapshot(plan.home, {
+		...options,
+		includeTopLevel: [.../* @__PURE__ */ new Set([...options.includeTopLevel ?? SNAPSHOT_INCLUDED_TOP_LEVEL, ...operationRoots])]
+	});
 	try {
 		const stateDir = join(snapshot.root, "guard-state");
 		mkdirSync(stateDir, {
@@ -1017,10 +1059,7 @@ function createTransitionPreflightSnapshot(plan) {
 			...plan,
 			home: snapshot.home
 		}, snapshot.home, stateDir, "preflight"), snapshot.home, stateDir, "preflight");
-		return {
-			home: snapshot.home,
-			cleanup: snapshot.cleanup
-		};
+		return snapshot;
 	} catch (error) {
 		snapshot.cleanup();
 		throw error;
@@ -2785,12 +2824,20 @@ async function runCli(argv, io) {
 			const snapshotStartedAt = Date.now();
 			let snapshot;
 			try {
-				snapshot = transitionPlan === void 0 ? createPreflightSnapshot(target.home) : createTransitionPreflightSnapshot(transitionPlan);
+				let lastProgressAt = 0;
+				const onProgress = (progress) => {
+					const now = Date.now();
+					if (now - lastProgressAt < 2e3) return;
+					lastProgressAt = now;
+					io.stdout(`preflight snapshot: ${progress.files} files / ${Math.round(progress.bytes / 1024 / 1024)} MB copied…\n`);
+				};
+				snapshot = transitionPlan === void 0 ? createPreflightSnapshot(target.home, { onProgress }) : createTransitionPreflightSnapshot(transitionPlan, { onProgress });
 			} catch (error) {
 				return refuse("preflight-snapshot", `reconfigure refused: could not prepare an isolated${transitionPlan === void 0 ? "" : " transitioned"} home: ${String(error)}\n`);
 			}
 			const snapshotMs = Date.now() - snapshotStartedAt;
-			if (snapshotMs > options.maxAgeMinutes * 6e4 / 2) io.stdout(`note: the isolated-home snapshot took ${Math.round(snapshotMs / 1e3)}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(`isolated home snapshot ready: ${snapshot.copiedFiles} files / ${Math.round(snapshot.copiedBytes / 1024 / 1024)} MB in ${Math.round(snapshotMs / 1e3)}s\n`);
+			if (snapshotMs > options.maxAgeMinutes * 6e4 / 2) io.stdout(`note: the isolated-home snapshot took ${Math.round(snapshotMs / 1e3)}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;
 				if (!await candidateProbeGate(target, timeout, io, snapshot.home)) return refuseQuiet("preflight", "reconfigure refused: the candidate probe failed (see stderr)");

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.js

@@ -1873,20 +1873,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;

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 {};

package/lib/types/transition.js

@@ -499,12 +499,26 @@ function snapshotCopyError(source, error) {
     return new Error(`preflight snapshot could not safely copy ${source}: ${String(error)}`);
 }
 /**
- * Top-level home entries that never join a preflight snapshot: scratch is
- * ephemeral by definition, and copying it can push prepare+canary past the
- * credential's freshness window (observed: a 24 GB scratch expired the
- * credential mid-cutover, the target canary then failed and restored).
+ * 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.
  */
-const SNAPSHOT_SKIPPED_TOP_LEVEL = new Set(['scratch']);
+export const SNAPSHOT_INCLUDED_TOP_LEVEL = [
+    'profiles',
+    'settings.yaml',
+    'cordis.patch.yml',
+    '.credentials.yaml',
+    '.anonymous-user-id',
+];
 function canonicalSnapshotSource(source) {
     try {
         return realpathSync(source);
@@ -558,7 +572,7 @@ function copySnapshotNode(source, destination, context) {
         });
         try {
             for (const name of readdirSync(canonical)) {
-                if (canonical === context.rootCanonical && SNAPSHOT_SKIPPED_TOP_LEVEL.has(name))
+                if (canonical === context.rootCanonical && !context.includeTopLevel.has(name))
                     continue;
                 copySnapshotNode(join(canonical, name), join(destination, name), context);
             }
@@ -574,6 +588,13 @@ function copySnapshotNode(source, destination, context) {
         copyFileSync(canonical, destination, constants.COPYFILE_FICLONE);
         chmodSync(destination, linkMetadata.mode & 0o7777);
         utimesSync(destination, linkMetadata.atime, linkMetadata.mtime);
+        context.copiedFiles++;
+        context.copiedBytes += linkMetadata.size;
+        context.onProgress?.({
+            files: context.copiedFiles,
+            bytes: context.copiedBytes,
+            skippedRuntimeEntries: context.skippedRuntimeEntries,
+        });
     }
     catch (error) {
         throw snapshotCopyError(source, error);
@@ -581,12 +602,19 @@ function copySnapshotNode(source, destination, context) {
 }
 /**
  * Preserve Node's ancestor node_modules lookup for an external package while
- * avoiding one copy per package link. Other external targets are materialized
- * individually and still deduplicated by canonical path.
+ * avoiding one copy per package link. The anchor is the package's OWN parent
+ * node_modules — the LAST node_modules segment in the resolved target: pnpm
+ * store links resolve to …/.pnpm/<name>@<version>/node_modules/<name>, where
+ * that parent already holds the package's dependency siblings, so the lookup
+ * survives at the tightest scope. Anchoring the FIRST segment instead dragged
+ * the whole multi-GB store root into the snapshot (observed 2026-09-27: 32
+ * profile links pulled in the host checkout's entire root node_modules).
+ * Other external targets are materialized individually and still deduplicated
+ * by canonical path.
  */
 function externalMaterializationAnchor(target) {
     const parsed = resolve(target).split(sep);
-    const nodeModulesIndex = parsed.indexOf('node_modules');
+    const nodeModulesIndex = parsed.lastIndexOf('node_modules');
     if (nodeModulesIndex >= 0) {
         const prefix = parsed.slice(0, nodeModulesIndex + 1).join(sep) || sep;
         return { source: prefix, destination: 'node_modules' };
@@ -665,17 +693,21 @@ function finalizeSnapshotDirectories(context) {
     }
 }
 /**
- * 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.
+ * 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 function createPreflightSnapshot(sourceHome) {
+export function createPreflightSnapshot(sourceHome, options = {}) {
     const root = mkdtempSync(join(tmpdir(), 'ankh-transition-preflight-'));
     const home = join(root, 'home');
     try {
@@ -684,31 +716,48 @@ export function createPreflightSnapshot(sourceHome) {
         const context = {
             externalRoot: join(root, 'materialized'),
             rootCanonical: source,
+            includeTopLevel: new Set(options.includeTopLevel ?? SNAPSHOT_INCLUDED_TOP_LEVEL),
             destinations: new Map(),
             pendingLinks: [],
             directories: [],
             skippedRuntimeEntries: 0,
+            copiedFiles: 0,
+            copiedBytes: 0,
+            ...(options.onProgress === undefined ? {} : { onProgress: options.onProgress }),
         };
         copySnapshotNode(source, home, context);
         resolveSnapshotLinks(context);
         assertSnapshotLinksContained(root, realpathSync(root));
         finalizeSnapshotDirectories(context);
-        return { home, root, skippedRuntimeEntries: context.skippedRuntimeEntries, cleanup: () => { rmSync(root, { recursive: true, force: true }); } };
+        return {
+            home,
+            root,
+            skippedRuntimeEntries: context.skippedRuntimeEntries,
+            copiedFiles: context.copiedFiles,
+            copiedBytes: context.copiedBytes,
+            cleanup: () => { rmSync(root, { recursive: true, force: true }); },
+        };
     }
     catch (error) {
         rmSync(root, { recursive: true, force: true });
         throw error;
     }
 }
-export function createTransitionPreflightSnapshot(plan) {
-    const snapshot = createPreflightSnapshot(plan.home);
+export function createTransitionPreflightSnapshot(plan, options = {}) {
+    // A transition rehearses the plan's exact operation paths, so their
+    // top-level roots join the copy even when they are not boot inputs.
+    const operationRoots = plan.operations.map(operation => operation.path.split(sep)[0]);
+    const snapshot = createPreflightSnapshot(plan.home, {
+        ...options,
+        includeTopLevel: [...new Set([...(options.includeTopLevel ?? SNAPSHOT_INCLUDED_TOP_LEVEL), ...operationRoots])],
+    });
     try {
         const stateDir = join(snapshot.root, 'guard-state');
         mkdirSync(stateDir, { recursive: true, mode: 0o700 });
         const rebound = { ...plan, home: snapshot.home };
         const reference = prepareTransition(rebound, snapshot.home, stateDir, 'preflight');
         applyTransition(reference, snapshot.home, stateDir, 'preflight');
-        return { home: snapshot.home, cleanup: snapshot.cleanup };
+        return snapshot;
     }
     catch (error) {
         snapshot.cleanup();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@khorsheed/dsh-ankh-guard",
   "description": "Hard gate for self-modification restarts: a green-build credential bound to the git HEAD, checked before any restart of the running instance",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -90,7 +90,7 @@
     },
     "compat": {
       "minHost": "0.1.5-rc.1",
-      "notes": "0.1.5-rc.1 full-line boot-verified 2026-09-25 (42 packages including capture) through the three compat layers: preset-registry dual-name probe, dual-shape typert codecs, and typert faces carrying zod@4; 0.1.7-rc.2 is the 3080 production-verified line; composition-preflight runs via the standalone preflight-runner and degrades to a notice when no live harness checkout resolves; original-tab browser handoff feature-probes optional WebServer/connection auth seams; reversible state quarantine was exercised in a live 0.1.1-rc.2 to 0.1.2-alpha.4 cutover",
+      "notes": "0.1.5-rc.1 full-line boot-verified 2026-09-25 (42 packages including capture) through the three compat layers: preset-registry dual-name probe, dual-shape typert codecs, and typert faces carrying zod@4; 0.1.7-rc.2 is the 3080 production-verified line; composition-preflight runs via the standalone preflight-runner and degrades to a notice when no live harness checkout resolves; original-tab browser handoff feature-probes optional WebServer/connection auth seams; reversible state quarantine was exercised in a live 0.1.1-rc.2 to 0.1.2-alpha.4 cutover; since 0.4.0 the preflight verdict also fails on any agent preset the registry marks broken — preset rows mount on standing scopes beside the profile tree, so a clean-booting profile whose presets cannot serve sessions (picker 加载失败, resume never-started) no longer passes the gate",
       "verifiedHost": "0.1.7-rc.2"
     }
   }