pi-pier 0.1.5 → 0.2.0

package/src/herdr-client.ts

@@ -1,34 +1,34 @@
 /**
- * herdr socket API 最小客户端（pi 扩展内使用）。
+ * Minimal herdr socket API client used inside the pi extension.
  *
- * 已对 herdr 0.8.0-preview（protocol 19, Windows named pipe）逐项实测（见 WIRE.md）：
- *  - 传输：NDJSON；请求 {id, method, params} → 响应 {id, result} | {id, error:{code,message}}；
- *  - **控制请求 = 一连接一请求**（server 应答后即关连接）；
- *  - Windows 目标 = named pipe，名称为完整 socket_path 字符串，连接时前缀 \\.\pipe\；
- *  - pane.report_agent {pane_id, source, agent, state, message?, agent_session_id?, agent_session_path?}
- *    其中 state ∈ idle|working|blocked|unknown（'done' 是 server 派生状态，客户端不报）；
- *  - pane.report_metadata {pane_id, source, title?, state_labels?, clear_title?, clear_state_labels?}
- *    M22 起只报标题投影；升级首次附带把旧 pi-herdr 分块 token 写成 null；
- *  - agent.list {} → {type:'agent_list', agents: AgentInfo[]}；
- *  - agent.wait {target, until[], timeout_ms?} → 状态命中返回 agent，超时为错误（timeout 语义）；
- *  - agent.send_keys {target, keys[]} / pane.send_text {pane_id, text}。
+ * Validated against herdr 0.8.0-preview (protocol 19, Windows named pipe; see WIRE.md):
+ *  - Transport is NDJSON: request {id, method, params} → response {id, result} | {id, error:{code,message}};
+ *  - **Control requests use one connection per request**; the server closes it after replying;
+ *  - Windows targets are named pipes whose name is the complete socket_path with a \\.\pipe\ prefix;
+ *  - pane.report_agent reports {pane_id, source, agent, state, message?, agent_session_id?, agent_session_path?}
+ *    where state ∈ idle|working|blocked|unknown ('done' is server-derived and is not reported by the client);
+ *  - pane.report_metadata reports {pane_id, source, title?, state_labels?, clear_title?, clear_state_labels?}
+ *    M22 reports only the title projection; the first upgrade also clears legacy pi-herdr chunk tokens to null;
+ *  - agent.list {} → {type:'agent_list', agents: AgentInfo[]};
+ *  - agent.wait {target, until[], timeout_ms?} → the matching agent, or an error on timeout;
+ *  - agent.send_keys {target, keys[]} / pane.send_text {pane_id, text}.
  *
- * v1.1（DESIGN.md §12）接口面：
- *  报告 ×3、目录、spawn、注入（send_text）、按键（send_keys）、等待（agent.wait）、会话路径查询。
- *  已删除：waitSettled（标记版）、readPaneText（pane 文本解析）、onAgentState（订阅长连接）
- *  —— 结果通道改会话 JSONL（session-tail.ts），状态等待改 server 端 agent.wait。
+ * The v1.1 (DESIGN.md §12) surface reports three projections, lists, spawns, injects
+ * text, sends keys, waits via agent.wait, and queries session paths. Removed operations
+ * (waitSettled marker polling, readPaneText parsing, onAgentState long-lived subscriptions)
+ * are replaced by session JSONL results (session-tail.ts) and server-side agent.wait.
  *
- * 设计（DESIGN.md §4.1）：无 herdr 环境 → Noop 降级，pi 独立可用；
- * 上报类调用失败静默，绝不影响 pi 主流程。
+ * Design (DESIGN.md §4.1): without herdr, fall back to Noop so pi remains independent;
+ * failures in reporting calls stay silent and never affect the main pi flow.
  */
 import { REPORT_AGENT_SOURCE, type TodoItem } from './vocab.ts';
 import { BLOCKED_LABEL_KEY, SIDEBAR_ASK_TOKEN, formatBlockedLabel, formatPaneTitle, sidebarTodoTokens, staleTokenClearance } from './pane-title.ts';
 import { LOCK_BATCH_LIMIT, LOCK_TTL_MS } from './lock-core.ts';
 import * as net from 'node:net';
 
