pi-pier 0.2.6 → 0.3.0

package/src/git-adapter.ts

@@ -22,8 +22,17 @@ export interface GitError extends Error {
 export type GitExecFile = (
   file: string,
   args: readonly string[],
-  options: { timeout: number; encoding: 'utf8' },
-) => Promise<{ stdout: string; stderr: string }>
+  options: { timeout: number; encoding: 'utf8'; maxBuffer: number },
+) => Promise<{ stdout: string; stderr: string }>;
+
+/**
+ * Output ceiling for one git call. `execFile` defaults to 1MB, which a large checkout exceeds
+ * (`status --porcelain` on a repo with tens of thousands of untracked files, or `diff --stat`
+ * across a wide change): the call then fails with ENOBUFS, callers normalize it to null, and the
+ * user sees a silently missing stat line — or "failed to create worktree" for a worktree that was
+ * in fact created. 64MB bounds memory without hitting realistic repositories.
+ */
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
 
 /**
  * Minimal Git adapter for worktree and status operations.
@@ -79,7 +88,7 @@ export class NodeGitAdapter implements GitAdapter {
       const { stdout, stderr } = await this.exec(
         this.gitExecutable,
         ['-C', cwd, ...args],
-        { timeout: this.timeoutMs, encoding: 'utf8' },
+        { timeout: this.timeoutMs, encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER },
       )
       return { stdout, stderr }
     } catch (err) {

package/src/herdr-client.ts

@@ -1,14 +1,17 @@
 /**
  * Minimal herdr socket API client used inside the pi extension.
  *
- * Validated against herdr 0.8.0-preview (protocol 19, Windows named pipe; see WIRE.md):
+ * 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:
  *  - 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;
+ *  - 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}.
@@ -49,8 +52,54 @@ export interface AgentInfo {
   session: string | null;
   stateLabels: Record<string, string>;
   tokens: Record<string, string | null>;
+  /** Herdr 0.9.1: foreground cwd of the process currently controlling the PTY. */
+  foregroundCwd?: string | null;
 }
 
+export interface PaneListItem {
+  paneId: string;
+  tabId: string;
+  workspaceId: string;
+  agentStatus: string;
+  foregroundCwd?: string | null;
+  terminalTitle?: string | null;
+  terminalTitleStripped?: string | null;
+}
+
+export interface PaneLayoutCell {
+  paneId: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  focused: boolean;
+}
+
+export interface PaneLayoutSnapshot {
+  tabId: string | null;
+  zoomed: boolean;
+  focusedPaneId: string | null;
+  panes: PaneLayoutCell[];
+}
+
+export interface OpenPluginPaneOptions {
+  pluginId: string;
+  entrypoint: string;
+  placement?: 'popup' | 'overlay' | 'split' | 'tab' | 'zoomed';
+  width?: string;
+  height?: string;
+  focus?: boolean;
+  cwd?: string;
+  env?: Record<string, string>;
+  targetPaneId?: string;
+  workspaceId?: string;
+}
+
+export type OpenPluginPaneResult =
+  | { mode: 'popup'; ok: true }
+  | { mode: 'pane'; paneId: string }
+  | { mode: 'fallback_tab'; tabId?: string; paneId?: string };
+
 /** TabInfo projection; fields mirror the observed tab schema. */
 export interface TabInfo {
   tabId: string;
@@ -79,12 +128,31 @@ export function herdrSocketTarget(socketPath: string, platform: NodeJS.Platform
   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.
+ */
+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)) {
+    return 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;
+
+export type WaitForOutputResult =
+  | { matched: true }
+  | { matched: false; reason: 'timeout' | 'unavailable' };
 
 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>;
+  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>;
   /**
@@ -109,21 +177,31 @@ export interface HerdrClientLike {
   /** 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 }): Promise<string>;
+  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. */
   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<Array<{ paneId: string; tabId: string; workspaceId: string; agentStatus: string }>>;
+  listPanes(): Promise<PaneListItem[]>;
   /** 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>;
+  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. */
   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). */
   sendPaneKeys(paneId: string, keys: string[]): Promise<void>;
   /** M14: Read the pane output buffer; recent preserves ANSI data for T6 detection by default. */
@@ -132,8 +210,14 @@ export interface HerdrClientLike {
     lines?: number;
     stripAnsi?: boolean;
   }): Promise<{ text: string; revision: number; truncated: boolean }>;
