pi-pier 0.1.5 → 0.2.0

package/src/pipe-channel.ts

@@ -1,49 +1,58 @@
 /**
- * M11 人机通道分离（D45–D47）：pi 扩展自建 Windows 命名管道。
+ * M11 separates the human/machine channels (D45–D47) by having the pi extension
+ * create its own Windows named pipe.
  *
- *  - 主控（客户端）：一连接一请求（与 herdr 客户端同风格）；
- *  - 子 pane（服务端）：PI_HERDR_SUBAGENT=1 的扩展在 session_start 起 server，
- *    收到 prompt/follow_up 后经 pi.sendUserMessage(followUp) 注入会话本身（TUI 可见）；
- *  - 完成信息不回传（权威路径 = herdr 状态 + 会话 JSONL + history，D47）。
+ *  - Controller (client): one connection per request, matching the herdr client;
+ *  - Child pane (server): when PI_HERDR_SUBAGENT=1, the extension starts a server at
+ *    session_start and injects prompt/follow_up through pi.sendUserMessage (visible in TUI);
+ *  - Completion data is not sent back; authoritative state lives in herdr, session JSONL,
+ *    and history (D47).
  *
- * 本文件只含传输层纯逻辑（可单测，不依赖 pi API）；
- * pi 注入由 index.ts 的服务端回调完成。
+ * This file contains only pure transport-layer logic for isolated tests; index.ts
+ * performs pi injection in the server callback.
  */
 import * as net from 'node:net';
-import { sessionDirName } from './session-tail.ts';
+import { sessionDirCandidates, sessionDirName } from './storage-layout.ts';
 
-/** 管道名：workspace 作用域（与 history.jsonl 目录命名同约定）+ paneId 编码。 */
+function encodePaneId(paneId: string): string {
+  return String(paneId).replace(/[^A-Za-z0-9_-]/g, '-');
+}
+
+/** Pipe name: workspace-scoped (same encoding as history dirs) + 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}`;
+  return `pi-herdr-${sessionDirName(cwd)}-${encodePaneId(paneId)}`;
 }
 
-/** Windows 命名管道完整地址（内核命名空间，非文件系统路径）。 */
+/** New encoding first, then legacy — client retries so mixed-version peers still connect. */
+export function pipeNameCandidates(cwd: string, paneId: string): string[] {
+  return sessionDirCandidates(cwd).map((dir) => `pi-herdr-${dir}-${encodePaneId(paneId)}`);
+}
+
+/** Windows named-pipe address in the kernel namespace, not a filesystem path. */
 export function pipePathFor(name: string): string {
   return process.platform === 'win32'
     ? (name.startsWith('\\\\.\\pipe\\') ? name : `\\\\.\\pipe\\${name}`)
     : `/tmp/${name}.sock`;
 }
 