-/* ── 类型 ──────────────────────────────────────────────────────────── */
+/* ── Types ──────────────────────────────────────────────────────────── */
 
-/** herdr agent 语义状态（schema 实测五态；'done' 为 server 派生）。 */
+/** Herdr agent semantic state; schema has five observed states and 'done' is server-derived. */
 export type HerdrAgentState = 'idle' | 'working' | 'blocked' | 'done' | 'unknown';
 
 export interface HerdrEnv {
@@ -38,20 +38,20 @@ export interface HerdrEnv {
   tabId: string;
 }
 
-/** report_agent 可上报的状态（'done' 由 server 派生）。 */
+/** State reportable through report_agent; 'done' is derived by the server. */
 export type PaneAgentState = 'idle' | 'working' | 'blocked' | 'unknown';
 
 export interface AgentInfo {
   paneId: string;
   agent: string | null;
   status: HerdrAgentState;
-  /** agent_session.value（session id 或路径），供恢复/跳转。 */
+  /** agent_session.value (session ID or path), retained for recovery and navigation. */
   session: string | null;
   stateLabels: Record<string, string>;
   tokens: Record<string, string | null>;
 }
 
-/** TabInfo 投影（schema 实测：tab_id/workspace_id/number/label/focused/pane_count/agent_status）。 */
+/** TabInfo projection; fields mirror the observed tab schema. */
 export interface TabInfo {
   tabId: string;
   workspaceId: string;
@@ -73,64 +73,71 @@ export function detectHerdrEnv(env: NodeJS.ProcessEnv = process.env): HerdrEnv |
   };
 }
 
