@oj-module/cli 0.2.18 → 0.2.20

package/templates/package.json

@@ -9,7 +9,7 @@
 		"preview": "ojm preview",
 		"info": "ojm info",
 		"typecheck": "tsc --noEmit -p tsconfig.json",
-		"typecheck:api": "tsc --noEmit -p api/tsconfig.json"
+		"typecheck:api": "tsc --noEmit -p src/tsconfig.json"
 	},
 	"devDependencies": {
 		"@ant-design/cssinjs": "catalog:",

package/templates/{api/src/_platform → src/_platform/api}/_lifecycle/installer.ts

@@ -89,6 +89,8 @@ export interface InstallRequest extends InstallContext {
 	expected?: string[]
 	/** 安装器内部通道（外部调用方忽略）：终态审计读 status/failedStage/taskId + migrate 捕获 appliedSeq */
 	outcome?: { taskId?: string, status?: TaskStatus, failedStage?: InstallStage, appliedSeq?: number | null, cancelled?: boolean }
+	/** 安装器内部通道（reloading → smoke）：本次新追加进 auth.anonymous_paths 的路径（restart_pending，探活对其 401 判待重启） */
+	deferredAnonymous?: string[]
 	/**
 	 * 取消安装令牌（U5，P3-8）：运行期外部置位（端点 `?cancel=<taskId>` 或任务状态 `cancelling` 驱动的闭包），
 	 * 返回 true 即中止——PIPELINE 循环每段前探测 + migrating 段 spawn 流逐块探测；幂等、可重入
@@ -347,6 +349,8 @@ async function reloadStage(req: InstallRequest): Promise<StageResult> {
 		const anonymous = Array.isArray(api.anonymous) ? api.anonymous.filter((x): x is string => typeof x === "string") : [];
 		const patched = anonymous.length > 0 ? appendAnonymousPaths(bumped.content, anonymous) : { content: bumped.content, added: [] };
 		await atomicWriteText(path, patched.content);
+		// 交接给 smoke：本次真正新增的匿名路径在重启前恒 401（restart_pending）
+		req.deferredAnonymous = patched.added;
 	}
 	catch (e) {
 		return { stage: "reloading", ok: false, retryable: true, message: `热更失败：config.yaml 安装序号自增/匿名端点接线失败（${String(e)}）——reload unchanged 判定基于 config 文档 sha，无变更则热更不可能生效（B-11，PRD E5 口径）` };

package/templates/{api/src/_platform → src/_platform/api}/_lifecycle/steps/smoke.ts

@@ -30,6 +30,12 @@ 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 {
@@ -116,6 +122,7 @@ export async function smoke(ctx: SmokeContext): Promise<StageResult> {
 	const web = isObj(m.web) ? m.web : undefined;
 
 	// ① 探活：health 优先（2xx），缺省首个非匿名路由（连通即可）
+	const notes: string[] = [];
 	try {
 		const health = typeof m.health === "string" && m.health !== "" ? m.health : undefined;
 		const target = health ?? firstNonAnonymousRoute(m);
@@ -123,7 +130,18 @@ export async function smoke(ctx: SmokeContext): Promise<StageResult> {
 			const url = probeUrlOf(ctx.apiPrefix, target);
 			const res = await ctx.fetch(url);
 			if (health !== undefined && !res.ok) {
-				failures.push({ item: "探活", retryable: true, reason: `health 端点 ${url} 返回 HTTP ${res.status}（C2-33 冒烟探针要求 2xx）` });
+				// 本次安装新增的匿名接线尚未生效（restart_pending）：此处的 401 反映的是
+				// 「宿主还没重启」，不是包或站点的问题——判待重启并落人话提示，不判失败。
+				const rel = (s: string) => s.replace(/^\/+/, "");
+				const healthRel = rel(health);
+				const pending = (ctx.deferredAnonymous ?? []).some(a => healthRel === rel(a) || healthRel.startsWith(`${rel(a)}/`));
+				const deferred = res.status === 401 && pending;
+				if (deferred) {
+					notes.push(`探活 ${url} 返回 401：该端点是本次安装新增的匿名路径（auth.anonymous_paths），匿名接线属 restart_pending——重启宿主后生效，不计入失败`);
+				}
+				else {
+					failures.push({ item: "探活", retryable: true, reason: `health 端点 ${url} 返回 HTTP ${res.status}（C2-33 冒烟探针要求 2xx）` });
+				}
 			}
 		}
 	}
@@ -205,7 +223,8 @@ export async function smoke(ctx: SmokeContext): Promise<StageResult> {
 	// ④ entry 浏览器加载不在安装器验（设计 §4.1）——无判定，口径钉于成功 message。
 
 	if (failures.length === 0) {
-		return { stage: "smoke", ok: true, message: "冒烟通过：探活 / integrity / 注册一致性 三项全过（entry 浏览器加载不在安装器验——设计 §4.1，宿主 error boundary + P2 深检兜底）" };
+		const passed = "冒烟通过：探活 / integrity / 注册一致性 三项全过（entry 浏览器加载不在安装器验——设计 §4.1，宿主 error boundary + P2 深检兜底）";
+		return { stage: "smoke", ok: true, message: notes.length === 0 ? passed : `${passed}\n${notes.map(n => `- ${n}`).join("\n")}` };
 	}
 	return {
 		stage: "smoke",

package/templates/{api/src/_platform → src/_platform/api}/market/api.ts

@@ -52,9 +52,9 @@ export interface MarketEnv {
 	trustPath: string
 	/** sqlite 库文件路径（R14 备份源；模板 config.yaml `sqlite://db.sqlite` → 站点根 db.sqlite） */
 	dbPath: string
-	/** 站点 web 模块目录（<dist>/modules） */
+	/** 站点 web 模块目录（站点产物根下的 modules/） */
 	siteModulesDir: string
-	/** 站点 modules.json 路径（与 siteModulesDir 同属 <dist>） */
+	/** 站点 modules.json 路径（与 siteModulesDir 同属站点产物根） */
 	modulesJsonPath: string
 	/** API 前缀（smoke 探针 URL 前缀） */
 	apiPrefix: string
@@ -78,17 +78,20 @@ export interface MarketEnv {
 	/** 迁移账本 head 真源（P1-16 接线①：缺省读 oj journal 表 `_oj_migrations` max(version)，查询失败 → null 不猜） */
 	ledgerHeadOf?: (name: string) => Promise<number | bigint | null>
 	/**
-	 * 宿主 versions.json（C2-09 peerRuntime 比对真源，键 = 包名）。缺省读 <dist>/versions.json
-	 * （ojm 宿主构建产物，与 modules.json 同目录，B-11 接线）；不可得 → undefined，manifest 声明
-	 * peerRuntime 即预检 fail-closed 拒装（C2-09 语义保持）。
+	 * 宿主 versions.json（C2-09 peerRuntime 比对真源，键 = 包名）。缺省读 `<sharedRoot>/versions.json`
+	 * （ojm 宿主构建产物：与 manifests.yaml 同层，即 release 根，B-11 接线）；不可得 → undefined，
+	 * manifest 声明 peerRuntime 即预检 fail-closed 拒装（C2-09 语义保持）。
 	 */
 	hostVersions?: Record<string, string>
 }
 
-/** 宿主 versions.json 布局推导（B-11）：与 modules.json 同目录（<dist>/versions.json） */
-export function versionsJsonPathOf(modulesJsonPath: string): string {
-	const slash = modulesJsonPath.lastIndexOf("/");
-	return slash === -1 ? "versions.json" : `${modulesJsonPath.slice(0, slash)}/versions.json`;
+/**
+ * 宿主 versions.json 布局推导（B-11）：与 manifests.yaml 同层（release 根 = `sharedRoot`），
+ * 不是站点产物根——两处根在 `src/<name>/{api,web}` 布局下已分流（`api/dist` vs `web/dist`）。
+ */
+export function versionsJsonPathOf(releaseRoot: string): string {
+	const trimmed = releaseRoot.replace(/\/+$/, "");
+	return trimmed === "" ? "versions.json" : `${trimmed}/versions.json`;
 }
 
 /** 宿主 versions.json 解析（纯函数）：{packageName: version} 全字符串表；任何违约 → undefined（fail-closed 不猜） */
@@ -113,30 +116,37 @@ export function parseVersionsJson(text: string): Record<string, string> | undefi
 	return out;
 }
 
-/** hostVersions 注入缺省：显式注入优先，否则读 <dist>/versions.json；不可得 → undefined（C2-09 fail-closed） */
+/** hostVersions 注入缺省：显式注入优先，否则读 `<sharedRoot>/versions.json`；不可得 → undefined（C2-09 fail-closed） */
 async function hostVersionsOf(env: MarketEnv): Promise<Record<string, string> | undefined> {
 	if (env.hostVersions !== undefined) {
 		return env.hostVersions;
 	}
 	try {
-		return parseVersionsJson(new TextDecoder().decode(await fsFace().readFile(versionsJsonPathOf(env.modulesJsonPath))));
+		return parseVersionsJson(new TextDecoder().decode(await fsFace().readFile(versionsJsonPathOf(env.sharedRoot))));
 	}
 	catch {
 		return undefined;
 	}
 }
 
-/** oj serve release 布局生产缺省（P1-16 B3/B4；全字段可覆盖） */
+/**
+ * oj serve release 布局生产缺省（P1-16 B3/B4；全字段可覆盖）。
+ *
+ * 两处根在 `src/<name>/{api,web}` 布局下分流，且都相对 fs jail 根（= config.yaml 所在目录）：
+ *   release 根 `api/dist` —— 版本目录 / manifests.yaml / versions.json / migrations（后端产物）
+ *   站点根   `web/dist`   —— modules/ + modules.json（前端产物，安装器 upsert 的落点）
+ * 暂存 / 任务 / 状态 / 信任库 / db 仍在 jail 根下：它们是安装器私有面，不属任何产物根。
+ */
 export function marketEnv(): MarketEnv {
 	return {
-		sharedRoot: "dist",
+		sharedRoot: "api/dist",
 		staging: "modules/.staging",
 		taskDir: "modules/.install-tasks",
 		statePath: "modules/.solutions/state.yaml",
 		trustPath: ".solutions/trusted-keys.yaml",
 		dbPath: "db.sqlite",
-		siteModulesDir: "dist/modules",
-		modulesJsonPath: "dist/modules.json",
+		siteModulesDir: "web/dist/modules",
+		modulesJsonPath: "web/dist/modules.json",
 		apiPrefix: "/api",
 		ledgerHeadOf: journalHeadOf,
 	};

package/templates/{api/src/_platform → src/_platform/api}/solutions/api.ts

@@ -30,12 +30,16 @@ import { journalHeadOf, siteOrigin } from "../_shared/site-facade";
 /** 线格式行（与 packages/runtime/src/api/rbac/types.ts 的 SolutionRouteRow 对齐） */
 export type { SolutionRouteRow } from "../_lifecycle/verify-checks";
 
-/** oj serve release 布局生产缺省 */
+/**
+ * oj serve release 布局生产缺省（与 marketEnv 同口径，见其注释）：
+ *   sharedRoot     = 后端 release 根（版本目录 / migrations）
+ *   modulesJsonPath = 站点产物根下的 modules.json（web 入口 integrity 真源）
+ */
 export function solutionsEnv(): SolutionsEnv {
 	return {
-		sharedRoot: "dist",
+		sharedRoot: "api/dist",
 		statePath: "modules/.solutions/state.yaml",
-		modulesJsonPath: "dist/modules.json",
+		modulesJsonPath: "web/dist/modules.json",
 		apiPrefix: "/api",
 	};
 }

package/templates/{api/src/auth → src/auth/api}/_shared/login-throttle.ts

@@ -1,7 +1,7 @@
 // 登录限速编排（B5/AC1-26）：auth/login 与 auth/ldap-login 共用的 (IP, username) 双维度守卫 + 失败记账。
 // 状态全在 DB（sys_login_throttle/sys_rate_window，迁移 0009）——oj 每请求重建模块，进程内方案恒失效（§9.3-3）。
-import { auditOp } from "../../_platform/_shared/service/infra/audit";
-import { loginBlocked, loginFailed, loginSucceeded, rateLimit } from "../../_platform/_shared/service/infra/rate";
+import { auditOp } from "#/_platform/_shared/service/infra/audit";
+import { loginBlocked, loginFailed, loginSucceeded, rateLimit } from "#/_platform/_shared/service/infra/rate";
 
 /** 客户端 IP：优先 X-Forwarded-For（反代后），回落 X-Real-IP。 */
 export async function clientIp(): Promise<string> {

package/templates/{api/src/auth → src/auth/api}/_shared/session.ts

@@ -4,8 +4,8 @@
 // B4：access JWT 仅载 sub（roles 走登录响应/资料接口，不进 claims）。
 // B3：refresh = 不透明随机串 + DB 存 SHA-256 哈希（sys_refresh_token，迁移 0008）；
 //     轮换作旧 + 滑动窗口（绝对 TTL 封顶 min(旧 exp, now+30d)）；reuse 检测全族吊销 + 审计。
-import { invalidateUser } from "../../_platform/_shared/service/infra/access";
-import { recordOp } from "../../_platform/_shared/service/infra/audit";
+import { invalidateUser } from "#/_platform/_shared/service/infra/access";
+import { recordOp } from "#/_platform/_shared/service/infra/audit";
 
 export interface SessionDeps {
 	randomHex: (bytes: number) => string

package/templates/{api/src/auth → src/auth/api}/api.ts

@@ -1,4 +1,4 @@
-import { respond } from "../_platform/_shared/respond";
+import { respond } from "#/_platform/_shared/respond";
 // oj 嵌套 handler 组：组名 = 路径段（login → POST /api/auth/login，路由不变）。
 // 阶段 B 登录链（D14/AC1-12/13/27）：领域逻辑全在 _shared/session.ts（createSession 注入 deps），
 // handler 只编排：取参 → 调 service → json 信封；B5 限速收敛在 _shared/login-throttle.ts（与 ldap-login 共用）。

package/templates/{api/src/auth → src/auth/api}/ldap-login/api.ts

@@ -1,6 +1,6 @@
 // POST /api/auth/ldap-login —— LDAP 目录登录（D1/AC1-12；匿名端点，E6：anonymous_paths 写 /auth/ldap-login）。
 // 编排：B5 限速守卫（与 auth/login 同维度）→ ldapLogin 九步 → respond 统一异常出口（§9.3-1）。
-import { respond } from "../../_platform/_shared/respond";
+import { respond } from "#/_platform/_shared/respond";
 import { createLdapLogin, runtimeLdapGateway } from "../_shared/ldap-login";
 import { clientIp, guardLoginThrottle, noteLoginFailed, noteLoginSucceeded } from "../_shared/login-throttle";
 import { createSession } from "../_shared/session";

package/templates/src/auth/api/manifest.yaml

@@ -0,0 +1,6 @@
+name: auth
+desc: JWT 鉴权端点（业务路由）：login/refresh/logout；Bearer 守卫由 oj-auth 提供
+version: 0.1.0
+deps: # 两处都用：login/refresh 读 _platform.users（ownership_guard: deny，§3/S003）；
+  # 跨模块别名 `#/_platform/…` 的依赖门禁（oj build S008）
+  _platform: ^0.1.0

package/templates/{web/src/oj-market → src/oj-market/web}/__tests__/InstallDialog.test.tsx

@@ -1,5 +1,6 @@
 import type { IndexRow, TaskRecord } from "../types";
-import { screen, waitFor } from "@testing-library/react";
+import { fireEvent, screen, waitFor } from "@testing-library/react";
+import { useState } from "react";
 import { describe, expect, it } from "vitest";
 import { InstallDialog } from "../components/InstallDialog";
 import { InMemoryMarketClient } from "./marketClient.fake";
@@ -69,4 +70,55 @@ describe("installDialog 安装进度（BDD）", () => {
 		expect(client.calls).toContain("install:alpha@1.1.0");
 		expect(screen.getByText("回滚中")).toBeTruthy();
 	});
+
+	it("given needs_trust 终态 When 打开 Then 渲染指纹与确认按钮，点击后入库并重试安装", async () => {
+		const pending: TaskRecord = {
+			id: "t1",
+			name: "alpha",
+			version: "1.2.0",
+			status: "needs_trust",
+			stage: "verifying",
+			progress: 18,
+			message: "待信任确认",
+			stages: [],
+			trust: { key_id: "alpha.author", public_key: "ab".repeat(32), fingerprint: "6afc".repeat(16) },
+			startedAt: 0,
+		};
+		const client = new InMemoryMarketClient({ taskRecord: pending, installResult: { task_id: "t1" } });
+		renderWithProviders(<InstallDialog row={row} open onClose={() => {}} />, client);
+		const button = await screen.findByText("指纹一致，信任并重试");
+		expect(screen.getByTestId("install-trust-fingerprint").textContent).toContain("6afc".repeat(16));
+		fireEvent.click(button);
+		await waitFor(() => expect(client.calls).toContain("trust:t1"));
+		// 确认入库后自动重试同一安装（staging 未清场，服务端续跑）
+		await waitFor(() => expect(client.calls.filter(c => c.startsWith("install:")).length).toBe(2));
+	});
+
+	it("given 终态 When 父级每次渲染都换 onDone 身份 Then 只通告一次（防 onDone→重渲染→onDone 死循环）", async () => {
+		const done: TaskRecord = {
+			id: "t1",
+			name: "alpha",
+			version: "1.2.0",
+			status: "done",
+			stage: "done",
+			progress: 100,
+			message: "ok",
+			stages: [],
+			startedAt: 0,
+		};
+		const client = new InMemoryMarketClient({ taskRecord: done, installResult: { task_id: "t1" } });
+		function Harness() {
+			const [n, setN] = useState(0);
+			return (
+				<>
+					<span data-testid="done-count">{n}</span>
+					<InstallDialog row={row} open onClose={() => {}} onDone={() => setN(v => v + 1)} />
+				</>
+			);
+		}
+		renderWithProviders(<Harness />, client);
+		await waitFor(() => expect(screen.getByTestId("install-message").textContent).toBe("ok"), { timeout: 5000 });
+		await new Promise(resolve => setTimeout(resolve, 50));
+		expect(screen.getByTestId("done-count").textContent).toBe("1");
+	});
 });

package/templates/{web/src/oj-market → src/oj-market/web}/__tests__/marketClient.fake.ts

@@ -11,6 +11,7 @@ export interface FakeState {
 	enableResult?: { ok: boolean, message: string }
 	uninstallResult?: { ok: boolean, message: string }
 	installResult?: { task_id: string }
+	trustResult?: { result: string, key_id: string, fingerprint: string }
 }
 
 export class InMemoryMarketClient implements MarketClient {
@@ -49,6 +50,11 @@ export class InMemoryMarketClient implements MarketClient {
 		} as TaskRecord);
 	}
 
+	async trust(taskId: string) {
+		this.calls.push(`trust:${taskId}`);
+		return this.state.trustResult ?? { result: "added", key_id: "k1", fingerprint: "f".repeat(64) };
+	}
+
 	async enable(input: EnableInput) {
 		this.calls.push(`enable:${input.name}:${input.enabled}`);
 		return this.state.enableResult ?? { ok: true, message: "ok" };

package/templates/{web/src/oj-market → src/oj-market/web}/api/client.ts

@@ -24,6 +24,11 @@ export interface MarketClient {
 	install: (input: InstallInput) => Promise<{ task_id: string }>
 	/** 任务轮询消费面（query 形态 ?id=） */
 	task: (id: string) => Promise<TaskRecord>
+	/**
+	 * TOFU 确认：把 needs_trust 任务记录里的发布方 key 写入宿主信任库（服务端自任务记录重取
+	 * 公钥复算指纹比对，防混淆代理）。确认成功后重试同一安装即可续跑（staging 未清场）。
+	 */
+	trust: (taskId: string) => Promise<{ result: string, key_id: string, fingerprint: string }>
 	/** 生命周期开关（同步 setEnabled，无任务模型；{ok,message} 200 渲染 ok 位） */
 	enable: (input: EnableInput) => Promise<{ ok: boolean, message: string }>
 	/** 市场操作历史（_platform 只读端点 /_platform/market/history） */

package/templates/{web/src/oj-market → src/oj-market/web}/api/defaultClient.ts

@@ -25,9 +25,10 @@ import {
 	platformMarketInstallPost,
 	platformMarketMetaGet,
 	platformMarketTaskGet,
+	platformMarketTrustPost,
 	platformMarketUninstallImpactGet,
 	platformMarketUninstallPost,
-} from "../../_platform/__client/api";
+} from "../../../_platform/web/__client/api";
 
 // 绑定运行时 request 到生成 client 的模块级单槽（生成 client 是静态单例，必须由某处
 // bindRequest；此处兜底确保市场子应用无论挂载顺序都能拿到请求实例）。与 _platform 模块
@@ -96,6 +97,11 @@ export const httpMarketClient: MarketClient = {
 		// 运行时形状由服务端真源 + DEV zod 校验保证，TS 侧以领域类型为准。
 		return (await platformMarketTaskGet({ id })) as unknown as TaskRecord;
 	},
+	async trust(taskId: string) {
+		// 服务端自任务记录重取公钥复算指纹比对（防混淆代理），前端只传 task_id，不传公钥
+		const data = await platformMarketTrustPost({ task_id: taskId });
+		return data as { result: string, key_id: string, fingerprint: string };
+	},
 	async enable(input: EnableInput) {
 		const data = await platformMarketEnablePost({ name: input.name, enabled: input.enabled });
 		return data as { ok: boolean, message: string };

package/templates/{web/src/oj-market → src/oj-market/web}/components/InstallDialog.tsx

@@ -1,6 +1,6 @@
 import type { IndexRow, TaskRecord } from "../types";
 import { Alert, Button, Modal, Progress, Space, Typography } from "antd";
-import React, { useEffect, useState } from "react";
+import React, { useEffect, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { useMarketClient } from "../api/context";
 import { useInstallTask } from "../hooks/useMarket";
@@ -18,6 +18,17 @@ export interface InstallDialogProps {
 
 const isTerminal = (r: TaskRecord | null) => r != null && r.status !== "running";
 
+/**
+ * 阶段失败指引（契约附录 A 的 `lifecycle.stage.*` key）→ 本模块文案。
+ * 附录 A 的这批 key 在模板 locales 里尚未落地，直接 t() 会把裸 key 显示给运维，
+ * 故此处显式映射；未收录的 key 保持原样（不吞信息）。
+ */
+const HINT_KEYS: Record<string, string> = {
+	"lifecycle.stage.smoke.hint": "oj-market:task:hintSmoke",
+	"lifecycle.stage.cancelled": "oj-market:task:hintCancelled",
+	"lifecycle.stage.reloading.hint": "oj-market:task:hintReloading",
+};
+
 /**
  * 安装/升级/回滚对话框：触发 POST install → 800ms 轮询 TaskRecord 终态渲染（reason+retryable+hintKey 双语）。
  *  回滚 = 对已装旧版降级安装（显式 version）；降版迁移差异校验（R12）的可读失败由终态 error 渲染。
@@ -27,7 +38,13 @@ export function InstallDialog({ row, open, onClose, onDone, version, mode }: Ins
 	const client = useMarketClient();
 	const [taskId, setTaskId] = useState<string | null>(null);
 	const [started, setStarted] = useState(false);
+	const [trusting, setTrusting] = useState(false);
+	const [trustError, setTrustError] = useState<string | null>(null);
 	const { record, done } = useInstallTask(taskId);
+	// onDone 对同一任务只通告一次：父级每次渲染都会换 onDone 身份，若只靠 deps 触发，
+	// 终态后 onDone → index.retry() → 父级重渲染 → onDone 身份变 → 再触发，会形成
+	// 无限请求循环（浏览器侧表现为 ERR_INSUFFICIENT_RESOURCES）。
+	const notifiedTaskId = useRef<string | null>(null);
 
 	const targetVersion = version ?? row?.latest ?? null;
 	const title
@@ -49,15 +66,43 @@ export function InstallDialog({ row, open, onClose, onDone, version, mode }: Ins
 		if (!open) {
 			setTaskId(null);
 			setStarted(false);
+			setTrustError(null);
+			notifiedTaskId.current = null;
 		}
 	}, [open, row, started, client, targetVersion]);
 
 	useEffect(() => {
-		if (record && isTerminal(record) && done)
-			onDone?.(record);
+		if (!record || !isTerminal(record) || !done)
+			return;
+		if (notifiedTaskId.current === record.id)
+			return;
+		notifiedTaskId.current = record.id;
+		onDone?.(record);
 	}, [record, done, onDone]);
 
+	// TOFU 确认：确认入库后重试同一安装（服务端 staging 未清场，续跑不重下）
+	const handleTrustConfirm = async () => {
+		if (taskId === null || taskId.startsWith("__error__"))
+			return;
+		setTrusting(true);
+		setTrustError(null);
+		try {
+			await client.trust(taskId);
+			notifiedTaskId.current = null;
+			setTaskId(null);
+			setStarted(false);
+		}
+		catch (e) {
+			setTrustError(e instanceof Error ? e.message : String(e));
+		}
+		finally {
+			setTrusting(false);
+		}
+	};
+
 	const terminal = isTerminal(record);
+	const needsTrust = record?.status === "needs_trust";
+	const succeeded = record?.status === "done";
 	const failed = record?.status === "failed" || record?.status === "partial";
 	const errorTask = typeof taskId === "string" && taskId.startsWith("__error__");
 
@@ -78,9 +123,35 @@ export function InstallDialog({ row, open, onClose, onDone, version, mode }: Ins
 			)}
 			{record && (
 				<>
-					<Progress percent={record.progress} status={terminal ? (failed ? "exception" : "success") : "active"} />
+					<Progress percent={record.progress} status={terminal ? (succeeded ? "success" : "exception") : "active"} />
 					<div data-testid="install-stage">{record.stage ? t(`oj-market:task:stage.${record.stage}`, record.stage) : record.stage}</div>
 					<div data-testid="install-message">{record.message}</div>
+					{needsTrust && record?.trust && (
+						<Alert
+							style={{ marginTop: 12 }}
+							type="warning"
+							showIcon
+							message={t("oj-market:task:trustTitle")}
+							description={(
+								<Space direction="vertical" size={4}>
+									<span>{t("oj-market:task:trustBody", { keyId: record.trust.key_id })}</span>
+									<span data-testid="install-trust-fingerprint">
+										{t("oj-market:task:trustFingerprint")}
+										<Typography.Text code copyable={{ text: record.trust.fingerprint }}>
+											{record.trust.fingerprint}
+										</Typography.Text>
+									</span>
+									<span>{t("oj-market:task:trustHint")}</span>
+								</Space>
+							)}
+						/>
+					)}
+					{needsTrust && trustError && <Alert style={{ marginTop: 8 }} type="error" showIcon message={trustError} />}
+					{needsTrust && (
+						<Button type="primary" style={{ marginTop: 12 }} loading={trusting} onClick={handleTrustConfirm}>
+							{t("oj-market:task:trustConfirm")}
+						</Button>
+					)}
 					{failed && record.error && (
 						<Alert
 							type="error"
@@ -89,7 +160,11 @@ export function InstallDialog({ row, open, onClose, onDone, version, mode }: Ins
 							description={(
 								<Space direction="vertical">
 									<span>{record.error.retryable ? t("oj-market:task:retryable") : t("oj-market:task:notRetryable")}</span>
-									{record.error.hintKey && <span data-testid="install-hint">{t(record.error.hintKey, record.error.hintKey)}</span>}
+									{record.error.hintKey && (
+										<span data-testid="install-hint">
+											{t(HINT_KEYS[record.error.hintKey] ?? record.error.hintKey, record.error.hintKey)}
+										</span>
+									)}
 								</Space>
 							)}
 						/>

package/templates/{web/src/oj-market → src/oj-market/web}/hooks/useMarket.ts

@@ -40,8 +40,13 @@ export function useInstallTask(taskId: string | null): {
 	const [done, setDone] = useState(false);
 
 	useEffect(() => {
-		if (!taskId)
+		// 无任务 id = 尚无任务：清空上一次任务的记录，避免「重新安装/信任后重试」时
+		// 旧终态（可能是 needs_trust）残留在弹窗里被误读成本次结果。
+		if (!taskId) {
+			setRecord(null);
+			setDone(false);
 			return;
+		}
 		let active = true;
 		setRecord(null);
 		setDone(false);

package/templates/{web/src/oj-market → src/oj-market/web}/locales/en-US.json

@@ -49,12 +49,21 @@
 			"running": "Running",
 			"done": "Done",
 			"failed": "Failed",
-			"partial": "Partial"
+			"partial": "Partial",
+			"needs_trust": "Awaiting trust"
 		},
+		"trustTitle": "Trust confirmation required: publisher key not in host trust store",
+		"trustBody": "The signing key of publisher \"{{keyId}}\" is not trusted by this host yet (first-use TOFU).",
+		"trustFingerprint": "Key fingerprint: ",
+		"trustHint": "Compare this fingerprint with the one published by the vendor; confirm only if they match. Confirming retries this install automatically and reuses the staged files.",
+		"trustConfirm": "Fingerprint matches — trust and retry",
 		"reason": "Reason",
 		"retryable": "Retryable",
 		"notRetryable": "Not retryable",
 		"hint": "Hint",
+		"hintSmoke": "Smoke probe failures usually mean one of two things: (1) the anonymous endpoints added by this install (auth.anonymous_paths) are pending a restart — restart the host and retry; (2) in dev the host already ships a module with the same name, so the route belongs to the source module and the probe is not hitting the freshly installed package.",
+		"hintCancelled": "This install was cancelled: lock file, version directory and staging were restored to their pre-install state. You can retry directly.",
+		"hintReloading": "Config hot-reload was partial: hot-applicable sections (vars, ...) are applied, while the auth section (including anonymous endpoints) needs a host restart.",
 		"close": "Close",
 		"viewLog": "View log"
 	},

package/templates/{web/src/oj-market → src/oj-market/web}/locales/zh-CN.json

@@ -49,12 +49,21 @@
 			"running": "进行中",
 			"done": "完成",
 			"failed": "失败",
-			"partial": "部分完成"
+			"partial": "部分完成",
+			"needs_trust": "待信任确认"
 		},
+		"trustTitle": "待信任确认：发布方密钥不在宿主信任库",
+		"trustBody": "发布方「{{keyId}}」的签名密钥尚未被本宿主信任（首次信任 TOFU）。",
+		"trustFingerprint": "密钥指纹：",
+		"trustHint": "请与发布方公布的公钥指纹逐字核对，一致才确认。确认后会自动重试本次安装，已暂存的内容不会重新下载。",
+		"trustConfirm": "指纹一致，信任并重试",
 		"reason": "原因",
 		"retryable": "可重试",
 		"notRetryable": "不可重试",
 		"hint": "提示",
+		"hintSmoke": "冒烟探活失败常见于两类原因：① 本次安装新增的匿名端点（auth.anonymous_paths）属「待重启生效」，重启宿主后再点重试即可；② dev 形态下宿主已内置同名模块，该路由由源码模块占位，探活打到的不是刚装的包。",
+		"hintCancelled": "本次安装已被取消：锁、版本目录与 staging 均已回到发起前状态，可直接重试。",
+		"hintReloading": "配置热更未完全生效：可热改段（vars 等）已应用，auth 段（含匿名端点）需重启宿主后生效。",
 		"close": "关闭",
 		"viewLog": "查看日志"
 	},

package/templates/{web/src/oj-market → src/oj-market/web}/types.ts

@@ -5,8 +5,12 @@
 /** 安装阶段名（契约附录 A 十阶段逐字 + lock_commit/audit/done 终态） */
 export type InstallStage = "preflight" | "downloading" | "verifying" | "extracting" | "migrating" | "lock_commit" | "registering" | "deploying_web" | "reloading" | "smoke" | "audit" | "done";
 
-/** 任务状态（§10.2 三态 + partial：锁后失败部分生效） */
-export type TaskStatus = "running" | "done" | "failed" | "partial";
+/**
+ * 任务状态（§10.2 三态 + partial：锁后失败部分生效 + needs_trust：未知发布方 key 待人工
+ * TOFU 确认，staging 不清场，确认入库后重试同一安装即可续跑）。
+ * needs_trust 是非成功态：消费面不得按绿色成功渲染（真源 api/src/_platform/_lifecycle/types.ts:64）。
+ */
+export type TaskStatus = "running" | "done" | "failed" | "partial" | "needs_trust";
 
 /** 阶段明细日志（UI 详情日志区数据源） */
 export interface TaskStageLog {
@@ -22,6 +26,13 @@ export interface TaskError {
 	hintKey?: string
 }
 
+/** needs_trust 终态：待确认的发布方 key（指纹 = sha256(public_key) 十六进制，供人核对） */
+export interface TaskTrust {
+	key_id: string
+	public_key: string
+	fingerprint: string
+}
+
 /** 安装任务记录（§10.2 + stages 明细日志；落 .install-tasks/<id>.json，800ms 轮询消费面） */
 export interface TaskRecord {
 	id: string
@@ -34,6 +45,8 @@ export interface TaskRecord {
 	message: string
 	stages: TaskStageLog[]
 	error?: TaskError
+	/** needs_trust 终态才有：待确认的发布方 key（POST /market/trust {task_id} 消费） */
+	trust?: TaskTrust
 	startedAt: number
 	finishedAt?: number
 	appliedSeq?: number

package/templates/{api/src/system → src/system/api}/login-methods/api.ts

@@ -1,7 +1,7 @@
-import { respond } from "../../_platform/_shared/respond";
+import { respond } from "#/_platform/_shared/respond";
 // GET /api/system/login-methods —— 登录方式发现（C5/D2；匿名端点：登录前无 token，
 // 项目 config.yaml auth.anonymous_paths 必须列 /system/login-methods，漏列则握手 401 登录页必坏）。
-import { listLoginMethods } from "../../_platform/_shared/service/domain/settings";
+import { listLoginMethods } from "#/_platform/_shared/service/domain/settings";
 
 async function get() {
 	await respond(async () => {

package/templates/src/system/api/manifest.yaml

@@ -0,0 +1,6 @@
+name: system
+desc: 框架管理域端点（/api/system/*）：角色/权限点管理（assertSystemAdmin 判权，H2）
+version: 0.1.0
+deps: # 两处都用：roles/bindings/permissions 读写 _platform 的 sys_* 表（ownership_guard: deny）；
+  # 跨模块别名 `#/_platform/…` 的依赖门禁（oj build S008）
+  _platform: ^0.1.0

package/templates/{api/src/system → src/system/api}/oplog/api.ts

@@ -1,9 +1,9 @@
-import { respond } from "../../_platform/_shared/respond";
+import { respond } from "#/_platform/_shared/respond";
 // GET /api/system/oplog?action=&username=&module=&limit= —— 操作日志查询（AC1-29；D13 admin 可查）。
 // POST /api/system/oplog —— 操作日志写入（C3；登录态即可，解决方案模块记录自身操作）。
-import { assertSystemAdmin, currentAccess } from "../../_platform/_shared/service/infra/access";
-import { recordOp } from "../../_platform/_shared/service/infra/audit";
-import { searchOplog } from "../../_platform/_shared/service/infra/oplog";
+import { assertSystemAdmin, currentAccess } from "#/_platform/_shared/service/infra/access";
+import { recordOp } from "#/_platform/_shared/service/infra/audit";
+import { searchOplog } from "#/_platform/_shared/service/infra/oplog";
 
 async function get() {
 	await respond(async () => {