-  /** 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>;
+  /** 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. */
+  waitForOutput(paneId: string, match: { type: 'substring' | 'regex'; value: string }, timeoutMs: number): Promise<WaitForOutputResult>;
   close(): void;
 }
 
@@ -156,7 +240,6 @@ function findIdIn(obj: unknown, key: string, depth = 0): string | null {
 export class NoopHerdrClient implements HerdrClientLike {
   readonly available = false;
   async reportAgent(): Promise<void> {}
-  async reportAgentSession(): Promise<void> {}
   async reportMetadata(): Promise<void> {}
   async reportLockTokens(): Promise<void> {}
   async reportDisplayAgent(): Promise<void> {}
@@ -182,12 +265,15 @@ export class NoopHerdrClient implements HerdrClientLike {
   async createTab(): Promise<{ tabId: string; paneId: string }> {
     throw new Error('subagent requires a herdr-managed pane');
   }
-  async listPanes(): Promise<Array<{ paneId: string; tabId: string; workspaceId: string; agentStatus: string }>> {
+  async listPanes(): Promise<PaneListItem[]> {
     return [];
   }
   async exportLayout(): Promise<null> {
     return null;
   }
+  async paneLayout(): Promise<null> {
+    return null;
+  }
   async tabList(): Promise<TabInfo[]> {
     return [];
   }
@@ -195,12 +281,27 @@ export class NoopHerdrClient implements HerdrClientLike {
     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 waitForOutput(): Promise<boolean | null> {
-    return null;
+  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 {}
 }
@@ -296,21 +397,11 @@ export class HerdrClient implements HerdrClientLike {
     }
   }
 
-  async reportAgentSession(sessionPath: string | null): Promise<void> {
-    if (!sessionPath) return;
-    try {
-      await this.request('pane.report_agent_session', {
-        pane_id: this.env.paneId,
-        source: REPORT_AGENT_SOURCE,
-        agent: 'pi',
-        agent_session_path: sessionPath,
-      });
-    } 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.
 
-  async reportMetadata(meta: { session: string; items: TodoItem[]; progressSuffix?: string | null; lastWriteAt?: number | null }): Promise<void> {
+  async reportMetadata(meta: { session: string; items: readonly TodoItem[]; progressSuffix?: string | null; lastWriteAt?: number | null }): Promise<void> {
     try {
       void meta.session;
       const title = formatPaneTitle(meta.items, null, {
@@ -407,6 +498,7 @@ export class HerdrClient implements HerdrClientLike {
         session: session?.value != null ? String(session.value) : null,
         stateLabels: (a.state_labels ?? {}) as Record<string, string>,
         tokens: (a.tokens ?? {}) as Record<string, string | null>,
+        ...(a.foreground_cwd ? { foregroundCwd: String(a.foreground_cwd) } : {}),
       };
     });
   }
@@ -438,6 +530,10 @@ export class HerdrClient implements HerdrClientLike {
     } catch (err) {
       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.
+      if (/agent_not_found|agent target .* not found/i.test(msg)) return null;
       throw err;
     }
   }
@@ -452,13 +548,28 @@ export class HerdrClient implements HerdrClientLike {
     await this.request('pane.focus', { pane_id: paneId });
   }
 
-  async splitPane(opts: { direction?: 'left' | 'right' | 'up' | 'down'; cwd?: string; env?: Record<string, string>; targetPaneId?: string } = {}): Promise<string> {
-    const result = (await this.request('pane.split', {
+  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',
       ...(opts.targetPaneId ? { target_pane_id: opts.targetPaneId } : {}),
       ...(opts.cwd ? { cwd: opts.cwd } : {}),
       ...(opts.env ? { env: opts.env } : {}),
-    })) as Record<string, unknown>;
+      ...(opts.focus !== undefined ? { focus: opts.focus } : {}),
+      ...(opts.ratio !== undefined ? { ratio: opts.ratio } : {}),
+    };
+    try {
+      return await this.splitPaneRequest(params);
+    } catch (err) {
+      if (opts.ratio === undefined) throw err;
+      const msg = String((err as Error)?.message ?? err);
+      if (!/unknown|invalid_params|unexpected/i.test(msg)) throw err;
+      const { ratio: _ratio, ...rest } = params;
+      return await this.splitPaneRequest(rest);
+    }
+  }
+
+  private async splitPaneRequest(params: Record<string, unknown>): Promise<string> {
+    const result = (await this.request('pane.split', params)) as Record<string, unknown>;
     const paneId = findIdIn(result, 'pane_id');
     if (!paneId) throw new Error('pane.split: no pane_id in response');
     return paneId;
@@ -481,17 +592,20 @@ export class HerdrClient implements HerdrClientLike {
     return { tabId, paneId: paneId ?? '' };
   }
 
-  async listPanes(): Promise<Array<{ paneId: string; tabId: string; workspaceId: string; agentStatus: string }>> {
+  async listPanes(): Promise<PaneListItem[]> {
     const result = (await this.request('pane.list', {})) as { panes?: Array<Record<string, unknown>> } | null;
     return (result?.panes ?? []).map((p) => ({
       paneId: String(p.pane_id ?? ''),
       tabId: String(p.tab_id ?? ''),
       workspaceId: String(p.workspace_id ?? ''),
       agentStatus: String(p.agent_status ?? 'unknown'),
+      ...(p.foreground_cwd ? { foregroundCwd: String(p.foreground_cwd) } : {}),
+      ...(p.terminal_title ? { terminalTitle: String(p.terminal_title) } : {}),
+      ...(p.terminal_title_stripped ? { terminalTitleStripped: String(p.terminal_title_stripped) } : {}),
     }));
   }
 
-  async exportLayout(opts: { paneId?: string; tabId?: string }): Promise<{ tabId: string | null; zoomed: boolean; root: unknown } | 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', {
         ...(opts.paneId ? { pane_id: opts.paneId } : {}),
@@ -504,6 +618,42 @@ export class HerdrClient implements HerdrClientLike {
         tabId: typeof layout.tab_id === 'string' ? layout.tab_id : null,
         zoomed: Boolean(layout.zoomed),
         root: layout.root ?? null,
+        // D-4: focus heat needs to know which pane the human is on; layout.export reports it.
+        focusedPaneId: typeof layout.focused_pane_id === 'string' ? layout.focused_pane_id : null,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  async paneLayout(opts: { paneId?: string } = {}): Promise<PaneLayoutSnapshot | null> {
+    try {
+      const result = (await this.request('pane.layout', {
+        ...(opts.paneId ? { pane_id: opts.paneId } : {}),
+      })) as Record<string, unknown> | null;
+      const layout = (result?.layout ?? result) as Record<string, unknown> | null | undefined;
+      if (!layout || typeof layout !== 'object' || !Array.isArray(layout.panes)) return null;
+      const panes: PaneLayoutCell[] = [];
+      for (const raw of layout.panes) {
+        if (!raw || typeof raw !== 'object') continue;
+        const p = raw as Record<string, unknown>;
+        const rect = (p.rect && typeof p.rect === 'object') ? p.rect as Record<string, unknown> : p;
+        const paneId = typeof p.pane_id === 'string' ? p.pane_id : null;
+        if (!paneId) continue;
+        panes.push({
+          paneId,
+          x: Number(rect.x) || 0,
+          y: Number(rect.y) || 0,
+          w: Number(rect.width ?? rect.w) || 0,
+          h: Number(rect.height ?? rect.h) || 0,
+          focused: p.focused === true,
+        });
+      }
+      return {
+        tabId: typeof layout.tab_id === 'string' ? layout.tab_id : null,
+        zoomed: Boolean(layout.zoomed),
+        focusedPaneId: typeof layout.focused_pane_id === 'string' ? layout.focused_pane_id : null,
+        panes,
       };
     } catch {
       return null;
@@ -535,6 +685,89 @@ export class HerdrClient implements HerdrClientLike {
     await this.request('tab.close', { tab_id: tabId });
   }
 
+  async openPluginPane(opts: OpenPluginPaneOptions): Promise<OpenPluginPaneResult> {
+    const params: Record<string, unknown> = {
+      plugin_id: opts.pluginId,
+      entrypoint: opts.entrypoint,
+      ...(opts.placement ? { placement: opts.placement } : {}),
+      ...(opts.width ? { width: opts.width } : {}),
+      ...(opts.height ? { height: opts.height } : {}),
+      ...(opts.focus !== undefined ? { focus: opts.focus } : {}),
+      ...(opts.cwd ? { cwd: opts.cwd } : {}),
+      ...(opts.env ? { env: opts.env } : {}),
+      ...(opts.targetPaneId ? { target_pane_id: opts.targetPaneId } : {}),
+      ...(opts.workspaceId ? { workspace_id: opts.workspaceId } : {}),
+    };
+    try {
+      const result = (await this.request('plugin.pane.open', params)) as Record<string, unknown> | null;
+      if (opts.placement === 'popup') {
+        return { mode: 'popup', ok: true };
+      }
+      return { mode: 'pane', paneId: findIdIn(result, 'pane_id') ?? '' };
+    } catch (err) {
+      // 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;
+      return {
+        mode: 'fallback_tab',
+        paneId: findIdIn(fallbackRes, 'pane_id') ?? undefined,
+        tabId: findIdIn(fallbackRes, 'tab_id') ?? undefined,
+      };
+    }
+  }
+
+  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;
+      if (!result || typeof result !== 'object') return null;
+      const nested = result.explain;
+      if (nested && typeof nested === 'object' && !Array.isArray(nested)) {
+        return nested as Record<string, unknown>;
+      }
+      return result;
+    } catch {
+      return null;
+    }
+  }
+
+  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 });
   }
@@ -560,7 +793,27 @@ export class HerdrClient implements HerdrClientLike {
     };
   }
 
-  async waitForOutput(paneId: string, match: { type: 'substring' | 'regex'; value: string }, timeoutMs: number): Promise<boolean | null> {
+  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 waitForOutput(paneId: string, match: { type: 'substring' | 'regex'; value: string }, timeoutMs: number): Promise<WaitForOutputResult> {
     try {
       await this.request('pane.wait_for_output', {
         pane_id: paneId,
@@ -568,10 +821,13 @@ export class HerdrClient implements HerdrClientLike {
         match,
         timeout_ms: timeoutMs,
       }, timeoutMs + 5000);
-      return true;
+      return { matched: true };
     } catch (err) {
       const msg = String((err as Error)?.message ?? err);
-      if (/timeout/i.test(msg)) return null;
+      if (/timeout/i.test(msg)) return { matched: false, reason: 'timeout' };
+      if (/not supported|not implemented|unknown method|unavailable|method not found/i.test(msg)) {
+        return { matched: false, reason: 'unavailable' };
+      }
       throw err;
     }
   }

package/src/index-locks.ts

@@ -16,6 +16,10 @@ import {
 } from './lock-core.ts';
 import type { HerdrClientLike, HerdrEnv } from './herdr-client.ts';
 
+export interface WriteLocksHandle {
+  getHeldLocks: () => readonly string[];
+}
+
 export function installWriteLocks(
   pi: ExtensionAPI,
   opts: {
@@ -23,11 +27,15 @@ export function installWriteLocks(
     env: HerdrEnv | null;
     hard: boolean;
   },
-): void {
+): WriteLocksHandle {
   const { client, env, hard } = opts;
   const heldLocks = new Set<string>();
   const lockWarnByToolCall = new Map<string, string>();
 
+  if (!client.available || !env) {
+    return { getHeldLocks: () => [] };
+  }
+
   async function acquireLocks(paths: readonly string[]): Promise<void> {
     for (const p of paths) heldLocks.add(p);
     await client.reportLockTokens(acquireTokensFor(paths, env?.paneId ?? ''));
@@ -37,17 +45,24 @@ export function installWriteLocks(
     if (!client.available || !env) return;
     const cwd = ctx?.cwd ?? process.cwd();
     let agents: LockAgentView[];
+    let ownForegroundCwd: string | null = null;
     try {
-      agents = (await client.listAgents()).map((a) => ({ paneId: a.paneId, tokens: a.tokens }));
+      const liveAgents = await client.listAgents();
+      agents = liveAgents.map((a) => ({ paneId: a.paneId, tokens: a.tokens }));
+      const me = liveAgents.find((a) => a.paneId === env.paneId);
+      if (me?.foregroundCwd) {
+        ownForegroundCwd = me.foregroundCwd;
+      }
     } catch {
       return;
     }
+    const effectiveCwd = ownForegroundCwd ?? cwd;
     const plan = planWriteGuard({
       toolName: event.toolName ?? '',
       input: event.input,
       agents,
       ownPaneId: env.paneId,
-      cwd,
+      cwd: effectiveCwd,
       hard,
     });
     if (plan.kind === 'skip') return;
@@ -60,13 +75,14 @@ export function installWriteLocks(
     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);
+  pi.on('tool_result', async (event: unknown) => {
+    const rec = (event ?? {}) as { toolCallId?: unknown; content?: unknown };
+    if (typeof rec.toolCallId !== 'string') return;
+    const warning = lockWarnByToolCall.get(rec.toolCallId);
     if (!warning) return;
-    lockWarnByToolCall.delete(event.toolCallId);
-    const content = Array.isArray(event.content) ? event.content : [];
-    return { content: [...content, { type: 'text', text: warning }] };
+    lockWarnByToolCall.delete(rec.toolCallId);
+    const content = Array.isArray(rec.content) ? rec.content as Array<{ type: 'text'; text: string }> : [];
+    return { content: [...content, { type: 'text' as const, text: warning }] };
   });
 
   pi.on('agent_settled', async () => {
@@ -102,4 +118,6 @@ export function installWriteLocks(
       ui?.notify?.(lines.join('\n'), 'info');
     },
   });
+
+  return { getHeldLocks: () => [...heldLocks] };
 }

package/src/index-master.ts

@@ -35,6 +35,8 @@ export interface MasterPluginMount {
   reconcileOnSettlement: (description: string, outcome: 'settled' | 'failed') => string[];
   withReconcileNotes: (base: string, notes: readonly string[]) => string;
   claimSettleNotice: (key: string) => boolean;
+  isCompactionInFlight?: () => boolean;
+  isIntentionalAbort?: () => boolean;
 }
 
 async function loadEntry(
@@ -89,9 +91,12 @@ export async function mountMasterPlugins(m: MasterPluginMount): Promise<void> {
       (m.pi as { appendEntry?: (t: string, d: unknown) => void }).appendEntry?.(customType, data);
     },
     state: m.todoUi,
+    getBlockedDepth: m.getBlockedDepth,
     stopReminder: {
       getBlockedDepth: m.getBlockedDepth,
       getRunningSubs: () => m.port.current?.listRunningSubs().length ?? 0,
+      isCompactionInFlight: m.isCompactionInFlight,
+      isIntentionalAbort: m.isIntentionalAbort,
     },
   });
   await loadEntry(sessionRoot, useLoader, './core/todo.ts', todoPlugin);

package/src/index-notices.ts

@@ -5,7 +5,7 @@
  * tool calls — a long master run queues every settlement and floods at the
  * end. Buffer while busy; flush at turn_end (steer) / agent_settled (followUp).
  */
-import { collapseNotices } from './notice-buffer.ts';
+import { NOTICE_MAX_SHOWN, collapseNotices } from './notice-buffer.ts';
 
 export type NoticeSendMode = 'steer' | 'followUp';
 
@@ -19,6 +19,12 @@ export function createNoticeBuffer(opts: {
   /** True while the agent is in a turn, or after an abort that must not wake a new run. */
   isBusy: () => boolean;
   send: (content: string, mode: NoticeSendMode) => Promise<void>;
+  /**
+   * P0-2 (RFC docs/rfc-jev-integration.md §3): relevance reorder of a collapsed
+   * batch before truncation. Only consulted above the show cap; returning null
+   * (or omitting the hook) keeps arrival order. Implementations must not throw.
+   */
+  rank?: (contents: readonly string[]) => Promise<readonly string[] | null>;
 }): NoticeBuffer {
   const pending: string[] = [];
   const pendingPaneIds = new Set<string>();
@@ -35,8 +41,13 @@ export function createNoticeBuffer(opts: {
     noticePending: () => pendingPaneIds,
     async flush(mode) {
       if (pending.length === 0) return;
-      const collapsed = collapseNotices(pending.splice(0));
+      const batch = pending.splice(0);
+      let ordered: readonly string[] = batch;
+      if (opts.rank && batch.length > NOTICE_MAX_SHOWN) {
+        ordered = (await opts.rank(batch)) ?? batch;
+      }
       pendingPaneIds.clear();
+      const collapsed = collapseNotices(ordered);
       if (collapsed) await opts.send(collapsed, mode);
     },
   };

package/src/index-pipe.ts

@@ -53,6 +53,11 @@ export async function handlePipeRequest(
       return { type: 'ok', id: req.id };
     case 'reply': {
       s.port.current?.applyReplySession(req.paneId, req.sessionFile);
+      // B8: the claim key is `${paneId}:${requestId}` and the poll loop claims exactly the same shape
+      // (subagent-poll-loop.ts settle path). The two agree because a child echoes the id of the pipe
+      // request it answered (`id: req.id` in index.ts's settle push), and the parent hands that same
+      // id to startPoller (`prompt-<taskId>` / `fu-<ts>` in core/subagent.ts). Keep both sides in step:
+      // a mismatch here surfaces as two "finished" notices for one settlement.
       if (s.claimSettleNotice(`${req.paneId}:${req.id}`)) {
         const notes = s.port.current?.reconcileOnReply(req.paneId) ?? [];
         const statLine = await s.port.current?.settleStatLine(req.paneId) ?? null;