+/** Resolve herdr socket target (Windows named-pipe prefix vs Unix path). */
+export function herdrSocketTarget(socketPath: string, platform: NodeJS.Platform = process.platform): string {
+  if (platform !== 'win32') return socketPath;
+  return socketPath.startsWith('\\\\.\\pipe\\') ? socketPath : `\\\\.\\pipe\\${socketPath}`;
+}
+
+
 export interface HerdrClientLike {
   readonly available: boolean;
   reportAgent(state: PaneAgentState, message: string | null): Promise<void>;
   reportAgentSession(sessionPath: string | null): Promise<void>;
   reportMetadata(meta: { session: string; items: TodoItem[]; progressSuffix?: string | null; lastWriteAt?: number | null }): Promise<void>;
-  /** M18：写锁 token 上报（键 lock-<hash>，值 paneId|path；null = 释放；≤16 键/批自动分批）。 */
+  /** M18: report write-lock tokens (lock-<hash> → paneId|path); null releases, and batches stay within 16 keys. */
   reportLockTokens(tokens: Record<string, string | null>): Promise<void>;
   /**
-   * D93：侧边栏 agent 显示名（display_agent = role 名）。
-   * 一次上报持续生效（无 TTL）；null = 清除回检测值。尽力而为。
+   * D93: sidebar agent display name (display_agent is the role name).
+   * The report persists without a TTL; null clears it back to the detected value. Best effort.
    */
   reportDisplayAgent(name: string | null): Promise<void>;
   /**
-   * D95：ask_user_question 等待标志（tokens['pi-ask']；null 清空）。
-   * 侧边栏/热力分级用：blocked + pi-ask = 人类闸门（ask 级），纯 blocked = block 级。
+   * D95: ask_user_question waiting marker (tokens['pi-ask']; null clears it).
+   * Sidebar/heatmap grading distinguishes blocked + pi-ask (ask level) from plain blocked (block level).
    */
   reportAskFlag(text: string | null): Promise<void>;
   listAgents(): Promise<AgentInfo[]>;
-  /** 在新 tab 里以 argv 启动子 pane（layout.apply），返回 pane/tab id。 */
+  /** Start a child pane with argv in a new tab (layout.apply), returning pane/tab IDs. */
   spawnSubPane(opts: { label: string; command: string[]; cwd: string; env?: Record<string, string> }): Promise<{ tabId: string; paneId: string }>;
-  /** 向 pane 终端注入文本（pi 编辑器输入 + Enter；send_text+CR 实测可直达；仅用于 launchLine 起进程）。 */
+  /** Inject text into a pane terminal (pi editor input + Enter); send_text+CR reaches it directly and is used only to start launchLine. */
   sendPaneText(paneId: string, text: string): Promise<void>;
-  /** server 端等待 agent 状态；命中返回状态，超时返回 null，错误抛出。 */
+  /** Wait for an agent state server-side; return the matched state, null on timeout, and throw on error. */
   waitAgent(paneId: string, until: HerdrAgentState[], timeoutMs: number): Promise<HerdrAgentState | null>;
-  /** 查询子代理上报的会话路径（agent_session.value，kind=path）；无则 null。 */
+  /** Query the child-agent session path (agent_session.value, kind=path); return null when absent. */
   getAgentSessionPath(paneId: string): Promise<string | null>;
-  /** v1.2：聚焦 pane（组 tab 追加的前置）。 */
+  /** v1.2: Focus a pane before adding it to a group tab. */
   focusPane(paneId: string): Promise<void>;
-  /** v1.2：在当前 tab 拆分出新 shell pane（focus 后调用，落组 tab）。返回新 paneId。 */
+  /** v1.2: Split a new shell pane in the current tab after focus, placing it in the group tab; return its pane ID. */
   splitPane(opts: { direction?: 'left' | 'right' | 'up' | 'down'; cwd?: string; env?: Record<string, string>; targetPaneId?: string }): Promise<string>;
-  /** v1.2：关闭 pane（实测杀进程树；空 tab 由 herdr 自动关）。 */
+  /** v1.2: Close a pane; observed behavior kills its process tree and herdr closes an empty tab. */
   closePane(paneId: string): Promise<void>;
-  /** v1.2：创建 tab（含根 shell pane），返回 tabId/paneId（组 tab 基础设施）。 */
+  /** v1.2: Create a tab with a root shell pane, returning tabId/paneId for group-tab infrastructure. */
   createTab(opts: { workspaceId: string; label?: string; cwd?: string; env?: Record<string, string> }): Promise<{ tabId: string; paneId: string }>;
-  /** v1.2：列出全部 pane（含 tab 归属；组 tab 追加用）。 */
+  /** v1.2: List all panes with tab ownership for group-tab additions. */
   listPanes(): Promise<Array<{ paneId: string; tabId: string; workspaceId: string; agentStatus: string }>>;
-  /** D91：导出 tab 布局树（layout.export；paneId/tabId 二选一定位）。尽力而为：失败返回 null。 */
+  /** D91: Export the tab layout tree, locating it by paneId or tabId; best effort returns null on failure. */
   exportLayout(opts: { paneId?: string; tabId?: string }): Promise<{ tabId: string | null; zoomed: boolean; root: unknown } | null>;
-  /** v1.3：列出 tab（tab.list → {type:'tab_list', tabs:[TabInfo]}，schema 实测）。 */
+  /** v1.3: List tabs (tab.list); fields follow the observed schema. */
   tabList(): Promise<TabInfo[]>;
-  /** v1.3：查 tab 详情（tab.get → {type:'tab_info', tab}）；不存在返回 null。 */
+  /** v1.3: Get tab details (tab.get); return null when absent. */
   tabGet(tabId: string): Promise<TabInfo | null>;
-  /** v1.3：关闭 tab（tab.close → {type:'tab_closed', ...}；级联关闭其 pane）。 */
+  /** v1.3: Close a tab (tab.close), cascading to its panes. */
   tabClose(tabId: string): Promise<void>;
-  /** M14：发送按键组合（pane.send_keys；Herdr key-combo：ctrl+c / enter / esc …）。 */
+  /** M14: Send a key combination (pane.send_keys; Herdr key combos include ctrl+c, enter, and esc). */
   sendPaneKeys(paneId: string, keys: string[]): Promise<void>;
-  /** M14：读 pane 输出缓冲（pane.read；source=recent 近期缓冲，strip_ansi=false 保留 T6 检测原料）。 */
+  /** M14: Read the pane output buffer; recent preserves ANSI data for T6 detection by default. */
   readPane(paneId: string, opts?: {
     source?: 'visible' | 'recent' | 'recent_unwrapped';
     lines?: number;
     stripAnsi?: boolean;
   }): Promise<{ text: string; revision: number; truncated: boolean }>;
-  /** M14：等输出匹配（pane.wait_for_output；substring/regex）。超时返回 null，错误抛出。 */
+  /** M14: Wait for output to match a substring or regex; return null on timeout and throw on error. */
   waitForOutput(paneId: string, match: { type: 'substring' | 'regex'; value: string }, timeoutMs: number): Promise<boolean | null>;
   close(): void;
 }
 
