pi-pier 0.2.7 → 0.3.1

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;

package/src/index-gates.ts

@@ -0,0 +1,124 @@
+/**
+ * Human-gate reporting: coalesces every blocking prompt (pier's ask tool, pi's own ctx.ui dialogs,
+ * external herdr:blocked producers) into ONE blocked edge.
+ *
+ * Depth semantics: only the 0→1 transition reports blocked (and marks the ask flag); only the 1→0
+ * transition restores working/idle. While the depth is positive, working/idle reports are dropped
+ * so the pane stays blocked for the whole dialog. */
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { HerdrClientLike } from './herdr-client.ts';
+
+/** pi surface pieces the gate runtime touches (ui_prompt events postdate the pinned devDependency). */
+type GatePi = ExtensionAPI & {
+  on?: (name: 'ui_prompt_start' | 'ui_prompt_end', handler: (event: unknown) => void) => void;
+};
+
+/** Only inherently human-blocking kinds open the gate; `custom` covers resident overlays too (D97). */
+const GATING_PROMPT_KINDS = new Set(['select', 'confirm', 'input', 'editor']);
+
+export interface GateRuntimeDeps {
+  pi: ExtensionAPI;
+  client: HerdrClientLike;
+  /** Collapse the todo widget to one line while a gate is open; restore on release. */
+  rerenderWidget: () => void;
+  /** True while an agent turn is active (drives the state reported on release). */
+  isAgentActive: () => boolean;
+  /** Idle activity text (idle role badge / current todo) reported with the idle state. */
+  idleMessage: () => string | null;
+  /** Working activity text (current todo) reported when a gate releases mid-turn. */
+  workingMessage: () => string | null;
+}
+
+export interface GateRuntime {
+  depth(): number;
+  /** Gate-aware agent-state report (blocked depth swallows working/idle). */
+  report(state: 'working' | 'idle', activity: string | null): void;
+  /** Open one gate; true when this call opened the outer one. */
+  enter(label: string | null): boolean;
+  /** Close one gate; an unmatched release is ignored. True when the outer gate closed. */
+  exit(): boolean;
+  /** enter/exit + publish the herdr:blocked edge for pier's own gates. */
+  publish(active: boolean, label: string | null): void;
+}
+
+export function createGateRuntime(d: GateRuntimeDeps): GateRuntime {
+  const { client } = d;
+  let blockedDepth = 0;
+
+  function report(state: 'working' | 'idle', activity: string | null): void {
+    if (!client.available || blockedDepth > 0) return;
+    const message = activity ?? (state === 'idle' ? d.idleMessage() : null);
+    client.reportAgent(state, message).catch(() => {});
+  }
+
+  function enter(label: string | null): boolean {
+    blockedDepth += 1;
+    if (blockedDepth > 1) return false;
+    if (client.available) client.reportAgent('blocked', label).catch(() => {});
+    // D95: human-gate marker lets the workbench heatmap distinguish ask from block.
+    if (label) void client.reportAskFlag(label).catch(() => {});
+    d.rerenderWidget();
+    return true;
+  }
+
+  function exit(): boolean {
+    if (blockedDepth === 0) return false;
+    blockedDepth -= 1;
+    d.rerenderWidget();
+    if (blockedDepth > 0) return false;
+    report(d.isAgentActive() ? 'working' : 'idle', d.isAgentActive() ? d.workingMessage() : null);
+    void client.reportAskFlag(null).catch(() => {});
+    return true;
+  }
+
+  // emit() is synchronous; this flag stops our own listener from double-counting depth.
+  let publishing = false;
+  function emitHerdrBlocked(active: boolean, label: string | null): void {
+    publishing = true;
+    try {
+      d.pi.events.emit(
+        'herdr:blocked',
+        active ? { active: true, ...(label ? { label } : {}) } : { active: false },
+      );
+    } finally {
+      publishing = false;
+    }
+  }
+
+  d.pi.events.on('herdr:blocked', (data) => {
+    if (publishing) return;
+    const active = typeof data === 'object' && data !== null && 'active' in data && data.active === true;
+    if (active) {
+      enter(typeof data === 'object' && 'label' in data && typeof data.label === 'string' ? data.label : null);
+    } else {
+      exit();
+    }
+  });
+
+  const gatePi = d.pi as GatePi;
+  gatePi.on?.('ui_prompt_start', (event) => {
+    const rec = (event ?? {}) as { kind?: unknown; title?: unknown };
+    const title = typeof rec.title === 'string' && rec.title.trim() ? rec.title.trim() : null;
+    const kind = typeof rec.kind === 'string' ? rec.kind : 'prompt';
+    if (!GATING_PROMPT_KINDS.has(kind)) return;
+    const label = title ?? kind;
+    // The ask tool opens its own gate first, so this is usually a nested no-op;
+    // prompts from other extensions or pi core open the gate here.
+    if (enter(label)) emitHerdrBlocked(true, label);
+  });
+  gatePi.on?.('ui_prompt_end', () => {
+    if (exit()) emitHerdrBlocked(false, null);
+  });
+
+  return {
+    depth: () => blockedDepth,
+    report,
+    enter,
+    exit,
+    publish(active: boolean, label: string | null): void {
+      if (active) enter(label);
+      else exit();
+      emitHerdrBlocked(active, label);
+    },
+  };
+}

