@oj-module/cli 0.2.66 → 0.2.67

package/templates/src/app/api/_platform/_lifecycle/installer.ts

@@ -24,8 +24,9 @@ import type { ReloadFace } from "./steps/reload";
 import type { InstallContext, InstallStage, StageResult, TaskRecord, TaskStatus } from "./types";
 import { auditOp } from "../_shared/service/infra/audit";
 import { atomicWriteText, fsFace, randomId } from "./atomic";
+import { compensate } from "./compensate";
 import { recordHistory } from "./history";
-import { acquireTaskLock, commitLockEntry, readLock, writeLock } from "./lock";
+import { acquireTaskLock, commitLockEntry, readLock, revertLock, writeLock } from "./lock";
 import { deployWeb } from "./steps/deploy-web";
 import { download } from "./steps/download";
 import { extract } from "./steps/extract";
@@ -36,7 +37,7 @@ import { reloadAndAssert } from "./steps/reload";
 import { smoke } from "./steps/smoke";
 import { verify } from "./steps/verify";
 import { getTask, readTasks, sweepTimedOut, writeTask } from "./tasks";
-import { appendAnonymousPaths, bumpInstallSeq } from "./text-edit";
+import { appendAnonymousPaths, readAnonymousPaths } from "./text-edit";
 import { createTrustStore } from "./trust";
 
 // db/http 为 oj isolate 注入全局（同模板 service 层惯例，register.ts/audit.ts 同款；测试由夹具装 globalThis.db）
