pi-pier 0.4.1 → 0.4.3

package/src/plugins/observation.ts

@@ -11,7 +11,7 @@ import type {
 } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
 import { containsReducerReceipt, countLines, deriveObservationId, estimateTokens, formatObservationPlaceholder, isObservationId, sha256Hex, shouldPackForCache } from '../observation-core.ts';
-import { appendEfficiencyLog, efficiencyLogPath, observationObjectPath, readStoredObjectChunk, resolveSessionRoot, storeContentAddressedObject } from '../efficiency-store.ts';
+import { appendEfficiencyLog, efficiencyLogPath, observationObjectExists, observationObjectPath, readStoredObjectChunk, resolveSessionRoot, storeContentAddressedObject } from '../efficiency-store.ts';
 import { resolveEfficiencyConfig, type EfficiencyConfig, type ObservationPackConfig } from '../efficiency-config-core.ts';
 import { resolveCacheRatioFromCost } from '../compact-economics-core.ts';
 import { planToolGate, type RuntimeRoleManifest } from '../tool-gate.ts';
@@ -51,14 +51,13 @@ function buildPlaceholder(
   toolCallId: string,
   text: string,
   textBytes: number,
+  contentHash: string,
   obsConfig: ObservationPackConfig,
   middle?: ExcerptMiddlePick,
-): { id: string; placeholder: string; contentHash: string } {
-  const contentHash = sha256Hex(text);
+): { id: string; placeholder: string } {
   const id = deriveObservationId(toolName, toolCallId, contentHash);
   return {
     id,
-    contentHash,
     placeholder: formatObservationPlaceholder({
       id,
       toolName,
@@ -77,6 +76,20 @@ function memoKeyFor(sessionRoot: string, toolCallId: string, charLength: number)
   return `${sessionRoot}:${toolCallId}:${charLength}`;
 }
 
+function rememberPlaceholder(
+  sessionRoot: string,
+  toolCallId: string,
+  charLength: number,
+  placeholder: string,
+  obsId: string,
+): void {
+  if (placeholderMemo.size >= MAX_MEMO_ENTRIES) {
+    const oldest = placeholderMemo.keys().next().value;
+    if (oldest) placeholderMemo.delete(oldest);
+  }
+  placeholderMemo.set(memoKeyFor(sessionRoot, toolCallId, charLength), { placeholder, obsId });
+}
+
 /** Append one observation.jsonl record; telemetry is always best-effort. */
 async function logObservation(sessionRoot: string, fields: Record<string, unknown>): Promise<void> {
   try {
@@ -100,8 +113,12 @@ interface ExcerptMiddlePick {
   label: string;
 }
 
-/** P0-3 seam: async middle-window picker (jev-backed); null keeps the legacy head+tail halves. */
-export type PickMiddleExcerpt = (text: string, excerptBudgetBytes: number) => Promise<ExcerptMiddlePick | null>;
+/** P0-3 seam: batched middle-window picker (jev-backed), one result per item in order; null keeps
+ *  the legacy head+tail halves. A whole compaction batch is one call. */
+export type PickMiddleExcerpts = (
+  items: ReadonlyArray<{ obsId: string; text: string }>,
+  excerptBudgetBytes: number,
+) => Promise<ReadonlyArray<ExcerptMiddlePick | null>>;
 
 /** Build the OCC `onBeforeCompact` hook: role-gated, config-gated batch packing of the branch's
  * large tool results before `ctx.compact()` rewrites the prefix. Exported so the gate behaviour is
@@ -110,7 +127,7 @@ export function createCompactionBatchPackHook(deps: {
   getObsConfig: () => ObservationPackConfig;
   getManifest?: () => RuntimeRoleManifest | null;
   getSessionId?: () => string | undefined;
-  pickMiddleExcerpt?: PickMiddleExcerpt;
+  pickMiddleExcerpts?: PickMiddleExcerpts;
 }): (sessionRoot: string, ctx: unknown) => Promise<void> {
   return async (sessionRoot: string, ctx: unknown): Promise<void> => {
     const obsConfig = deps.getObsConfig();
@@ -133,7 +150,7 @@ export function createCompactionBatchPackHook(deps: {
       sessionId: deps.getSessionId?.(),
       messages,
       obsConfig,
-      pickMiddleExcerpt: deps.pickMiddleExcerpt,
+      pickMiddleExcerpts: deps.pickMiddleExcerpts,
     });
   };
 }
@@ -147,20 +164,22 @@ async function packOneMessage(opts: {
   text: string;
   textBytes: number;
   charLength: number;
+  contentHash: string;
+  obsId: string;
   obsConfig: ObservationPackConfig;
   /** `extra` carries audit fields such as `source: 'compaction'`, `sendCount`, `tailTokensAfter`. */
   log?: { logEnabled: boolean; event: 'packed' | 'packed-batch'; sessionId?: string; extra?: Record<string, unknown> };
-  pickMiddleExcerpt?: PickMiddleExcerpt;
-  /** Prefetched middle excerpt (the batch path runs picks concurrently); null/undefined = none. */
+  pickMiddleExcerpts?: PickMiddleExcerpts;
+  /** Prefetched middle excerpt (the batch path picks for all items in one call); null/undefined = none. */
   middle?: ExcerptMiddlePick | null;
 }): Promise<string | null> {
-  const { sessionRoot, toolName, toolCallId, text, textBytes, charLength, obsConfig, log, pickMiddleExcerpt } = opts;
+  const { sessionRoot, toolName, toolCallId, text, textBytes, charLength, contentHash, obsConfig, log, pickMiddleExcerpts } = opts;
   const middle = opts.middle !== undefined
     ? (opts.middle ?? undefined)
-    : pickMiddleExcerpt
-      ? (await pickMiddleExcerpt(text, obsConfig.excerptBytes)) ?? undefined
+    : pickMiddleExcerpts
+      ? (await pickMiddleExcerpts([{ obsId: opts.obsId, text }], obsConfig.excerptBytes))[0] ?? undefined
       : undefined;
-  const { id: obsId, placeholder, contentHash } = buildPlaceholder(toolName, toolCallId, text, textBytes, obsConfig, middle);
+  const { id: obsId, placeholder } = buildPlaceholder(toolName, toolCallId, text, textBytes, contentHash, obsConfig, middle);
   const originalTokens = estimateTokens(text);
   const placeholderTokens = estimateTokens(placeholder);
 
@@ -174,11 +193,7 @@ async function packOneMessage(opts: {
     return null;
   }
 
-  if (placeholderMemo.size >= MAX_MEMO_ENTRIES) {
-    const oldest = placeholderMemo.keys().next().value;
-    if (oldest) placeholderMemo.delete(oldest);
-  }
-  placeholderMemo.set(memoKeyFor(sessionRoot, toolCallId, charLength), { placeholder, obsId });
+  rememberPlaceholder(sessionRoot, toolCallId, charLength, placeholder, obsId);
 
   if (log?.logEnabled && !loggedPackedObsIds.has(obsId)) {
     loggedPackedObsIds.add(obsId);
@@ -198,20 +213,65 @@ async function packOneMessage(opts: {
   return placeholder;
 }
 
-/** One packable message: a non-error tool result with text-only content that is not yet packed. */
-interface PackCandidate { toolName: string; toolCallId: string; text: string; textBytes: number; charLength: number }
+/** One packable message: a non-error, text-only tool result over the size threshold. */
+interface PackCandidate {
+  toolName: string;
+  toolCallId: string;
+  text: string;
+  textBytes: number;
+  charLength: number;
+  contentHash: string;
+  obsId: string;
+}
 
-function packCandidateAt(messages: readonly unknown[], index: number, sessionRoot: string): PackCandidate | null {
+function packCandidateAt(
+  messages: readonly unknown[],
+  index: number,
+  sessionRoot: string,
+  minBytes: number,
+): PackCandidate | null {
   const msg = messages[index] as ContextMessage | undefined;
   const content = toolResultContent(msg);
   if (!content) return null;
   const { texts, charLength } = content;
   const text = texts.join('\n');
+  const textBytes = Buffer.byteLength(text, 'utf8');
+  if (textBytes < minBytes) return null;
   const toolName = typeof msg?.toolName === 'string' ? msg.toolName : 'tool';
   const toolCallId = typeof msg?.toolCallId === 'string' ? msg.toolCallId : `call_${index}`;
   if (placeholderMemo.has(memoKeyFor(sessionRoot, toolCallId, charLength))) return null;
   if (containsReducerReceipt(text)) return null;
-  return { toolName, toolCallId, text, textBytes: Buffer.byteLength(text, 'utf8'), charLength };
+  const contentHash = sha256Hex(text);
+  return {
+    toolName,
+    toolCallId,
+    text,
+    textBytes,
+    charLength,
+    contentHash,
+    obsId: deriveObservationId(toolName, toolCallId, contentHash),
+  };
+}
+
+/** A resumed process starts with an empty memo, but the content-addressed object is still on disk.
+ *  Rebuild the deterministic placeholder from it instead of asking jev again, rewriting the object,
+ *  and logging the same saving twice. Returns null when the object is not (verifiably) there. */
+async function reusePackedObservation(
+  candidate: PackCandidate,
+  sessionRoot: string,
+  obsConfig: ObservationPackConfig,
+): Promise<string | null> {
+  if (!(await observationObjectExists(sessionRoot, candidate.obsId, candidate.textBytes))) return null;
+  const { placeholder } = buildPlaceholder(
+    candidate.toolName,
+    candidate.toolCallId,
+    candidate.text,
+    candidate.textBytes,
+    candidate.contentHash,
+    obsConfig,
+  );
+  rememberPlaceholder(sessionRoot, candidate.toolCallId, candidate.charLength, placeholder, candidate.obsId);
+  return placeholder;
 }
 
 export async function batchPackObservations(opts: {
@@ -220,7 +280,7 @@ export async function batchPackObservations(opts: {
   messages: readonly unknown[];
   obsConfig: ObservationPackConfig;
   limits?: { maxItems?: number; maxBytes?: number };
-  pickMiddleExcerpt?: PickMiddleExcerpt;
+  pickMiddleExcerpts?: PickMiddleExcerpts;
 }): Promise<number> {
   const { sessionRoot, sessionId, messages, obsConfig } = opts;
   if (!obsConfig.enabled || !sessionRoot || !Array.isArray(messages)) return 0;
@@ -228,24 +288,25 @@ export async function batchPackObservations(opts: {
   const maxItems = opts.limits?.maxItems ?? MAX_BATCH_PACK_ITEMS;
   const maxBytes = opts.limits?.maxBytes ?? MAX_BATCH_PACK_BYTES;
 
-  // Pass 1 — select with the deterministic checks (memo, receipt, size, soft byte cap). Selection is
-  // optimistic on bytes: a later store failure can only pack fewer items, never more than the caps.
+  // Pass 1 — select with the deterministic checks (memo, receipt, size, existing store object, soft
+  // byte cap). A reused object is memoized here, so no jev ask, write, or telemetry follows for it.
   const candidates: PackCandidate[] = [];
   let selectedBytes = 0;
   for (let i = 0; i < messages.length && candidates.length < maxItems; i++) {
-    const candidate = packCandidateAt(messages, i, sessionRoot);
-    if (!candidate || candidate.textBytes < obsConfig.thresholdBytes) continue;
+    const candidate = packCandidateAt(messages, i, sessionRoot, obsConfig.thresholdBytes);
+    if (!candidate) continue;
+    if (await reusePackedObservation(candidate, sessionRoot, obsConfig)) continue;
     if (selectedBytes + candidate.textBytes > maxBytes && candidates.length > 0) break;
     selectedBytes += candidate.textBytes;
     candidates.push(candidate);
   }
   if (candidates.length === 0) return 0;
 
-  // Pass 2 — prefetch middle excerpts concurrently: every packed output asks jev, so a serial loop
-  // would block onBeforeCompact for maxItems × (0.25–0.77s) per compaction.
-  const picker = opts.pickMiddleExcerpt;
+  // Pass 2 — one batched pick for every selected output: per-item asks were a 6-20-way burst that
+  // all failed together when jev was down.
+  const picker = opts.pickMiddleExcerpts;
   const middles = picker
-    ? await Promise.all(candidates.map((c) => picker(c.text, obsConfig.excerptBytes)))
+    ? await picker(candidates.map((c) => ({ obsId: c.obsId, text: c.text })), obsConfig.excerptBytes)
     : [];
 
   let packedCount = 0;
@@ -274,7 +335,11 @@ async function runRecall(
     return toolError(`invalid observation id format: "${String(rawId)}"`);
   }
   const id = rawId;
-  const offset = typeof params?.offset === 'number' ? params.offset : 0;
+  const rawOffset = params?.offset;
+  if (rawOffset !== undefined && (typeof rawOffset !== 'number' || !Number.isInteger(rawOffset) || rawOffset < 0)) {
+    return toolError(`invalid observation offset: "${String(rawOffset)}"`);
+  }
+  const offset = rawOffset ?? 0;
 
   const sessionDir = ctx?.sessionManager?.getSessionDir?.();
   const sessionId = ctx?.sessionManager?.getSessionId?.();
@@ -288,9 +353,12 @@ async function runRecall(
       maxBytes: effConfig.observationPack.recallChunkBytes ?? RECALL_MAX_BYTES,
       maxLines: RECALL_MAX_LINES,
     });
+    // Mid-line offsets are advanced to the next line start by the reader; the header and telemetry
+    // report the offset the returned chunk actually starts at.
+    const alignedOffset = chunk.offset;
 
     const header = [
-      `[obs_recall id=${id} offset=${offset} next_offset=${chunk.nextOffset} eof=${chunk.eof}]`,
+      `[obs_recall id=${id} offset=${alignedOffset} next_offset=${chunk.nextOffset} eof=${chunk.eof}]`,
       `[chunk_bytes=${chunk.bytes} chunk_lines=${chunk.lines}; use next_offset to continue]`,
     ].join('\n');
 
@@ -299,7 +367,7 @@ async function runRecall(
         event: 'recall',
         sessionId: sessionId ?? 'unknown',
         obsId: id,
-        offset,
+        offset: alignedOffset,
         chunkBytes: chunk.bytes,
         lines: chunk.lines,
         nextOffset: chunk.nextOffset,
@@ -312,7 +380,7 @@ async function runRecall(
       content: [{ type: 'text', text: `${header}\n${chunk.text}` }],
       details: {
         id,
-        offset,
+        offset: alignedOffset,
         bytes: chunk.bytes,
         lines: chunk.lines,
         nextOffset: chunk.nextOffset,
@@ -341,7 +409,7 @@ interface ObservationPackDeps {
   getConfig?: (ctx: ExtensionContext) => EfficiencyConfig;
   getRuntimeManifest?: () => RuntimeRoleManifest | null;
   getRemainingHorizon?: () => number;
-  pickMiddleExcerpt?: PickMiddleExcerpt;
+  pickMiddleExcerpts?: PickMiddleExcerpts;
 }
 
 async function projectPlaceholders(
@@ -395,8 +463,16 @@ async function projectPlaceholders(
     const sendCount = priorAssistantCounts[i] ?? 0;
     if (sendCount < obsConfig.fullSends) continue;
 
-    const candidate = packCandidateAt(projected, i, sessionRoot);
-    if (!candidate || candidate.textBytes < obsConfig.thresholdBytes) continue;
+    const candidate = packCandidateAt(projected, i, sessionRoot, obsConfig.thresholdBytes);
+    if (!candidate) continue;
+
+    // Resume: the object survived the restart even though the memo did not. Project the same
+    // deterministic placeholder without re-asking jev or re-logging the saving.
+    const reused = await reusePackedObservation(candidate, sessionRoot, obsConfig);
+    if (reused) {
+      projected[i] = { ...msg, content: [{ type: 'text', text: reused }] };
+      continue;
+    }
 
     let tailTokensAfter = 0;
     for (let j = i + 1; j < len; j++) {
@@ -410,7 +486,7 @@ async function projectPlaceholders(
     // Projected saving of the legacy placeholder drives the economic decision; packOneMessage
     // recomputes the same placeholder when the answer is yes.
     const originalTokens = estimateTokens(candidate.text);
-    const estimate = buildPlaceholder(candidate.toolName, candidate.toolCallId, candidate.text, candidate.textBytes, obsConfig);
+    const estimate = buildPlaceholder(candidate.toolName, candidate.toolCallId, candidate.text, candidate.textBytes, candidate.contentHash, obsConfig);
     const removedTokens = Math.max(0, originalTokens - estimateTokens(estimate.placeholder));
     // Same resolution as OCC (provider family / token-account fallback): passing a raw 'auto' would
     // let shouldPackForCache fall back on its own hardcoded ratio and diverge from compaction.
@@ -437,7 +513,7 @@ async function projectPlaceholders(
         sessionId,
         extra: { sendCount, tailTokensAfter },
       },
-      pickMiddleExcerpt: deps.pickMiddleExcerpt,
+      pickMiddleExcerpts: deps.pickMiddleExcerpts,
     });
     if (!packed) continue;
     projected[i] = { ...msg, content: [{ type: 'text', text: packed }] };
@@ -454,11 +530,7 @@ export function registerObservationPack(deps: ObservationPackDeps & { pi: Extens
     name: RECALL_TOOL_NAME,
     label: 'Recall Observation',
     description:
-      'Recall a paged slice of a previously replaced large tool result by observation id and byte offset.',
-    promptGuidelines: [
-      'Call obs_recall with id and offset to inspect specific parts of large tool outputs.',
-      'Check the returned next_offset and eof to page through long logs.',
-    ],
+      'Recall a paged slice of a previously replaced large tool result by observation id and byte offset; page on with the returned next_offset until eof.',
     parameters: Type.Object({
       id: Type.String({ description: 'Observation ID from placeholder (e.g. obs_...)' }),
       offset: Type.Optional(

package/src/plugins/subagent.ts

@@ -84,24 +84,35 @@ export interface SubagentDeps {
   logRouting?: (row: RoutingTelemetryRecord) => void;
 }
 
+/** Sent with every request: what a call needs. Details live in SUBAGENT_MANUAL (`action: "help"`). */
 const SUBAGENT_DESCRIPTION = [
-  'Delegate a self-contained subtask to an isolated subagent that runs in its own herdr pane as an interactive pi session (separate context window; it does NOT see this conversation). A human can also open that pane and talk to the subagent directly.',
-  '`action` (optional, default "spawn"): spawn | resume | list | send | interrupt | output | role.',
-  '[spawn] `description`: short display label for the pane; `prompt`: the COMPLETE task — include all needed context, since only the prompt reaches the subagent. The description also doubles as the todo-reconcile key: when delegating a todo entry, use the entry content WITHOUT its ` <sub>` marker as the description, and the entry is auto-completed when this subagent settles.',
-  '[spawn] The subagent shares this workspace and works independently; the result is its final text answer.',
-  '[spawn] Concurrent delegation is supported: several spawn calls in one message run in parallel (at most 4 at once). Use this for well-scoped, independent subtasks; do not delegate the current step itself.',
-  '[spawn] `run_in_background` (default false): when true, the call returns immediately with an agentId; the subagent keeps running in its pane. Use action list to see its state, action send to give it follow-up work, action interrupt to stop it. When it settles, you receive a notification message with its closing output.',
-  '[spawn] `tab` (optional): name of a task tab to place the subagent into (join if a tab with this name exists, otherwise create it). Overrides the default placement. Default placement groups by git worktree: a subagent working in your checkout shares your tab; one working in a separate worktree (pass its path via `cwd`; create worktrees with `git worktree add`) gets its own tab named after the worktree directory.',
-  '[spawn] `role` + `allowed_tools`: when role matches a profile (searched: workspace .pi-herdr/roles/ → user-global ~/.pi/agent/herdr-pi/roles/ → builtin), the worker toolset becomes the composed manifest — baseline ∪ allowed_tools minus role-deny tools (deny always wins). Custom roles: drop a JSON profile into .pi-herdr/roles/ (master/worker-default reserved). Unknown role names remain display labels only.',
-  '[spawn] `isolate` (default false): creates a FRESH git worktree for this subagent and runs it there (branch pier/<slug> from your HEAD under ~/.herdr/worktrees/<repo>/). Three-way choice: heavy independent writing in parallel with your own edits or other workers, or work needing its own clean reviewable diff → isolate; read-mostly or sequential helper work → omit (shared checkout, writes guarded by the write-lock); targeting an existing directory/worktree → cwd. In isolate mode the subagent\'s writes cannot conflict with your checkout; its panes group into a tab named after the worktree; its prompt is prefixed with commit discipline (commit to its own branch, NEVER push); when it settles you get a diff summary (commits since base, files changed, uncommitted count). Review with git log/diff HEAD..<branch>, merge with git merge --no-ff <branch>; once merged and clean the worktree auto-removes (branch kept). Mutually exclusive with cwd.',
-  '[resume] `taskId`: revive a finished (collected) subagent from the delegation ledger — opens its saved conversation in a new pane (pi --session), then use action send to give it new work. The ledger is an append-only JSONL file, one row per status change (same taskId rows = generations, latest row is current): fields taskId, description, status (running|settled|consumed|closed), outcome (closing text), paneId, sessionFile, launchCommand, createdAt. Ledgers are per-checkout at ~/.pi/agent/herdr-pi/history/<flattened-cwd>/history.jsonl, but resume searches every checkout this master has spawned into, not only the current cwd. A still-running task is not resumed — use action send or output. Use action list for live panes.',
-  '[list] no extra parameters: list background subagents with live state (running / idle), pane ids, last activity, role, and descriptions. Foreground one-shot panes are not listed.',
-  '[output] `agentId` (required, the subagent pane id): view incremental output of a running or background subagent since the last output call. Text returned to the model is bounded (default 6000 chars) with status metadata (running/idle/blocked/settled), revision, and a truncated flag. When the delta cannot be computed the full text is returned with a "buffer scrolled or reset" note — that is normal for fullscreen TUI panes, not a crash indicator. Use this to observe subagent progress before settlement.',
-  '[interrupt] `agentId`: abort the current turn (fire-and-return). The pane stays; you can send again.',
-  '[role] `agentId` + `role`: switch that worker\'s role profile mid-session (pi 0.86 transcript tool delta — the new toolset applies on its next request and survives resume). Same role resolution as spawn; the reply reports the tool diff. Use when a task outgrew its delegation (needs more tools) or should be narrowed.',
-  '[send] `agentId` + `message`: follow-up to a background subagent. If working, delivered at next tool-call gap (steer, seconds); if idle, wakes a new turn. After settle, send to wake it; do not spawn a duplicate.',
+  'Delegate a self-contained task to a subagent: an isolated pi session in its own herdr pane (separate context — it does NOT see this conversation; a human can talk to it in that pane).',
+  'Actions (default spawn): spawn | send | output | list | interrupt | resume | role | help.',
+  'spawn: `prompt` is the COMPLETE task, since only the prompt reaches it; `description` labels the pane and is the todo-reconcile key — when delegating a todo entry, pass its content without the ` <sub>` marker and the entry auto-completes on settle. Several spawns in one message run in parallel (max 4).',
+  'A foreground spawn BLOCKS this call for up to ~5 minutes; pass run_in_background: true for long tasks. A background (or timed-out foreground) worker\'s settlement notice arrives automatically at your next tool boundary — no need to sleep or poll.',
+  'send: follow-up to a running or settled worker (steered between its tool calls). output: what it printed since your last check, plus its final report once done. resume: revive a collected task by taskId. role: switch a worker\'s role profile mid-session.',
+  'help: the full manual (isolate/cwd/tab placement, role profiles, the delegation ledger).',
 ].join(' ');
 
+/** Returned by `action: "help"`: the reference text that used to ride every request. */
+const SUBAGENT_MANUAL = [
+  'subagent manual',
+  '',
+  'spawn — the subagent shares this workspace and works independently; its result is its final text answer. Do not delegate the current step itself. Placement: by default panes group by git worktree — a subagent in your checkout shares your tab, one in a separate worktree gets its own tab named after the worktree directory. `tab` joins or creates a named task tab instead. `cwd` targets an existing directory or worktree (create worktrees with git worktree add).',
+  '',
+  'isolate (default false) — creates a FRESH git worktree (branch pier/<slug> from your HEAD under ~/.herdr/worktrees/<repo>/). Choose it for heavy independent writing in parallel with your own edits or other workers, or work needing its own clean reviewable diff; omit it for read-mostly or sequential helper work (shared checkout, writes guarded by the write-lock); use cwd for an existing directory/worktree. Its writes cannot conflict with your checkout, its prompt is prefixed with commit discipline (commit to its own branch, never push), and on settle you get a diff summary (commits since base, files changed, uncommitted count). Review with git log/diff HEAD..<branch>, merge with git merge --no-ff <branch>; once merged and clean the worktree auto-removes (branch kept). Mutually exclusive with cwd.',
+  '',
+  'role + allowed_tools — when role matches a profile (searched: workspace .pi-herdr/roles/ → user-global ~/.pi/agent/herdr-pi/roles/ → builtin), the worker toolset becomes baseline ∪ allowed_tools minus role-deny tools (deny always wins). Custom roles: drop a JSON profile into .pi-herdr/roles/ (master/worker-default reserved). Unknown role names stay display labels. action role switches a live worker (pi transcript tool delta: applies on its next request, survives resume); the reply reports the tool diff.',
+  '',
+  'list — background subagents with live state (running / idle), pane ids, last activity, role and description; foreground one-shot panes are not listed.',
+  '',
+  'output — `agentId` required; returns the delta since your last output call (default 6000 chars, max_chars 100-16000) with status (running/idle/blocked/settled), revision and a truncated flag. TUI chrome is stripped; once the worker has finished, the complete transcript report is attached. A "buffer scrolled or reset" note means the full text was returned — normal for fullscreen TUI panes.',
+  '',
+  'send — `agentId` + `message`: if working, delivered at its next tool-call gap (seconds); if idle or settled, wakes a new turn. Do not spawn a duplicate for the same task. interrupt — aborts its current turn; the pane stays and you can send again.',
+  '',
+  'resume — `taskId`: revives a collected subagent from the delegation ledger in a new pane (pi --session); then use send. The ledger is append-only JSONL, one row per status change (taskId, description, status running|settled|consumed|closed, outcome, paneId, sessionFile, launchCommand, createdAt), per checkout at ~/.pi/agent/herdr-pi/history/<flattened-cwd>/history.jsonl; resume searches every checkout this master spawned into. A still-running task is not resumed — use send or output.',
+].join('\n');
+
 const SUBAGENT_CONCURRENCY = 4;
 
 function defaultAgentSessionsDir(): string {
@@ -224,8 +235,8 @@ export default function subagentPlugin(ctx: Context): void {
     if (port.current === boundPort) port.current = null;
   }, 'subagent-port');
 
-  const injectNotice = (content: string): Promise<void> => {
-    if (d.deliverNotice) return d.deliverNotice(content);
+  const injectNotice = (content: string, paneId?: string): Promise<void> => {
+    if (d.deliverNotice) return d.deliverNotice(content, paneId);
     pi.sendUserMessage?.(content, { deliverAs: 'followUp' });
     return Promise.resolve();
   };
@@ -353,7 +364,7 @@ export default function subagentPlugin(ctx: Context): void {
         [DELEGATION_ENV]: JSON.stringify({
           parentPaneId: env?.paneId ?? '',
           parentSessionId: bareSessionId(d.getSessionId()),
-          // Phase 2: report_progress needs the master's pipe; kind 'task' maps to the composed default.
+          // todo_sync needs the master's pipe; kind 'task' maps to the composed default.
           parentPipe: pipeNameFor(process.cwd(), env?.paneId ?? ''),
           taskId: entry.taskId,
           description: entry.description,
@@ -638,7 +649,9 @@ export default function subagentPlugin(ctx: Context): void {
     const lines: string[] = [];
     for (const sub of byTask.values()) {
       const tabTag = sub.tabName ? ` [tab: ${sub.tabName}]` : '';
-      const wtTag = sub.isolate ? ` [wt: ${sub.isolate.branch}]` : '';
+      // The branch (`pier/<slug>`) is not a directory; printing it made masters cd into
+      // `<repo>/pier/<slug>`. Always print the absolute worktree path they can actually enter.
+      const wtTag = sub.isolate ? ` [wt: ${sub.isolate.worktreePath}]` : '';
       if (sub.status === 'closed') {
         lines.push(`${sub.taskId.slice(0, 8)} [idle] (${sub.kind}, closed; action send revives)${tabTag}${wtTag} ${sub.description}`);
         continue;
@@ -692,6 +705,7 @@ export default function subagentPlugin(ctx: Context): void {
     // carry the final report. No preferred file — start from herdr's per-pane report, not a stale registry value.
     readFinalReport: async (paneId: string, entryCwd: string) =>
       (await session.subSessionState(paneId, entryCwd, 0)).text,
+    persistSubs,
   };
 
   const ACTIONS: Record<string, (params: ToolParams, toolCtx: unknown, onUpdate?: (u: unknown) => void) => Promise<unknown>> = {
@@ -702,6 +716,7 @@ export default function subagentPlugin(ctx: Context): void {
     interrupt: (params, toolCtx) => executeSubagentInterrupt(params, toolCtx),
     output: (params, toolCtx) => executeSubagentOutput(params, toolCtx, outputActionDeps),
     role: (params, toolCtx) => executeSubagentRole(params, toolCtx),
+    help: async () => ({ content: [{ type: 'text', text: SUBAGENT_MANUAL }], details: {} }),
   };
 
   scoped.registerTool({
@@ -709,15 +724,12 @@ export default function subagentPlugin(ctx: Context): void {
     label: 'Subagent',
     // B4: the model picks tools from the system prompt's snippet/guideline surface; delegation
     // decisions are made here, so state them rather than hoping for recall.
-    promptSnippet: 'subagent: delegate a self-contained task to a pi worker pane (spawn/isolate/background/send/output/interrupt/resume/list/role).',
+    promptSnippet: 'subagent: delegate a self-contained task to a pi worker pane (spawn/isolate/background/send/output/interrupt/resume/list/role/help).',
     promptGuidelines: [
-      'Use subagent when the work is self-contained and the result is what matters: pipelines that would flood this context, long builds/test runs, or independent parts of a bigger change that can proceed in parallel.',
-      'Prefer run_in_background: true for work that will not finish in a few tool calls, then collect with action: "output" — a foreground subagent blocks this turn.',
-      'Use isolate: true when the worker will write files for a task you (or another worker) are editing at the same time, or when you want its own reviewable branch; use cwd to send work into an existing worktree (create it with git worktree add first).',
-      'Keep the prompt complete and self-contained: the worker does not see this conversation, so include paths, acceptance criteria, the test command, and what to report back.',
-      'Do not poll with action: "output" in a tight loop: the pane pushes a settlement notice when it finishes. Check once, then continue other work.',
-      'Send follow-up instructions with action: "send" (delivered as a steer between tool calls) instead of spawning a second worker for the same task.',
-      'Pass agentId, taskId, message, and max_chars as top-level arguments. Do not wrap them in a parameters object.',
+      'Use subagent for self-contained work whose result is what matters: output that would flood this context, long builds/test runs, or independent parts of a bigger change that can run in parallel.',
+      'The worker does not see this conversation: put paths, acceptance criteria, the test command and what to report back into the prompt.',
+      'Use isolate: true when the worker writes files you or another worker edit at the same time, or when its work needs its own reviewable branch.',
+      'Pass agentId, taskId, message and max_chars as top-level arguments, not inside a parameters object.',
     ],
     description: SUBAGENT_DESCRIPTION,
     parameters: Type.Object({
@@ -729,19 +741,20 @@ export default function subagentPlugin(ctx: Context): void {
         Type.Literal('interrupt'),
         Type.Literal('output'),
         Type.Literal('role'),
-      ], { description: 'Operation to perform (default: spawn)' })),
-      description: Type.Optional(Type.String({ description: '[spawn] Short label for this subtask (pane title)' })),
-      prompt: Type.Optional(Type.String({ description: '[spawn] The complete self-contained task for the subagent' })),
-      run_in_background: Type.Optional(Type.Boolean({ description: '[spawn] Return immediately with an agentId; the subagent keeps running in its own pane (default false)' })),
-      cwd: Type.Optional(Type.String({ description: '[spawn] Working directory for the subagent (absolute, or relative to this workspace). Use it to delegate into a git worktree: panes group by worktree — same checkout as you share your tab; a separate worktree gets its own tab named after the worktree directory. Create worktrees yourself with git worktree add. Use isolate:true instead when you want a FRESH worktree created for this task rather than targeting an existing one' })),
-      isolate: Type.Optional(Type.Boolean({ description: '[spawn] Create a fresh git worktree and run the subagent there. Use when the task writes files heavily and independently — in parallel with your own edits or other workers\' — or needs its own clean, reviewable diff. For read-mostly or sequential helper work omit it (shared checkout, writes guarded by the write-lock); use `cwd` only to target an existing directory/worktree (e.g. a retained pier worktree). Mechanics: branch pier/<slug> from your HEAD under ~/.herdr/worktrees/<repo>/; its writes cannot conflict with your checkout; panes group into a tab named after the worktree; the prompt is prefixed with commit discipline (commit to its branch, never push); on settle you get a diff summary. Review with git log/diff HEAD..<branch>, merge with git merge --no-ff <branch>; once merged and clean the worktree auto-removes (branch kept). Mutually exclusive with cwd' })),
-      role: Type.Optional(Type.String({ description: '[spawn|role] Role label or profile name. [spawn] When role matches a profile (searched: workspace .pi-herdr/roles/ → user-global ~/.pi/agent/herdr-pi/roles/ → builtin), the worker toolset becomes the composed manifest. Unknown role names remain display labels only. [role] Target profile for the mid-session switch' })),
-      tab: Type.Optional(Type.String({ description: '[spawn] Name of a task tab to place the subagent into (join if exists, otherwise create). Default placement groups by git worktree.' })),
-      allowed_tools: Type.Optional(Type.Array(Type.String(), { description: '[spawn] Additional tools for role composition (union with role baseline)' })),
-      taskId: Type.Optional(Type.String({ description: '[resume] The task id to revive from the delegation ledger' })),
-      agentId: Type.Optional(Type.String({ description: '[send|interrupt|output|role] The subagent reference: task slug (e.g. "fix-auth"), herdr pane id, or "slug@paneId" as printed by spawn/list' })),
-      message: Type.Optional(Type.String({ description: '[send] The follow-up message' })),
-      max_chars: Type.Optional(Type.Integer({ description: '[output] Maximum characters of output delta to return (default 6000, 100-16000)' })),
+        Type.Literal('help'),
+      ], { description: 'Default spawn' })),
+      description: Type.Optional(Type.String({ description: '[spawn] Pane label; also the todo-reconcile key' })),
+      prompt: Type.Optional(Type.String({ description: '[spawn] The complete self-contained task' })),
+      run_in_background: Type.Optional(Type.Boolean({ description: '[spawn] Return at once; the settlement notice arrives later (default false)' })),
+      cwd: Type.Optional(Type.String({ description: '[spawn] Existing directory or worktree to run in (absolute or workspace-relative); exclusive with isolate' })),
+      isolate: Type.Optional(Type.Boolean({ description: '[spawn] Run in a fresh git worktree (branch pier/<slug>) for heavy parallel writes or a reviewable diff; settle reports a diff summary (see help)' })),
+      role: Type.Optional(Type.String({ description: '[spawn|role] Role profile name; unknown names are display labels only' })),
+      tab: Type.Optional(Type.String({ description: '[spawn] Task tab to join or create (default: grouped by worktree)' })),
+      allowed_tools: Type.Optional(Type.Array(Type.String(), { description: '[spawn] Extra tools on top of the role baseline' })),
+      taskId: Type.Optional(Type.String({ description: '[resume] Task id from the delegation ledger' })),
+      agentId: Type.Optional(Type.String({ description: '[send|interrupt|output|role] Slug, pane id, or slug@paneId as printed by spawn/list' })),
+      message: Type.Optional(Type.String({ description: '[send] Follow-up message' })),
+      max_chars: Type.Optional(Type.Integer({ description: '[output] Output cap (default 6000, 100-16000)' })),
     }),
     outputSchema: SUBAGENT_OUTPUT_SCHEMA,
     // B2: `action` is optional in the schema; normalize it so the validated arguments and the