-/** 深度优先在响应对象里找第一个字符串字段（herdr 信封形状多样，id 位置不一）。 */
+/** Find the first string field named key by depth-first search; herdr envelopes place IDs inconsistently. */
 function findIdIn(obj: unknown, key: string, depth = 0): string | null {
   if (!obj || depth > 6) return null;
   if (typeof obj === 'object') {
@@ -198,23 +205,24 @@ export class NoopHerdrClient implements HerdrClientLike {
   close(): void {}
 }
 
-/* ── 实现 ──────────────────────────────────────────────────────────── */
+/* ── Implementation ────────────────────────────────────────────────── */
 
 export class HerdrClient implements HerdrClientLike {
   readonly available = true;
   private clearedStaleTokens = false;
+  private readonly env: HerdrEnv;
 
-  constructor(private readonly env: HerdrEnv) {}
+  constructor(env: HerdrEnv) {
+    this.env = env;
+  }
 
   private target(): string {
-    const p = this.env.socketPath;
-    if (process.platform !== 'win32') return p;
-    return p.startsWith('\\\\.\\pipe\\') ? p : `\\\\.\\pipe\\${p}`;
+    return herdrSocketTarget(this.env.socketPath);
   }
 
   /**
-   * 控制请求：一连接一请求（server 应答后关连接，实测协议行为）。
-   * 读满一行响应即完成；响应是 {id, result} | {id, error}。
+   * Control requests use one connection per request; the server closes it after replying, as observed in the protocol.
+   * Reading a complete response line finishes the request; responses are {id, result} or {id, error}.
    */
   private request(method: string, params: Record<string, unknown>, timeoutMs = 15000): Promise<unknown> {
     return new Promise((resolve, reject) => {
@@ -272,7 +280,7 @@ export class HerdrClient implements HerdrClientLike {
     });
   }
 
-  /* ── 上报类（失败静默：工作台镜像尽力而为，绝不影响 pi 主流程） ── */
+  /* ── Reporting (silent best effort: the workbench mirror must never affect pi's main flow) ── */
 
   async reportAgent(state: PaneAgentState, message: string | null): Promise<void> {
     try {
@@ -284,7 +292,7 @@ export class HerdrClient implements HerdrClientLike {
         ...(message ? { message } : {}),
       });
     } catch {
-      /* 静默 */
+      /* Silent best effort. */
     }
   }
 
@@ -298,7 +306,7 @@ export class HerdrClient implements HerdrClientLike {
         agent_session_path: sessionPath,
       });
     } catch {
-      /* 静默 */
+      /* Silent best effort. */
     }
   }
 
@@ -310,8 +318,8 @@ export class HerdrClient implements HerdrClientLike {
         lastWriteAt: meta.lastWriteAt,
       });
       const blocked = formatBlockedLabel(meta.items);
-      // D96：stale 清理与日常上报分离——stale(16) + pi-todo(1) = 17 > herdr tokens max=16
-      // → 整个请求被拒 → title/tokens 全丢（D93 回归根因）。stale 单独批次，成功后才置位。
+      // D96: separate stale cleanup from the daily report—stale(16) + pi-todo(1) exceeds herdr's 16-token limit,
+      // so one rejected request would lose both title and tokens (the D93 regression root cause). Set stale in its own batch first.
       if (!this.clearedStaleTokens) {
         await this.request('pane.report_metadata', {
           pane_id: this.env.paneId,
@@ -328,12 +336,12 @@ export class HerdrClient implements HerdrClientLike {
         ...(blocked
           ? { state_labels: { [BLOCKED_LABEL_KEY]: blocked } }
           : { clear_state_labels: true }),
-        // D93：todo 摘要进 custom token（空串 = 清键，无 todo 不留旧摘要）
+        // D93: put the todo summary in a custom token; an empty string clears the key so stale summaries do not remain.
         tokens: sidebarTodoTokens(title),
         ttl_ms: 86400000,
       });
     } catch {
-      /* 静默：标题投影尽力而为，绝不影响 pi 主流程 */
+      /* Silent best effort: the title projection must never affect pi's main flow. */
     }
   }
 