@@ -66,7 +67,7 @@ export interface InstallRequest extends InstallContext {
 	modulesJsonPath: string
 	/** API 前缀（smoke 探针 URL 前缀，C2-13） */
 	apiPrefix: string
-	/** 站点 config.yaml 路径（reloading 段 vars.ojm_install_seq 自增落盘处；缺省 config.yaml） */
+	/** 站点 config.yaml 路径（reloading 段 anonymous_paths 接线落盘处；缺省 config.yaml） */
 	configPath?: string
 	/** 注入面（DIP）：下载 / exec（tar+oj）/ 热更 / sha384（R10 integrity 重算） */
 	fetch: FetchFace
@@ -352,7 +353,11 @@ function previewSiblingOf(configPath: string): string {
 	return cut < 0 ? PREVIEW_CONFIG_NAME : `${configPath.slice(0, cut + 1)}${PREVIEW_CONFIG_NAME}`;
 }
 
-/** 把「安装序号自增 + 匿名端点接线」写到一份 config 文本上；`optional` 用于派生文件不存在即跳过 */
+/**
+ * 把「匿名端点接线」写到一份 config 文本上；`optional` 用于派生文件不存在即跳过。
+ * 仅当匿名端点确有新增（added 非空）才落盘——无谓重写会改动 config 文档 sha，反而引发假阳性
+ * （reload unchanged 判定基于文档 sha + 锁 diff；盘上本就一致时什么都不写才是正确的幂等态）。
+ */
 async function patchConfigAt(configPath: string, anonymous: string[], optional = false): Promise<string[]> {
 	let content: string;
 	try {
@@ -363,17 +368,22 @@ async function patchConfigAt(configPath: string, anonymous: string[], optional =
 			return [];
 		throw e;
 	}
-	const bumped = bumpInstallSeq(content);
-	const patched = anonymous.length > 0 ? appendAnonymousPaths(bumped.content, anonymous) : { content: bumped.content, added: [] };
+	if (anonymous.length === 0)
+		return [];
+	const patched = appendAnonymousPaths(content, anonymous);
+	if (patched.added.length === 0)
+		return [];
 	await atomicWriteText(configPath, patched.content);
 	return patched.added;
 }
 
 /**
- * 热更段适配（B-11 reload 触发面）：先落盘触发变更再 reloadAndAssert——reloadConfig 的
- * unchanged 判定基于 config 文档 sha（oj-bin reload_bridge 真源），不落盘变更则热更恒
- * unchanged 必失败。触发变更 = vars.ojm_install_seq 自增（PRD E5 实测先例：vars 段语义值
- * 改动 applied 可热生效，无需改 mounts），经 text-edit 纯文本行操作（R18，注释/键序逐字保留）。
+ * 热更段适配（B-11 reload 触发面，R18 修订）：先落盘 anonymous_paths 接线再 reloadAndAssert。
+ * oj 0.1.122+ 的 `unchanged` 由 **manifests 锁 diff 自然触发**（安装/升级/降级即锁变化），
+ * 不再依赖 config 文档 sha（旧的 vars.ojm_install_seq 哨兵已删）；本段只做 anonymous_paths
+ * 接线（且幂等、仅 added 非空才落盘），其余变更（模块装配）由锁 diff 驱动，无需此处制造。
+ * 触发变更判定 = 文档 sha 或锁 diff 任一变化（oj-bin reload_bridge 真源）；盘上本就一致则
+ * `unchanged=true` = 已是最新装配 = 幂等成功（R18 修订：不再视为失败）。
  *
  * **preview 形态（`ojm preview`）**：服务端读的是同目录派生出来的 `.ojm-preview.yaml`（spa 挂载 +
  * platform.root 改写到 dist），安装器改的 `config.yaml` 它根本不看——于是 reload 按文档 sha 判
@@ -395,9 +405,12 @@ async function reloadStage(req: InstallRequest): Promise<StageResult> {
 		req.deferredAnonymous = added;
 	}
 	catch (e) {
-		return { stage: "reloading", ok: false, retryable: true, message: `热更失败：config.yaml 安装序号自增/匿名端点接线失败（${String(e)}）——reload unchanged 判定基于 config 文档 sha，无变更则热更不可能生效（B-11，PRD E5 口径）` };
+		return { stage: "reloading", ok: false, retryable: true, message: `热更失败：config.yaml 匿名端点接线失败（${String(e)}）——reload 由锁 diff / 文档 sha 变化触发，接线本身失败则热更无变更可落` };
 	}
-	return reloadAndAssert(req);
+	const rr = await reloadAndAssert(req);
+	// 捕获待重启段（P0 §3.6 / 验收 15）：非空 = 部分生效，installer 终态据其标 partial + restartRequired
+	req.restartPending = rr.restartPending;
+	return rr;
 }
 
 /** 终态审计（AC-P1-14）：done/partial 都落 oplog；自身失败仅日志（附录 B-5，不阻断任务终态） */
@@ -492,13 +505,7 @@ async function cancelCleanup(req: InstallRequest, lockBefore: Record<string, str
 		// staging 已不存在（首装取消 / 重复回退）不掩盖取消终态
 	}
 	try {
-		if (lockExisted) {
-			await writeLock(`${req.sharedRoot}/manifests.yaml`, lockBefore);
-		}
-		else {
-			// 首装：装前本无锁文件，取消后也不该留空锁（空锁拒启 S1-1.2）
-			await f.remove(`${req.sharedRoot}/manifests.yaml`, { force: true });
-		}
+		await revertLock(req.sharedRoot, lockBefore, lockExisted);
 	}
 	catch {
 		// 锁回退失败由 reconcile 对账兜底（D11）
@@ -570,6 +577,15 @@ export async function runInstall(req: InstallRequest): Promise<TaskRecord> {
 		catch {
 			lockExisted = false;
 		}
+		// P0 §3.2 质辩1 / E8：写锁前读 config 的 auth.anonymous_paths，注入 preflight 做残留检测
+		// （preflight 保持只读 ctx 的纯校验段纪律，不自己读盘）。config 缺失/解析失败 → 视为无残留。
+		try {
+			const cfg = new TextDecoder().decode(await fsFace().readFile(req.configPath ?? "config.yaml"));
+			req.existingAnonymousPaths = readAnonymousPaths(cfg);
+		}
+		catch {
+			req.existingAnonymousPaths = [];
+		}
 		// P2-13 段内进度：migrating 段 spawn 流式路径逐块触发；写链串行（回调 fire-and-forget
 		// 防交错），失败静默（进度观测面不阻断安装）
 		let progressChain: Promise<void> = Promise.resolve();
@@ -658,8 +674,27 @@ export async function runInstall(req: InstallRequest): Promise<TaskRecord> {
 					}
 				}
 				else {
-					// 失败语义②：锁后 partial——部分生效，不回滚已落位产物，给回滚指引 key
+				// 失败语义②：锁后 partial——执行补偿回滚到装前代（旧代继续服务、任务可重试），
+				// 不再「不回滚已落位产物」：消除失败放大匿名面/残留注册（final §0 缺陷之三）。
+				// 补偿各步独立 try/catch，单步失败仍尽力回滚其余步，结果进 task.stages 供运维定位。
+					const comp = await compensate({
+						name: req.name,
+						version: req.version,
+						configPath: req.configPath ?? "config.yaml",
+						deferredAnonymous: req.deferredAnonymous ?? [],
+						sharedRoot: req.sharedRoot,
+						modulesJsonPath: req.modulesJsonPath,
+						lockBefore,
+						lockExisted,
+						reload: req.reload,
+					});
+					for (const s of comp.steps) {
+						task.stages.push({ stage: `compensate.${s.step}`, ok: s.ok, message: s.message });
+					}
 					task.status = "partial";
+					if (!comp.allOk) {
+						task.message = `${r.message}；补偿回滚存在失败步（${comp.steps.filter(s => !s.ok).map(s => s.step).join("、")}），可重试`;
+					}
 				}
 				req.outcome = { ...req.outcome, status: task.status, failedStage: def.name };
 				break;
@@ -737,8 +772,22 @@ export async function runInstall(req: InstallRequest): Promise<TaskRecord> {
 			});
 		}
 		if (task.status === "done") {
-			task.stage = "done";
-			task.progress = 100;
+			// 无守护形态部分生效判定（P0 §3.6 / 验收 15）：热更返回的待重启段非空，且无 supervisor
+			// 自动换进程（P4 暂未实施）——安装产物已落位，但宿主须重启才完全生效（匿名接线/路由等
+			// restart_pending 段）。此时不判 done（避免「假成功」误导，final §0 缺陷之四），改标 partial
+			// + restartRequired，由 UI 展示重启提示。失败语义②的补偿不触发（本次安装成功，无需回滚）。
+			const pending = req.restartPending ?? [];
+			if (pending.length > 0) {
+				task.status = "partial";
+				task.restartRequired = true;
+				task.stage = "reloading";
+				req.outcome = { ...req.outcome, status: "partial", failedStage: "reloading" };
+				task.message = `安装已落位但需宿主重启才完全生效：待重启段 [${pending.join("、")}]（无守护形态无自动换进程；请重启 oj serve 后生效）。其余阶段均成功（partial，可重试以复检）`;
+			}
+			else {
+				task.stage = "done";
+				task.progress = 100;
+			}
 		}
 		task.finishedAt = Date.now();
 		await writeTask(req.taskDir, task);

package/templates/src/app/api/_platform/_lifecycle/lock.ts

@@ -93,6 +93,29 @@ export interface TaskLock {
 	release: () => Promise<void>
 }
 
+/**
+ * 回退锁到装前快照（D12 反向，与 setEnabled/cancelCleanup 同纪律）：装前存在 → 写回
+ * lockBefore；首装（装前无锁文件）→ 删锁文件（空锁拒启 S1-1.2）。失败上抛由调用方兜底
+ * （reconcile 对账 / 任务 partial）。cancelCleanup 与补偿清单共用此原语，避免两处各写一份锁回退。
+ */
+export async function revertLock(sharedRoot: string, lockBefore: Record<string, string>, lockExisted: boolean): Promise<void> {
+	const f = fsFace();
+	const lockPath = `${sharedRoot}/manifests.yaml`;
+	if (lockExisted) {
+		await writeLock(lockPath, lockBefore);
+	}
+	else {
+		try {
+			await f.remove(lockPath, { force: true });
+		}
+		catch (e) {
+			if (!isMissingPath(e)) {
+				throw e;
+			}
+		}
+	}
+}
+
 /** stale 阈值：与任务超时判 failed 同款 30min（R13/B9/R31 口径一致） */
 export const LOCK_STALE_MS = 30 * 60_000;
 

package/templates/src/app/api/_platform/_lifecycle/steps/deploy-web.ts

@@ -188,3 +188,31 @@ export async function deployWeb(ctx: DeployWebContext): Promise<StageResult> {
 		message: `部署完成：staging web/ → ${ctx.siteModulesDir}/，modules.json 已 upsert ${ctx.name}（entry ${entry.entry}${integrity ? `；integrity ${integrity}` : ""}；D13 原子写，读者永不见半截 JSON）`,
 	};
 }
