@khorsheed/dsh-ankh-guard 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 变更记录
 
+## 0.3.1（2026-09-26）
+
+适配宿主 rc.1 线并实证 0.1.5/0.1.7 双线可用（0.1.5-rc.1 全量 boot 实证，2026-09-25；0.1.7-rc.1 为 3080 生产验证线）。
+
+- **修复 0.1.5 上 boot 即死**：preset 派生对宿主 preset-registry 包的导入从顶层静态导入改为运行期双名探测（0.1.7-rc.1 把官方包从 `dsh-agent-presets` 改名为 `dsh-agent-preset-registry`，0.1.5 宿主只装旧名，静态导入在模块解析期就炸穿整个 loader 树）；两个名字都装不上时按既定「无 preset 回落部署默认预设」降级，不再抛错
+- rc.1 适配波：中断续跑消息的 source 改为 V4 生产者归属 kind（退役的 `plugin` 外壳在 rc.1 持久层写入即抛）；preflight 执行器按宿主代际探测组合解析面（三代际→四代际）；`agent/created` 监听在 0.1.6 串行模式下保持 fire-and-forget
+- 插件清单展示元数据（`locale/*.json`）：rc.1 宿主插件页的卡面标题/描述中文化
+- 修复 boot 代际刷新过早：代际通道此前只凭「boot id 变了」就回 `ready/reload`，而 Web-server 座位与兄弟行共用——端口刚监听时 `/api` 路由 owner 可能还没挂上，被刷新的页面于是向半挂载的宿主发出第一次、也是唯一一次会话列表拉取，左侧列表只剩重启时被召回的那个会话（重新手动刷新才恢复）。现在代际回答先等新进程的 Loader 树结算（与 web-app 放行浏览器用的是同一信号）；就绪前的 poll 回 `waiting` 且**不下发 boot id**，标签页保持陈旧 id 持续重询，就绪即刷；无 Loader 的裸组合仍视为就绪。宿主侧新增「就绪前不回 reload、就绪后仍一次性刷新」单测，客户端侧新增「held 响应不消费代际判定」单测
+
 ## 0.3.0（2026-09-11）
 
 适配宿主 0.1.5 线。

package/README.en.md

@@ -184,7 +184,7 @@ dsh-ankh-guard restart \
 
 Mounted as a cordis plugin (base bundle), the same surface is available as the `selfRestartGuard` service for in-app gates. Config: `maxAgeMinutes` (default 10), `stateDir`, `repoDir`, `reportRestartContext` (default `followup`), `fallbackGraceMs` (default 300000).
 
