pi-pier 0.1.0

package/src/pipe-channel.ts

@@ -0,0 +1,181 @@
+/**
+ * M11 人机通道分离（D45–D47）：pi 扩展自建 Windows 命名管道。
+ *
+ *  - 主控（客户端）：一连接一请求（与 herdr 客户端同风格）；
+ *  - 子 pane（服务端）：PI_HERDR_SUBAGENT=1 的扩展在 session_start 起 server，
+ *    收到 prompt/follow_up 后经 pi.sendUserMessage(followUp) 注入会话本身（TUI 可见）；
+ *  - 完成信息不回传（权威路径 = herdr 状态 + 会话 JSONL + history，D47）。
+ *
+ * 本文件只含传输层纯逻辑（可单测，不依赖 pi API）；
+ * pi 注入由 index.ts 的服务端回调完成。
+ */
+import * as net from 'node:net';
+import { sessionDirName } from './session-tail.ts';
+
+/** 管道名：workspace 作用域（与 history.jsonl 目录命名同约定）+ paneId 编码。 */
+export function pipeNameFor(cwd: string, paneId: string): string {
+  const dir = sessionDirName(cwd);
+  const encoded = String(paneId).replace(/[^A-Za-z0-9_-]/g, '-');
+  return `pi-herdr-${dir}-${encoded}`;
+}
+
+/** Windows 命名管道完整地址（内核命名空间，非文件系统路径）。 */
+export function pipePathFor(name: string): string {
+  return process.platform === 'win32'
+    ? (name.startsWith('\\\\.\\pipe\\') ? name : `\\\\.\\pipe\\${name}`)
+    : `/tmp/${name}.sock`;
+}
+
+/** 管道消息（JSON 行协议；一连接一请求 = 一个请求一个响应）。 */
+export type PipeRequest =
+  | { type: 'ping'; id: string }
+  | {
+      type: 'prompt' | 'follow_up';
+      id: string;
+      text: string;
+      /** 发送方管道名（D49：回复随 from 走；无主从硬编码）。 */
+      from?: string | null;
+      /** D50：结算时是否 push reply（后台 true、前台 false——前台由调用方同步取结果）。 */
+      push?: boolean;
+    }
+  | { type: 'interrupt'; id: string }
+  | {
+      /** D50：结算快路径回信（子 → 请求方；带摘要 + 会话路径，渐进式披露）。 */
+      type: 'reply';
+      id: string;
+      paneId: string;
+      text: string | null;
+      sessionFile: string | null;
+    };
+
+export type PipeResponse =
+  | { type: 'ok'; id: string; detail?: string }
+  | { type: 'error'; id: string; message: string };
+
+/** 解析一行 JSON（坏行返回 null）。 */
+export function parsePipeLine(line: string): PipeRequest | PipeResponse | null {
+  const t = (line ?? '').trim();
+  if (!t) return null;
+  try {
+    const obj = JSON.parse(t);
+    if (obj && typeof obj === 'object' && typeof obj.type === 'string') return obj as PipeRequest | PipeResponse;
+  } catch {
+    /* 坏行 */
+  }
+  return null;
+}
+
+/**
+ * 一连接一请求：连接 → 写一行 JSON → 等一行 JSON 响应 → 断开。
+ * 超时/连接失败/坏响应 → 抛错（调用方决定重试）。
+ */
+export function pipeRequest(
+  pipeName: string,
+  payload: PipeRequest,
+  timeoutMs = 8000,
+): Promise<PipeResponse> {
+  return new Promise((resolve, reject) => {
+    const sock = net.createConnection(pipePathFor(pipeName));
+    sock.setEncoding('utf8');
+    let buf = '';
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        sock.destroy();
+        reject(new Error(`pipe ${pipeName}: ${payload.type} timeout`));
+      }
+    }, timeoutMs);
+    sock.on('connect', () => {
+      sock.write(JSON.stringify(payload) + '\n');
+    });
+    sock.on('data', (chunk) => {
+      buf += chunk;
+      const i = buf.indexOf('\n');
+      if (i < 0) return;
+      clearTimeout(timer);
+      if (settled) return;
+      settled = true;
+      sock.destroy();
+      const parsed = parsePipeLine(buf.slice(0, i));
+      if (!parsed) {
+        reject(new Error(`pipe ${pipeName}: bad response frame`));
+        return;
+      }
+      resolve(parsed);
+    });
+    sock.on('error', (err) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        reject(err);
+      }
+    });
+  });
+}
+
+/** 带重试的 ping（就绪探测；D47 取代 waitSubReady 的 agent 状态门）。 */
+export async function pingUntilReady(
+  pipeName: string,
+  timeoutMs: number,
+  intervalMs = 1000,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await pipeRequest(pipeName, { type: 'ping', id: `ping-${Date.now()}` }, 3000);
+      if (res.type === 'ok') return true;
+    } catch {
+      /* 未就绪，继续 */
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}
+
+export type PipeMessageHandler = (req: PipeRequest) => Promise<PipeResponse>;
+
+/**
+ * 服务端：每连接读一行 → 分发 handler → 回一行 → 断开。
+ * 返回 server 实例（调用方管理 close）。
+ */
+export function startPipeServer(
+  pipeName: string,
+  handler: PipeMessageHandler,
+): net.Server {
+  const server = net.createServer((sock) => {
+    sock.setEncoding('utf8');
+    let buf = '';
+    sock.on('data', (chunk) => {
+      buf += chunk;
+      const i = buf.indexOf('\n');
+      if (i < 0) return;
+      const line = buf.slice(0, i);
+      buf = buf.slice(i + 1);
+      const req = parsePipeLine(line);
+      if (!req) {
+        sock.end(JSON.stringify({ type: 'error', id: '', message: 'bad frame' }) + '\n');
+        return;
+      }
+      void handler(req)
+        .then((res) => {
+          sock.end(JSON.stringify(res) + '\n');
+        })
+        .catch((err: unknown) => {
+          sock.end(JSON.stringify({
+            type: 'error',
+            id: req.id,
+            message: String((err as Error)?.message ?? err),
+          }) + '\n');
+        });
+    });
+    sock.on('error', () => {
+      /* 客户端断开等：静默 */
+    });
+  });
+  server.on('error', () => {
+    /* 地址占用等：由调用方观察（listen 抛错由 startPipeServer 调用方处理） */
+  });
+  server.listen(pipePathFor(pipeName));
+  return server;
+}