+
+/**
+ * 移除 modules.json 中指定 name 的条目（P0 补偿清单 §3.5）：读→filter→原子写，与 upsert 同纪律
+ * （D13，原子写读者无感）；清单不存在 = 该模块从未入清单，视为已移除返回 removed=false；清单损坏
+ * 上抛 fail-closed。返回 removed 标志供补偿流程断言「写出后该 name 条目确已不存在」。
+ */
+export async function removeModulesJsonEntry(name: string, opts: { modulesJsonPath: string }): Promise<{ removed: boolean }> {
+	const f = fsFace();
+	let list: unknown;
+	try {
+		list = JSON.parse(new TextDecoder().decode(await f.readFile(opts.modulesJsonPath)));
+	}
+	catch (e) {
+		if (isMissingPath(e)) {
+			return { removed: false };
+		}
+		throw e;
+	}
+	if (!Array.isArray(list)) {
+		throw new TypeError("modules.json 顶层不是数组，拒绝修改（避免覆盖丢失既有条目）");
+	}
+	const next = list.filter(e => !(isObj(e) && e.name === name));
+	const removed = next.length !== list.length;
+	if (removed) {
+		await atomicWriteText(opts.modulesJsonPath, `${JSON.stringify(next, null, 2)}\n`);
+	}
+	return { removed };
+}

package/templates/src/app/api/_platform/_lifecycle/steps/preflight.ts

@@ -52,6 +52,9 @@ const RANGE_RE = /^(>=|<=|[><^=])?([0-9A-Z.-]+)$/i;
 /** C2-26①：anonymous 相对路径语法（无前导斜杠、无通配符；首字符 [a-z0-9] 使 _system/_platform 天然禁入） */
 const ANONYMOUS_RE = /^[a-z0-9][a-z0-9\-_.]*(?:\/[a-z0-9][a-z0-9\-_.]*)*$/;
 
+/** P0 §3.2 匿名保留段黑名单（显式拒装清单；与 C2-26 段内收敛互补——C2-26 挡「跨段」，本清单挡「保留段本身」） */
+const ANON_RESERVED_PREFIXES = ["_platform", "_system", "auth", "_lifecycle"];
+
 /** C2-17：路由 path 语法（首段首字符为字母；无参数段/通配符/尾斜杠） */
 const ROUTE_PATH_RE = /^\/[a-z][a-z0-9\-_]*(?:\/[a-z0-9\-_]+)*$/;
 
@@ -205,6 +208,18 @@ export async function preflight(ctx: InstallContext): Promise<StageResult> {
 		return e === undefined ? undefined : `${key}@${e.version}`;
 	};
 