-Beyond the verify/record/canary gates, the service exposes `requestRestart({ start, profile, initiator })` — the in-process restart trigger for UI-grade callers (e.g. the mode switcher): `initiator` is required (the requesting session's real id) and the port comes from the launch record. With no live watchdog it drives `restart`; supervised instances drive the `reconfigure` transactional cutover (the only safe way to change the launch command under a watchdog). The credential/preflight/marker/lock gate chain is the CLI's own, refusals return a structured `{ accepted, stage, reason }` and never stop the instance. On the browser side, beside the cutover receipt channel there is a boot-generation channel: after an ordinary restart or a crash respawn, open tabs notice the process's boot id changed over the handoff long-poll and reload once to pick up the new bundle; visible sustained failures (~5 s) show a non-blocking connection banner with Retry; only confirmed cutovers use the restart overlay. Background/offline time does not count as failure. Returning to the foreground or online immediately resets backoff and restarts polling; stalled requests time out after 35 s and stale responses cannot trigger a reload.
+Beyond the verify/record/canary gates, the service exposes `requestRestart({ start, profile, initiator })` — the in-process restart trigger for UI-grade callers (e.g. the mode switcher): `initiator` is required (the requesting session's real id) and the port comes from the launch record. With no live watchdog it drives `restart`; supervised instances drive the `reconfigure` transactional cutover (the only safe way to change the launch command under a watchdog). The credential/preflight/marker/lock gate chain is the CLI's own, refusals return a structured `{ accepted, stage, reason }` and never stop the instance. On the browser side, beside the cutover receipt channel there is a boot-generation channel: after an ordinary restart or a crash respawn, open tabs notice the process's boot id changed over the handoff long-poll and reload once to pick up the new bundle — before reloading it waits for the successor's composition to settle (the Web-server seat is shared, so `/api`'s route owner can still be mounting while the port already answers; until the Loader settles the poll is answered `waiting` with no boot id, the tab keeps asking with its stale id and reloads the moment the tree is up); visible sustained failures (~5 s) show a non-blocking connection banner with Retry; only confirmed cutovers use the restart overlay. Background/offline time does not count as failure. Returning to the foreground or online immediately resets backoff and restarts polling; stalled requests time out after 35 s and stale responses cannot trigger a reload.
 
 ## Model Experience
 
@@ -196,9 +196,10 @@ None.
 
 ## Compatibility
 
-- npm release line (`@deepseek-ai/dsh@0.1.5-rc.1`): ⚠️ degraded — everything works; the composition-preflight gate runs through the standalone `preflight-runner` (composing through the published `@deepseek-ai/dsh-app-boot` primitives with a drift tripwire, since 0.1.5-rc.1 still does not export `composeProfile`) wherever a dsh app layout resolves — `--harness-root`, the durable launch spec, `DSH_HARNESS`, or the default checkout. On a pure npm deployment with no harness checkout the gate reports a notice and proceeds instead. The original-tab bridge feature-probes the optional WebServer/connection authentication seams; hosts without token auth naturally take the existing-cookie path. Cold reads (the parked probe and the preset derivation) ride the 0.1.5 handle-based sessionPersistence (`open(id, 'read')` → `read` → `close`; the one-shot `inspect` is gone). Every other capability is intact on the npm line. minHost moves up to 0.1.5-rc.1 — older hosts stay on the previous release line.
+- npm release line (`@deepseek-ai/dsh@0.1.5-rc.1`): supported — 0.1.5-rc.1 full-line boot-verified (42 packages including capture, 2026-09-25) — with two designed degrades. The composition-preflight gate runs through the standalone `preflight-runner` (composing through the published `@deepseek-ai/dsh-app-boot` primitives with a drift tripwire, since 0.1.5-rc.1 still does not export `composeProfile`) wherever a dsh app layout resolves — `--harness-root`, the durable launch spec, `DSH_HARNESS`, or the default checkout. On a pure npm deployment with no harness checkout the gate reports a notice and proceeds instead. The original-tab bridge feature-probes the optional WebServer/connection authentication seams; hosts without token auth naturally take the existing-cookie path. Cold reads (the parked probe and the preset derivation) ride the 0.1.5 handle-based sessionPersistence (`open(id, 'read')` → `read` → `close`; the one-shot `inspect` is gone). Every other capability is intact on the npm line. minHost stays 0.1.5-rc.1 — older hosts stay on the previous release line.
 - Historical verification: a live npm-host 0.1.1-rc.2 → 0.1.2-alpha.4 isolated cutover passed (transition preflight removed a v3 whole-unit projection cache with an old-schema record from a home copy, live apply quarantined the old file, and target completed Token URL → 303 → cookie 200, the ownership stability window, and canary at zero retries; the old file remained byte-exact in the cutover directory. An untransitioned control over the same home failed on the missing Alpha.4 record fields, demonstrating that acceptance covered the real schema break).
-- source line (deepseek-harness master, fork or upstream): ✅ (verifiedHost: 0.1.5-rc.1) — the gate runs through the standalone `preflight-runner` (resolves the published `@deepseek-ai/dsh-app-boot` etc. from the live checkout), so no fork patch is required.
+- source line (deepseek-harness master, fork or upstream): ✅ (verifiedHost: 0.1.7-rc.1) — the gate runs through the standalone `preflight-runner` (resolves the published `@deepseek-ai/dsh-app-boot` etc. from the live checkout), so no fork patch is required.
+- Dual-line evidence: the 0.1.5 boot passes end-to-end through three compat layers — the [preset-registry dual-name probe](../../.agents/notes/implemented/bug-fix/2026-09-25-preset-registry-dual-name-probe.md), [dual-shape typert codecs](../../.agents/notes/implemented/bug-fix/2026-09-25-typert-codec-dual-shape.md), and [typert faces carrying zod@4](../../.agents/notes/implemented/bug-fix/2026-09-25-typert-faces-carry-zod-v4.md).
 
 **Version line mapping**: the first release after 0.2.0 supports host `0.1.5-rc.1` and later; hosts on `0.1.2-rc.1` stay on `0.2.0`, hosts on `0.1.0-rc.6` ~ `0.1.1-rc.2` stay on the 0.1.x release line (last release `0.1.1`).
 
@@ -214,6 +215,10 @@ None.
 - **`restart`/`supervise` discover the listener via `lsof`** (macOS/Linux with lsof); the guard prefers absolute system paths, while other platforms need `--pid`.
 - **Kills are per-pid identity with a descendant sweep, never per process group** — the instance is not setsid'd, so `restart`, `schedule-exit`'s exit agent, and watchdog cleanup target recorded child/listener identities. Cutover forced paths `SIGSTOP` first, then revalidate a Linux boot/start-tick token or macOS `proc_pidinfo` microsecond start time; a mismatch is only resumed and refused. Descendants are likewise frozen and their parentage rechecked while walking `pgrep -P`. Ordinary non-cutover port recovery retains a bounded listener-cleanup escape hatch; cutovers never select or kill a process by port.
 
+## Test concurrency
+
+Process integration tests run up to 4 shards concurrently by default; the unit lane caps at 2. On constrained machines, use `DSH_TEST_MAX_WORKERS=1 pnpm --filter @khorsheed/dsh-ankh-guard test` to schedule every shard serially. The same variable applies to the repository-wide `pnpm gate`. This only reduces scheduling concurrency: it does not omit tests, extend assertion deadlines, or change production restart behavior. Invalid values retain the defaults.
+
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md).

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: 0fcdb11556dd49ca9046648075ffcde6cab9e894
-packages/ankh-guard/README.md: 3cba2785e56bdfdf3566255aa3629e47c44f8570
+packages/ankh-guard/README.en.md: 551302cb33397c2c0e363d86de2a9fd66d52185a
+packages/ankh-guard/README.md: 7bd89a16642978a8ded951d2248b2a51887c294c

package/README.md

@@ -183,7 +183,7 @@ dsh-ankh-guard restart \
 
 以 cordis 插件挂载（base bundle）后，同一套能力以 `selfRestartGuard` 服务的形式供应用内闸门使用。配置：`maxAgeMinutes`（默认 10）、`stateDir`、`repoDir`、`reportRestartContext`（默认 `followup`）、`fallbackGraceMs`（默认 300000）。
 
-除 verify/record/canary 等闸门外，服务还暴露 `requestRestart({ start, profile, initiator })`——UI 级调用方（如 mode-switcher）的进程内重启触发缝：`initiator` 必填（发起会话的真实 id），端口从 launch 记录自知；无活 watchdog 走 `restart`，受监督走 `reconfigure` 事务 cutover（受监督下唯一安全的换命令通道），凭证/preflight/marker/lock 全套闸门与 CLI 同源，拒绝返回结构化 `{ accepted, stage, reason }` 且绝不停机。浏览器侧，除 cutover receipt 通道外还有 boot 代际通道：普通重启或崩溃救回后，打开的标签页经 handoff 长轮询发现进程 boot id 已变，自动全页刷新一次拿到新 bundle；仅前台持续失败约 5 秒后显示带重试按钮的轻量连接提示；只有确认的 cutover 使用重启遮罩。后台或离线时间不计入失败时长；回前台或恢复联网立即清除退避并重新轮询；挂起的请求在 35 秒后超时，过期响应不能触发刷新。
+除 verify/record/canary 等闸门外，服务还暴露 `requestRestart({ start, profile, initiator })`——UI 级调用方（如 mode-switcher）的进程内重启触发缝：`initiator` 必填（发起会话的真实 id），端口从 launch 记录自知；无活 watchdog 走 `restart`，受监督走 `reconfigure` 事务 cutover（受监督下唯一安全的换命令通道），凭证/preflight/marker/lock 全套闸门与 CLI 同源，拒绝返回结构化 `{ accepted, stage, reason }` 且绝不停机。浏览器侧，除 cutover receipt 通道外还有 boot 代际通道：普通重启或崩溃救回后，打开的标签页经 handoff 长轮询发现进程 boot id 已变，自动全页刷新一次拿到新 bundle；刷新前会等新进程的组合挂载完成（Web-server 座位与兄弟行共用，端口刚应答时 `/api` 路由 owner 可能还没挂上；Loader 结算前一律回 `waiting` 且不下发 boot id，标签页保持陈旧 id 继续问，就绪即刷）；仅前台持续失败约 5 秒后显示带重试按钮的轻量连接提示；只有确认的 cutover 使用重启遮罩。后台或离线时间不计入失败时长；回前台或恢复联网立即清除退避并重新轮询；挂起的请求在 35 秒后超时，过期响应不能触发刷新。
 
 ## Model Experience
 
@@ -195,9 +195,10 @@ dsh-ankh-guard restart \
 
 ## Compatibility
 
-- npm 发布线（`@deepseek-ai/dsh@0.1.5-rc.1`）：⚠️ 降级——一切可用；composition-preflight 门禁通过独立的 `preflight-runner` 运行（0.1.5-rc.1 仍未导出 `composeProfile`，runner 改经已发布的 `@deepseek-ai/dsh-app-boot` 原语组装，带漂移绊线测试），只要能解析到 dsh app 布局——`--harness-root`、耐久 launch spec、`DSH_HARNESS` 或默认检出路径——就完整运行。没有 harness 检出的纯 npm 部署下门禁退化为提示后放行。原标签页桥会探测可选 WebServer/connection 认证 seam，不使用 token 认证的宿主自然走现有 Cookie 路径；冷读（停靠探测与 preset 推导）走 0.1.5 的 handle 制 sessionPersistence（`open(id, 'read')` → `read` → `close`，一次性 `inspect` 已移除）。其余能力在 npm 线上完整。minHost 前移至 0.1.5-rc.1，旧宿主请停留在旧发布线。
+- npm 发布线（`@deepseek-ai/dsh@0.1.5-rc.1`）：支持——0.1.5-rc.1 全量 boot 实证通过（42 包含 capture，2026-09-25）——带两处设计内降级。composition-preflight 门禁通过独立的 `preflight-runner` 运行（0.1.5-rc.1 仍未导出 `composeProfile`，runner 改经已发布的 `@deepseek-ai/dsh-app-boot` 原语组装，带漂移绊线测试），只要能解析到 dsh app 布局——`--harness-root`、耐久 launch spec、`DSH_HARNESS` 或默认检出路径——就完整运行。没有 harness 检出的纯 npm 部署下门禁退化为提示后放行。原标签页桥会探测可选 WebServer/connection 认证 seam，不使用 token 认证的宿主自然走现有 Cookie 路径；冷读（停靠探测与 preset 推导）走 0.1.5 的 handle 制 sessionPersistence（`open(id, 'read')` → `read` → `close`，一次性 `inspect` 已移除）。其余能力在 npm 线上完整。minHost 保持 0.1.5-rc.1，旧宿主请停留在旧发布线。
 - 历史验证：npm host 的 0.1.1-rc.2 → 0.1.2-alpha.4 隔离切换已通过（transition preflight 在 home 副本上移开带旧 schema record 的 v3 whole-unit projection cache，live apply 隔离旧文件，target 以零重试完成 Token URL → 303 → Cookie 200、ownership 稳定窗口与 canary；旧文件逐字节保留在 cutover 目录。相同 home 的无 transition 对照因缺少 Alpha.4 record 字段而拒绝，证明验收覆盖了真实 schema 断裂面）。
-- 源码线（deepseek-harness master，fork 或上游）：✅（verifiedHost: 0.1.5-rc.1）——门禁通过独立的 `preflight-runner` 运行（从在线 checkout 解析已发布的 `@deepseek-ai/dsh-app-boot` 等），不再需要 fork 补丁。
+- 源码线（deepseek-harness master，fork 或上游）：✅（verifiedHost: 0.1.7-rc.1）——门禁通过独立的 `preflight-runner` 运行（从在线 checkout 解析已发布的 `@deepseek-ai/dsh-app-boot` 等），不再需要 fork 补丁。
+- 双线证据：0.1.5 的 boot 经三层兼容修复端到端通过——[preset-registry 双名探测](../../.agents/notes/implemented/bug-fix/2026-09-25-preset-registry-dual-name-probe.md)、[typert codec 双形状](../../.agents/notes/implemented/bug-fix/2026-09-25-typert-codec-dual-shape.md)、[face 自带 zod@4](../../.agents/notes/implemented/bug-fix/2026-09-25-typert-faces-carry-zod-v4.md)。
 
 **版本线对照**：0.2.0 之后的首个发布起支持宿主 `0.1.5-rc.1` 及以后；宿主 `0.1.2-rc.1` 请停留在 `0.2.0`，宿主 `0.1.0-rc.6` ~ `0.1.1-rc.2` 请停留在 0.1.x 发布线（末版 `0.1.1`）。
 
@@ -213,6 +214,10 @@ dsh-ankh-guard restart \
 - **`restart`/`supervise` 通过 `lsof` 发现监听者**（macOS / 带 lsof 的 Linux）；guard 优先使用系统绝对路径，其他平台需用 `--pid`。
 - **杀进程一律按单 pid identity + 后代回收，从不按进程组**——实例不是 setsid 的，所以 `restart`、`schedule-exit` 的退出代理和 watchdog 清理都针对已记录的 child/listener；cutover 强制路径先 `SIGSTOP`，再用 Linux boot/start-tick 或 macOS `proc_pidinfo` 微秒启动时间复核 identity，不匹配就只 `SIGCONT` 并拒绝，然后才沿 `pgrep -P` 冻结、复核亲缘并回收后代。普通非 cutover 端口恢复仍有受限的 listener 清理兜底；cutover 禁止凭端口选择或杀进程。
 
+## 测试并发
+
+进程集成测试默认并行运行 4 个分片，unit lane 上限为 2。资源紧张时可用 `DSH_TEST_MAX_WORKERS=1 pnpm --filter @khorsheed/dsh-ankh-guard test` 串行调度全部分片；全仓 `pnpm gate` 也可使用这个环境变量。只降低调度并发，不减少测试、延长断言期限或改变生产重启行为；无效值保留默认值。
+
 ## 变更记录
 
 见 [CHANGELOG.md](CHANGELOG.md)。

package/lib/index.js

@@ -11,7 +11,6 @@ import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import z from "@deepseek-ai/schemastery";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import * as agentPresetsHost from "@deepseek-ai/dsh-agent-presets";
 //#region lib/types/browser-handoff.js
 /**
 * Browser handoff bridge for launch cutovers.
@@ -31,6 +30,14 @@ import * as agentPresetsHost from "@deepseek-ai/dsh-agent-presets";
 * means the process it knew is gone — answer ready/reload. A cutover receipt
 * always wins over the generation check: during a cutover the old tab's known
 * id is already stale, and the receipt protocol owns the pacing.
+*
+* The generation answer waits for the successor's composition to settle. The
+* shared Web-server seat answers as soon as it listens — well before sibling
+* rows mount — and a page that loads then calls into a half-mounted /api
+* surface (the Web app gates its own browser handoff on the same Loader
+* settlement for that reason). Until then the poll is answered `waiting`
+* WITHOUT the boot id: teaching the tab the successor's id would consume its
+* one-shot generation check and strand it on an unusable page.
 */
 const BROWSER_HANDOFF_ROUTE = "/_ankh-guard/browser-handoff";
 const CAPABILITY_PATTERN = /^[A-Za-z0-9_-]{43}$/;
@@ -278,6 +285,10 @@ function createBrowserHandoffHandler(dependencies) {
 				});
 			};
 			if (bootId !== void 0 && message.knownBootId !== void 0 && message.knownBootId !== bootId && activeCutover(dependencies.stateDir) === null) {
+				if (dependencies.applicationReady?.() === false) {
+					json(res, 200, { state: "waiting" });
+					return;
+				}
 				respond(200, {
 					state: "ready",
 					action: "reload",
@@ -448,7 +459,8 @@ function registerBrowserHandoff(ctx, stateDir) {
 		if (webServer === void 0) return;
 		const handler = createBrowserHandoffHandler({
 			stateDir,
-			connectionProvider: () => webCtx.get("connection")
+			connectionProvider: () => webCtx.get("connection"),
+			applicationReady: applicationReadyProbe(webCtx)
 		});
 		webCtx.effect(() => webServer.register({
 			kind: "exact",
@@ -457,6 +469,30 @@ function registerBrowserHandoff(ctx, stateDir) {
 		}), "ankh-guard: browser handoff route");
 	});
 }
+/**
+* Build the generation channel's readiness probe from the Loader tree.
+*
+* The Web-server seat is shared: it answers as soon as it listens, while
+* sibling rows — including the /api route owner a reloaded page immediately
+* calls into — are still mounting. The Web app gates its own URL line and
+* browser handoff on this exact settlement, so the guard's automatic reload
+* must wait for it too. A composition without a Loader is already complete.
+*
+* Only settlement counts as ready: a failed tree leaves the tab on its old
+* page (the watchdog's crash recovery owns that outcome), and the next healthy
+* process answers the still-stale poll.
+* @param ctx - context owning the Loader service.
+* @returns probe consulted by every boot-generation poll.
+*/
+function applicationReadyProbe(ctx) {
+	const settled = ctx.get("loader")?.await();
+	if (settled === void 0) return () => true;
+	let ready = false;
+	settled.then(() => {
+		ready = true;
+	}, () => {});
+	return () => ready;
+}
 //#endregion
 //#region lib/types/restart-request.js
 /**
@@ -628,6 +664,29 @@ async function requestRestart(request, context) {
 }
 //#endregion
 //#region lib/types/index.js
+let presetRegistryProbe;
+/**
+* Resolve the preset-registry module by name. The 0.1.7-rc.1 host renamed
+* `@deepseek-ai/dsh-agent-presets` to `@deepseek-ai/dsh-agent-preset-registry`
+* (the resolve/mount/livePresetMounts/agentPresetProjectionDefinition API
+* carried over); 0.1.5/0.1.6 hosts install only the old name, and a host
+* without preset composition installs neither — `null`, and the derivation
+* then receives `{}`, the established no-preset degrade (the resume falls
+* back to the deployment's default preset). A STATIC import of either name is
+* a module-resolution failure at load on hosts installing only the other —
+* pack-dist strips `dependencies`, so the specifier resolves against the
+* host's install tree. Both specifiers stay static string literals so tsdown
+* externalizes them and tsc type-checks them.
+* @returns the module namespace, or null when neither name resolves.
+*/
+function loadPresetRegistry() {
+	presetRegistryProbe ??= import("@deepseek-ai/dsh-agent-preset-registry").catch(() => import("@deepseek-ai/dsh-agent-presets")).catch(() => null);
+	return presetRegistryProbe;
+}
+/** Test seam: drop the cached probe so a mocked resolution path re-runs. */
+function resetPresetRegistryProbeForTest() {
+	presetRegistryProbe = void 0;
+}
 /**
 * Which preset a session actually runs, newest selection winning. The rc host
 * exports `resolveSessionPreset` for exactly this fold; the 0.1.2 host
@@ -788,7 +847,7 @@ function apply(ctx, config) {
 				text
 			}],
 			source: {
-				kind: "plugin",
+				kind: "ankh-guard",
 				plugin: name,
 				form: "snapshot",
 				sections: [{
@@ -902,7 +961,7 @@ function apply(ctx, config) {
 			const persistence = probeColdReader(ctx);
 			if (presets !== void 0 && persistence !== void 0) {
 				const inspected = await readColdLog(persistence, id);
-				const presetId = deriveSessionPreset(agentPresetsHost, {
+				const presetId = deriveSessionPreset(await loadPresetRegistry() ?? {}, {
 					header: inspected.meta,
 					events: inspected.events
 				});
@@ -988,7 +1047,7 @@ function apply(ctx, config) {
 					text
 				}],
 				source: {
-					kind: "plugin",
+					kind: "ankh-guard",
 					plugin: name,
 					form: "snapshot",
 					sections: [{
@@ -1066,4 +1125,4 @@ function apply(ctx, config) {
 	})();
 }
 //#endregion
-export { Config, apply, deriveSessionPreset, inject, name };
+export { Config, apply, deriveSessionPreset, inject, loadPresetRegistry, name, resetPresetRegistryProbeForTest };

package/lib/preflight-runner.js

@@ -121,7 +121,7 @@ var PreflightInfraError = class extends Error {};
 * bundle layers in `dsh.profile.bundles` order, the profile user layer, the
 * home-level user layer, `--patch` overlays, the agent-presets roots overlay
 * (rc host line only; the 0.1.2 line's preset package self-ships its root),
-* then the telemetry switch. Two host API generations are mirrored and
+* then the telemetry switch. Three host API generations are mirrored and
 * feature-detected per run — see the `hostLine` branch below. Exported so
 * the drift tripwire can compare this assembly against the launcher's own
 * dump without booting anything.
@@ -147,13 +147,15 @@ async function composePreflightPatches(profile, patchFiles, root, home, binding
 	}
 	const composeEntries = appBoot.composeEntries;
 	const healProfilesModuleFallback = appBoot.healProfilesModuleFallback;
+	const createProfileResolutionGeneration = appBoot.createProfileResolutionGeneration;
+	const createRuntimeResolution = appBoot.createRuntimeResolution;
 	const loadOptionalPatches = appBoot.loadOptionalPatches;
 	const loadOverlayPatches = appBoot.loadOverlayPatches;
 	const loadProfile = appBoot.loadProfile;
 	const resolveDshHome = homePaths.resolveDshHome;
 	const anchor = binding.installAnchor;
 	const resolvedHome = resolveDshHome(home);
-	const hostLine = "DEFAULT_PROFILE_PATCH_RELOAD" in appBoot ? "0.1.2" : "rc";
+	const hostLine = "createRuntimeResolution" in appBoot ? "0.1.7" : "createProfileResolutionGeneration" in appBoot ? "0.1.6" : "DEFAULT_PROFILE_PATCH_RELOAD" in appBoot ? "0.1.2" : "rc";
 	if (hostLine === "rc") healProfilesModuleFallback(anchor, resolvedHome);
 	const composed = loadProfile(NAME, profile, anchor, resolvedHome, { userLayer: true });
 	writeFileSync(join(composed.dir, PROFILE_ROOT_FILENAME), PROFILE_ROOT_CONFIG);
@@ -162,6 +164,15 @@ async function composePreflightPatches(profile, patchFiles, root, home, binding
 		profile: composed,
 		home: resolvedHome
 	});
+	else if (hostLine === "0.1.6") await createProfileResolutionGeneration({
+		installAnchor: anchor,
+		profile: composed,
+		home: resolvedHome
+	});
+	else if (hostLine === "0.1.7") await createRuntimeResolution({
+		installAnchor: anchor,
+		profile: composed
+	});
 	const homePatches = loadOptionalPatches(NAME, join(resolvedHome, HOME_PATCH_FILENAME)) ?? [];
 	const overlays = patchFiles.flatMap((file) => loadOverlayPatches(NAME, resolve(file)));
 	const bundlePatches = composed.layers.flatMap((layer) => layer.patches);

package/lib/types/browser-handoff.d.ts

@@ -41,6 +41,12 @@ interface BrowserHandoffDependencies {
     connection?: ConnectionSlice;
     /** Resolve lazily because WebServer can activate before the optional connection service. */
     connectionProvider?: () => ConnectionSlice | undefined;
+    /**
+     * Whether the serving composition has finished mounting, consulted only by
+     * the boot-generation channel. Omitted means ready — a hand-built tree
+     * without a Loader is already complete.
+     */
+    applicationReady?: () => boolean;
     /** Test seams; production defaults turn idle polling into a held request. */
     longPollMs?: number;
     longPollIntervalMs?: number;

package/lib/types/browser-handoff.js

@@ -16,6 +16,14 @@
  * means the process it knew is gone — answer ready/reload. A cutover receipt
  * always wins over the generation check: during a cutover the old tab's known
  * id is already stale, and the receipt protocol owns the pacing.
+ *
+ * The generation answer waits for the successor's composition to settle. The
+ * shared Web-server seat answers as soon as it listens — well before sibling
+ * rows mount — and a page that loads then calls into a half-mounted /api
+ * surface (the Web app gates its own browser handoff on the same Loader
+ * settlement for that reason). Until then the poll is answered `waiting`
+ * WITHOUT the boot id: teaching the tab the successor's id would consume its
+ * one-shot generation check and strand it on an unusable page.
  */
 import { createHash, randomBytes } from 'node:crypto';
 import { chmodSync, linkSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
@@ -313,6 +321,13 @@ export function createBrowserHandoffHandler(dependencies) {
             // would race the registration/ack dance.
             if (bootId !== undefined && message.knownBootId !== undefined && message.knownBootId !== bootId
                 && activeCutover(dependencies.stateDir) === null) {
+                if (dependencies.applicationReady?.() === false) {
+                    // The successor's composition is still mounting. Answer WITHOUT the
+                    // boot id (not through `respond`): the tab must keep its stale id so
+                    // this one-shot generation check survives until readiness lands.
+                    json(res, 200, { state: 'waiting' });
+                    return;
+                }
                 respond(200, { state: 'ready', action: 'reload', authentication: 'existing-cookie' });
                 return;
             }
@@ -483,7 +498,31 @@ export function registerBrowserHandoff(ctx, stateDir) {
         const handler = createBrowserHandoffHandler({
             stateDir,
             connectionProvider: () => webCtx.get('connection'),
+            applicationReady: applicationReadyProbe(webCtx),
         });
         webCtx.effect(() => webServer.register({ kind: 'exact', path: BROWSER_HANDOFF_ROUTE, handler }), 'ankh-guard: browser handoff route');
     });
 }
+/**
+ * Build the generation channel's readiness probe from the Loader tree.
+ *
+ * The Web-server seat is shared: it answers as soon as it listens, while
+ * sibling rows — including the /api route owner a reloaded page immediately
+ * calls into — are still mounting. The Web app gates its own URL line and
+ * browser handoff on this exact settlement, so the guard's automatic reload
+ * must wait for it too. A composition without a Loader is already complete.
+ *
+ * Only settlement counts as ready: a failed tree leaves the tab on its old
+ * page (the watchdog's crash recovery owns that outcome), and the next healthy
+ * process answers the still-stale poll.
+ * @param ctx - context owning the Loader service.
+ * @returns probe consulted by every boot-generation poll.
+ */
+function applicationReadyProbe(ctx) {
+    const settled = ctx.get('loader')?.await();
+    if (settled === undefined)
+        return () => true;
+    let ready = false;
+    void settled.then(() => { ready = true; }, () => { });
+    return () => ready;
+}

package/lib/types/index.d.ts

@@ -18,6 +18,15 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import type { ContextFormed } from '@deepseek-ai/dsh-llm';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'ankh-guard': {
+            kind: 'ankh-guard';
+            plugin: string;
+        } & ContextFormed;
+    }
+}
 import { type RestartRequest, type RestartRequestResult } from './restart-request.ts';
 import { type GuardState, type VerifyResult } from './state.ts';
 /**
@@ -52,6 +61,23 @@ export interface PresetDerivationSurface {
     };
     resolveSessionPreset?: (session: PersistedPresetSource) => string | undefined;
 }
+/**
+ * Resolve the preset-registry module by name. The 0.1.7-rc.1 host renamed
+ * `@deepseek-ai/dsh-agent-presets` to `@deepseek-ai/dsh-agent-preset-registry`
+ * (the resolve/mount/livePresetMounts/agentPresetProjectionDefinition API
+ * carried over); 0.1.5/0.1.6 hosts install only the old name, and a host
+ * without preset composition installs neither — `null`, and the derivation
+ * then receives `{}`, the established no-preset degrade (the resume falls
+ * back to the deployment's default preset). A STATIC import of either name is
+ * a module-resolution failure at load on hosts installing only the other —
+ * pack-dist strips `dependencies`, so the specifier resolves against the
+ * host's install tree. Both specifiers stay static string literals so tsdown
+ * externalizes them and tsc type-checks them.
+ * @returns the module namespace, or null when neither name resolves.
+ */
+export declare function loadPresetRegistry(): Promise<unknown>;
+/** Test seam: drop the cached probe so a mocked resolution path re-runs. */
+export declare function resetPresetRegistryProbeForTest(): void;
 /**
  * Which preset a session actually runs, newest selection winning. The rc host
  * exports `resolveSessionPreset` for exactly this fold; the 0.1.2 host
@@ -68,11 +94,11 @@ export declare function deriveSessionPreset(host: PresetDerivationSurface, sessi
 /** Plugin configuration. */
 export interface SelfRestartGuardConfig {
     /** Credential freshness window in minutes (default 10). */
-    maxAgeMinutes?: number;
+    maxAgeMinutes?: number | undefined;
     /** State directory; defaults to $DSH_HOME/state, else `<cwd>/.dsh-guard-state`. */
-    stateDir?: string;
+    stateDir?: string | undefined;
     /** Repository the credential binds to; defaults to the process cwd. */
-    repoDir?: string;
+    repoDir?: string | undefined;
     /**
      * How to surface a scheduled restart's record to the agent (default
      * `followup` — fully autonomous: the plugin queues the report as the next
@@ -80,7 +106,7 @@ export interface SelfRestartGuardConfig {
      * system uses for reminders, so the agent reports without any user message).
      * `step` rides the first step of whatever turn comes next; `off` disables.
      */
-    reportRestartContext?: 'followup' | 'step' | 'off';
+    reportRestartContext?: 'followup' | 'step' | 'off' | undefined;
     /**
      * Resume the sessions a restart interrupted (default true). At SIGTERM the
      * plugin snapshots which root sessions had a live turn (plus the restart's
@@ -90,21 +116,21 @@ export interface SelfRestartGuardConfig {
      * The pass only runs on a restart boot (restart marker or pending restart
      * record present); a cold start drops the snapshot without acting.
      */
-    resumeInterrupted?: boolean;
+    resumeInterrupted?: boolean | undefined;
     /**
      * Delay before the interrupted-session resume pass runs after plugin load
      * (default 5000 ms), so the pass starts turns only after the app's services
      * are up.
      */
-    resumeDelayMs?: number;
+    resumeDelayMs?: number | undefined;
     /**
      * Maximum age of the interrupted-session snapshot the resume pass honors
      * (default 600000 ms, ten minutes). A snapshot older than that comes from a
      * manual stop/start, not a restart, and is dropped without acting.
      */
-    resumeMaxSnapshotAgeMs?: number;
+    resumeMaxSnapshotAgeMs?: number | undefined;
 }
