dsh-plugin-t-expert 0.2.7 → 0.2.10

package/lib/plan-check.js

@@ -1,43 +1,19 @@
+// @ts-check
 /**
  * DAG 预检（只读）：把「打算创建的一整套任务」先跑一遍引擎的校验，**一次报出全部问题**。
  *
  * 为什么需要它：引擎建任务是**逐条**的（依赖只能引用已存在的任务），每条硬校验都单独拒绝，
  * 中途失败会留下半成品，模型再重试就容易出现重复任务（本机实测踩过）。
- * 这里复用引擎自己的 `validateCreateTask`（契约/写域重叠/质量门槛），再补上引擎在
- * `validateStagedGraph`（未导出）里做的引用与环检查，全部在内存里模拟、不写任何状态。
+ * 这里复用引擎自己的 `validateCreateTask`（契约/写域重叠/质量门槛），**并复用引擎导出的
+ * `collectStagedGraphProblems`** 做引用与环检查 —— 全部在内存里模拟、不写任何状态。
+ *
+ * 规则**只有一份**（`lib/teams/tools.js`）：过去这里按同规则复刻过一遍，两处一旦漂移，
+ * 预检就会说 ok、真建任务却被引擎拒 —— 而预检的全部意义正是提前发现这种岔路。
  */
-import { CAPTAIN_KEY, readTeam } from "./teams/state.js";
+import { CAPTAIN_KEY } from "./teams/state.js";
+import { normalizeAssigneeForCreate } from "./teams/assignee-contract.js";
 import { validateCreateTask } from "./teams/quality-gates.js";