-/** 管道消息（JSON 行协议；一连接一请求 = 一个请求一个响应）。 */
+/** Pipe message in the JSON-lines protocol; one connection carries one request and response. */
 export type PipeRequest =
   | { type: 'ping'; id: string }
   | {
       type: 'prompt' | 'follow_up';
       id: string;
       text: string;
-      /** 发送方管道名（D49：回复随 from 走；无主从硬编码）。 */
+      /** D49: reply follows the sender's pipe name, avoiding hard-coded controller/child roles. */
       from?: string | null;
-      /** D50：结算时是否 push reply（后台 true、前台 false——前台由调用方同步取结果）。 */
+      /** D50: whether settlement pushes a reply (background true, foreground false because the caller reads synchronously). */
       push?: boolean;
-      /** B3：follow_up 以 steer 投递（tool-call 间隙即达，秒级）。缺省/ false =
-       * followUp 队列语义（run 结束才投）——初始 prompt 保持队列语义，续作指令走 steer。 */
+      /** B3: deliver follow_up as steer so it arrives between tool calls within seconds. Missing/false keeps
+       * queue semantics (delivered when the run ends); the initial prompt stays queued while continuations steer. */
       steer?: boolean;
     }
   | { type: 'interrupt'; id: string }
   | {
-      /** D50：结算快路径回信（子 → 请求方；带摘要 + 会话路径，渐进式披露）。 */
+      /** D50: fast-path settlement reply from child to requester, with summary and session path for progressive disclosure. */
       type: 'reply';
       id: string;
       paneId: string;
@@ -55,7 +64,7 @@ export type PipeResponse =
   | { type: 'ok'; id: string; detail?: string }
   | { type: 'error'; id: string; message: string };
 
-/** 解析一行 JSON（坏行返回 null）。 */
+/** Parse one JSON line, returning null for malformed input. */
 export function parsePipeLine(line: string): PipeRequest | PipeResponse | null {
   const t = (line ?? '').trim();
   if (!t) return null;
@@ -63,14 +72,14 @@ export function parsePipeLine(line: string): PipeRequest | PipeResponse | null {
     const obj = JSON.parse(t);
     if (obj && typeof obj === 'object' && typeof obj.type === 'string') return obj as PipeRequest | PipeResponse;
   } catch {
-    /* 坏行 */
+    /* Malformed line. */
   }
   return null;
 }
 
 /**
- * 一连接一请求：连接 → 写一行 JSON → 等一行 JSON 响应 → 断开。
- * 超时/连接失败/坏响应 → 抛错（调用方决定重试）。
+ * One connection, one request: connect → write JSON line → wait for JSON line → close.
+ * Timeout / connect failure / bad frame throw (caller retries).
  */
 export function pipeRequest(
   pipeName: string,
@@ -117,19 +126,43 @@ export function pipeRequest(
   });
 }
 
-/** 带重试的 ping（就绪探测；D47 取代 waitSubReady 的 agent 状态门）。 */
+/**
+ * Try new then legacy pipe names so a new client can still reach an old server.
+ */
+export async function pipeRequestTo(
+  cwd: string,
+  paneId: string,
+  payload: PipeRequest,
+  timeoutMs = 8000,
+): Promise<PipeResponse> {
+  const names = pipeNameCandidates(cwd, paneId);
+  let lastErr: unknown;
+  for (const name of names) {
+    try {
+      return await pipeRequest(name, payload, timeoutMs);
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  throw lastErr instanceof Error ? lastErr : new Error(`pipe ${names[0] ?? paneId}: unreachable`);
+}
+
+/** Ping with retry (readiness probe). Accepts one name or new+legacy candidates. */
 export async function pingUntilReady(
-  pipeName: string,
+  pipeName: string | readonly string[],
   timeoutMs: number,
   intervalMs = 1000,
 ): Promise<boolean> {
+  const names = typeof pipeName === 'string' ? [pipeName] : pipeName;
   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 {
-      /* 未就绪，继续 */
+    for (const name of names) {
+      try {
+        const res = await pipeRequest(name, { type: 'ping', id: `ping-${Date.now()}` }, 3000);
+        if (res.type === 'ok') return true;
+      } catch {
+        /* not ready on this name */
+      }
     }
     await new Promise((r) => setTimeout(r, intervalMs));
   }
@@ -139,8 +172,8 @@ export async function pingUntilReady(
 export type PipeMessageHandler = (req: PipeRequest) => Promise<PipeResponse>;
 
 /**
- * 服务端：每连接读一行 → 分发 handler → 回一行 → 断开。
- * 返回 server 实例（调用方管理 close）。
+ * Server: one line in → handler → one line out → close.
+ * Returns the server (caller closes it).
  */
 export function startPipeServer(
   pipeName: string,
@@ -173,11 +206,11 @@ export function startPipeServer(
         });
     });
     sock.on('error', () => {
-      /* 客户端断开等：静默 */
+      /* client disconnect: silent */
     });
   });
   server.on('error', () => {
-    /* 地址占用等：由调用方观察（listen 抛错由 startPipeServer 调用方处理） */
+    /* address in use: caller observes listen errors */
   });
   server.listen(pipePathFor(pipeName));
   return server;

package/src/platform-paths.ts

