pi-pier 0.3.0 → 0.3.1

package/src/herdr-client.ts

@@ -1,28 +1,20 @@
 /**
  * Minimal herdr socket API client used inside the pi extension.
  *
- * Validated against herdr 0.9.1 (protocol 22, Windows named pipe; see WIRE.md). The request shapes
- * pier builds are pinned to herdr's own `api schema` by test/herdr-contract.test.ts — regenerate
- * test/fixtures/herdr-contract.json and bump HERDR_PROTOCOL_EXPECTED when the server moves on:
+ * Validated against herdr 0.9.1 (protocol 22; see WIRE.md). The request shapes pier builds are pinned
+ * to herdr's own `api schema` by test/herdr-client.test.ts — regenerate test/fixtures/herdr-contract.json
+ * and bump HERDR_PROTOCOL_EXPECTED when the server moves on:
  *  - 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?,
- *    tokens?, ttl_ms?} (ttl_ms is capped at 24 h by the server); the first report of a session 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}.
+ *  - pane.report_agent reports {pane_id, source, agent, state, message?} 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_*, tokens?, ttl_ms?}
+ *    (ttl_ms is capped at 24 h by the server; the first report of a session also clears legacy
+ *    pi-herdr chunk tokens to null).
  *
- * 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 (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.
+ * Reporting failures stay silent and never affect the main pi flow; without herdr the Noop client
+ * keeps pi independent (DESIGN.md §4.1).
  */
 import { REPORT_AGENT_SOURCE, type TodoItem } from './vocab.ts';
 import { BLOCKED_LABEL_KEY, SIDEBAR_ASK_TOKEN, formatBlockedLabel, formatPaneTitle, sidebarTodoTokens, staleTokenClearance } from './pane-title.ts';
@@ -31,7 +23,6 @@ import * as net from 'node:net';
 
 /* ── Types ──────────────────────────────────────────────────────────── */
 