-
-/** 与引擎 `validateStagedGraph` 对齐的引用/环检查（该函数未导出，这里按同规则复刻）。 */
-function graphProblems(tasks) {
-  const problems = [];
-  const ids = new Set(tasks.map((task) => task.id));
-  for (const task of tasks) {
-    if (String(task.subject ?? "").trim() === "") problems.push(`任务 ${task.id} 缺少 subject`);
-    for (const dependency of task.dependencies ?? []) {
-      if (dependency === task.id) problems.push(`任务 ${task.id} 不能依赖自己`);
-      else if (!ids.has(dependency)) problems.push(`任务 ${task.id} 依赖不存在的 ${dependency}`);
-    }
-  }
-  // 环路检测（DFS 三色）
-  const visiting = new Set();
-  const visited = new Set();
-  const byId = new Map(tasks.map((task) => [task.id, task]));
-  const walk = (id, trail) => {
-    if (visiting.has(id)) {
-      problems.push(`依赖成环：${[...trail, id].join(" → ")}`);
-      return;
-    }
-    if (visited.has(id)) return;
-    visiting.add(id);
-    for (const dependency of byId.get(id)?.dependencies ?? []) walk(dependency, [...trail, id]);
-    visiting.delete(id);
-    visited.add(id);
-  };
-  for (const task of tasks) walk(task.id, []);
-  return [...new Set(problems)];
-}
+import { collectStagedGraphProblems } from "./teams/tools.js";
 
 /** 拓扑序（依赖在前）；有环时返回已排好的部分。 */
 function topologicalOrder(tasks) {
@@ -76,37 +52,61 @@ export function checkPlan(team, tasks) {
   // 逐条模拟：先做静态检查，再跑引擎的 validateCreateTask（它只看已存在的任务 + 已接受的模拟任务）
   const sim = { ...(team ?? {}), tasks: [...existing] };
   const taken = new Set(existing.map((task) => task.id));
-  const labels = new Map(); // 本批 id → 模拟 id
+  // 本批 id（标签）→ 引擎会分配的模拟 id。**按声明顺序累积**，不预先解析全批 —— 见
+  // `resolveDependencies` 的说明：引擎要求依赖已存在，前向引用本就建不出来。
+  const labels = new Map();
+  // 每个位置（含**没有 id 的**任务）→ 模拟 id：发号与标签解析必须共用同一次发号，
+  // 否则「只给带 id 的发号」会让报告里的 id 与实际创建顺序不一致。
+  const simulatedIds = [];
   // 引擎分配的是 `t${team.taskSeq + 1}` 并随后自增（不是"现有任务条数"）。两者只在
   // taskSeq === tasks.length 时才一致 —— 有任务被删除/取消过就会分叉，所以以 taskSeq 为准。
   let counter = Number.isSafeInteger(team?.taskSeq) ? team.taskSeq : existing.length;
-  const report = [];
-
-  proposed.forEach((raw, index) => {
-    const local = [];
-    const wantId = typeof raw?.id === "string" && raw.id.trim() !== "" ? raw.id.trim() : undefined;
+  const issueSimulatedId = () => {
     let simulatedId;
     do {
       counter += 1;
       simulatedId = `t${counter}`;
-    } while (taken.has(simulatedId));
+    } while (taken.has(simulatedId) || existing.some((task) => task.id === simulatedId));
     taken.add(simulatedId);
+    return simulatedId;
+  };
+  const resolveDependencies = (raw) => (Array.isArray(raw?.dependencies) ? raw.dependencies : [])
+    .map((dependency) => String(dependency))
+    .map((dependency) => labels.get(dependency) ?? dependency);
+  const report = [];
+
+  proposed.forEach((raw, index) => {
+    const local = [];
+    const wantId = typeof raw?.id === "string" && raw.id.trim() !== "" ? raw.id.trim() : undefined;
+    const simulatedId = issueSimulatedId();
+    simulatedIds[index] = simulatedId;
+    // 登记在本条**解析依赖之后**：这样 `dependencies` 里的同批标签只有「已声明过的」
+    // 才能解析成模拟 id，与引擎的「依赖必须已存在」一致。
     if (wantId !== undefined) labels.set(wantId, simulatedId);
 
     const subject = String(raw?.subject ?? "").trim();
     if (subject === "") local.push("缺少 subject");
     const kind = typeof raw?.kind === "string" && raw.kind !== "" ? raw.kind : "work";
-    const dependencies = (Array.isArray(raw?.dependencies) ? raw.dependencies : [])
-      .map((dependency) => String(dependency))
-      .map((dependency) => labels.get(dependency) ?? dependency);
+    const dependencies = resolveDependencies(raw);
     if (dependencies.includes(simulatedId)) local.push("不能依赖自己");
+    // 判定「不存在的依赖」时，本批**已声明**的标签算作已知（它们会在模拟里成为真实任务 id）。
     const unknown = dependencies.filter(
-      (dependency) => !taken.has(dependency) && !existing.some((task) => task.id === dependency),
+      (dependency) => !taken.has(dependency) && !labels.has(dependency) && !existing.some((task) => task.id === dependency),
     );
     if (unknown.length > 0) local.push(`依赖不存在的任务：${unknown.join(", ")}`);
-    const assignee = typeof raw?.assignee === "string" && raw.assignee.trim() !== "" ? raw.assignee.trim() : undefined;
-    if (assignee !== undefined && assignee !== CAPTAIN_KEY && !memberNames.has(assignee)) {
-      local.push(`assignee「${assignee}」不是当前成员（用 t_team_status 看成员名，或先 add_member）`);
+    const rawAssignee = typeof raw?.assignee === "string" && raw.assignee.trim() !== "" ? raw.assignee.trim() : undefined;
+    let assignee = rawAssignee;
+    if (rawAssignee !== undefined) {
+      // 预检必须与引擎的 create_task **同规**：captain 不能在这里被"通过"，
+      // 否则预检说 ok、真建任务却被拒 —— 而预检的全部意义就是提前发现这种岔路。
+      try {
+        assignee = normalizeAssigneeForCreate(rawAssignee) ?? rawAssignee;
+      } catch (error) {
+        local.push(error instanceof Error ? error.message : String(error));
+      }
+      if (local.length === 0 && assignee !== undefined && !memberNames.has(assignee)) {
+        local.push(`assignee「${assignee}」不是当前成员（用 t_team_status 看成员名，或先 add_member）`);
+      }
     }
 
     // 引擎的契约/写域/质量门槛校验
@@ -131,8 +131,9 @@ export function checkPlan(team, tasks) {
     report.push({ index, id: wantId ?? simulatedId, simulatedId, subject, ok: local.length === 0, error: local.join("；") });
   });
 
-  // 环检查（含已存在的任务）
-  problems.push(...graphProblems(sim.tasks).map((error) => ({ index: -1, id: "graph", subject: "", error })));
+  // 环/引用检查（含已存在的任务）：**调用引擎导出实现**，不再本地复刻。
+  // 用 requireRunnable=false —— 预检允许"成员还没加"，那是 approve 阶段才要求的。
+  problems.push(...collectStagedGraphProblems(sim, false).map((error) => ({ index: -1, id: "graph", subject: "", error })));
 
   // 提示（不阻塞）：成员同时只能有 1 个未完成任务（引擎在 claim/reassign 时才会拒）
   const openStatuses = new Set(["pending", "claimed", "in_progress"]);
@@ -163,11 +164,3 @@ export function checkPlan(team, tasks) {
     existing: existing.map((task) => ({ id: task.id, status: task.status, kind: task.kind ?? "work", assignee: task.assignee ?? "" })),
   };
 }
-
-/** 从磁盘读当前团队（captain 会话 → 团队）。 */
-export async function readCaptainTeam({ stateRoot, captainSessionId, findTeamByCaptain }) {
-  const team = await findTeamByCaptain(stateRoot, captainSessionId);
-  return team;
-}
-
-export { readTeam };

package/lib/remote-schemas.js

@@ -0,0 +1,156 @@
+// @ts-check
+/**
+ * Remote 线格式的**单一 schema 源**（A-2 / A-3）。
+ *
+ * 为什么要有这个文件：这些 schema 过去在 host（`lib/remote.js`）与客户端（`src/client.jsx`）
+ * 各写了一份，**13 个同名定义逐字重复**。加一个 remote 方法或改一个字段要改两处，漏改一处
+ * 不会在加载期报错，只会在调用期炸（或更糟：静默把字段剥掉）。
+ *
+ * 权威在 **host**：它同时是生产方与校验方（`lib/remote.js` 的 DESCRIPTORS 用的就是这些对象），
+ * 客户端只是消费方。所以统一后 host 的校验强度不变，客户端变严——方向是安全的。
+ * 统一过程中修正了两处真实不一致：
+ *   1. `squadInputSchema.key` 客户端原来没有 `min(1).max(64)`；
+ *   2. 客户端原来把团队快照叫 `catalogSchema`、把 `teamMemberSchema` 内联写了一遍。
+ *
+ * ⚠️ 本文件只放**纯 schema**，不放 host 专属的 `descriptor()` 或客户端专属的 `direct()` 信封
+ * —— 两端信封的字段（`id` 前缀、`result` 形状）本来就不同，强行合并反而更脆。
+ */
+import { z } from "zod";
+
+export const expertSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  nameEn: z.string(),
+  description: z.string(),
+  descriptionEn: z.string(),
+  emoji: z.string(),
+  division: z.string(),
+  divisionZh: z.string(),
+  divisionEn: z.string(),
+  conflict: z.boolean().optional(),
+  /** 用户自建专家（可编辑/可删除）；内置专家不带此标记。 */
+  custom: z.boolean().optional(),
+  /** 自建专家文件指纹：编辑/删除时回传，用于拦住并发覆盖。 */
+  hash: z.string().optional(),
+});
+
+/** 新建/编辑自建专家的入参（面板表单字段）。 */
+export const customExpertInputSchema = z.object({
+  slug: z.string().min(1).max(128).optional(),
+  name: z.string().min(1).max(200),
+  nameEn: z.string().max(200).optional(),
+  description: z.string().min(1).max(1000),
+  descriptionEn: z.string().max(1000).optional(),
+  emoji: z.string().max(16).optional(),
+  body: z.string().min(1).max(60000),
+  /** 落点分区（自建分区目录名）；留空＝默认分区。服务端仍会自己校验一遍。 */
+  division: z.string().max(128).optional(),
+  /** 新建分区时的中文显示名（落在 <customRoot>/divisions.json）。 */
+  divisionLabel: z.string().max(40).optional(),
+});
+
+/** `getCatalog` 及分类写回方法的返回快照。 */
+export const catalogSnapshotSchema = z.object({
+  experts: z.array(expertSchema),
+  enabled: z.array(z.string()),
+  revision: z.number().int().min(0),
+  // 这两个字段必须声明：zod 会把 schema 里没有的键**直接剥掉**（实测），
+  // 漏声明时面板拿到的快照里根本没有它们，界面上表现为"分区标签是空的"。
+  customDivision: z.string().optional(),
+  customDivisionLabel: z.string().optional(),
+  /** 可选的落点分类（面板「分类」下拉与管理页）：官方在前，其余按目录/声明发现。 */
+  categories: z.array(z.object({
+    key: z.string(),
+    label: z.string(),
+    official: z.boolean(),
+    count: z.number().int().min(0),
+    customCount: z.number().int().min(0),
+  })).optional(),
+});
+
+export const enabledStateSchema = z.object({
+  enabled: z.array(z.string()),
+  revision: z.number().int().min(0),
+});
+
+export const promptSchema = z.object({ prompt: z.string() });
+
+export const squadMemberSchema = z.object({
+  slug: z.string(),
+  role: z.string(),
+  name: z.string(),
+  nameZh: z.string(),
+  division: z.string(),
+  divisionZh: z.string(),
+  known: z.boolean(),
+});
+
+export const squadSchema = z.object({
+  key: z.string(),
+  description: z.string(),
+  aliases: z.array(z.string()),
+  taskPlanning: z.enum(["captain", "seed"]),
+  enabled: z.boolean(),
+  members: z.array(squadMemberSchema),
+});
+
+export const rosterExpertSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  nameZh: z.string(),
+  division: z.string(),
+  divisionZh: z.string(),
+  enabled: z.boolean(),
+  conflict: z.boolean(),
+});
+
+export const squadsSnapshotSchema = z.object({
+  revision: z.string(),
+  squads: z.array(squadSchema),
+  experts: z.array(rosterExpertSchema),
+  lastBuild: z.object({ at: z.number(), ok: z.boolean(), output: z.string() }),
+});
+
+export const teamMemberSchema = z.object({
+  name: z.string(),
+  role: z.string(),
+  status: z.string(),
+  activity: z.string(),
+  done: z.number(),
+  total: z.number(),
+});
+
+export const teamSchema = z.object({
+  teamId: z.string(),
+  name: z.string(),
+  workspace: z.string(),
+  captainSessionId: z.string(),
+  phase: z.string(),
+  halted: z.boolean(),
+  members: z.array(teamMemberSchema),
+  tasks: z.array(z.object({ id: z.string(), subject: z.string(), status: z.string(), assignee: z.string() })),
+});
+
+export const teamsSnapshotSchema = z.object({ teams: z.array(teamSchema) });
+
+export const startResultSchema = z.object({
+  profile: z.string(),
+  label: z.string(),
+  members: z.number(),
+});
+
+export const stopResultSchema = z.object({
+  teamName: z.string(),
+  cancelledTasks: z.number(),
+  alreadyHalted: z.boolean(),
+});
+
+/** 面板提交的小队定义（saveSquads 的入参）。 */
+export const squadInputSchema = z.object({
+  key: z.string().min(1).max(64),
+  description: z.string(),
+  aliases: z.array(z.string()),
+  taskPlanning: z.enum(["captain", "seed"]),
+  enabled: z.boolean(),
+  members: z.array(z.string()),
+});