@@ -0,0 +1,72 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/**
+ * Platform-aware storage and workspace path resolution.
+ * 
+ * Why: Centralizes platform-specific path logic to support Windows (LOCALAPPDATA),
+ * Unix XDG conventions, and testability through injection.
+ */
+
+export interface PlatformPaths {
+  /** Base directory for agent sessions and state */
+  readonly agentDataDir: string
+  /** Base directory for worktrees */
+  readonly worktreeBaseDir: string
+  /** Sessions subdirectory under agent data */
+  readonly sessionsDir: string
+}
+
+function getDefaultDataDir(): string {
+  const platform = process.platform
+  
+  if (platform === 'win32') {
+    // Windows: use LOCALAPPDATA or fallback to homedir
+    return process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local')
+  }
+  
+  // Unix: XDG_DATA_HOME or ~/.local/share on Linux, ~/.local/share on macOS
+  if (platform === 'linux') {
+    return process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share')
+  }
+  
+  // macOS: use ~/.local/share for consistency, but .pi is acceptable legacy
+  return process.env.XDG_DATA_HOME || join(homedir(), '.pi')
+}
+
+function getDefaultWorktreeDir(): string {
+  const platform = process.platform
+  
+  if (platform === 'win32') {
+    const localAppData = process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local')
+    return join(localAppData, 'herdr', 'worktrees')
+  }
+  
+  // Unix: use XDG_DATA_HOME or ~/.local/share
+  if (platform === 'linux') {
+    const dataHome = process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share')
+    return join(dataHome, 'herdr', 'worktrees')
+  }
+  
+  // macOS legacy: ~/.herdr/worktrees
+  return join(homedir(), '.herdr', 'worktrees')
+}
+
+export function createPlatformPaths(overrides?: Partial<PlatformPaths>): PlatformPaths {
+  const defaultAgentDataDir = join(getDefaultDataDir(), 'agent')
+  const agentDataDir = overrides?.agentDataDir || defaultAgentDataDir
+  const sessionsDir = overrides?.sessionsDir || join(agentDataDir, 'sessions')
+  const worktreeBaseDir = overrides?.worktreeBaseDir || getDefaultWorktreeDir()
+  
+  return {
+    agentDataDir,
+    sessionsDir,
+    worktreeBaseDir,
+  }
+}
+
+/**
+ * Singleton platform paths for production use.
+ * Tests should inject via createPlatformPaths().
+ */
+export const platformPaths = createPlatformPaths()

package/src/progress-core.ts

@@ -1,39 +1,41 @@
 /**
- * M16 进度可见性纯核心（开发方案.md §M16；保守形态优先，D3 无新协议）。
+ * M16 pure core for progress visibility (development plan §M16; prioritize conservative output, with no new D3 protocol).
  *
- * 承载通道（post-M22 世界）：
- *  - 进度徽标（N/M + 可选 ETA）→ pane title 内嵌（state_labels 键仅五态，进不了 label）；
- *  - 工具徽标（🔧 tool）→ report_agent.message；
- *  - 速率估算对齐 kimi 估算器语义：速率窗口、未完成 cap、置信度门。
+ * Channels in the post-M22 world:
+ *  - Progress badge (N/M plus optional ETA) is embedded in the pane title (state_labels has only five keys, so it cannot fit there);
+ *  - Tool badge (🔧 tool) is sent through report_agent.message;
+ *  - Rate estimates follow kimi estimator semantics: rate window, unfinished cap, and confidence gate.
  *
- * 保守原则（风险⑥拍板）：估算不可信时回退纯计数「N/M」，绝不显示误导性 ETA。
+ * Conservative principle (risk ⑥ decision): when an estimate is not trustworthy, fall back to plain `N/M` and
+ * never display a misleading ETA.
  */
+
 import { countTodos, type TodoItem } from './vocab.ts';
 
-/** ETA 需要的最少完成点数（<2 无法算速率）。 */
+/** Minimum completed points needed for an ETA (<2 cannot establish a rate). */
 export const ETA_MIN_SAMPLES = 2;