+	// ── P0 §3.9 宿主能力门禁：模板声明所需 host 能力子集（manifest.requiresCapabilities），
+	// 宿主 ojInfo().capabilities 缺项即写锁前失败（零痕迹，不碰锁/库表/清单）。缺省 undefined 视为
+	// 宿主未上报 → fail-closed（能力缺失即拒）。既有模板不声明 → 门禁恒放行（不依赖上游 US-1 即先落地）。
+	const requires = Array.isArray(m.requiresCapabilities) ? m.requiresCapabilities as unknown[] : [];
+	if (requires.length > 0) {
+		const caps = ctx.capabilities ?? [];
+		const missing = requires.filter(c => typeof c === "string" && !caps.includes(c));
+		if (missing.length > 0) {
+			v.push({ clause: "C2-cap", code: "host_capability", detail: `宿主 oj 不支持本方案所需能力 ${JSON.stringify(missing)}（请升级 oj 至具备 ${JSON.stringify(requires)} 的版本后再装）` });
+		}
+	}
+
 	// ── C2-01 身份 name：白名单 + 保留名（§4.2，market 经 R9 恢复保留）──
 	if (typeof m.name !== "string" || !NAME_RE.test(m.name)) {
 		v.push({ clause: "C2-01", detail: `name「${String(m.name)}」不匹配 ^[a-z][a-z0-9-]{0,63}$（小写字母开头，仅小写字母/数字/连字符）` });
@@ -288,6 +303,8 @@ export async function preflight(ctx: InstallContext): Promise<StageResult> {
 	// ── api 段（C2-12/12a/12b/13/26）──
 	// C2-26② 段内收敛的「本方案段」：api.prefix 缺省 = name
 	let apiSeg = name;
+	// P0 §3.2 质辩1 / E8：本 manifest 声明的匿名条目集合（供下方 config 残留检测比对）
+	const declaredSet = new Set<string>();
 	const api = m.api;
 	if (api !== undefined) {
 		if (!isObj(api)) {
@@ -354,9 +371,13 @@ export async function preflight(ctx: InstallContext): Promise<StageResult> {
 							v.push({ clause: "C2-26", detail: `anonymous「${a}」不匹配相对路径语法 ^[a-z0-9][a-z0-9\\-_.]*(/[a-z0-9][a-z0-9\\-_.]*)*$（无前导斜杠/通配符；_system/_platform 段禁入）` });
 							continue;
 						}
+						declaredSet.add(a);
 						if (a.split("/")[0] !== apiSeg) {
 							v.push({ clause: "C2-26", detail: `anonymous「${a}」越段：首段必须 = 本方案段「${apiSeg}」（R8 段内收敛；_system/_platform 等保留段因此禁入）` });
 						}
+						if (ANON_RESERVED_PREFIXES.includes(a.split("/")[0] ?? "")) {
+							v.push({ clause: "C2-26", detail: `anonymous「${a}」指向保留段（${ANON_RESERVED_PREFIXES.join("/")}），禁用于匿名接线（P0 §3.2 黑名单）` });
+						}
 						if (LOGIN_ENDPOINT_RE.test(a)) {
 							v.push({ clause: "C2-26", detail: `anonymous「${a}」命中登录语义端点禁令（R8/S1 纵深防御：login/logout/token/session/signin/signup/auth）` });
 						}
@@ -370,6 +391,31 @@ export async function preflight(ctx: InstallContext): Promise<StageResult> {
 		}
 	}
 
+	// ── P0 §3.2 质辩1 / E8：config 残留匿名检测（写锁前拒装，避免同 prefix 换装静默继承）──
+	// 站点 config 已存在的 auth.anonymous_paths 中，凡落在目标 prefix（apiSeg）下却未被本次 manifest
+	// 声明的条目，一律拒装。运行期新增的匿名条目卸载即失效，仅「启动期已在 config 的残留」构成暴露面——
+	// 此处只挡安装入口，不挡已运行实例。真源 = ctx.existingAnonymousPaths（调用方写锁前读 config 注入；
+	// preflight 保持只读 ctx 的纯校验段纪律）。
+	// **保留段条目不在此查**：config 里 /auth/*、/_platform/* 等属宿主内建（如 /auth/login），方案永不
+	// 能注入（C2-26 段内收敛已挡住方案声明保留段匿名），故保留段 config 条目绝不会是方案残留——
+	// 纳入比对只会误伤宿主内建匿名端点（F4 假阳性）。
+	{
+		const existing = ctx.existingAnonymousPaths ?? [];
+		const residual: string[] = [];
+		// config 条目带前导斜杠（appendAnonymousPaths 统一补 /），归一去斜杠再取首段，
+		// 与 manifest 相对形态（无前导 /）保持一致比对口径。
+		const norm = (p: string) => p.replace(/^\//, "");
+		for (const e of existing) {
+			const seg = norm(e).split("/")[0] ?? "";
+			if (seg === apiSeg && !declaredSet.has(norm(e))) {
+				residual.push(e);
+			}
+		}
+		if (residual.length > 0) {
+			v.push({ clause: "C2-26", code: "anonymous_residual", detail: `config 已存在未被本次 manifest 声明的匿名条目（同 prefix 换装会静默继承）：${residual.join("、")}——请先清理 config.yaml 的 auth.anonymous_paths 后再安装` });
+		}
+	}
+
 	// ── web 段（C2-27 语法；integrity 重算比对属 deployWeb→smoke 段，不在本段）──
 	const web = m.web;
 	if (web !== undefined) {

package/templates/src/app/api/_platform/_lifecycle/steps/reload.ts

@@ -1,12 +1,17 @@
-// 热更步骤（P1-9，十阶段 stage reloading；R18）：经注入 reload 面调 oj server.reloadConfig()
-// （platform 特权 API，oj 0.1.75 起落地；S1-5.2 实测五键形状 {generation, unchanged, applied[],
-// restart_pending[], kept_listener[]}，与 POST /_system/config 同一 executor 同一把串行锁——
-// 并发第二次触发抛 busy 409）。终态断言（R18）：unchanged = config 改写未实际生效判失败
-// （幂等回显 = 热更目标未达成，重试不自愈）；expected 段键须逐一 ∈ applied——缺省 ["vars"]
-// （B-11 安装触发面 = vars.ojm_install_seq 自增，PRD E5 实测 vars 可热生效；S1-5 实测
-// anonymous_paths 热改属 restart_pending 不可热生效，mounts 断言可经 ctx.expected 覆盖）。
-// reload 面经 ctx 注入（DIP）：生产 = (globalThis as any).server.reloadConfig 包装（P1-10 接线），
-// 测试 stub 注入成功/unchanged/抛错三态。
+// 热更步骤（P1-9，十阶段 stage reloading）：经注入 reload 面调 oj server.reloadConfig()
+// （platform 特权 API，oj 0.1.75 起落地；v0.1.122 起 manifests 锁纳入变化检测——装/卸只动锁即
+// 触发装配，卸载空转由此解决）。返回形状恒定（api-manual §10）：
+//   { generation, unchanged, applied[], restart_pending[], kept_listener[] }
+// - applied 双符号契约（v0.1.122）：模块条目 `+<name>@<ver>`（装/升级）/ `-<name>@<ver>`（卸），
+//   段 diff 条目（mounts/tenant/tasks）同列一数组；升级 = `-旧@v` + `+新@v` 成对。
+// - unchanged=true 时三清单为空（config 与 manifests 锁双双未变）；v0.1.122 起 vars/auth 等
+//   冻结/特权段**如实归入 restart_pending**——旧版把 vars 静默误标进 applied 已修正。
+// 并发撞锁 → 抛 `reload in progress (busy)`（409）；归一/装配失败 → 抛 HTTP 400；交接中断 / cron
+// 拉起失败 → 抛 500（old task pool did not stop within 10s 等，新代任务就地收场）。
+// 终态断言（R18 修订 / §2.7）：安装路径 unchanged=true = 已是最新装配 = 幂等成功（不再判失败）；
+// 卸载 unchanged=true = 空转回归仍判失败。applied 符号：卸载强制 -name@ver；安装默认不强制
+// +name@ver（smoke 段行为化校验挂载是否真通——探活拿到 200 即证模块已装配）。force 透传
+// （v0.1.123）要求 reload 实际重跑（unchanged=false），否则判失败。reload 面经 ctx 注入（DIP）。
 
 import type { InstallContext } from "./preflight";
 
@@ -20,13 +25,17 @@ export interface ReloadResult {
 }
 
 export interface ReloadFace {
-	reloadConfig: () => Promise<ReloadResult>
+	/** oj 0.1.123+ 支持 reloadConfig(force)：force=true 强制重装配，绕过 unchanged 幂等短路 */
+	reloadConfig: (force?: boolean) => Promise<ReloadResult>
 }
 
 export interface ReloadContext extends InstallContext {
 	/** 注入式 reload 面（生产 = platform 特权 server.reloadConfig 包装；测试 stub） */
 	reload: ReloadFace
-	/** 须实际生效的段键（R18 终态断言）；缺省 ["vars"]（B-11 安装触发面） */
+	/**
+	 * 除模块符号外须逐一 ∈ applied 的附加段键（缺省空；v0.1.122 起 vars/auth 等冻结/特权段已归入
+	 *  restart_pending，不再入 applied——故不再默认期望 vars）
+	 */
 	expected?: string[]
 }
 
@@ -35,47 +44,102 @@ export interface StageResult {
 	ok: boolean
 	message: string
 	retryable?: boolean
+	/**
+	 * 热更返回的待重启段（v0.1.122 restart_pending）；非空 = 部分生效、需宿主重启后才完全生效。
+	 *  install/卸载形态均据其标 partial + restartRequired（无守护形态，P0 §3.6 / 验收 15）
+	 */
+	restartPending?: string[]
 }
 
-export async function reloadAndAssert(ctx: ReloadContext): Promise<StageResult> {
-	let r: ReloadResult;
-	try {
-		r = await ctx.reload.reloadConfig();
-	}
-	catch (e) {
-		return { stage: "reloading", ok: false, retryable: true, message: `热更失败：reloadConfig 抛错（${String(e)}）——并发 busy 可重试（附录 A reloading；R18）` };
-	}
+function isObj(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** 是否有 api 模块（决定 oj 是否产出装配条目）：web-only（无 api 段）不强制模块符号，仅校验 reload 已探测变更 */
+export function hasApiModule(manifest: unknown): boolean {
+	return isObj(manifest) && isObj(manifest.api);
+}
+
+/** 模块符号（v0.1.122 applied 双符号契约）：装 = +<name>@<ver>；卸 = -<name>@<ver> */
+export function moduleSymbolOf(name: string, version: string, kind: "install" | "uninstall"): string {
+	return `${kind === "install" ? "+" : "-"}${name}@${version}`;
+}
+
+/**
+ * reload 终态断言（R18 修订 / §2.7）：
+ * - 形状违约（非对象 / applied 非数组 / unchanged 非布尔）→ 失败。
+ * - unchanged=true（config 与 manifests 锁双双未变）：
+ *     · 卸载（kind=uninstall）→ 失败：锁未摘除 = 卸载空转回归（重试不自愈）。
+ *     · 安装 + force=true → 失败：--force 要求强制重装配，宿主却报告无变更可重做（装配径失效）。
+ *     · 安装 + 非强制 → **成功**：unchanged = 已是最新装配 = 幂等成功（R18 修订：不再视为失败；
+ *       升级/重装本就由 manifests 锁 diff 自然触发 unchanged=false，盘上本就一致时 idempotent ok）。
+ * - 模块符号（卸 -name@ver）：仅卸载且 hasApi 为真时强制——卸载必须显式拆装；安装**默认不强制**
+ *   +name@ver（R18 修订：smoke 段行为化校验挂载是否真通——探活端点 200 即证模块已装配，不必在
+ *   reload 层重复断言；锁 diff 自会驱动装配，applied 空属正常幂等态）。
+ * - 附加段键（ctx.expected，如 mounts/tenant/tasks）逐一 ∈ applied（覆盖项保留）。
+ * 返回 {ok, message?} 供调用方生成人话。
+ */
+export function assertReloadApplied(r: ReloadResult, opts: { hasApi: boolean, kind: "install" | "uninstall", name: string, version: string, additional?: string[], /** 强制热更（oj 0.1.123+ reloadConfig(force)）：unchanged 时须失败（强制装配未生效） */ force?: boolean }): { ok: boolean, message?: string } {
 	if (typeof r !== "object" || r === null || !Array.isArray(r.applied) || typeof r.unchanged !== "boolean") {
 		return {
-			stage: "reloading",
 			ok: false,
-			retryable: false,
-			message: `热更失败：reloadConfig 返回形状违约（S1-5.2 五键形状 {generation, unchanged, applied, restart_pending, kept_listener}）：${JSON.stringify(r)?.slice(0, 200)}`,
+			message: `reloadConfig 返回形状违约（v0.1.122 五键 {generation, unchanged, applied[], restart_pending[], kept_listener[]}）：${JSON.stringify(r)?.slice(0, 200)}`,
 		};
 	}
+	// 无代际信号（dev/embedded 的 reload 回落 no-op：不提供 generation）= 无法验证，放行（不阻挡
+	// 卸载/安装主流程；真实 reload 恒返回 generation，故此信号等价于「reload 未实际执行」）。
+	if (r.generation === undefined) {
+		return { ok: true };
+	}
 	if (r.unchanged) {
+		if (opts.kind === "uninstall") {
+			return {
+				ok: false,
+				message: "reloadConfig 返回 unchanged——卸载后锁未变化，疑似卸载空转（锁未摘除）；请确认宿主已开启 reload_api 且 oj ≥ v0.1.122",
+			};
+		}
+		if (opts.force === true) {
+			return {
+				ok: false,
+				message: "reloadConfig 返回 unchanged——--force 要求强制重装配，但宿主报告无变更可重做（锁 diff / 文档 sha 变化后仍 unchanged 说明强制装配未生效）；请确认宿主 oj ≥ v0.1.123 且 reload_api 已开启",
+			};
+		}
+		// 非强制安装：unchanged = 已是最新装配 = 幂等成功（R18 修订）
 		return {
-			stage: "reloading",
-			ok: false,
-			retryable: false,
-			message: "热更失败：reloadConfig 返回 unchanged——config 改写未实际生效（R18 终态断言：幂等回显 = 热更目标未达成，重试不自愈），请检查 config 写入段后重试安装",
+			ok: true,
+			message: "reloadConfig 返回 unchanged——当前已是最新装配（幂等成功，R18 修订：锁 / 文档未变化即无需重装配）",
 		};
 	}
-	// 安装路径缺省期望 vars（B-11：reload 触发变更 = vars.ojm_install_seq 自增，PRD E5 实测
-	// vars 可热生效；unchanged 判定基于 config 文档 sha，安装器 reloading 段前置落盘自增）。
-	// anonymous 并入即 mounts 段生效的语义保留——调用方经 ctx.expected 显式覆盖。
-	const expected = ctx.expected ?? ["vars"];
-	const missing = expected.filter(k => !r.applied.includes(k));
+	// 模块符号：仅卸载且 hasApi 为真时强制 -name@ver（R18 修订：安装默认不强制 +name@ver，
+	// 由 smoke 段行为化校验挂载；本层只拦卸载空转——锁未摘除 = 未实际拆除）。
+	const requireSymbol = opts.kind === "uninstall" && opts.hasApi;
+	const symbol = requireSymbol ? moduleSymbolOf(opts.name, opts.version, "uninstall") : undefined;
+	const missing = [...(symbol ? [symbol] : []), ...(opts.additional ?? [])].filter(k => !r.applied.includes(k));
 	if (missing.length > 0) {
 		return {
-			stage: "reloading",
 			ok: false,
-			retryable: false,
-			message: `热更失败：applied [${r.applied.join("、")}] 未含预期生效段 ${missing.join("、")}（R18：以 reload 返回的 mounts/vars 实际生效值做终态断言）`,
+			message: `reloadConfig applied [${r.applied.join("、")}] 未含预期生效项 ${missing.join("、")}（R18 / §2.7：以 reload 实际 applied 做终态断言，卸载空转回归的唯一拦截点）`,
 		};
 	}
+	return { ok: true };
+}
+
+export async function reloadAndAssert(ctx: ReloadContext): Promise<StageResult> {
+	let r: ReloadResult;
+	try {
+		r = await ctx.reload.reloadConfig(ctx.force === true ? ctx.force : undefined);
+	}
+	catch (e) {
+		return { stage: "reloading", ok: false, retryable: true, message: `热更失败：reloadConfig 抛错（${String(e)}）——并发 busy / 归一装配失败 / 交接中断 / cron 拉起失败均可重试（R18）` };
+	}
+	// 安装路径（R18 修订）：默认不强制 +name@ver——模块装配由锁 diff 驱动，smoke 段行为化校验挂载；
+	// 仅 force 未生效 / ctx.expected 覆盖项缺失 / 形状违约会判失败。
+	const a = assertReloadApplied(r, { hasApi: hasApiModule(ctx.manifest), kind: "install", name: ctx.name, version: ctx.version, additional: ctx.expected, force: ctx.force === true });
+	if (!a.ok) {
+		return { stage: "reloading", ok: false, retryable: false, message: `热更失败：${a.message}` };
+	}
 	const pending = Array.isArray(r.restart_pending) && r.restart_pending.length > 0
-		? `；待重启段 [${r.restart_pending.join("、")}]（anonymous_paths 热改属 restart_pending，S1-5）`
+		? `；待重启段 [${r.restart_pending.join("、")}]（anonymous_paths / vars 等冻结·特权段热改属 restart_pending，v0.1.122）`
 		: "";
-	return { stage: "reloading", ok: true, message: `热更完成：generation ${r.generation ?? "?"}，已生效段 [${r.applied.join("、")}]${pending}` };
+	return { stage: "reloading", ok: true, message: `热更完成：generation ${r.generation ?? "?"}，已生效段 [${r.applied.join("、")}]${pending}`, restartPending: Array.isArray(r.restart_pending) ? r.restart_pending : [] };
 }

package/templates/src/app/api/_platform/_lifecycle/steps/smoke.ts

@@ -30,12 +30,6 @@ export interface SmokeContext extends InstallContext {
 	modulesJsonPath: string
 	/** 注册快照查询；缺省回落 queryRegistered（isolate db 全局；测试注入 stub） */
 	query?: (name: string) => Promise<SolutionSnapshot | null>
-	/**
-	 * 本次安装**新追加**进 config.yaml `auth.anonymous_paths` 的路径（reloading 段注入，带前导 /）。
-	 * 匿名接线属 restart_pending（reload 段已明示），本进程内尚未生效——探活对这些路径的
-	 * 401 判「待重启」而非失败；已在配置里却仍 401 才是真失败（说明接线或守卫有问题）。
-	 */
-	deferredAnonymous?: string[]
 }
 
 export interface StageResult {
@@ -138,17 +132,15 @@ export async function smoke(ctx: SmokeContext): Promise<StageResult> {
 		if (target !== undefined) {
 			const url = probeUrlOf(ctx.apiPrefix, target);
 			const res = await ctx.fetch(url, { headers: { [PROBE_TENANT_HEADER]: PROBE_TENANT } });
-			if (health !== undefined && !res.ok) {
-				// health 探针本就是「无凭证预期 401」（文件头注释：非匿名无凭证预期 401；D14/Q-A：health 不强制）。
-				// 租户化站点上安装/重装/升级后宿主需重启才能加载新配置（含匿名接线、路由），探针在重启前收 401
-				// 是 restart_pending 的常态，不是包或站点的问题——一律判 deferred，不计入失败（P2 深检可兜底真异常）。
-				// 非 401（如 500）仍视为真实失败，正常报错。
-				const deferred = res.status === 401;
-				if (deferred) {
-					notes.push(`探活 ${url} 返回 401：health 端点为无凭证探针，宿主重启加载新配置（路由/匿名接线）后即 2xx——属 restart_pending，重启宿主后生效，不计入失败`);
+			if (!res.ok) {
+				// 无凭证探针（含租户化站点强制 X-TENANT-ID，仍无业务凭证）收 401 是 restart_pending 常态——
+				// 宿主重启加载新配置（路由/匿名接线）后即 2xx，不是包或站点问题，一律判 deferred 不计入失败。
+				// 非 401（如 404/500）视为真实失败（P0 §3.5：首个路由 404/连通失败 = 冒烟失败，避免假成功）。
+				if (res.status === 401) {
+					notes.push(`探活 ${url} 返回 401：无凭证探针，宿主重启加载新配置（路由/匿名接线）后即 2xx——属 restart_pending，重启宿主后生效，不计入失败`);
 				}
 				else {
-					failures.push({ item: "探活", retryable: true, reason: `health 端点 ${url} 返回 HTTP ${res.status}（C2-33 冒烟探针要求 2xx）` });
+					failures.push({ item: "探活", retryable: true, reason: `探针 ${url} 返回 HTTP ${res.status}（期望 2xx；404/5xx 视为冒烟失败）` });
 				}
 			}
 		}

package/templates/src/app/api/_platform/_lifecycle/text-edit.ts

@@ -49,25 +49,6 @@ export function ensureReloadApi(content: string): { content: string, changed: bo
 	return { content: insertAnchor(content, "# ojm:reload", "reload_api: true"), changed: true };
 }
 
-/**
- * 安装序号自增（B-11 reload 触发面；PRD E5 实测先例：vars 段语义值改动可热生效，而
- * reloadConfig 的 unchanged 判定基于 config 文档 sha——不落盘变更则热更恒 unchanged）。
- * R18 同纪律：纯文本行操作，注释/缩进/键序逐字保留，`ojm_install_seq: N` 整行自增为 N+1
- * （行内尾注释原样保留）。键缺失/形状不符 = 可读报错不猜位置（键随模板 config.yaml 发布；
- * 用户删行 = 显式退出热更触发，安装器拒绝静默安装）。
- */
-export function bumpInstallSeq(content: string): { content: string, seq: number } {
-	const lines = content.split("\n");
-	const idx = lines.findIndex(l => /^\s*ojm_install_seq\s*:\s*\d+\s*(?:#.*)?$/.test(l));
-	if (idx === -1) {
-		throw new Error("text-edit: config.yaml 缺 ojm_install_seq: N 行（vars 安装序号，模板 config.yaml 随发，勿删）——reload 热更无变更可落（unchanged 恒真），安装终止于 reloading 段");
-	}
-	const m = /^(\s*ojm_install_seq\s*:\s*)(\d+)/.exec(lines[idx]!)!;
-	const seq = Number(m[2]) + 1;
-	lines[idx] = `${m[1]}${seq}${lines[idx]!.slice(m[0].length)}`;
-	return { content: lines.join("\n"), seq };
-}
-
 /**
  * C2-26 anonymous 运行时接线（P2-15③ 承载，观察项 6 收口）：把方案的匿名端点追加进
  * config.yaml `auth.anonymous_paths` 列表（oj 匿名模型 config 独占；热改属
@@ -108,3 +89,74 @@ export function appendAnonymousPaths(content: string, paths: string[]): { conten
 	lines.splice(last + 1, 0, ...added.map(p => `${itemIndent}- ${p}`));
 	return { content: lines.join("\n"), added };
 }
+
+/**
+ * `appendAnonymousPaths` 的逆操作（P0 补偿清单 §3.5）：把指定匿名路径从 `auth.anonymous_paths`
+ * 列表移除。纯文本判定，与 append 同源——按行 `- <path>`（trim 匹配）删除，列表其余项/注释/空行
+ * 原样保留；幂等：路径不在列表内则 no-op、返回 removed=[]。键缺失（从未接线）= 没东西可删，no-op。
+ * `paths` 形态应与 append 传入一致（方案相对形态），本函数统一补前导 `/` 对齐写入形态。
+ */
+export function removeAnonymousPaths(content: string, paths: string[]): { content: string, removed: string[] } {
+	if (paths.length === 0) {
+		return { content, removed: [] };
+	}
+	const wanted = new Set(paths.map(p => (p.startsWith("/") ? p : `/${p}`)));
+	const lines = content.split("\n");
+	const idx = lines.findIndex(l => /^\s*anonymous_paths\s*:/.test(l));
+	if (idx === -1) {
+		return { content, removed: [] };
+	}
+	// 收集列表项行区间（键行之后连续 `- item`，跳过空行/注释，遇首个其他行即止）
+	const itemLines: number[] = [];
+	for (let i = idx + 1; i < lines.length; i++) {
+		const line = lines[i]!;
+		if (line.trim() === "" || /^\s*#/.test(line)) {
+			continue;
+		}
+		const stripped = line.replace(/#.*$/, "").trim();
+		if (!stripped.startsWith("- ")) {
+			break;
+		}
+		itemLines.push(i);
+	}
+	const removeSet = new Set<number>();
+	const removed: string[] = [];
+	for (const i of itemLines) {
+		const val = lines[i]!.replace(/#.*$/, "").trim().slice(2).trim();
+		if (wanted.has(val)) {
+			removeSet.add(i);
+			removed.push(val);
+		}
+	}
+	if (removed.length === 0) {
+		return { content, removed: [] };
+	}
+	const next = lines.filter((_, i) => !removeSet.has(i));
+	return { content: next.join("\n"), removed };
+}
+
+/**
+ * 纯文本解析 `auth.anonymous_paths` 列表（P0 §3.2 质辩1 / E8 残留检测消费面）：与 append/remove
+ * 同源的列表收集口径——从 `anonymous_paths:` 键行起，连续 `- item` 行（跳过空行/注释）逐行取值。
+ * 用于「读」已装站点的匿名条目，不修改文本。键缺失 = 返回 []。
+ */
+export function readAnonymousPaths(content: string): string[] {
+	const lines = content.split("\n");
+	const idx = lines.findIndex(l => /^\s*anonymous_paths\s*:/.test(l));
+	if (idx === -1) {
+		return [];
+	}
+	const out: string[] = [];
+	for (let i = idx + 1; i < lines.length; i++) {
+		const line = lines[i]!;
+		if (line.trim() === "" || /^\s*#/.test(line)) {
+			continue;
+		}
+		const stripped = line.replace(/#.*$/, "").trim();
+		if (!stripped.startsWith("- ")) {
+			break;
+		}
+		out.push(stripped.slice(2).trim());
+	}
+	return out;
+}