package/src/progress-core.ts

@@ -0,0 +1,109 @@
+/**
+ * M16 进度可见性纯核心（开发方案.md §M16；保守形态优先，D3 无新协议）。
+ *
+ * 承载通道（post-M22 世界）：
+ *  - 进度徽标（N/M + 可选 ETA）→ pane title 内嵌（state_labels 键仅五态，进不了 label）；
+ *  - 工具徽标（🔧 tool）→ report_agent.message；
+ *  - 速率估算对齐 kimi 估算器语义：速率窗口、未完成 cap、置信度门。
+ *
+ * 保守原则（风险⑥拍板）：估算不可信时回退纯计数「N/M」，绝不显示误导性 ETA。
+ */
+import { countTodos, type TodoItem } from './vocab.ts';
+
+/** ETA 需要的最少完成点数（<2 无法算速率）。 */
+export const ETA_MIN_SAMPLES = 2;
+/** 速率样本窗口（kimi rate window 语义；取最近 K 个完成点算速率）。 */
+export const RATE_WINDOW_MS = 45_000;
+/** 未完成进度显示上限（kimi unfinished cap 语义；防"快完了"假象）。 */
+export const UNFINISHED_CAP = 0.85;
+/** 完成点新鲜度门：最近完成点距今超过该值 → 数据陈旧，不估 ETA。 */
+export const PROGRESS_STALE_MS = 5 * 60_000;
+/** 速率拟合取最近 K 个完成点。 */
+const RATE_SAMPLE_POINTS = 5;
+
+export interface EtaEstimate {
+  /** 剩余步数。 */
+  remaining: number;
+  /** 预计剩余时间（毫秒）。 */
+  etaMs: number;
+  confidence: 'ok';
+}
+
+/**
+ * 速率估算：完成时间戳 → 剩余步数的 ETA。
+ *  - 完成点 <2 → null（无速率可言）；
+ *  - 最近完成点距今 > PROGRESS_STALE_MS → null（陈旧：爆发后停顿/人为搁置）；
+ *  - 速率 = 取最近 K(≤5) 个点，(k-1) / (t_k - t_1)；eta = remaining / rate。
+ */
+export function estimateEta(opts: {
+  completedAt: readonly number[];
+  total: number;
+  now: number;
+}): EtaEstimate | null {
+  const { completedAt, total, now } = opts;
+  if (total <= 0) return null;
+  const pts = [...completedAt].filter((t) => Number.isFinite(t)).sort((a, b) => a - b);
+  const completed = pts.length;
+  if (completed < ETA_MIN_SAMPLES) return null;
+  if (now - pts[pts.length - 1] > PROGRESS_STALE_MS) return null;
+  const remaining = total - completed;
+  if (remaining <= 0) return { remaining: 0, etaMs: 0, confidence: 'ok' };
+  const sample = pts.slice(-RATE_SAMPLE_POINTS);
+  const span = sample[sample.length - 1] - sample[0];
+  const steps = sample.length - 1;
+  if (steps < 1 || span <= 0) return null;
+  const ratePerMs = steps / span;
+  return { remaining, etaMs: Math.round(remaining / ratePerMs), confidence: 'ok' };
+}
+
+/** title 进度后缀：保守 `3/7`；置信 ETA 时 `3/7 ~4m`；total=0 → 空串；全完成 `5/5 ✓`。 */
+export function formatProgressSuffix(opts: {
+  completed: number;
+  total: number;
+  eta: EtaEstimate | null;
+}): string {
+  const { completed, total, eta } = opts;
+  if (total <= 0) return '';
+  const base = completed >= total ? `${completed}/${total} ✓` : `${completed}/${total}`;
+  if (!eta || eta.etaMs <= 0) return base;
+  const human = eta.etaMs < 60_000 ? '<1m'
+    : (() => {
+      const mins = Math.ceil(eta.etaMs / 60_000);
+      return mins < 60 ? `~${mins}m` : `~${Math.round((mins / 60) * 10) / 10}h`;
+    })();
+  return `${base} ${human}`;
+}
+
+/** 工具徽标（report_agent.message）：单工具名；多工具首 + 计数；空 → null（不覆盖）。 */
+export function planToolBadge(runningToolNames: readonly string[]): string | null {
+  if (runningToolNames.length === 0) return null;
+  const first = runningToolNames[0];
+  return runningToolNames.length === 1 ? `🔧 ${first}` : `🔧 ${first} +${runningToolNames.length - 1}`;
+}
+
+/** 从列表算进度输入（completed 计数 / total 开放计数）。 */
+export function progressOf(items: readonly TodoItem[]): { completed: number; total: number } {
+  const c = countTodos(items);
+  const blockedCount = items.filter((it) => it.status === 'blocked').length;
+  return { completed: c.completed, total: c.completed + c.pending + c.inProgress + blockedCount };
+}
+
+/** 进度徽标徽记整个生命周期后不再显示（防"完成态常驻"噪音；调用方比对用）。 */
+export const PROGRESS_HIDE_MS = 60_000;
+
+/**
+ * 两份列表间的 completed 转换数（按 content 匹配；新列表中 completed 且旧状态非
+ * completed —— 含新增即 completed 的条目）。M16 速率估算的原料：所有编辑路径
+ * （todo_write / 人类编辑 / M17 对账）都过 TodosService，在此统一 diff。
+ */
+export function countCompletedTransitions(
+  before: readonly TodoItem[],
+  after: readonly TodoItem[],
+): number {
+  const oldStatus = new Map(before.map((it) => [it.content, it.status]));
+  let n = 0;
+  for (const it of after) {
+    if (it.status === 'completed' && oldStatus.get(it.content) !== 'completed') n += 1;
+  }
+  return n;
+}