-/** 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 {
@@ -100,7 +91,6 @@ export type OpenPluginPaneResult =
   | { mode: 'pane'; paneId: string }
   | { mode: 'fallback_tab'; tabId?: string; paneId?: string };
 
-/** TabInfo projection; fields mirror the observed tab schema. */
 export interface TabInfo {
   tabId: string;
   workspaceId: string;
@@ -122,17 +112,13 @@ 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}`;
 }
 
-/**
- * B5: herdr can be configured but unreachable (server stopped, stale/typo'd HERDR_SOCKET_PATH).
- * A raw errno ("connect ENOENT /Users/…/herdr.sock") tells the model nothing to act on, so tool
- * layers append this one sentence. Returns null when the failure is not a transport failure.
- */
+/** B5: herdr configured but unreachable (stopped server, stale HERDR_SOCKET_PATH) — tool layers append
+ * this sentence because a raw errno tells the model nothing. Null when the failure is not transport. */
 export function herdrUnavailableHint(err: unknown): string | null {
   const msg = String((err as { message?: unknown })?.message ?? err);
   if (!/ENOENT|ECONNREFUSED|ECONNRESET|EPIPE|ENOTCONN|not connected|socket|connect |timeout/i.test(msg)) {
@@ -141,7 +127,6 @@ export function herdrUnavailableHint(err: unknown): string | null {
   return `herdr unreachable (${msg}) — check that the herdr server is running and HERDR_SOCKET_PATH matches its socket`;
 }
 
-
 /** Wire protocol this client is written against (herdr 0.9.1). See test/fixtures/herdr-contract.json. */
 export const HERDR_PROTOCOL_EXPECTED = 22;
 
@@ -149,74 +134,60 @@ export type WaitForOutputResult =
   | { matched: true }
   | { matched: false; reason: 'timeout' | 'unavailable' };
 
+/** pane.read / agent.read selection: `recent` keeps ANSI so T6 fullscreen detection still sees it. */
+export interface ReadOptions {
+  source?: 'visible' | 'recent' | 'recent_unwrapped';
+  lines?: number;
+  stripAnsi?: boolean;
+}
+
+/** Decoded read payload; `revision` is the server's buffer revision (0 when unreadable). */
+export interface ReadBuffer {
+  text: string;
+  revision: number;
+  truncated: boolean;
+}
+
 export interface HerdrClientLike {
   readonly available: boolean;
   reportAgent(state: PaneAgentState, message: string | null): Promise<void>;
   reportMetadata(meta: { session: string; items: readonly TodoItem[]; progressSuffix?: string | null; lastWriteAt?: number | null }): Promise<void>;
   /** 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: 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.
-   */
+  /** D93: sidebar agent display name (display_agent is the role name); null clears it. Persists, no TTL. */
   reportDisplayAgent(name: string | null): Promise<void>;
   /**
-   * 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).
+   * D95: ask_user_question waiting marker (tokens['pi-ask']; null clears it). The sidebar/heatmap
+   * grade blocked + pi-ask as the ask level, distinct from plain block.
    */
   reportAskFlag(text: string | null): Promise<void>;
   listAgents(): Promise<AgentInfo[]>;
-  /** 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 }>;
-  /** Inject text into a pane terminal (pi editor input + Enter); send_text+CR reaches it directly and is used only to start launchLine. */
+  /** Inject text into a pane terminal (pi editor input + Enter); the PTY channel is used only to start launchLine. */
   sendPaneText(paneId: string, text: string): Promise<void>;
-  /** Wait for an agent state server-side; return the matched state, null on timeout, and throw on error. */
+  /** Server-side wait; null on timeout, throws on any other error. */
   waitAgent(paneId: string, until: HerdrAgentState[], timeoutMs: number): Promise<HerdrAgentState | null>;
   /** Query the child-agent session path (agent_session.value, kind=path); return null when absent. */
   getAgentSessionPath(paneId: string): Promise<string | null>;
-  /** v1.2: Focus a pane before adding it to a group tab. */
-  focusPane(paneId: string): Promise<void>;
-  /** 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; focus?: boolean; ratio?: number }): Promise<string>;
-  /** v1.2: Close a pane; observed behavior kills its process tree and herdr closes an empty tab. */
+  /** Close a pane; herdr kills its process tree and closes an empty tab. */
   closePane(paneId: string): Promise<void>;
-  /** 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: List all panes with tab ownership for group-tab additions. */
   listPanes(): Promise<PaneListItem[]>;
-  /** D91: Export the tab layout tree, locating it by paneId or tabId; best effort returns null on failure. */
+  /** D91: layout tree by paneId or tabId; null on failure. */
   exportLayout(opts?: { paneId?: string; tabId?: string }): Promise<{ tabId: string | null; zoomed: boolean; root: unknown; focusedPaneId: string | null } | null>;
   /** 0.9.1: live pane rects for the tab containing paneId. Best effort returns null. */
   paneLayout(opts?: { paneId?: string }): Promise<PaneLayoutSnapshot | null>;
-  /** v1.3: List tabs (tab.list); fields follow the observed schema. */
   tabList(): Promise<TabInfo[]>;
-  /** v1.3: Get tab details (tab.get); return null when absent. */
-  tabGet(tabId: string): Promise<TabInfo | null>;
-  /** v1.3: Close a tab (tab.close), cascading to its panes. */
+  /** v1.3: tab.close cascades to the tab's panes. */
   tabClose(tabId: string): Promise<void>;
   /** 0.9.1: Launch a manifest pane entrypoint with placement (popup/tab/split/overlay/zoomed). */
   openPluginPane(opts: OpenPluginPaneOptions): Promise<OpenPluginPaneResult>;
-  /** 0.9.1: Close active popup if open; returns false if no popup was open. */
-  closePopup(): Promise<boolean>;
-  /** 0.9.1: Query agent explain diagnostics. */
   agentExplain(target: string): Promise<Record<string, unknown> | null>;
-  /** 0.9.1: Query server version via ping. Cached in memory. */
   getServerVersion(): Promise<string | null>;
-  /** M14: Send a key combination (pane.send_keys; Herdr key combos include ctrl+c, enter, and esc). */
+  /** pane.send_keys; herdr key combos include ctrl+c, enter, and esc. */
   sendPaneKeys(paneId: string, keys: string[]): Promise<void>;
-  /** 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 }>;
-  /** Read the agent output buffer via herdr 0.9 agent.read RPC. */
-  readAgent(target: string, opts?: {
-    source?: 'visible' | 'recent' | 'recent_unwrapped';
-    lines?: number;
-    stripAnsi?: boolean;
-  }): Promise<{ text: string; revision: number; truncated: boolean }>;
-  /** M14: Wait for output to match a substring or regex; return discriminated result on match/timeout/unavailable. */
+  readPane(paneId: string, opts?: ReadOptions): Promise<ReadBuffer>;
+  readAgent(target: string, opts?: ReadOptions): Promise<ReadBuffer>;
   waitForOutput(paneId: string, match: { type: 'substring' | 'regex'; value: string }, timeoutMs: number): Promise<WaitForOutputResult>;
   close(): void;
 }
@@ -237,6 +208,7 @@ function findIdIn(obj: unknown, key: string, depth = 0): string | null {
 
 /* ── Noop ──────────────────────────────────────────────────────────── */
 
+/** Stand-in outside a herdr pane: queries answer empty, pane creation throws, reporting is a no-op. */
 export class NoopHerdrClient implements HerdrClientLike {
   readonly available = false;
   async reportAgent(): Promise<void> {}
@@ -244,66 +216,26 @@ export class NoopHerdrClient implements HerdrClientLike {
   async reportLockTokens(): Promise<void> {}
   async reportDisplayAgent(): Promise<void> {}
   async reportAskFlag(): Promise<void> {}
-  async listAgents(): Promise<AgentInfo[]> {
-    return [];
-  }
-  async spawnSubPane(): Promise<{ tabId: string; paneId: string }> {
-    throw new Error('subagent requires a herdr-managed pane');
-  }
   async sendPaneText(): Promise<void> {}
-  async waitAgent(): Promise<null> {
-    return null;
-  }
-  async getAgentSessionPath(): Promise<null> {
-    return null;
-  }
-  async focusPane(): Promise<void> {}
-  async splitPane(): Promise<string> {
-    throw new Error('subagent requires a herdr-managed pane');
-  }
   async closePane(): Promise<void> {}
-  async createTab(): Promise<{ tabId: string; paneId: string }> {
-    throw new Error('subagent requires a herdr-managed pane');
-  }
-  async listPanes(): Promise<PaneListItem[]> {
-    return [];
-  }
-  async exportLayout(): Promise<null> {
-    return null;
-  }
-  async paneLayout(): Promise<null> {
-    return null;
-  }
-  async tabList(): Promise<TabInfo[]> {
-    return [];
-  }
-  async tabGet(): Promise<TabInfo | null> {
-    return null;
-  }
   async tabClose(): Promise<void> {}
-  async openPluginPane(): Promise<OpenPluginPaneResult> {
-    throw new Error('plugin pane requires a herdr-managed pane');
-  }
-  async closePopup(): Promise<boolean> {
-    return false;
-  }
-  async agentExplain(): Promise<null> {
-    return null;
-  }
-  async getServerVersion(): Promise<null> {
-    return null;
-  }
   async sendPaneKeys(): Promise<void> {}
-  async readPane(): Promise<{ text: string; revision: number; truncated: boolean }> {
-    return { text: '', revision: 0, truncated: false };
-  }
-  async readAgent(): Promise<{ text: string; revision: number; truncated: boolean }> {
-    return { text: '', revision: 0, truncated: false };
-  }
-  async waitForOutput(): Promise<WaitForOutputResult> {
-    return { matched: false, reason: 'unavailable' };
-  }
   close(): void {}
+  async listAgents(): Promise<AgentInfo[]> { return []; }
+  async listPanes(): Promise<PaneListItem[]> { return []; }
+  async tabList(): Promise<TabInfo[]> { return []; }
+  async waitAgent(): Promise<null> { return null; }
+  async getAgentSessionPath(): Promise<null> { return null; }
+  async exportLayout(): Promise<null> { return null; }
+  async paneLayout(): Promise<null> { return null; }
+  async agentExplain(): Promise<null> { return null; }
+  async getServerVersion(): Promise<null> { return null; }
+  async readPane(): Promise<ReadBuffer> { return { text: '', revision: 0, truncated: false }; }
+  async readAgent(): Promise<ReadBuffer> { return { text: '', revision: 0, truncated: false }; }
+  async waitForOutput(): Promise<WaitForOutputResult> { return { matched: false, reason: 'unavailable' }; }
+  async splitPane(): Promise<string> { throw new Error('subagent requires a herdr-managed pane'); }
+  async createTab(): Promise<{ tabId: string; paneId: string }> { throw new Error('subagent requires a herdr-managed pane'); }
+  async openPluginPane(): Promise<OpenPluginPaneResult> { throw new Error('plugin pane requires a herdr-managed pane'); }
 }
 
 /* ── Implementation ────────────────────────────────────────────────── */
@@ -321,10 +253,7 @@ export class HerdrClient implements HerdrClientLike {
     return herdrSocketTarget(this.env.socketPath);
   }
 
-  /**
-   * 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}.
-   */
+  /** One connection per control request: the reply is a single {id,result}|{id,error} line. */
   private request(method: string, params: Record<string, unknown>, timeoutMs = 15000): Promise<unknown> {
     return new Promise((resolve, reject) => {
       const sock = net.createConnection(this.target());
@@ -393,13 +322,11 @@ export class HerdrClient implements HerdrClientLike {
         ...(message ? { message } : {}),
       });
     } catch {
-      /* Silent best effort. */
     }
   }
 
-  // D-2: no reportAgentSession(). herdr's native pi integration owns the session path; pier stopped
-  // sending pane.report_agent_session so the field has a single writer. `report_agent` keeps carrying the
-  // activity badge, because `state` is a required field there and pier's todo/role text is pier-only data.
+  // Single writer: herdr's native pi integration owns the session path, so pier never sends
+  // pane.report_agent_session; the activity badge stays on report_agent.
 
   async reportMetadata(meta: { session: string; items: readonly TodoItem[]; progressSuffix?: string | null; lastWriteAt?: number | null }): Promise<void> {
     try {
@@ -409,8 +336,8 @@ export class HerdrClient implements HerdrClientLike {
         lastWriteAt: meta.lastWriteAt,
       });
       const blocked = formatBlockedLabel(meta.items);
-      // 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.
+      // D96: stale cleanup needs its own batch — stale(16) + pi-todo(1) exceeds herdr's 16-token
+      // limit, and the rejected request would drop both the title and the tokens.
       if (!this.clearedStaleTokens) {
         await this.request('pane.report_metadata', {
           pane_id: this.env.paneId,
@@ -427,12 +354,11 @@ export class HerdrClient implements HerdrClientLike {
         ...(blocked
           ? { state_labels: { [BLOCKED_LABEL_KEY]: blocked } }
           : { clear_state_labels: true }),
-        // D93: put the todo summary in a custom token; an empty string clears the key so stale summaries do not remain.
+        // D93: the todo summary is a custom token; an empty string clears the key instead of leaving a stale summary.
         tokens: sidebarTodoTokens(title),
         ttl_ms: 86400000,
       });
     } catch {
-      /* Silent best effort: the title projection must never affect pi's main flow. */
     }
   }
 
@@ -440,7 +366,6 @@ export class HerdrClient implements HerdrClientLike {
     const keys = Object.keys(tokens);
     if (keys.length === 0) return;
     try {
-      // 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];
@@ -464,7 +389,6 @@ export class HerdrClient implements HerdrClientLike {
         ...(name ? { display_agent: name } : { clear_display_agent: true }),
       });
     } catch {
-      /* Silent best effort: sidebar identity is supplementary. */
     }
   }
 
@@ -477,7 +401,6 @@ export class HerdrClient implements HerdrClientLike {
         ttl_ms: 86400000,
       });
     } catch {
-      /* Silent best effort: the human-gate marker is supplementary. */
     }
   }
 
@@ -503,16 +426,6 @@ export class HerdrClient implements HerdrClientLike {
     });
   }
 
-  async spawnSubPane(opts: { label: string; command: string[]; cwd: string; env?: Record<string, string> }): Promise<{ tabId: string; paneId: string }> {
-    const result = (await this.request('layout.apply', {
-      tab_label: opts.label,
-      root: { type: 'pane', command: opts.command, cwd: opts.cwd, ...(opts.env ? { env: opts.env } : {}) },
-    })) as Record<string, unknown>;
-    const paneId = findIdIn(result, 'pane_id');
-    if (!paneId) throw new Error('layout.apply: no pane_id in response');
-    return { tabId: findIdIn(result, 'tab_id') ?? '', paneId };
-  }
-
   async sendPaneText(paneId: string, text: string): Promise<void> {
     // 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' });
@@ -531,8 +444,7 @@ export class HerdrClient implements HerdrClientLike {
       const msg = String((err as Error)?.message ?? err);
       if (/timeout/i.test(msg)) return null;
       // A14: herdr reports agent_not_found while a freshly spawned pane's agent is still registering;
-      // callers poll `waitAgent`, so map it to the same "nothing yet" result as a timeout instead of
-      // failing the whole spawn with a raw server error.
+      // callers poll, so map it to the same "nothing yet" result as a timeout.
       if (/agent_not_found|agent target .* not found/i.test(msg)) return null;
       throw err;
     }
@@ -544,10 +456,6 @@ export class HerdrClient implements HerdrClientLike {
     return a?.session ?? null;
   }
 
-  async focusPane(paneId: string): Promise<void> {
-    await this.request('pane.focus', { pane_id: paneId });
-  }
-
   async splitPane(opts: { direction?: 'left' | 'right' | 'up' | 'down'; cwd?: string; env?: Record<string, string>; targetPaneId?: string; focus?: boolean; ratio?: number } = {}): Promise<string> {
     const params: Record<string, unknown> = {
       direction: opts.direction ?? 'right',
@@ -676,11 +584,6 @@ export class HerdrClient implements HerdrClientLike {
     return (result?.tabs ?? []).map((t) => this.mapTabInfo(t)).filter((t): t is TabInfo => t !== null);
   }
 
-  async tabGet(tabId: string): Promise<TabInfo | null> {
-    const result = (await this.request('tab.get', { tab_id: tabId })) as { tab?: Record<string, unknown> | null } | null;
-    return this.mapTabInfo(result?.tab ?? null);
-  }
-
   async tabClose(tabId: string): Promise<void> {
     await this.request('tab.close', { tab_id: tabId });
   }
@@ -708,15 +611,8 @@ export class HerdrClient implements HerdrClientLike {
       // 0.9.0 serde rejects unknown `popup` as "unknown variant" / invalid_params — not a dedicated
       // invalid_placement code. Any popup failure retries as tab; tab failure surfaces to Level 3.
       if (opts.placement !== 'popup') throw err;
-      const fallbackRes = (await this.request('plugin.pane.open', {
-        plugin_id: opts.pluginId,
-        entrypoint: opts.entrypoint,
-        placement: 'tab',
-        ...(opts.focus !== undefined ? { focus: opts.focus } : {}),
-        ...(opts.cwd ? { cwd: opts.cwd } : {}),
-        ...(opts.env ? { env: opts.env } : {}),
-        ...(opts.workspaceId ? { workspace_id: opts.workspaceId } : {}),
-      })) as Record<string, unknown> | null;
+      const { width: _width, height: _height, target_pane_id: _target, ...base } = params;
+      const fallbackRes = (await this.request('plugin.pane.open', { ...base, placement: 'tab' })) as Record<string, unknown> | null;
       return {
         mode: 'fallback_tab',
         paneId: findIdIn(fallbackRes, 'pane_id') ?? undefined,
@@ -725,19 +621,6 @@ export class HerdrClient implements HerdrClientLike {
     }
   }
 
-  async closePopup(): Promise<boolean> {
-    try {
-      await this.request('popup.close', {});
-      return true;
-    } catch (err) {
-      const msg = String((err as Error)?.message ?? err);
-      if (/popup_not_open|not found|not supported|unknown method/i.test(msg)) {
-        return false;
-      }
-      throw err;
-    }
-  }
-
   async agentExplain(target: string): Promise<Record<string, unknown> | null> {
     try {
       const result = (await this.request('agent.explain', { target })) as Record<string, unknown> | null;
@@ -763,7 +646,6 @@ export class HerdrClient implements HerdrClientLike {
         return result.version;
       }
     } catch {
-      /* ignore */
     }
     return null;
   }
@@ -772,19 +654,23 @@ export class HerdrClient implements HerdrClientLike {
     await this.request('pane.send_keys', { pane_id: paneId, keys });
   }
 
-  async readPane(paneId: string, opts: {
-    source?: 'visible' | 'recent' | 'recent_unwrapped';
-    lines?: number;
-    stripAnsi?: boolean;
-  } = {}): Promise<{ text: string; revision: number; truncated: boolean }> {
-    // 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,
+  /** Shared pane.read/agent.read decode: payload nested under `read` (older servers answer it flat). */
+  private async readBuffer(
+    method: 'pane.read' | 'agent.read',
+    target: { pane_id: string } | { target: string },
+    opts: ReadOptions,
+    stripAnsiDefault: boolean,
+  ): Promise<ReadBuffer> {
+    const result = (await this.request(method, {
+      ...target,
       source: opts.source ?? 'recent',
       format: 'text',
-      strip_ansi: opts.stripAnsi ?? false,
+      strip_ansi: opts.stripAnsi ?? stripAnsiDefault,
       ...(opts.lines != null ? { lines: opts.lines } : {}),
-    })) as { read?: { text?: unknown; revision?: unknown; truncated?: unknown }; text?: unknown; revision?: unknown; truncated?: unknown } | null;
+    })) as {
+      read?: { text?: unknown; revision?: unknown; truncated?: unknown };
+      text?: unknown; revision?: unknown; truncated?: unknown;
+    } | null;
     const payload = result?.read ?? result ?? {};
     return {
       text: typeof payload.text === 'string' ? payload.text : '',
@@ -793,24 +679,12 @@ export class HerdrClient implements HerdrClientLike {
     };
   }
 
-  async readAgent(target: string, opts: {
-    source?: 'visible' | 'recent' | 'recent_unwrapped';
-    lines?: number;
-    stripAnsi?: boolean;
-  } = {}): Promise<{ text: string; revision: number; truncated: boolean }> {
-    const result = (await this.request('agent.read', {
-      target,
-      source: opts.source ?? 'recent',
-      format: 'text',
-      strip_ansi: opts.stripAnsi ?? true,
-      ...(opts.lines != null ? { lines: opts.lines } : {}),
-    })) as { read?: { text?: unknown; revision?: unknown; truncated?: unknown }; text?: unknown; revision?: unknown; truncated?: unknown } | null;
-    const payload = result?.read ?? result ?? {};
-    return {
-      text: typeof payload.text === 'string' ? payload.text : '',
-      revision: typeof payload.revision === 'number' ? payload.revision : 0,
-      truncated: payload.truncated === true,
-    };
+  async readPane(paneId: string, opts: ReadOptions = {}): Promise<ReadBuffer> {
+    return this.readBuffer('pane.read', { pane_id: paneId }, opts, false);
+  }
+
+  async readAgent(target: string, opts: ReadOptions = {}): Promise<ReadBuffer> {
+    return this.readBuffer('agent.read', { target }, opts, true);
   }
 
   async waitForOutput(paneId: string, match: { type: 'substring' | 'regex'; value: string }, timeoutMs: number): Promise<WaitForOutputResult> {

package/src/history-store.ts

@@ -1,10 +1,7 @@
 /**
- * Workspace history (v1.2, DESIGN.md §13.4).
- *
- * Task history is append-only JSONL partitioned by cwd, mirroring pi session partitioning:
- *   <agentRoot>/herdr-pi/history/--<cwd>--/history.jsonl
- * Records are immutable so GC can remove panes without deleting history. Recovery keeps
- * both the sessionFile and launchCommand snapshots as fallbacks.
+ * Delegation ledger: append-only JSONL partitioned by cwd, mirroring pi's session partitioning
+ * (<agentRoot>/herdr-pi/history/--<cwd>--/history.jsonl). Rows are immutable, so GC can drop panes
+ * without losing history; recovery keeps both the sessionFile and launchCommand snapshots.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -12,13 +9,13 @@ import { historyFilePath, preferredHistoryFile } from './storage-layout.ts';
 
 export { historyFilePath, preferredHistoryFile };
 
-/** Legacy short/resident entries normalize to task; missing values do too, while role names pass through unchanged. */
+/** Legacy short/resident entries normalize to task, as do missing values; role names pass through. */
 export function normalizeEntryKind(kind: string | null | undefined): string {
   if (!kind || kind === 'short' || kind === 'resident') return 'task';
   return kind;
 }
 
-/** O6: only a .jsonl path is accepted during settlement, so invalid reports cannot overwrite a valid path. */
+/** Only a .jsonl path is accepted, so an invalid report cannot overwrite a valid one. */
 export function applyReportedSessionFile(
   current: string | null,
   reported: string | null | undefined,
@@ -29,11 +26,9 @@ export function applyReportedSessionFile(
 
 export interface HistoryEntry {
   taskId: string;
-  /** 'task' or a role name; disk reads normalize short/resident to task for compatibility. */
   kind: string;
   paneId: string;
   tabId: string;
-  /** v1.3: task tab name retained for history review and revival; omitted by older entries. */
   tabName?: string;
   workspaceId: string;
   cwd: string;
@@ -45,19 +40,17 @@ export interface HistoryEntry {
   status: 'running' | 'settled' | 'consumed' | 'closed';
   outcome?: string | null;
   createdAt: number;
-  /** M13c: durable consumption time, which provides the GC TTL basis. */
   consumedAt?: number | null;
   closedAt?: number | null;
-  /** Previous-generation pane ID, retained when work is redone or revived. */
   revivedFrom?: string | null;
-  /** 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). */
+  /** Writer marker (spawn / poll-settle / poll-timeout / gc / zombie-sweep …) for auditability. */
   via?: string;
 }
 
-/** 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. */
+/**
+ * When a patch omits `outcome`, inherit the latest non-empty value for the taskId: GC bookkeeping
+ * must not erase a settlement result 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;
@@ -82,7 +75,6 @@ function coerceHistoryEntry(obj: unknown): HistoryEntry | null {
   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/)) {
@@ -107,7 +99,7 @@ export type HistoryReadResult =
   | { status: 'missing' }
   | { status: 'unreadable'; error: Error };
 
-/** Distinguish missing vs permission/IO failure. readHistory still returns [] for both. */
+/** Distinguish missing vs permission/IO failure; readHistory still returns [] for both. */
 export function inspectHistory(file: string): HistoryReadResult {
   try {
     if (!fs.existsSync(file)) return { status: 'missing' };
@@ -118,15 +110,37 @@ export function inspectHistory(file: string): HistoryReadResult {
   }
 }
 
-/** Read a history file; missing or unreadable yields []. */
 export function readHistory(file: string): HistoryEntry[] {
   const r = inspectHistory(file);
   return r.status === 'ok' ? r.entries : [];
 }
 
+/** Every ledger under `<agentRoot>/herdr-pi/history`. Resume must see tasks spawned into another checkout. */
+export function readHistoryTree(agentRoot: string): HistoryEntry[] {
+  const root = path.join(agentRoot, 'herdr-pi', 'history');
+  let names: string[];
+  try {
+    names = fs.readdirSync(root);
+  } catch {
+    return [];
+  }
+  const all: HistoryEntry[] = [];
+  for (const name of names) {
+    let isDir = false;
+    try {
+      isDir = fs.statSync(path.join(root, name)).isDirectory();
+    } catch {
+      continue;
+    }
+    if (!isDir) continue;
+    all.push(...readHistory(path.join(root, name, 'history.jsonl')));
+  }
+  return all;
+}
+
 export type HistoryWriteResult = { ok: true } | { ok: false; error: Error };
 
-/** Append one entry. Failures are logged and returned so the ledger is not silently lost. */
+/** 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 });
@@ -139,7 +153,6 @@ export function appendHistory(file: string, entry: HistoryEntry): HistoryWriteRe
   }
 }
 
-/** 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) {
@@ -151,7 +164,7 @@ export function generationsByTask(entries: readonly HistoryEntry[]): Map<string,
   return map;
 }
 
-/** Return the newest generation for taskId, which is the one used for resume. */
+/** Newest generation for taskId — 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;