pi-pier 0.3.0 → 0.4.1

package/src/herdr-client.ts

@@ -1,37 +1,31 @@
 /**
  * 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.5 (protocol 22; see WIRE.md — unchanged since 0.9.1; 0.9.2 removed only the
+ * pane.graphics.* API, which pier never used). The request shapes pier builds are pinned to the
+ * 0.9.5 methods snapshot in test/fixtures/herdr-contract.json (recent `api schema` releases no longer
+ * emit a methods map) — after a herdr upgrade, re-verify the protocol number and the method set, then
+ * regenerate the fixture 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';
+import { applyWorkerTag, delegationSidebarTokens, type DelegationContext } from './delegation-core.ts';
 import { LOCK_BATCH_LIMIT, LOCK_TTL_MS } from './lock-core.ts';
 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 {
@@ -66,6 +60,18 @@ export interface PaneListItem {
   terminalTitleStripped?: string | null;
 }
 
+/** pane.process_info: the processes currently holding the pane's PTY foreground. */
+export interface PaneProcessInfo {
+  paneId: string;
+  shellPid: number | null;
+  foreground: ReadonlyArray<{
+    name: string | null;
+    argv0: string | null;
+    pid: number | null;
+    cwd: string | null;
+  }>;
+}
+
 export interface PaneLayoutCell {
   paneId: string;
   x: number;
@@ -97,10 +103,11 @@ export interface OpenPluginPaneOptions {
 
 export type OpenPluginPaneResult =
   | { mode: 'popup'; ok: true }
+  /** Another popup/modal owns the session; the caller may switch that panel instead of opening a tab. */
+  | { mode: 'busy' }
   | { 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 +129,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,82 +144,75 @@ 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. */
+/** Wire protocol this client is written against (herdr 0.9.5, contract fixture regenerated 2026-10-20). */
 export const HERDR_PROTOCOL_EXPECTED = 22;
 
 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. */
+  reportMetadata(meta: { session: string; items: readonly TodoItem[]; progressSuffix?: string | null; lastWriteAt?: number | null; workerTag?: string | null }): Promise<void>;
   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>;
+  /** Delegation identity tokens (pi-parent/pi-task): who delegated this pane and for what task. */
+  reportDelegationTokens(d: DelegationContext | null): Promise<void>;
+  /**
+   * herdr 0.9.2+ self-reported restore: register the command that reopens this exact session after
+   * a server restart. Worker panes only; masters stay with herdr's native pi integration.
+   * Silently no-ops on older servers and on any error — resume is always best-effort.
+   */
+  reportAgentSessionResume(sessionId: string, resumeArgv: readonly string[]): 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. */
+  /** Foreground process snapshot; null when the server predates the method or the pane is gone. */
+  processInfo(paneId: string): Promise<PaneProcessInfo | null>;
+  /** 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,73 +233,36 @@ 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> {}
+  async reportAgentSessionResume(): Promise<void> {}
   async reportMetadata(): Promise<void> {}
   async reportLockTokens(): Promise<void> {}
+  async reportDelegationTokens(): 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 processInfo(): Promise<PaneProcessInfo | null> { return null; }
+  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 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 +280,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());
@@ -383,6 +339,13 @@ export class HerdrClient implements HerdrClientLike {
 
   /* ── Reporting (silent best effort: the workbench mirror must never affect pi's main flow) ── */
 
+  /**
+   * D-2 (verified 2026-10-20): herdr's native `herdr:pi` integration owns `agent_status`
+   * (`screen_detection_skip_reason: full_lifecycle_hook_authority`), but it never reports the
+   * activity text. `pane.report_agent` is still the only carrier for the tool badge, so pier keeps
+   * sending state with the message; removing it requires migrating the badge to
+   * `report_metadata.state_labels` first.
+   */
   async reportAgent(state: PaneAgentState, message: string | null): Promise<void> {
     try {
       await this.request('pane.report_agent', {
@@ -393,24 +356,53 @@ 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.
+  /**
+   * Master panes stay with herdr's native pi integration (it owns the session path); workers
+   * self-report so a restart replays pier's own launch line — extension loaded, role model, approve,
+   * fullscreen frame — instead of a bare `pi --resume` without `-e`. herdr requires the source to
+   * hold the pane before accepting a resume command (resume_not_accepted), so an idle state report
+   * goes first, with one retry to tolerate a lost race with the session_start gate report.
+   */
+  async reportAgentSessionResume(sessionId: string, resumeArgv: readonly string[]): Promise<void> {
+    if (!this.env) return;
+    try {
+      await this.reportAgent('idle', null);
+      const params = {
+        pane_id: this.env.paneId,
+        source: REPORT_AGENT_SOURCE,
+        agent: 'pi',
+        agent_session_id: sessionId,
+        resume_argv: [...resumeArgv],
+      };
+      try {
+        await this.request('pane.report_agent_session', params);
+      } catch {
+        const { promise: retryDelay, resolve: retryNow } = Promise.withResolvers<void>();
+        setTimeout(retryNow, 250);
+        await retryDelay;
+        await this.request('pane.report_agent_session', params);
+      }
+    } catch {
+      /* best effort: live sessions never depend on restore metadata */
+    }
+  }
 
-  async reportMetadata(meta: { session: string; items: readonly TodoItem[]; progressSuffix?: string | null; lastWriteAt?: number | null }): Promise<void> {
+  async reportMetadata(meta: { session: string; items: readonly TodoItem[]; progressSuffix?: string | null; lastWriteAt?: number | null; workerTag?: string | null }): Promise<void> {
     try {
       void meta.session;
-      const title = formatPaneTitle(meta.items, null, {
-        progressSuffix: meta.progressSuffix,
-        lastWriteAt: meta.lastWriteAt,
-      });
+      const title = applyWorkerTag(
+        formatPaneTitle(meta.items, null, {
+          progressSuffix: meta.progressSuffix,
+          lastWriteAt: meta.lastWriteAt,
+        }),
+        meta.workerTag ?? null,
+      );
       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 +419,27 @@ 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. */
+    }
+  }
+
+  /** RFC rfc-delegation-identity §2.3: separate batch — tokens patches never merge with the stale
+   * cleanup or the todo title (D96 discipline); an unknown parent pane skips the report. */
+  async reportDelegationTokens(d: DelegationContext | null): Promise<void> {
+    const tokens = d ? delegationSidebarTokens(d) : {};
+    if (Object.keys(tokens).length === 0) return;
+    try {
+      await this.request('pane.report_metadata', {
+        pane_id: this.env.paneId,
+        source: REPORT_AGENT_SOURCE,
+        tokens,
+        ttl_ms: 86400000,
+      });
+    } catch {
     }
   }
 
@@ -440,7 +447,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 +470,6 @@ export class HerdrClient implements HerdrClientLike {
         ...(name ? { display_agent: name } : { clear_display_agent: true }),
       });
     } catch {
-      /* Silent best effort: sidebar identity is supplementary. */
     }
   }
 
@@ -477,7 +482,6 @@ export class HerdrClient implements HerdrClientLike {
         ttl_ms: 86400000,
       });
     } catch {
-      /* Silent best effort: the human-gate marker is supplementary. */
     }
   }
 
@@ -503,16 +507,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 +525,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 +537,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',
@@ -605,6 +594,29 @@ export class HerdrClient implements HerdrClientLike {
     }));
   }
 