@@ -341,7 +349,7 @@ export class HerdrClient implements HerdrClientLike {
     const keys = Object.keys(tokens);
     if (keys.length === 0) return;
     try {
-      // schema maxProperties=16 → 分批（每批独立请求，全部尽力而为）
+      // schema maxProperties=16, so split into independent best-effort requests.
       for (let i = 0; i < keys.length; i += LOCK_BATCH_LIMIT) {
         const batch: Record<string, string | null> = {};
         for (const k of keys.slice(i, i + LOCK_BATCH_LIMIT)) batch[k] = tokens[k];
@@ -353,7 +361,7 @@ export class HerdrClient implements HerdrClientLike {
         });
       }
     } catch {
-      /* 锁登记尽力而为（软 veto 下失败 = 少一次警告，不阻断） */
+      /* Lock registration is best effort; under soft veto, failure only loses a warning and does not block. */
     }
   }
 
@@ -365,7 +373,7 @@ export class HerdrClient implements HerdrClientLike {
         ...(name ? { display_agent: name } : { clear_display_agent: true }),
       });
     } catch {
-      /* 静默：侧边栏标识尽力而为 */
+      /* Silent best effort: sidebar identity is supplementary. */
     }
   }
 
@@ -378,11 +386,11 @@ export class HerdrClient implements HerdrClientLike {
         ttl_ms: 86400000,
       });
     } catch {
-      /* 静默：人类闸门标志尽力而为 */
+      /* Silent best effort: the human-gate marker is supplementary. */
     }
   }
 
-  /* ── 查询与控制 ───────────────────────────────────────────────────── */
+  /* ── Queries and control ─────────────────────────────────────────── */
 
   async listAgents(): Promise<AgentInfo[]> {
     const result = (await this.request('agent.list', {})) as {
@@ -414,7 +422,7 @@ export class HerdrClient implements HerdrClientLike {
   }
 
   async sendPaneText(paneId: string, text: string): Promise<void> {
-    // 尾部 \r 即 Enter（实测：文本进入 pi 编辑器并提交）
+    // A trailing \r acts as Enter; observed behavior sends text to the pi editor and submits it.
     await this.request('pane.send_text', { pane_id: paneId, text: text + '\r' });
   }
 
@@ -489,7 +497,7 @@ export class HerdrClient implements HerdrClientLike {
         ...(opts.paneId ? { pane_id: opts.paneId } : {}),
         ...(opts.tabId ? { tab_id: opts.tabId } : {}),
       })) as Record<string, unknown> | null;