package/src/index-locks.ts

@@ -1,10 +1,5 @@
-/**
- * M18 file write-lock installer (soft veto / hard block).
- *
- * Why: lock acquire/release/command lived in the composition root next to
- * unrelated session wiring. The installer owns the three pi hooks and the
- * held-lock set; fail-open on agent.list remains the collaboration policy.
- */
+/** M18 file write-lock installer (soft veto / hard block): owns the three pi hooks and the
+ *  held-lock set; fail-open on agent.list is the collaboration policy. */
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import {
   acquireTokensFor,
@@ -16,6 +11,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 +22,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 +40,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 +70,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 +113,6 @@ export function installWriteLocks(
       ui?.notify?.(lines.join('\n'), 'info');
     },
   });
+
+  return { getHeldLocks: () => [...heldLocks] };
 }

package/src/index-master.ts

@@ -1,22 +1,21 @@
-/**
- * Master-process plugin mount (cordis loader + terminal/todo/subagent).
- *
- * Why: worker must never load bootstrap/subagent-scope (C3). This module is
- * dynamically imported only from the master branch of index.ts.
- */
+/** Master-process plugin mount (cordis loader + terminal/todo/subagent), dynamically imported from
+ *  the master branch of index.ts only: a worker must never load bootstrap/subagent-poller (C3). */
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import type { Context } from '@deepseek-ai/cordis';
 import type { Server } from 'node:net';
 import { PiSurface } from './pi-surface.ts';
 import { createCordisApp } from './bootstrap.ts';
-import { disposeSessionRoot } from './subagent-scope.ts';
-import terminalPlugin from './core/terminal.ts';
-import todoPlugin from './core/todo.ts';
-import subagentPlugin from './core/subagent.ts';
+import { disposeSessionRoot } from './subagent-poller.ts';
+import terminalPlugin from './plugins/terminal.ts';
+import todoPlugin from './plugins/todo.ts';
+import subagentPlugin from './plugins/subagent.ts';
 import type { HerdrClientLike, HerdrEnv } from './herdr-client.ts';
+import type { JevRuntime } from './jev-client.ts';
+import type { RoutingTelemetryRecord } from './routing-telemetry.ts';
 import type { TodosService } from './todos-service.ts';