-export declare const Config: z<SelfRestartGuardConfig>;
+export declare const Config: z;
 /** One canary check line. */
 export interface CanaryCheck {
     name: string;

package/lib/types/index.js

@@ -1,13 +1,6 @@
 import z from '@deepseek-ai/schemastery';
 import { connect } from 'node:net';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
-// Namespace handle for runtime feature detection: the 0.1.2 host replaced
-// the `resolveSessionPreset` free function (and the `PresetBearingSession`
-// type) with the `agentPresetProjectionDefinition` unit, and a STATIC named
-// import of a removed export is a SyntaxError at module load — exactly the
-// failure this dual-host probing exists to survive. The derivation below
-// reads both surfaces through one structural cast.
-import * as agentPresetsHost from '@deepseek-ai/dsh-agent-presets';
 import { existsSync, readFileSync, unlinkSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -20,6 +13,31 @@ import { registerBrowserHandoff } from "./browser-handoff.js";
 import { requestRestart } from "./restart-request.js";
 import { acknowledgeRestartRecord, buildLaunchCommand, continueAndReportText, continueInterruptedText, interruptedSnapshotFile, isParkedOnUserInput, writeInstanceLaunch, writeSkillRegistration, pendingRestartRecord, readInterruptedSnapshot, restartContextText, writeInterruptedSnapshot, } from "./restart-context.js";
 import { clearCredential, loadState, recordCredential, setCheckpoint, verifyCredential, } from "./state.js";
+let presetRegistryProbe;
+/**
+ * Resolve the preset-registry module by name. The 0.1.7-rc.1 host renamed
+ * `@deepseek-ai/dsh-agent-presets` to `@deepseek-ai/dsh-agent-preset-registry`
+ * (the resolve/mount/livePresetMounts/agentPresetProjectionDefinition API
+ * carried over); 0.1.5/0.1.6 hosts install only the old name, and a host
+ * without preset composition installs neither — `null`, and the derivation
+ * then receives `{}`, the established no-preset degrade (the resume falls
+ * back to the deployment's default preset). A STATIC import of either name is
+ * a module-resolution failure at load on hosts installing only the other —
+ * pack-dist strips `dependencies`, so the specifier resolves against the
+ * host's install tree. Both specifiers stay static string literals so tsdown
+ * externalizes them and tsc type-checks them.
+ * @returns the module namespace, or null when neither name resolves.
+ */
+export function loadPresetRegistry() {
+    presetRegistryProbe ??= import('@deepseek-ai/dsh-agent-preset-registry')
+        .catch(() => import('@deepseek-ai/dsh-agent-presets'))
+        .catch(() => null);
+    return presetRegistryProbe;
+}
+/** Test seam: drop the cached probe so a mocked resolution path re-runs. */
+export function resetPresetRegistryProbeForTest() {
+    presetRegistryProbe = undefined;
+}
 /**
  * Which preset a session actually runs, newest selection winning. The rc host
  * exports `resolveSessionPreset` for exactly this fold; the 0.1.2 host
@@ -178,7 +196,7 @@ export function apply(ctx, config) {
     if (followupReport || resumeInterrupted) {
         const pluginMessage = (text) => createUserMessage({
             content: [{ type: 'text', text }],
-            source: { kind: 'plugin', plugin: name, form: 'snapshot', sections: [{ name: 'restart', text }] },
+            source: { kind: 'ankh-guard', plugin: name, form: 'snapshot', sections: [{ name: 'restart', text }] },
         });
         // Interrupted sessions awaiting their `agent/created` to receive the
         // "continue" followup: session id → exitAt of the interrupting exit.
@@ -359,7 +377,8 @@ export function apply(ctx, config) {
             const persistence = probeColdReader(ctx);
             if (presets !== undefined && persistence !== undefined) {
                 const inspected = await readColdLog(persistence, id);
-                const presetId = deriveSessionPreset(agentPresetsHost, {
+                const host = await loadPresetRegistry();
+                const presetId = deriveSessionPreset((host ?? {}), {
                     header: inspected.meta,
                     events: inspected.events,
                 });
@@ -452,6 +471,9 @@ export function apply(ctx, config) {
             }, 250);
             ctx.effect(() => () => { clearInterval(releaseTimer); });
         }
+        // agent/created went @mode serial in 0.1.6: the creation transaction
+        // awaits whatever a listener returns, so delivery stays fire-and-forget
+        // here — return nothing, and never await agent.whenIdle in this listener.
         ctx.on('agent/created', ({ agent }) => {
             if (!ctx.agents.roots().includes(agent))
                 return;
@@ -482,7 +504,7 @@ export function apply(ctx, config) {
                     createUserMessage({
                         content: [{ type: 'text', text }],
                         source: {
-                            kind: 'plugin', plugin: name, form: 'snapshot',
+                            kind: 'ankh-guard', plugin: name, form: 'snapshot',
                             sections: [{ name: 'restart', text }],
                         },
                     }),

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

@@ -58,7 +58,7 @@ export interface PreflightComposition {
  * bundle layers in `dsh.profile.bundles` order, the profile user layer, the
  * home-level user layer, `--patch` overlays, the agent-presets roots overlay
  * (rc host line only; the 0.1.2 line's preset package self-ships its root),
- * then the telemetry switch. Two host API generations are mirrored and
+ * then the telemetry switch. Three host API generations are mirrored and
  * feature-detected per run — see the `hostLine` branch below. Exported so
  * the drift tripwire can compare this assembly against the launcher's own
  * dump without booting anything.

package/lib/types/preflight-runner.js

@@ -131,7 +131,7 @@ class PreflightInfraError extends Error {
  * bundle layers in `dsh.profile.bundles` order, the profile user layer, the
  * home-level user layer, `--patch` overlays, the agent-presets roots overlay
  * (rc host line only; the 0.1.2 line's preset package self-ships its root),
- * then the telemetry switch. Two host API generations are mirrored and
+ * then the telemetry switch. Three host API generations are mirrored and
  * feature-detected per run — see the `hostLine` branch below. Exported so
  * the drift tripwire can compare this assembly against the launcher's own
  * dump without booting anything.
@@ -158,6 +158,8 @@ export async function composePreflightPatches(profile, patchFiles, root, home, b
     }
     const composeEntries = appBoot.composeEntries;
     const healProfilesModuleFallback = appBoot.healProfilesModuleFallback;
+    const createProfileResolutionGeneration = appBoot.createProfileResolutionGeneration;
+    const createRuntimeResolution = appBoot.createRuntimeResolution;
     const loadOptionalPatches = appBoot.loadOptionalPatches;
     const loadOverlayPatches = appBoot.loadOverlayPatches;
     const loadProfile = appBoot.loadProfile;
@@ -174,12 +176,21 @@ export async function composePreflightPatches(profile, patchFiles, root, home, b
     // the profile composition: the heal moved behind the async options API and
     // below the profile load (see HealProfilesModuleFallback), and the launcher
     // dropped its agent-presets shipped-root overlay because the preset package
-    // now self-ships its root. DEFAULT_PROFILE_PATCH_RELOAD is a value export
-    // only the new line carries, so it is the feature marker; a version parse
-    // would break on exactly the unreleased builds this runner must dry-run.
-    // Both lines stay supported: prod hosts run the rc line until 0.1.2 lands
-    // on npm.
-    const hostLine = 'DEFAULT_PROFILE_PATCH_RELOAD' in appBoot ? '0.1.2' : 'rc';
+    // now self-ships its root. The 0.1.6 line flipped the default resolution
+    // mode from link to runtime: its compose computes an immutable resolution
+    // generation instead of materializing fallback links, and it removed
+    // DEFAULT_PROFILE_PATCH_RELOAD — the 0.1.2 line's marker. The 0.1.7 line
+    // deleted the fallback projections outright (in-memory runtime resolution
+    // interception): its compose calls createRuntimeResolution and carries
+    // neither older marker, so the markers must be probed newest-first. Each
+    // marker is a value export only its line carries; a version parse would
+    // break on exactly the unreleased builds this runner must dry-run. All
+    // lines stay supported: prod hosts run 0.1.5 until the next npm line lands.
+    const hostLine = 'createRuntimeResolution' in appBoot
+        ? '0.1.7'
+        : 'createProfileResolutionGeneration' in appBoot
+            ? '0.1.6'
+            : 'DEFAULT_PROFILE_PATCH_RELOAD' in appBoot ? '0.1.2' : 'rc';
     if (hostLine === 'rc')
         healProfilesModuleFallback(anchor, resolvedHome);
     const composed = loadProfile(NAME, profile, anchor, resolvedHome, { userLayer: true });
@@ -192,6 +203,22 @@ export async function composePreflightPatches(profile, patchFiles, root, home, b
     if (hostLine === '0.1.2') {
         await healProfilesModuleFallback({ installAnchor: anchor, profile: composed, home: resolvedHome });
     }
+    else if (hostLine === '0.1.6') {
+        // The launcher compose's runtime-mode step (apps/cli composeProfile):
+        // compute the generation AFTER the profile load and root-config rewrite,
+        // materializing nothing. Awaited, so a resolution-graph failure rejects
+        // the compose instead of escaping as an unhandled rejection. The explicit
+        // home keeps the recorded profilesDir on the deployment under check.
+        await createProfileResolutionGeneration({ installAnchor: anchor, profile: composed, home: resolvedHome });
+    }
+    else if (hostLine === '0.1.7') {
+        // The 0.1.7 launcher compose (apps/cli composeProfile): the resolution is
+        // computed in memory right after the profile load and root-config rewrite
+        // — the older lines' fallback projections are gone for good. Awaited, so
+        // a resolution-graph failure rejects the compose instead of escaping as
+        // an unhandled rejection.
+        await createRuntimeResolution({ installAnchor: anchor, profile: composed });
+    }
     const homePatches = loadOptionalPatches(NAME, join(resolvedHome, HOME_PATCH_FILENAME)) ?? [];
     const overlays = patchFiles.flatMap(file => loadOverlayPatches(NAME, resolve(file)));
     const bundlePatches = composed.layers.flatMap(layer => layer.patches);

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Ankh Guard",
+    "description": "Gate self-modification restarts on a green build and test credential."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "重启守卫",
+    "description": "先证明构建与测试通过，才放行自我修改的重启。"
+  }
+}