package/src/reconcile-core.ts

@@ -0,0 +1,130 @@
+/**
+ * M17：todo↔subagent 自动对账纯规划器（开发方案.md §M17；P2 = 低置信度不勾+提示）。
+ *
+ * 时机（adapter）：主控收到结算 push（pollLoop / pipe reply）后、注入 followUp 前。
+ * 语义（对齐 omp reconcileTodosWithSubagents）：
+ *  - 匹配：description ↔ todo.content，norm（小写+空白折叠）后 exact → prefix（双向）
+ *    → substring，与 D38 fuzzyFind 同族；
+ *  - 自动勾：仅 settled 且最优档唯一且 ∈ {exact, prefix}，一次结算至多一条；
+ *  - 解锁：blocker ↔ description 同档匹配（exact/prefix）的 blocked 条目回 pending
+ *    （可多条；failed/低置信度不解锁）；
+ *  - 低置信度/歧义/失败：不动列表，noteLines 随结算通知提示（P2 拍板）；
+ *  - 落盘：edits 走 D38 权威路径（pi-herdr.todo-edit custom 条目，分支回放生效）。
+ */
+import { applyTodoEdits, type TodoEdit, type TodoItem } from './todo-core.ts';
+
+export type ReconcileOutcome = 'settled' | 'failed';
+export type MatchTier = 'exact' | 'prefix' | 'substring' | null;
+
+export interface ReconcilePlan {
+  /** 应用 edits 后的列表（无编辑 = 原引用）。 */
+  items: TodoItem[];
+  /** 经权威路径持久化的编辑（done 至多一条 + unblock 若干）。 */
+  edits: TodoEdit[];
+  /** 被自动勾掉的条目（至多一条）。 */
+  completed: TodoItem | null;
+  /** 自动勾的匹配档位（candidates 存在时的最优档；无候选 null）。 */
+  tier: MatchTier;
+  /** 被解锁的条目（blocker 匹配）。 */
+  unblocked: TodoItem[];
+  /** 随结算通知注入的提示行（对齐 D36 反馈语风；无提示 = 空数组）。 */
+  noteLines: string[];
+  /** 匹配率指标（P2：采集用，随结算通知落会话 JSONL）。 */
+  metric: {
+    description: string;
+    outcome: ReconcileOutcome;
+    bestTier: MatchTier;
+    candidates: number;
+    autoCompleted: boolean;
+    unblocked: number;
+  };
+}
+
+function norm(s: string): string {
+  return s.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+
+function matchTier(a: string, b: string): MatchTier {
+  const na = norm(a);
+  const nb = norm(b);
+  if (!na || !nb) return null;
+  if (na === nb) return 'exact';
+  if (na.startsWith(nb) || nb.startsWith(na)) return 'prefix';
+  if (na.includes(nb) || nb.includes(na)) return 'substring';
+  return null;
+}
+
+const TIER_ORDER: Record<Exclude<MatchTier, null>, number> = { exact: 0, prefix: 1, substring: 2 };
+
+export function reconcileTodos(
+  prev: readonly TodoItem[],
+  opts: { description: string; outcome: ReconcileOutcome },
+): ReconcilePlan {
+  const { description, outcome } = opts;
+  const edits: TodoEdit[] = [];
+  const noteLines: string[] = [];
+
+  // 1) 勾选候选：pending / in_progress（completed/abandoned 永不参与）
+  const matchable = prev.filter((t) => t.status === 'pending' || t.status === 'in_progress');
+  const scored = matchable
+    .map((t) => ({ item: t, tier: matchTier(description, t.content) }))
+    .filter((c): c is { item: TodoItem; tier: Exclude<MatchTier, null> } => c.tier !== null)
+    .sort((a, b) => TIER_ORDER[a.tier] - TIER_ORDER[b.tier]);
+  const bestTier = scored.length ? scored[0].tier : null;
+  const best = bestTier ? scored.filter((c) => c.tier === bestTier) : [];
+
+  let completed: TodoItem | null = null;
+  if (bestTier === 'exact' || bestTier === 'prefix') {
+    if (best.length === 1 && outcome === 'settled') {
+      completed = best[0].item;
+      edits.push({ op: 'done', content: completed.content });
+      noteLines.push(`Reconciled: completed "${completed.content}" (${bestTier} match with subagent description).`);
+    } else if (best.length > 1) {
+      // 歧义：列候选，留给人
+      noteLines.push(
+        `Todo match ambiguous between: ${best.map((c) => `"${c.item.content}"`).join(', ')} — update todo_write yourself.`,
+      );
+    } else if (outcome === 'failed') {
+      // 高置信候选但子代理未成功结算 → 保持打开，提示
+      for (const c of best) {
+        noteLines.push(`Todo kept open: "${c.item.content}" (subagent did not settle successfully).`);
+      }
+    }
+  } else if (bestTier === 'substring') {
+    // 低置信度（P2）：不勾，提示候选
+    for (const c of best) {
+      noteLines.push(`Todo not auto-completed (low-confidence match): "${c.item.content}" — update todo_write if this work is done.`);
+    }
+  }
+
+  // 2) 解锁：blocker 任意档匹配（含 substring——真实 blocker 是「等 X 完成」短语，
+  //    描述嵌在中间，prefix 会漏；低置信度闸只管勾选，解锁回 pending 是软操作）且 settled（可多条）
+  const unblocked: TodoItem[] = [];
+  if (outcome === 'settled') {
+    for (const t of prev) {
+      if (t.status !== 'blocked' || typeof t.blocker !== 'string') continue;
+      if (matchTier(description, t.blocker) !== null) {
+        unblocked.push(t);
+        edits.push({ op: 'unblock', content: t.content });
+        noteLines.push(`Unblocked "${t.content}" (was waiting on: ${t.blocker}).`);
+      }
+    }
+  }
+
+  return {
+    items: edits.length ? applyTodoEdits(prev, edits) : prev as TodoItem[],
+    edits,
+    completed,
+    tier: bestTier,
+    unblocked,
+    noteLines,
+    metric: {
+      description,
+      outcome,
+      bestTier,
+      candidates: scored.length,
+      autoCompleted: completed !== null,
+      unblocked: unblocked.length,
+    },
+  };
+}

package/src/role-loader.ts

@@ -0,0 +1,164 @@
+/**
+ * 档2 Week1：role 档案加载器（2026-08-18）；v1.1（2026-08-22）两层用户目录。
+ *
+ * 查找序（v1.1，用户拍板）：
+ *  1. workspace 级 `<cwd>/.pi-herdr/roles/<name>.json`（随 clone 走，团队共享）
+ *  2. 用户全局 `~/.pi/agent/herdr-pi/roles/<name>.json`（跨仓库个人偏好）
+ *  3. 内置 `src/roles/`（本包随附）兜底
+ *
+ * 内置名保留（master / worker-default）：用户/工作区层撞名直接拒绝——D83 镜像
+ * 单测与 D82 姿态锚在内置档案上，被覆盖会破坏这些保证。
+ *
+ * 角色名白名单 [a-z0-9-]+ —— 防路径穿越（不合法名不触盘）。
+ * 档案 role 字段必须与文件名一致（防错挂）。
+ * 校验失败分类：读不到 = ROLE_NOT_FOUND（逐层尝试后才报）；读到了但
+ * JSON/校验/名字不符 = INVALID_ROLE_CONFIG（**在命中层立即报**，不静默落到
+ * 下一层——静默会掩盖用户改了档案却写错的问题）。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { validateRoleManifest, type RoleManifest } from './role-manifest.ts';
+
+/** 内置档案目录（src/roles/）。 */
+export const ROLES_DIR = join(dirname(fileURLToPath(import.meta.url)), 'roles');
+
+/** workspace 级目录（相对基准默认 = 进程 cwd，即 master 的工作目录）。 */
+export function workspaceRolesDir(baseDir?: string): string {
+  return join(baseDir ?? process.cwd(), '.pi-herdr', 'roles');
+}
+
+/** 用户全局目录（~/.pi/agent/herdr-pi/roles/）。 */
+export function userRolesDir(): string {
+  return join(homedir(), '.pi', 'agent', 'herdr-pi', 'roles');
+}
+
+/** 内置保留名（不可被任何用户层覆盖）。 */
+export const RESERVED_ROLE_NAMES: readonly string[] = ['master', 'worker-default'];
+
+const ROLE_NAME_RE = /^[a-z0-9-]+$/;
+
+export class RoleLoaderError extends Error {
+  readonly code: 'ROLE_NOT_FOUND' | 'INVALID_ROLE_CONFIG' | 'ROLE_RESERVED';
+  readonly issues: readonly string[];
+  constructor(
+    code: 'ROLE_NOT_FOUND' | 'INVALID_ROLE_CONFIG' | 'ROLE_RESERVED',
+    message: string,
+    issues: readonly string[] = [],
+  ) {
+    super(message);
+    this.name = 'RoleLoaderError';
+    this.code = code;
+    this.issues = issues;
+  }
+}
+
+export type RoleReader = (fileName: string) => string;
+
+/** 单层读取器（注入式；生产 = existsSync + readFileSync 该目录）。 */
+export type LayerReader = (dir: string, fileName: string) => string | null;
+
+const defaultLayerRead: LayerReader = (dir, fileName) => {
+  const p = resolve(dir, fileName);
+  if (!existsSync(p)) return null;
+  return readFileSync(p, 'utf8');
+};
+
+export interface LoadRoleOptions {
+  /** 单 reader 注入（旧形态：仅命中内置层——测试兼容用）。 */
+  read?: RoleReader;
+  /** 多层 reader 注入（v1.1）。 */
+  layerRead?: LayerReader;
+  /** workspace 层基准目录（默认 process.cwd()）。 */
+  baseDir?: string;
+  /**
+   * 内置名直读：master 自应用（WS-D7）专用——保留名跳过用户层与撞名检查，
+   * 永远加载内置档案。否则 workspace 放 master.json 会让自应用 fail-open，
+   * master 静默丢失 manifest（d11 活体抓到的边界）。
+   */
+  builtinDirect?: boolean;
+}
+
+/** 解析查找层序：workspace → 用户全局 → 内置（每层 {label, dir}）。 */
+export function roleLayers(opts?: { baseDir?: string }): Array<{ label: string; dir: string }> {
+  const base = opts?.baseDir && isAbsolute(opts.baseDir) ? opts.baseDir
+    : resolve(opts?.baseDir ?? process.cwd());
+  return [
+    { label: 'workspace (.pi-herdr/roles/)', dir: workspaceRolesDir(base) },
+    { label: `user (${'~/.pi/agent/herdr-pi/roles/'})`, dir: userRolesDir() },
+    { label: 'builtin (src/roles/)', dir: ROLES_DIR },
+  ];
+}
+
+export function loadRoleConfig(name: string, opts?: LoadRoleOptions): RoleManifest {
+  if (typeof name !== 'string' || !ROLE_NAME_RE.test(name)) {
+    throw new RoleLoaderError('ROLE_NOT_FOUND', `role 不存在或名字非法（[a-z0-9-]+）: ${JSON.stringify(name)}`);
+  }
+  const fileName = `${name}.json`;
+
+  // 旧形态单 reader：直接按内置层语义（既有单测/合成器注入路径不破）
+  if (opts?.read && !opts.layerRead) {
+    let text: string;
+    try {
+      text = opts.read(fileName);
+    } catch (err) {
+      const code = (err as { code?: unknown })?.code;
+      throw new RoleLoaderError('ROLE_NOT_FOUND', `role "${name}" 不存在（读 ${fileName} 失败: ${typeof code === 'string' ? code : 'error'}）`);
+    }
+    return parseAndValidate(name, fileName, text, 'builtin (src/roles/)');
+  }
+
+  const layerRead = opts?.layerRead ?? defaultLayerRead;
+  let layers = roleLayers({ baseDir: opts?.baseDir });
+
+  // 内置名直读（自应用）：只查内置层，不受用户层诱饵/撞名影响
+  if (opts?.builtinDirect && RESERVED_ROLE_NAMES.includes(name)) {
+    layers = [layers[2]];
+  } else if (RESERVED_ROLE_NAMES.includes(name)) {
+    // 内置名保留：workspace/用户层撞名 → 拒绝（spawn 侧响亮报错，不静默覆盖内置语义）
+    for (const layer of layers.slice(0, 2)) {
+      if (layerRead(layer.dir, fileName) != null) {
+        throw new RoleLoaderError(
+          'ROLE_RESERVED',
+          `role "${name}" 是内置保留名，不能在 ${layer.label} 层定义（内置档案优先；请删除该档案或改名）`,
+        );
+      }
+    }
+  }
+
+  for (const layer of layers) {
+    const text = layerRead(layer.dir, fileName);
+    if (text == null) continue; // 本层无此档案 → 下一层
+    return parseAndValidate(name, fileName, text, layer.label); // 命中层：错误立即报
+  }
+  throw new RoleLoaderError(
+    'ROLE_NOT_FOUND',
+    `role "${name}" 不存在（查找层：${layers.map((l) => l.label).join(' → ')}）`,
+  );
+}
+
+function parseAndValidate(name: string, fileName: string, text: string, layerLabel: string): RoleManifest {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new RoleLoaderError('INVALID_ROLE_CONFIG', `role "${name}"（${layerLabel}）不是合法 JSON: ${(err as Error).message}`);
+  }
+  const result = validateRoleManifest(parsed);
+  if (!result.ok) {
+    throw new RoleLoaderError(
+      'INVALID_ROLE_CONFIG',
+      `role "${name}"（${layerLabel}）校验失败:\n${result.issues.map((i) => `  - ${i}`).join('\n')}`,
+      result.issues,
+    );
+  }
+  if (result.value.role !== name) {
+    throw new RoleLoaderError(
+      'INVALID_ROLE_CONFIG',
+      `role 档案名不符：${layerLabel} 的 ${fileName} 内 role="${result.value.role}"`,
+      [`role 字段 "${result.value.role}" 与请求的 "${name}" 不一致`],
+    );
+  }
+  return result.value;
+}