-import type { TodoUiSlot } from './core/todo.ts';
-import type { SubagentPortBox } from './subagent-port.ts';
+import type { TodoUiSlot } from './plugins/todo.ts';
+import type { SubagentPortBox } from './subagent-core.ts';
+import type { SubagentDeps } from './plugins/subagent.ts';
 
 export interface MasterPluginMount {
   pi: ExtensionAPI;
@@ -35,6 +34,12 @@ 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;
+  /** Optional jev seam for subagent settle attribution (fail-open when absent). */
+  jev?: { ask: JevRuntime['ask']; getMinConfidence: () => number };
+  /** Phase 0 routing telemetry append (RFC rfc-jev-role-routing §8); absent in tests. */
+  appendRoutingLog?: (row: RoutingTelemetryRecord) => void;
 }
 
 async function loadEntry(
@@ -60,8 +65,7 @@ export async function mountMasterPlugins(m: MasterPluginMount): Promise<void> {
   // strip-types) and misses pi's typebox alias. HMR-only; production uses plugin().
   const useLoader = cordisApp.loaderReady && cordisApp.hmrActive;
 
-  // Pipe server is created in the common segment; closing it from a core
-  // plugin would kill it on hmr reload (d87).
+  // Pipe server is created in the common segment; closing it from a core plugin would kill it on hmr reload (d87).
   sessionRoot.effect(() => () => {
     if (m.pipeServerBox.current) {
       try { m.pipeServerBox.current.close(); } catch { /* already closed */ }
@@ -78,7 +82,7 @@ export async function mountMasterPlugins(m: MasterPluginMount): Promise<void> {
   };
   sessionRoot.provide('pi-herdr.terminal-deps', terminalDeps);
 
-  await loadEntry(sessionRoot, useLoader, './core/terminal.ts', terminalPlugin);
+  await loadEntry(sessionRoot, useLoader, './plugins/terminal.ts', terminalPlugin);
 
   sessionRoot.provide('pi-herdr.todo-deps', {
     todos: m.todos,
@@ -86,17 +90,21 @@ export async function mountMasterPlugins(m: MasterPluginMount): Promise<void> {
     maxItems: 15,
     mirrorTodos: m.mirrorTodos,
     appendEntry: (customType: string, data: unknown) => {
-      (m.pi as { appendEntry?: (t: string, d: unknown) => void }).appendEntry?.(customType, d);
+      (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);
+  await loadEntry(sessionRoot, useLoader, './plugins/todo.ts', todoPlugin);
 
+  // D98 regression guard: `satisfies` makes tsc reject a missing/mistyped key here — the bag is
+  // consumed untyped by plugins/subagent.ts, and the fe99252 crash was exactly a dropped key.
   sessionRoot.provide('pi-herdr.subagent-deps', {
     client: m.client,
     env: m.env,
@@ -110,8 +118,10 @@ export async function mountMasterPlugins(m: MasterPluginMount): Promise<void> {
     withReconcileNotes: m.withReconcileNotes,
     claimSettleNotice: m.claimSettleNotice,
     terminalState: terminalDeps.state,
-  });
-  await loadEntry(sessionRoot, useLoader, './core/subagent.ts', subagentPlugin);
+    ...(m.jev ? { jev: m.jev } : {}),
+    ...(m.appendRoutingLog ? { logRouting: m.appendRoutingLog } : {}),
+  } satisfies SubagentDeps);
+  await loadEntry(sessionRoot, useLoader, './plugins/subagent.ts', subagentPlugin);
 
   m.pi.on('session_shutdown', () => {
     void disposeSessionRoot(sessionRoot);

package/src/index-notices.ts

@@ -1,14 +1,23 @@
 /**
- * D92 settlement-notice buffer (busy-run collapse).
- *
- * Why: `sendUserMessage(followUp)` only delivers when the agent has no more
- * 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';
+ * D92 settlement-notice buffer: `sendUserMessage(followUp)` only delivers when the agent has no
+ * more tool calls, so a long master run would queue every settlement and flood at the end. Buffer
+ * while busy; flush at turn_end (steer) / agent_settled (followUp), collapsing large batches. */
 
 export type NoticeSendMode = 'steer' | 'followUp';
 
+export const NOTICE_MAX_SHOWN = 3;
+
+/** Collapse a batch into one message body: empty → null; above the cap, the first max originals plus
+ *  a tail pointing at history / subagent list. A single-item batch stays byte-identical to the
+ *  direct-send format. */
+export function collapseNotices(contents: readonly string[], max = NOTICE_MAX_SHOWN): string | null {
+  if (contents.length === 0) return null;
+  if (contents.length <= max) return contents.join('\n\n');
+  const hidden = contents.length - max;
+  const tail = `…另有 ${hidden} 条结算未逐条展示。全量结果看 history 台账（路径公式见 subagent resume 工具描述）；在跑代理用 subagent list 查看。`;
+  return [...contents.slice(0, max), tail].join('\n\n');
+}
+
 export interface NoticeBuffer {
   deliverNotice(content: string, paneId?: string): Promise<void>;
   noticePending(): ReadonlySet<string>;
@@ -19,14 +28,19 @@ 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 pending: Array<{ content: string; paneId?: string }> = [];
   const pendingPaneIds = new Set<string>();
   return {
     async deliverNotice(content, paneId) {
       if (content !== '' && paneId !== undefined) pendingPaneIds.add(paneId);
       if (opts.isBusy()) {
-        pending.push(content);
+        pending.push({ content, paneId });
         return;
       }
       await opts.send(content, 'followUp');
@@ -35,8 +49,18 @@ export function createNoticeBuffer(opts: {
     noticePending: () => pendingPaneIds,
     async flush(mode) {
       if (pending.length === 0) return;
-      const collapsed = collapseNotices(pending.splice(0));
-      pendingPaneIds.clear();
+      const flushed = pending.splice(0);
+      const batch = flushed.map((n) => n.content);
+      let ordered: readonly string[] = batch;
+      if (opts.rank && batch.length > NOTICE_MAX_SHOWN) {
+        ordered = (await opts.rank(batch)) ?? batch;
+      }
+      // Release only this batch's panes: a notice buffered during the rank await is still undelivered,
+      // and GC must keep its pane until it is.
+      for (const { paneId } of flushed) {
+        if (paneId !== undefined && !pending.some((n) => n.paneId === paneId)) pendingPaneIds.delete(paneId);
+      }
+      const collapsed = collapseNotices(ordered);
       if (collapsed) await opts.send(collapsed, mode);
     },
   };

package/src/index-pipe.ts

@@ -1,12 +1,7 @@
-/**
- * Common-segment pipe request handler (prompt / interrupt / reply).
- *
- * Why: index.ts owned the NDJSON switch next to session lifecycle. The
- * dispatch is a pure-ish adapter over the subagent port and notice buffer.
- */
+/** Common-segment pipe request handler (prompt / interrupt / reply) over the subagent port and notice buffer. */
 import { formatSettlementNotice } from './vocab.ts';
 import type { PipeRequest, PipeResponse } from './pipe-channel.ts';
-import type { SubagentPortBox } from './subagent-port.ts';
+import type { SubagentPortBox } from './subagent-core.ts';
 
 export interface MachineRequest {
   id: string;
@@ -24,6 +19,8 @@ export interface PipeHandlerSession {
   sendUserMessageAs: (content: string, mode: 'steer' | 'followUp') => Promise<void>;
   abort: () => void;
   setPendingMachineRequest: (req: MachineRequest | null) => void;
+  /** P0 (RFC §4.4): apply a role switch requested over the pipe (master → worker). */
+  applyRoleSwitch: (role: string, switchedBy: string) => Promise<{ ok: boolean; message: string }>;
 }
 
 export async function handlePipeRequest(
@@ -51,8 +48,21 @@ export async function handlePipeRequest(
       s.abort();
       s.setPendingMachineRequest(null);
       return { type: 'ok', id: req.id };
+    case 'role': {
+      const res = await s.applyRoleSwitch(req.role, s.paneId || 'pipe');
+      return res.ok
+        ? { type: 'ok', id: req.id, detail: res.message }
+        : { type: 'error', id: req.id, message: res.message };
+    }
     case 'reply': {
       s.port.current?.applyReplySession(req.paneId, req.sessionFile);
+      // Consume before the finish notice: otherwise listRunningSubs still reports the pane and the
+      // next master settle injects "still running" for an agent just announced finished.
+      s.port.current?.consumeReply(req.paneId, req.text);
+      // B8: the claim key `${paneId}:${requestId}` must match the poll loop's (subagent-poller.ts):
+      // 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>`).
+      // A mismatch 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;