-/** 速率样本窗口（kimi rate window 语义；取最近 K 个完成点算速率）。 */
+/** Rate sample window (kimi rate-window semantics; use the most recent K completion points). */
 export const RATE_WINDOW_MS = 45_000;
-/** 未完成进度显示上限（kimi unfinished cap 语义；防"快完了"假象）。 */
+/** Cap for displayed unfinished progress (kimi unfinished-cap semantics; prevent a false "almost done" impression). */
 export const UNFINISHED_CAP = 0.85;
-/** 完成点新鲜度门：最近完成点距今超过该值 → 数据陈旧，不估 ETA。 */
+/** Completion freshness gate: if the most recent completion is older than this, data is stale and no ETA is estimated. */
 export const PROGRESS_STALE_MS = 5 * 60_000;
-/** 速率拟合取最近 K 个完成点。 */
+/** Number of recent completion points used for rate fitting. */
 const RATE_SAMPLE_POINTS = 5;
 
 export interface EtaEstimate {
-  /** 剩余步数。 */
+  /** Remaining steps. */
   remaining: number;
-  /** 预计剩余时间（毫秒）。 */
+  /** Estimated remaining time (milliseconds). */
   etaMs: number;
   confidence: 'ok';
 }
 
 /**
- * 速率估算：完成时间戳 → 剩余步数的 ETA。
- *  - 完成点 <2 → null（无速率可言）；
- *  - 最近完成点距今 > PROGRESS_STALE_MS → null（陈旧：爆发后停顿/人为搁置）；
- *  - 速率 = 取最近 K(≤5) 个点，(k-1) / (t_k - t_1)；eta = remaining / rate。
+ * Estimate ETA from completion timestamps and remaining steps.
+ *  - Fewer than 2 completion points → null (no rate can be inferred);
+ *  - Most recent completion older than PROGRESS_STALE_MS → null (stale after a burst followed by a pause or manual hold);
+ *  - Rate = use the latest K(≤5) points, (k-1) / (t_k - t_1); eta = remaining / rate.
  */
 export function estimateEta(opts: {
   completedAt: readonly number[];
@@ -56,7 +58,7 @@ export function estimateEta(opts: {
   return { remaining, etaMs: Math.round(remaining / ratePerMs), confidence: 'ok' };
 }
 
-/** title 进度后缀：保守 `3/7`；置信 ETA 时 `3/7 ~4m`；total=0 → 空串；全完成 `5/5 ✓`。 */
+/** Title progress suffix: conservative `3/7`; trusted ETA gives `3/7 ~4m`; total=0 → empty; all complete → `5/5 ✓`. */
 export function formatProgressSuffix(opts: {
   completed: number;
   total: number;
@@ -74,27 +76,27 @@ export function formatProgressSuffix(opts: {
   return `${base} ${human}`;
 }
 
-/** 工具徽标（report_agent.message）：单工具名；多工具首 + 计数；空 → null（不覆盖）。 */
+/** Tool badge (report_agent.message): one tool name; multiple use the first plus a count; empty → null (do not overwrite). */
 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 开放计数）。 */
+/** Derive progress input from a list (completed count / total open-work count). */
 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 };
 }
 
-/** 进度徽标徽记整个生命周期后不再显示（防"完成态常驻"噪音；调用方比对用）。 */
+/** Hide the progress badge after it has been marked for the full lifecycle (avoid persistent completed-state noise; callers compare this). */
 export const PROGRESS_HIDE_MS = 60_000;
 
 /**
- * 两份列表间的 completed 转换数（按 content 匹配；新列表中 completed 且旧状态非
- * completed —— 含新增即 completed 的条目）。M16 速率估算的原料：所有编辑路径
- * （todo_write / 人类编辑 / M17 对账）都过 TodosService，在此统一 diff。
+ * Count completed transitions between two lists (match by content; an item completed in the new list whose old status
+ * was not completed, including items newly added as completed). M16 ETA estimation uses this as input: every edit path
+ * (todo_write / human edit / M17 reconciliation) passes through TodosService, so the diff is centralized here.
  */
 export function countCompletedTransitions(
   before: readonly TodoItem[],

package/src/reconcile-core.ts

@@ -1,35 +1,35 @@
 /**
- * M17：todo↔subagent 自动对账纯规划器（开发方案.md §M17；P2 = 低置信度不勾+提示）。
+ * M17: pure planner for automatic todo↔subagent reconciliation (development plan §M17; P2 = do not check off low-confidence matches, only prompt).
  *
- * 时机（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 条目，分支回放生效）。
+ * Timing (adapter): after the controller receives a settlement push (pollLoop / pipe reply), before injecting followUp.
+ * Semantics (aligned with omp reconcileTodosWithSubagents):
+ *  - Match description ↔ todo.content: normalize (lowercase + collapse whitespace), then exact → bidirectional prefix
+ *    → substring, in the same family as D38 fuzzyFind;
+ *  - Auto-complete only when settled and the unique best tier is in {exact, prefix}; at most one item per settlement;
+ *  - Unblock blocked items whose blocker ↔ description matches at any tier (exact/prefix)
+ *    (multiple allowed; failed/low-confidence matches do not unblock);
+ *  - Low confidence/ambiguity/failure: leave the list unchanged and add a noteLines prompt to the settlement notice (P2 decision);
+ *  - Persistence: edits use the D38 authoritative path (pi-herdr.todo-edit custom entry, effective during branch replay).
  */
+
 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 后的列表（无编辑 = 原引用）。 */
+  /** List after applying edits (original reference when there are no edits). */
   items: TodoItem[];
-  /** 经权威路径持久化的编辑（done 至多一条 + unblock 若干）。 */
+  /** Edits persisted through the authoritative path (at most one done plus any unblocks). */
   edits: TodoEdit[];
-  /** 被自动勾掉的条目（至多一条）。 */
+  /** Item automatically checked off (at most one). */
   completed: TodoItem | null;
-  /** 自动勾的匹配档位（candidates 存在时的最优档；无候选 null）。 */
+  /** Best matching tier for auto-completion (null when there are no candidates). */
   tier: MatchTier;
-  /** 被解锁的条目（blocker 匹配）。 */
+  /** Items unblocked by a blocker match. */
   unblocked: TodoItem[];
-  /** 随结算通知注入的提示行（对齐 D36 反馈语风；无提示 = 空数组）。 */
+  /** Prompt lines injected into the settlement notice (aligned with D36 feedback tone; empty when none). */
   noteLines: string[];
-  /** 匹配率指标（P2：采集用，随结算通知落会话 JSONL）。 */
+  /** Match-rate metric (P2: collected with the settlement notice in session JSONL). */
   metric: {
     description: string;
     outcome: ReconcileOutcome;
@@ -64,7 +64,7 @@ export function reconcileTodos(
   const edits: TodoEdit[] = [];
   const noteLines: string[] = [];
 
-  // 1) 勾选候选：pending / in_progress（completed/abandoned 永不参与）
+  // 1) Check-off candidates: pending / in_progress (completed/abandoned never participate).
   const matchable = prev.filter((t) => t.status === 'pending' || t.status === 'in_progress');
   const scored = matchable
     .map((t) => ({ item: t, tier: matchTier(description, t.content) }))
@@ -80,25 +80,26 @@ export function reconcileTodos(
       edits.push({ op: 'done', content: completed.content });
       noteLines.push(`Reconciled: completed "${completed.content}" (${bestTier} match with subagent description).`);
     } else if (best.length > 1) {
-      // 歧义：列候选，留给人
+      // Ambiguous match: list candidates and leave the decision to a person.
       noteLines.push(
         `Todo match ambiguous between: ${best.map((c) => `"${c.item.content}"`).join(', ')} — update todo_write yourself.`,
       );
     } else if (outcome === 'failed') {
-      // 高置信候选但子代理未成功结算 → 保持打开，提示
+      // High-confidence candidate, but the subagent did not settle successfully: keep it open and prompt.
       for (const c of best) {
         noteLines.push(`Todo kept open: "${c.item.content}" (subagent did not settle successfully).`);
       }
     }
   } else if (bestTier === 'substring') {
-    // 低置信度（P2）：不勾，提示候选
+    // Low-confidence match (P2): do not check it off; prompt with the candidate.
     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（可多条）
+  // 2) Unblock on any blocker match, including substring—real blockers are phrases such as "waiting for X to finish",
+  //    so the description may be embedded in the middle and prefix would miss it. The low-confidence gate applies only
+  //    to check-offs; returning an unblocked item to pending is a soft operation. Only settled subagents can unblock (possibly multiple).
   const unblocked: TodoItem[] = [];
   if (outcome === 'settled') {
     for (const t of prev) {

package/src/role-loader.ts

@@ -1,40 +1,37 @@
 /**
- * 档2 Week1：role 档案加载器（2026-08-18）；v1.1（2026-08-22）两层用户目录。
+ * Layer 2 Week 1: load role manifests (2026-08-18); v1.1 (2026-08-22) adds two user-directory layers.
  *
- * 查找序（v1.1，用户拍板）：
- *  1. workspace 级 `<cwd>/.pi-herdr/roles/<name>.json`（随 clone 走，团队共享）
- *  2. 用户全局 `~/.pi/agent/herdr-pi/roles/<name>.json`（跨仓库个人偏好）
- *  3. 内置 `src/roles/`（本包随附）兜底
+ * Lookup order (v1.1, user-approved):
+ *  1. Workspace-level `<cwd>/.pi-herdr/roles/<name>.json` (travels with the clone and is team-shared)
+ *  2. User-global `~/.pi/agent/herdr-pi/roles/<name>.json` (personal preference across repositories)
+ *  3. Bundled `src/roles/` as the fallback shipped with this package
  *
- * 内置名保留（master / worker-default）：用户/工作区层撞名直接拒绝——D83 镜像
- * 单测与 D82 姿态锚在内置档案上，被覆盖会破坏这些保证。
+ * Built-in names remain reserved (master / worker-default): reject collisions in user/workspace layers—D83 mirror.
+ * Tests and the D82 stance are anchored to bundled manifests; allowing overrides would break those guarantees.
  *
- * 角色名白名单 [a-z0-9-]+ —— 防路径穿越（不合法名不触盘）。
- * 档案 role 字段必须与文件名一致（防错挂）。
- * 校验失败分类：读不到 = ROLE_NOT_FOUND（逐层尝试后才报）；读到了但
- * JSON/校验/名字不符 = INVALID_ROLE_CONFIG（**在命中层立即报**，不静默落到
- * 下一层——静默会掩盖用户改了档案却写错的问题）。
+ * Role names are restricted to [a-z0-9-]—this prevents path traversal and avoids touching disk for invalid names.
+ * The manifest role field must match the filename to prevent attaching the wrong manifest.
+ * Validation failures are classified as: unreadable = ROLE_NOT_FOUND (reported only after trying every layer);
+ * parsed but invalid JSON/validation/name = INVALID_ROLE_CONFIG (report immediately at the hit layer rather than
+ * silently falling through, because silence would hide a user editing a manifest incorrectly).
  */
 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';
+import { userRolesDir, workspaceRolesDir as layoutWorkspaceRolesDir } from './storage-layout.ts';
 
-/** 内置档案目录（src/roles/）。 */
+export { userRolesDir };
+
+/** Bundled manifest directory (`src/roles/`). */
 export const ROLES_DIR = join(dirname(fileURLToPath(import.meta.url)), 'roles');
 
-/** workspace 级目录（相对基准默认 = 进程 cwd，即 master 的工作目录）。 */
+/** Workspace-level directory (the default base is the process cwd, i.e. the master's working directory). */
 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');
+  return layoutWorkspaceRolesDir(baseDir ?? process.cwd());
 }
 
-/** 内置保留名（不可被任何用户层覆盖）。 */
+/** Reserved built-in names (no user layer may override them). */
 export const RESERVED_ROLE_NAMES: readonly string[] = ['master', 'worker-default'];
 
 const ROLE_NAME_RE = /^[a-z0-9-]+$/;
@@ -56,7 +53,7 @@ export class RoleLoaderError extends Error {
 
 export type RoleReader = (fileName: string) => string;
 
-/** 单层读取器（注入式；生产 = existsSync + readFileSync 该目录）。 */
+/** Single-layer reader (injectable; production uses existsSync + readFileSync for that directory). */
 export type LayerReader = (dir: string, fileName: string) => string | null;
 
 const defaultLayerRead: LayerReader = (dir, fileName) => {
@@ -66,21 +63,21 @@ const defaultLayerRead: LayerReader = (dir, fileName) => {
 };
 
 export interface LoadRoleOptions {
-  /** 单 reader 注入（旧形态：仅命中内置层——测试兼容用）。 */
+  /** Inject one reader (legacy shape: only the bundled layer is hit, for test compatibility). */
   read?: RoleReader;
-  /** 多层 reader 注入（v1.1）。 */
+  /** Inject layered readers (v1.1). */
   layerRead?: LayerReader;
-  /** workspace 层基准目录（默认 process.cwd()）。 */
+  /** Base directory for the workspace layer (defaults to process.cwd()). */
   baseDir?: string;
   /**
-   * 内置名直读：master 自应用（WS-D7）专用——保留名跳过用户层与撞名检查，
-   * 永远加载内置档案。否则 workspace 放 master.json 会让自应用 fail-open，
-   * master 静默丢失 manifest（d11 活体抓到的边界）。
+   * Direct built-in lookup: used by master's self-application (WS-D7). Reserved names skip user layers and
+   * collision checks and always load the bundled manifest. Otherwise, a workspace master.json could cause
+   * self-application to fail open and silently lose master's manifest (the boundary caught by d11 live testing).
    */
   builtinDirect?: boolean;
 }
 
-/** 解析查找层序：workspace → 用户全局 → 内置（每层 {label, dir}）。 */
+/** Resolve lookup layers in order: workspace → user-global → bundled (each layer has {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());
@@ -97,7 +94,7 @@ export function loadRoleConfig(name: string, opts?: LoadRoleOptions): RoleManife
   }
   const fileName = `${name}.json`;
 
-  // 旧形态单 reader：直接按内置层语义（既有单测/合成器注入路径不破）
+  // Legacy single reader: use bundled-layer semantics so existing tests/composer injection paths remain intact.
   if (opts?.read && !opts.layerRead) {
     let text: string;
     try {
@@ -112,11 +109,11 @@ export function loadRoleConfig(name: string, opts?: LoadRoleOptions): RoleManife
   const layerRead = opts?.layerRead ?? defaultLayerRead;
   let layers = roleLayers({ baseDir: opts?.baseDir });
 
-  // 内置名直读（自应用）：只查内置层，不受用户层诱饵/撞名影响
+  // Direct built-in lookup (self-application): inspect only the bundled layer, ignoring user-layer bait/collisions.
   if (opts?.builtinDirect && RESERVED_ROLE_NAMES.includes(name)) {
     layers = [layers[2]];
   } else if (RESERVED_ROLE_NAMES.includes(name)) {
-    // 内置名保留：workspace/用户层撞名 → 拒绝（spawn 侧响亮报错，不静默覆盖内置语义）
+    // Reserved built-in name: reject workspace/user collisions instead of silently overriding built-in semantics.
     for (const layer of layers.slice(0, 2)) {
       if (layerRead(layer.dir, fileName) != null) {
         throw new RoleLoaderError(
@@ -129,8 +126,8 @@ export function loadRoleConfig(name: string, opts?: LoadRoleOptions): RoleManife
 
   for (const layer of layers) {
     const text = layerRead(layer.dir, fileName);
-    if (text == null) continue; // 本层无此档案 → 下一层
-    return parseAndValidate(name, fileName, text, layer.label); // 命中层：错误立即报
+    if (text == null) continue; // No manifest in this layer; try the next layer.
+    return parseAndValidate(name, fileName, text, layer.label); // At the hit layer, report errors immediately.
   }
   throw new RoleLoaderError(
     'ROLE_NOT_FOUND',