+  async processInfo(paneId: string): Promise<PaneProcessInfo | null> {
+    try {
+      const result = (await this.request('pane.process_info', { pane_id: paneId })) as Record<string, unknown> | null;
+      const info = (result?.process_info ?? result) as Record<string, unknown> | null | undefined;
+      if (!info || typeof info !== 'object') return null;
+      const raw = Array.isArray(info.foreground_processes) ? info.foreground_processes : [];
+      return {
+        paneId: typeof info.pane_id === 'string' ? info.pane_id : paneId,
+        shellPid: typeof info.shell_pid === 'number' ? info.shell_pid : null,
+        foreground: raw
+          .filter((p): p is Record<string, unknown> => p !== null && typeof p === 'object')
+          .map((p) => ({
+            name: typeof p.name === 'string' ? p.name : null,
+            argv0: typeof p.argv0 === 'string' ? p.argv0 : null,
+            pid: typeof p.pid === 'number' ? p.pid : null,
+            cwd: typeof p.cwd === 'string' ? p.cwd : null,
+          })),
+      };
+    } catch {
+      return null;
+    }
+  }
+
   async exportLayout(opts: { paneId?: string; tabId?: string } = {}): Promise<{ tabId: string | null; zoomed: boolean; root: unknown; focusedPaneId: string | null } | null> {
     try {
       const result = (await this.request('layout.export', {
@@ -676,11 +688,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 });
   }
@@ -705,18 +712,17 @@ export class HerdrClient implements HerdrClientLike {
       }
       return { mode: 'pane', paneId: findIdIn(result, 'pane_id') ?? '' };
     } catch (err) {
+      // A live popup/modal is a transient state, not an old server: opening a tab would orphan a
+      // second dashboard and silently change the surface. Callers decide whether to switch panels.
+      const message = err instanceof Error ? err.message : String(err);
+      if (opts.placement === 'popup' && /ui_busy|popup pane is already open/i.test(message)) {
+        return { mode: 'busy' };
+      }
       // 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.
+      // invalid_placement code. Any other 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 +731,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;
@@ -752,39 +745,27 @@ export class HerdrClient implements HerdrClientLike {
     }
   }
 
-  private cachedVersion: string | null = null;
-
-  async getServerVersion(): Promise<string | null> {
-    if (this.cachedVersion) return this.cachedVersion;
-    try {
-      const result = (await this.request('ping', {})) as { version?: unknown } | null;
-      if (typeof result?.version === 'string') {
-        this.cachedVersion = result.version;
-        return result.version;
-      }
-    } catch {
-      /* ignore */
-    }
-    return null;
-  }
-
   async sendPaneKeys(paneId: string, keys: string[]): Promise<void> {
     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 +774,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> {