-      // 响应信封：{layout:{tab_id,zoomed,root}}；兼容 root 直接在顶层
+      // Observed envelope: {layout:{tab_id,zoomed,root}}; accept root directly at the top level for compatibility.
       const layout = (result?.layout ?? result) as Record<string, unknown> | null | undefined;
       if (!layout || typeof layout !== 'object' || !('root' in layout)) return null;
       return {
@@ -536,7 +544,7 @@ export class HerdrClient implements HerdrClientLike {
     lines?: number;
     stripAnsi?: boolean;
   } = {}): Promise<{ text: string; revision: number; truncated: boolean }> {
-    // 信封实测：{type:'pane_read', read:{text, revision, truncated, ...}}（payload 套在 read 下）
+    // Observed envelope: {type:'pane_read', read:{text, revision, truncated, ...}}; the payload is nested under read.
     const result = (await this.request('pane.read', {
       pane_id: paneId,
       source: opts.source ?? 'recent',
@@ -569,7 +577,7 @@ export class HerdrClient implements HerdrClientLike {
   }
 
   close(): void {
-    /* v1.1 无长驻连接；保留接口语义（Noop） */
+    /* v1.1 has no long-lived connection; retain the interface semantics as a no-op. */
   }
 }
 

package/src/history-store.ts

@@ -1,21 +1,24 @@
 /**
- * workspace 历史记录（v1.2，DESIGN.md §13.4）。
+ * Workspace history (v1.2, DESIGN.md §13.4).
  *
- * 任务历史 = append-only JSONL，按 cwd 分区（与 pi 会话分区同构）：
+ * Task history is append-only JSONL partitioned by cwd, mirroring pi session partitioning:
  *   <agentRoot>/herdr-pi/history/--<cwd>--/history.jsonl
- * 记录不可变：GC 只关 pane，绝不删历史。恢复双保险：sessionFile + launchCommand 快照。
+ * Records are immutable so GC can remove panes without deleting history. Recovery keeps
+ * both the sessionFile and launchCommand snapshots as fallbacks.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { sessionDirName } from './session-tail.ts';
+import { historyFilePath, preferredHistoryFile } from './storage-layout.ts';
 
-/** 旧 short/resident → task；空/缺省 → task；role 名原样。 */
+export { historyFilePath, preferredHistoryFile };
+
+/** Legacy short/resident entries normalize to task; missing values do too, while role names pass through unchanged. */
 export function normalizeEntryKind(kind: string | null | undefined): string {
   if (!kind || kind === 'short' || kind === 'resident') return 'task';
   return kind;
 }
 
-/** 结算回写：只接受 .jsonl 路径，非法不覆盖（O6）。 */
+/** O6: only a .jsonl path is accepted during settlement, so invalid reports cannot overwrite a valid path. */
 export function applyReportedSessionFile(
   current: string | null,
   reported: string | null | undefined,
@@ -26,57 +29,70 @@ export function applyReportedSessionFile(
 
 export interface HistoryEntry {
   taskId: string;
-  /** 'task' 或 role 名；读盘时 short/resident 归一为 task。 */
+  /** 'task' or a role name; disk reads normalize short/resident to task for compatibility. */
   kind: string;
   paneId: string;
   tabId: string;
-  /** v1.3：任务 tab 名（历史回看/复活参考；旧条目缺省）。 */
+  /** v1.3: task tab name retained for history review and revival; omitted by older entries. */
   tabName?: string;
   workspaceId: string;
   cwd: string;
   description: string;
-  /** 子代理会话文件（resume 首选）。 */
+  /** Child-agent session file, preferred when resuming. */
   sessionFile: string | null;
-  /** 启动命令快照（sessionFile 丢失时重建空会话续接）。 */
+  /** Launch command snapshot, used to rebuild an empty continuation when sessionFile is missing. */
   launchCommand: string[];
   status: 'running' | 'settled' | 'consumed' | 'closed';
   outcome?: string | null;
   createdAt: number;
-  /** 消费时间（M13c 起随条目落盘；GC TTL 判据的 durable 记录）。 */
+  /** M13c: durable consumption time, which provides the GC TTL basis. */
   consumedAt?: number | null;
   closedAt?: number | null;
-  /** 打回重做/复活时的前代 paneId。 */
+  /** Previous-generation pane ID, retained when work is redone or revived. */
   revivedFrom?: string | null;
-  /** B5：写手标记（spawn / poll-settle / poll-timeout / gc / zombie-sweep …）——
-   * 同秒多行可审计（01a03c0d 台账 row#23/24 双写实证）。 */
+  /** B5: writer marker (spawn / poll-settle / poll-timeout / gc / zombie-sweep …), so
+   * multiple entries in one second remain auditable (ledger row#23/24 proves both writes). */
   via?: string;
 }
 
-/** B5：closed 行 outcome 继承——patch 未显式指定 outcome 时沿用该 taskId 最近非空值，
- * 「最新行即现状」语义下结算成果不因 GC 补记而丢失。 */
+/** B5: inherit outcome for a closed row—when patch omits it, use the latest non-empty value
+ * for that taskId, preventing GC bookkeeping from erasing settlement results under the
+ * “latest row is state” rule. */
 export function inheritOutcome(lastOutcome: string | null | undefined, patchOutcome: string | null | undefined): string | null {
   if (patchOutcome !== undefined) return patchOutcome;
   return lastOutcome ?? null;
 }
 
-export function historyFilePath(agentRoot: string, cwd: string): string {
-  return path.join(agentRoot, 'herdr-pi', 'history', sessionDirName(cwd), 'history.jsonl');
+
+
+const HISTORY_STATUSES: Record<string, true> = {
+  running: true,
+  settled: true,
+  consumed: true,
+  closed: true,
+};
+
+function coerceHistoryEntry(obj: unknown): HistoryEntry | null {
+  if (obj === null || typeof obj !== 'object') return null;
+  const rec = obj as Record<string, unknown>;
+  if (typeof rec.taskId !== 'string' || rec.taskId.trim() === '') return null;
+  if (typeof rec.status !== 'string' || HISTORY_STATUSES[rec.status] !== true) return null;
+  if (rec.createdAt !== undefined && !Number.isFinite(rec.createdAt)) return null;
+  const raw = rec as unknown as HistoryEntry;
+  return { ...raw, kind: normalizeEntryKind(raw.kind) };
 }
 
-/** 容忍式逐行解析（损坏行跳过）。 */
+/** Parse line by line; skip junk JSON and records missing taskId/status. */
 export function parseHistoryEntries(text: string): HistoryEntry[] {
   const entries: HistoryEntry[] = [];
   for (const line of (text ?? '').split(/\r?\n/)) {
     const t = line.trim();
     if (!t) continue;
     try {
-      const obj = JSON.parse(t);
-      if (obj && typeof obj === 'object' && typeof obj.taskId === 'string') {
-        const raw = obj as HistoryEntry;
-        entries.push({ ...raw, kind: normalizeEntryKind(raw.kind) });
-      }
+      const next = coerceHistoryEntry(JSON.parse(t));
+      if (next) entries.push(next);
     } catch {
-      /* 跳过损坏行 */
+      /* Skip malformed records. */
     }
   }
   return entries;
@@ -86,26 +102,44 @@ function serializeEntry(entry: HistoryEntry): string {
   return JSON.stringify(entry);
 }
 
-/** 读取历史文件；不存在返回 []。 */
-export function readHistory(file: string): HistoryEntry[] {
+export type HistoryReadResult =
+  | { status: 'ok'; entries: HistoryEntry[] }
+  | { status: 'missing' }
+  | { status: 'unreadable'; error: Error };
+
+/** Distinguish missing vs permission/IO failure. readHistory still returns [] for both. */
+export function inspectHistory(file: string): HistoryReadResult {
   try {
-    return parseHistoryEntries(fs.readFileSync(file, 'utf8'));
-  } catch {
-    return [];
+    if (!fs.existsSync(file)) return { status: 'missing' };
+    return { status: 'ok', entries: parseHistoryEntries(fs.readFileSync(file, 'utf8')) };
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    return { status: 'unreadable', error: err };
   }
 }
 
-/** 追加一条（确保目录存在）。 */
-export function appendHistory(file: string, entry: HistoryEntry): void {
+/** Read a history file; missing or unreadable yields []. */
+export function readHistory(file: string): HistoryEntry[] {
+  const r = inspectHistory(file);
+  return r.status === 'ok' ? r.entries : [];
+}
+
+export type HistoryWriteResult = { ok: true } | { ok: false; error: Error };
+
+/** Append one entry. Failures are logged and returned so the ledger is not silently lost. */
+export function appendHistory(file: string, entry: HistoryEntry): HistoryWriteResult {
   try {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.appendFileSync(file, serializeEntry(entry) + '\n');
-  } catch {
-    /* 尽力而为：历史写入失败不影响主流程 */
+    return { ok: true };
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    console.error(`[pi-herdr] history append failed: ${file}: ${err.message}`);
+    return { ok: false, error: err };
   }
 }
 
-/** 折叠：每个 taskId 的全部代际（按 createdAt 升序）。 */
+/** Group all generations of each taskId in ascending createdAt order for review. */
 export function generationsByTask(entries: readonly HistoryEntry[]): Map<string, HistoryEntry[]> {
   const map = new Map<string, HistoryEntry[]>();
   for (const e of entries) {
@@ -117,7 +151,7 @@ export function generationsByTask(entries: readonly HistoryEntry[]): Map<string,
   return map;
 }
 
-/** 取 taskId 的最新代（resume 用）。 */
+/** Return the newest generation for taskId, which is the one used for resume. */
 export function latestGeneration(entries: readonly HistoryEntry[], taskId: string): HistoryEntry | null {
   const gens = generationsByTask(entries).get(taskId);
   if (!gens || gens.length === 0) return null;

package/src/index-locks.ts

@@ -0,0 +1,105 @@
+/**
+ * M18 file write-lock installer (soft veto / hard block).
+ *
+ * Why: lock acquire/release/command lived in the composition root next to
+ * unrelated session wiring. The installer owns the three pi hooks and the
+ * held-lock set; fail-open on agent.list remains the collaboration policy.
+ */
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import {
+  acquireTokensFor,
+  isLockTokenKey,
+  parseLockTokenValue,
+  planWriteGuard,
+  releaseTokensFor,
+  type LockAgentView,
+} from './lock-core.ts';
+import type { HerdrClientLike, HerdrEnv } from './herdr-client.ts';
+
+export function installWriteLocks(
+  pi: ExtensionAPI,
+  opts: {
+    client: HerdrClientLike;
+    env: HerdrEnv | null;
+    hard: boolean;
+  },
+): void {
+  const { client, env, hard } = opts;
+  const heldLocks = new Set<string>();
+  const lockWarnByToolCall = new Map<string, string>();
+
+  async function acquireLocks(paths: readonly string[]): Promise<void> {
+    for (const p of paths) heldLocks.add(p);
+    await client.reportLockTokens(acquireTokensFor(paths, env?.paneId ?? ''));
+  }
+
+  pi.on('tool_call', async (event: { toolName?: string; toolCallId?: string; input?: unknown }, ctx: { cwd?: string }) => {
+    if (!client.available || !env) return;
+    const cwd = ctx?.cwd ?? process.cwd();
+    let agents: LockAgentView[];
+    try {
+      agents = (await client.listAgents()).map((a) => ({ paneId: a.paneId, tokens: a.tokens }));
+    } catch {
+      return;
+    }
+    const plan = planWriteGuard({
+      toolName: event.toolName ?? '',
+      input: event.input,
+      agents,
+      ownPaneId: env.paneId,
+      cwd,
+      hard,
+    });
+    if (plan.kind === 'skip') return;
+    if (plan.kind === 'block') {
+      return { block: true, reason: plan.reason };
+    }
+    if (plan.kind === 'warn' && typeof event.toolCallId === 'string') {
+      lockWarnByToolCall.set(event.toolCallId, plan.warning);
+    }
+    await acquireLocks(plan.paths);
+  });
+
+  pi.on('tool_result', async (event: { toolCallId?: string; content?: Array<{ type: string; text: string }> }) => {
+    if (typeof event?.toolCallId !== 'string') return;
+    const warning = lockWarnByToolCall.get(event.toolCallId);
+    if (!warning) return;
+    lockWarnByToolCall.delete(event.toolCallId);
+    const content = Array.isArray(event.content) ? event.content : [];
+    return { content: [...content, { type: 'text', text: warning }] };
+  });
+
+  pi.on('agent_settled', async () => {
+    if (heldLocks.size === 0) return;
+    const paths = [...heldLocks];
+    heldLocks.clear();
+    await client.reportLockTokens(releaseTokensFor(paths));
+  });
+
+  pi.registerCommand('locks', {
+    description: 'Show write locks held by this pane and all live panes (M18)',
+    handler: async (_args, ctx) => {
+      const ui = (ctx as { ui?: { notify?: (text: string, level?: string) => void } }).ui;
+      const mine = [...heldLocks];
+      const lines = [`held by this pane (${mine.length}):`];
+      lines.push(...(mine.length ? mine.map((p) => `  ${p}`) : ['  (none)']));
+      lines.push('all live locks:');
+      let any = false;
+      try {
+        for (const a of await client.listAgents()) {
+          for (const [k, v] of Object.entries(a.tokens)) {
+            if (!isLockTokenKey(k) || typeof v !== 'string' || !v) continue;
+            const parsed = parseLockTokenValue(v);
+            if (!parsed) continue;
+            any = true;
+            lines.push(`  ${parsed.path} → pane ${parsed.holderPaneId}`);
+          }
+        }
+      } catch {
+        lines.push('  (agent.list failed)');
+      }
+      if (!any && lines[lines.length - 1] !== '  (agent.list failed)') lines.push('  (none)');
+      ui?.notify?.(lines.join('\n'), 'info');
+    },
+  });
+}