package/lib/remote.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * T专家 remote 服务：把 host 侧的名册/启用状态/persona 通过 Typert Gateway 暴露给客户端面板。
  *
@@ -6,142 +7,39 @@
  */
 import { Remote, RemoteError, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { z } from "zod";
-import { CATALOG_SERVICE, SETTINGS_NAMESPACE, SQUAD_SERVICE, TEAM_SERVICE } from "./index.js";
+import { CATALOG_SERVICE, SETTINGS_NAMESPACE, SQUAD_SERVICE, TEAM_SERVICE, UNKNOWN_SLUG_ERROR_CODE } from "./index.js";
 
-const expertSchema = z.object({
-  slug: z.string(),
-  name: z.string(),
-  nameEn: z.string(),
-  description: z.string(),
-  descriptionEn: z.string(),
-  emoji: z.string(),
-  division: z.string(),
-  divisionZh: z.string(),
-  divisionEn: z.string(),
-  conflict: z.boolean().optional(),
-  /** 用户自建专家（可编辑/可删除）；内置专家不带此标记。 */
-  custom: z.boolean().optional(),
-  /** 自建专家文件指纹：编辑/删除时回传，用于拦住并发覆盖。 */
-  hash: z.string().optional(),
-});
-
-/** 新建/编辑自建专家的入参（面板表单字段）。 */
-const customExpertInputSchema = z.object({
-  slug: z.string().min(1).max(128).optional(),
-  name: z.string().min(1).max(200),
-  nameEn: z.string().max(200).optional(),
-  description: z.string().min(1).max(1000),
-  descriptionEn: z.string().max(1000).optional(),
-  emoji: z.string().max(16).optional(),
-  body: z.string().min(1).max(60000),
-  /** 落点分区（自建分区目录名）；留空＝默认分区。服务端仍会自己校验一遍。 */
-  division: z.string().max(128).optional(),
-  /** 新建分区时的中文显示名（落在 <customRoot>/divisions.json）。 */
-  divisionLabel: z.string().max(40).optional(),
-});
-
-const catalogSnapshotSchema = z.object({
-  experts: z.array(expertSchema),
-  enabled: z.array(z.string()),
-  revision: z.number().int().min(0),
-  // 这两个字段必须声明：zod 会把 schema 里没有的键**直接剥掉**（实测），
-  // 漏声明时面板拿到的快照里根本没有它们，界面上表现为"分区标签是空的"。
-  customDivision: z.string().optional(),
-  customDivisionLabel: z.string().optional(),
-  /** 可选的落点分类（面板「分类」下拉与管理页）：官方在前，其余按目录/声明发现。 */
-  categories: z.array(z.object({
-    key: z.string(),
-    label: z.string(),
-    official: z.boolean(),
-    count: z.number().int().min(0),
-    customCount: z.number().int().min(0),
-  })).optional(),
-});
-
-const enabledStateSchema = z.object({
-  enabled: z.array(z.string()),
-  revision: z.number().int().min(0),
-});
-
-const promptSchema = z.object({ prompt: z.string() });
-
-const squadMemberSchema = z.object({
-  slug: z.string(),
-  role: z.string(),
-  name: z.string(),
-  nameZh: z.string(),
-  division: z.string(),
-  divisionZh: z.string(),
-  known: z.boolean(),
-});
-
-const squadSchema = z.object({
-  key: z.string(),
-  description: z.string(),
-  aliases: z.array(z.string()),
-  taskPlanning: z.enum(["captain", "seed"]),
-  enabled: z.boolean(),
-  members: z.array(squadMemberSchema),
-});
-
-const rosterExpertSchema = z.object({
-  slug: z.string(),
-  name: z.string(),
-  nameZh: z.string(),
-  division: z.string(),
-  divisionZh: z.string(),
-  enabled: z.boolean(),
-  conflict: z.boolean(),
-});
-
-const squadsSnapshotSchema = z.object({
-  revision: z.string(),
-  squads: z.array(squadSchema),
-  experts: z.array(rosterExpertSchema),
-  lastBuild: z.object({ at: z.number(), ok: z.boolean(), output: z.string() }),
-});
-
-const teamMemberSchema = z.object({
-  name: z.string(),
-  role: z.string(),
-  status: z.string(),
-  activity: z.string(),
-  done: z.number(),
-  total: z.number(),
-});
-
-const teamSchema = z.object({
-  teamId: z.string(),
-  name: z.string(),
-  workspace: z.string(),
-  captainSessionId: z.string(),
-  phase: z.string(),
-  halted: z.boolean(),
-  members: z.array(teamMemberSchema),
-  tasks: z.array(z.object({ id: z.string(), subject: z.string(), status: z.string(), assignee: z.string() })),
-});
-
-const teamsSnapshotSchema = z.object({ teams: z.array(teamSchema) });
-const startResultSchema = z.object({
-  profile: z.string(),
-  label: z.string(),
-  members: z.number(),
-});
-const stopResultSchema = z.object({
-  teamName: z.string(),
-  cancelledTasks: z.number(),
-  alreadyHalted: z.boolean(),
-});
+/**
+ * 领域码形态：`<domain>/<reason>`（如 `tTeam/squads-invalid`）。
+ *
+ * 只有通过它校验的 `error.code` 才允许当 wire code 透传 —— 系统 errno（`EACCES`…）不是领域码，
+ * 透传出去会让客户端按 code 分支时把「文件权限」误认成业务失败类型（D-17）。口径与宿主网关一致
+ * （`<domain>/<reason>`，见 docs/cookbook/adding-a-remote-api.md）。
+ */
+const DOMAIN_CODE_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*\/[a-z0-9-]+$/u;
+/** 与 `lib/index.js` 共用的「未知专家 slug」稳定码（不用显示文案做分类，见 D-3）。 */
+const UNKNOWN_SLUG_CODE = UNKNOWN_SLUG_ERROR_CODE;
+
+// A-2/A-3：线格式 schema 的**单一源**在 ./remote-schemas.js（客户端也从这里取），
+// 不再在本文件重复定义一份。host 仍是权威（本文件是生产方与校验方）。
+import {
+  catalogSnapshotSchema,
+  customExpertInputSchema,
+  enabledStateSchema,
+  expertSchema,
+  promptSchema,
+  rosterExpertSchema,
+  squadInputSchema,
+  squadMemberSchema,
+  squadSchema,
+  squadsSnapshotSchema,
+  startResultSchema,
+  stopResultSchema,
+  teamMemberSchema,
+  teamSchema,
+  teamsSnapshotSchema,
+} from "./remote-schemas.js";
 
-/** 面板提交的小队定义（saveSquads 的入参）。 */
-const squadInputSchema = z.object({
-  key: z.string().min(1).max(64),
-  description: z.string(),
-  aliases: z.array(z.string()),
-  taskPlanning: z.enum(["captain", "seed"]),
-  enabled: z.boolean(),
-  members: z.array(z.string()),
-});
 
 /** 一个 direct 调用描述符。 */
 function descriptor(method, parameters, typeSymbol, schema) {
@@ -337,6 +235,8 @@ function exposeRemoteMethods(Class, methods) {
       access: { has: (object) => method in object, get: (object) => object[method] },
       addInitializer: (initializer) => initializer.call(Object.create(Class.prototype)),
     };
+// @ts-expect-error 上游类型缺口：ClassMethodDecoratorContext 的形状比这里手工构造的上下文更严。
+// 运行时有效（dsh-typert-protocol 的 addMarkerInitializer 只读 kind/name/static/private），见 verify 的 remote 小节。
     Remote(method)(Class.prototype[method], context);
   }
 }
@@ -346,19 +246,44 @@ class TTeamRemote extends TypertRemoteService {
 
   constructor(ctx) {
     super(ctx, "tTeam");
+// @ts-expect-error 上游类型缺口：TypertRegistry.register(contribution) 未写进 TypertRegistryContract。
+// 运行时有效：DSH 实际提供的 TypertRegistry 类实现了它（dsh-typert-registry/lib/index.js:398）。
     this.ctx.typert.register(TYPERT);
   }
 
+  /**
+   * host 侧服务缺失的统一领域错误。
+   *
+   * 三个访问器（catalog / squads / teams）共用它：**不要**裸抛 `Error` —— 裸 Error 过线会被
+   * 网关折成 `gateway/internal`，领域信息全丢；也**不要**把「host 没加载」塞进别的领域码
+   * （例如 `tTeam/missing-expert`），那会把「服务不可用」显示成「专家不存在」（D-4）。
+   * @param name - 服务名（写进 details，便于面板区分是哪一个）。
+   * @param hint - 面向用户/面板的原因说明。
+   * @returns 带稳定 code 的 RemoteError。
+   */
+  hostUnavailable(name, hint) {
+// @ts-expect-error 上游类型缺口：RemoteErrorDetailsMap 是**闭合**的 gateway 错误码集合，业务码不在其中。
+// 运行时有效且是设计用法：plugin 自己的 tTeam/* 稳定码（映射文本是**远端**它时自行分类的，见 remote.js 顶部的业务码说明）。
+    return new RemoteError("tTeam/host-unavailable", hint, { service: name });
+  }
+
   /** 名册服务由 host 主插件通过 ctx.reflect.provide 提供。 */
   catalog() {
     const service = this.ctx.get(CATALOG_SERVICE);
-    if (service === undefined) throw new Error("T专家 名册服务不可用（host 插件未加载或已卸载）");
+    if (service === undefined) {
+      throw this.hostUnavailable(CATALOG_SERVICE, "T专家 名册服务不可用（host 插件未加载或已卸载）");
+    }
     return service;
   }
 
   /** 动态名册：完整专家列表 + 已启用 slug + 修订号。 */
   async getCatalog() {
-    return this.catalog().snapshot();
+    try {
+      return await this.catalog().snapshot();
+    } catch (error) {
+      // 服务缺失已在 catalog() 里铸成 tTeam/host-unavailable；这里只兜业务失败。
+      throw this.businessError(error, "tTeam/catalog-unreadable");
+    }
   }
 
   /** 整体替换启用列表；过期修订号由 settings 服务拒绝。 */
@@ -369,27 +294,55 @@ class TTeamRemote extends TypertRemoteService {
       const message = error instanceof Error ? error.message : String(error);
       const code = typeof error === "object" && error !== null ? error.code : undefined;
       // 裸 Error 过线会退化成 gateway/internal 并丢掉 code，所以业务错误统一转成 RemoteError。
-      if (code === "SETTINGS_CONFLICT" || /changed since it was read|another window|其他窗口/.test(message)) {
+      //
+      // 冲突**只认稳定 code**，不再按显示文案兜底（复核 F-3）。依据：
+      //   · 宿主 SettingsConflictError 自带 `code = "SETTINGS_CONFLICT"`，且 dsh-settings 的
+      //     Service Definition 在 JSDoc 里承诺「namespace 移动后拒绝写入即抛 SettingsConflictError」
+      //     —— 也就是说这个 code 是**契约的一部分**，不是实现细节；
+      //   · 原先那条 `/changed since it was read|another window|其他窗口/` 与 D-3 被修掉的根因同类：
+      //     用随宿主版本/locale 变的文案做身份判断，宿主一改措辞冲突就会被误归成 settings-failed；
+      //   · 「其他窗口」在本仓根本不存在于宿主侧，纯属臆测的变体。
+      // 因此无 code 的同类错误会落到下面的 settings-failed（可见且可诊断），而不是被文案猜成冲突。
+      if (code === "SETTINGS_CONFLICT") {
+// @ts-expect-error 上游类型缺口：同上，tTeam/* 业务码不在闭合的 RemoteErrorDetailsMap 里。
         throw new RemoteError("tTeam/conflict", message, { expectedRevision: String(expectedRevision) });
       }
-      if (message.includes("未知专家")) {
+      // 未知专家 slug 由 host 侧抛带稳定 code 的错误（lib/index.js 的 customError）。
+      // **不再**用 message.includes("未知专家") 分类 —— 显示文案随 locale 变，用它做身份会让
+      // 非中文 locale（或任何文案改写）下的错误直接退化成裸 Error，客户端只剩 gateway/internal（D-3）。
+      if (code === UNKNOWN_SLUG_CODE) {
+// @ts-expect-error 上游类型缺口：同上，tTeam/* 业务码不在闭合的 RemoteErrorDetailsMap 里。
         throw new RemoteError("tTeam/unknown-expert", message, {});
       }
-      throw error;
+      throw this.businessError(error, "tTeam/settings-failed");
     }
   }
 
   /** 小队定义服务（设置页「小队」标签）。 */
   squads() {
     const service = this.ctx.get(SQUAD_SERVICE);
-    if (service === undefined) throw new Error("T专家 小队服务不可用（host 插件未加载）");
+    if (service === undefined) {
+      throw this.hostUnavailable(SQUAD_SERVICE, "T专家 小队服务不可用（host 插件未加载）");
+    }
     return service;
   }
 
-  /** 团队运行服务（设置页「团队」标签）。 */
+  /**
+   * 团队运行服务（设置页「团队」标签）。
+   *
+   * 这一处**刻意偏离**「缺服务一律 tTeam/host-unavailable」的统一口径，原因有两条，都记录在此：
+   * ① 语义上仍准确 —— 对 `startSquad` 来说「host 没挂团队服务」就是「这支小队起不来」，
+   *    `tTeam/start-failed` 是可读的，而 `host-unavailable` 会丢掉「用户点的是启动」这层上下文；
+   * ② 向后兼容 —— 既有自检（verify.mjs 的 "startSquad 未知小队 → tTeam/start-failed"）与客户端都把
+   *    这个码当作「启动失败」的分类键，改成新码会让唯一被断言的分类断裂。
+   * 缺的是 `catalog`/`squads` 那两个访问器（没有等价的历史承诺），它们统一走 hostUnavailable()。
+   */
   teams() {
     const service = this.ctx.get(TEAM_SERVICE);
-    if (service === undefined) throw new Error("T专家 团队服务不可用（host 插件未加载）");
+    if (service === undefined) {
+// @ts-expect-error 上游类型缺口：同上，tTeam/* 业务码不在闭合的 RemoteErrorDetailsMap 里。
+      throw new RemoteError("tTeam/start-failed", "T专家 团队服务不可用（host 插件未加载）", { service: TEAM_SERVICE });
+    }
     return service;
   }
 
@@ -439,21 +392,31 @@ class TTeamRemote extends TypertRemoteService {
     }
   }
 
-  /** 业务错误统一转 RemoteError（裸 Error 过线会退化成 gateway/internal 并丢掉 code）。 */
+  /**
+   * 业务错误统一转 RemoteError（裸 Error 过线会退化成 gateway/internal 并丢掉 code）。
+   *
+   * `error.code` 只有**形如 `<domain>/<reason>`** 才能当 wire code 用：系统 errno
+   * （`EACCES`/`ENOENT`/`EPERM`…）过线后被客户端按 code 分支时会误当领域码（D-17），
+   * 所以形态不符一律回落 `fallbackCode`。
+   * @param error - 被捕获的原错误。
+   * @param fallbackCode - 该访问器的领域码。
+   */
   businessError(error, fallbackCode) {
     if (error instanceof RemoteError) return error;
     const message = error instanceof Error ? error.message : String(error);
-    const code = typeof error === "object" && error !== null && typeof error.code === "string" ? error.code : fallbackCode;
-    return new RemoteError(code, message, {});
+    const candidate = typeof error === "object" && error !== null && typeof error.code === "string" ? error.code : undefined;
+    return new RemoteError(DOMAIN_CODE_PATTERN.test(candidate ?? "") ? candidate : fallbackCode, message, {});
   }
 
   /** 按需读取一位专家的 persona 正文（面板预览用）。 */
   async getPrompt(slug, division) {
+    // 先判服务：服务缺失要说「host 不可用」，不能说「专家不存在」——客户端把后者当
+    // 「这位专家不在名册里」，用户于是去一个根本没加载的名册里找人（D-4）。
+    const service = this.catalog();
     try {
-      return await this.catalog().prompt(slug, division);
+      return await service.prompt(slug, division);
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      throw new RemoteError("tTeam/missing-expert", message, { slug });
+      throw this.businessError(error, "tTeam/missing-expert");
     }
   }