pi-pier 0.3.1 → 0.4.2

package/src/subagent-core.ts

@@ -3,6 +3,7 @@
  * decisions, task-id resolution, and the outbound port types. Pure: planners decide, adapters do I/O.
  */
 import { normalizeEntryKind } from './history-store.ts';
+import { Type } from 'typebox';
 
 export function sleep(ms: number): Promise<void> {
   const { promise, resolve } = Promise.withResolvers<void>();
@@ -24,6 +25,113 @@ export function buildLaunchLine(parts: readonly string[], platform: NodeJS.Platf
   return (win ? '& ' : '') + quoted.join(' ');
 }
 
+/** Shells that mean a freshly split pane is at its prompt and can accept a launch line. */
+const SHELL_PROCESS_NAMES: ReadonlySet<string> = new Set([
+  'sh', 'bash', 'zsh', 'fish', 'dash', 'ksh', 'mksh', 'tcsh', 'csh', 'nu', 'login',
+  'pwsh', 'powershell', 'cmd',
+]);
+
+/** Normalize `name` / `argv0` (`/bin/zsh`, `C:\\Windows\\System32\\cmd.exe`, `-zsh`) to a shell key. */
+export function shellProcessName(value: string | null | undefined): string {
+  const base = String(value ?? '').replace(/\\/g, '/').split('/').pop()?.toLowerCase() ?? '';
+  const stripped = base.replace(/^-/, '').replace(/\.exe$/, '');
+  return stripped;
+}
+
+/**
+ * Decide whether a pane's foreground set means its shell is ready for input. `null`/`undefined`
+ * means the probe was unavailable: return ready so an older herdr never adds spawn latency.
+ * An empty set is not proof (the shell may still be starting), so callers wait for the timeout.
+ */
+export function planShellReady(
+  foreground: ReadonlyArray<{ name?: string | null; argv0?: string | null }> | null | undefined,
+): 'ready' | 'wait' {
+  if (foreground == null) return 'ready';
+  if (foreground.length === 0) return 'wait';
+  return foreground.some((p) => SHELL_PROCESS_NAMES.has(shellProcessName(p.name)) || SHELL_PROCESS_NAMES.has(shellProcessName(p.argv0)))
+    ? 'ready'
+    : 'wait';
+}
+
+/** Flags pier passes at spawn (buildLaunchParts) that a herdr 0.9.2+ resume command must replay. */
+const RESUME_FLAG_ARITY: Record<string, number> = {
+  '-a': 0,
+  '-e': 1,
+  '--extension': 1,
+  '--tui-mode': 1,
+  '--provider': 1,
+  '--model': 1,
+  '--session': 1,
+};
+
+const RESUME_MAX_ARGS = 64;
+const RESUME_MAX_BYTES = 8 * 1024;
+
+/**
+ * herdr 0.9.2 self-report (docs "Add Herdr support to your agent"): rebuild this worker's launch
+ * line as a `resume_argv` herdr runs after a server restart. The worker's own process.argv is the
+ * source of truth — interpreter and cli.js paths are dropped, whitelisted spawn flags are mirrored
+ * (`--flag=value` splits), argv[0] becomes a plain PATH command name. herdr rules: argv[0] plain,
+ * no apostrophes/control characters, ≤64 args, ≤8 KiB; violations (or a missing `-e`, which could
+ * not restore the extension) return null and the caller skips the report — restore stays best-effort.
+ */
+export function buildResumeArgv(workerArgv: readonly string[], piBin = 'pi'): string[] | null {
+  if (!/^[A-Za-z0-9._-]+$/.test(piBin)) return null;
+  const collected: string[] = [];
+  let index = 0;
+  // Skip interpreter + cli script (everything before the first flag).
+  while (index < workerArgv.length && !workerArgv[index]!.startsWith('-')) index++;
+  for (; index < workerArgv.length; index++) {
+    const raw = workerArgv[index]!;
+    if (!raw.startsWith('-')) continue; // positional (unknown flag's value) — not pier spawn shape
+    const eq = raw.indexOf('=');
+    const flag = eq > 0 ? raw.slice(0, eq) : raw;
+    const inlineValue = eq > 0 ? raw.slice(eq + 1) : null;
+    const arity = RESUME_FLAG_ARITY[flag];
+    if (arity === undefined) continue; // pi-internal flags are not replayed
+    if (arity === 0) {
+      collected.push(flag);
+    } else if (inlineValue !== null) {
+      collected.push(flag, inlineValue);
+    } else if (index + 1 < workerArgv.length) {
+      collected.push(flag, workerArgv[++index]!);
+    }
+  }
+  if (!collected.some((f, i) => (f === '-e' || f === '--extension') && i + 1 < collected.length)) return null;
+  const argv = [piBin, ...collected];
+  if (argv.length > RESUME_MAX_ARGS) return null;
+  if (argv.some((a) => /['\u0000-\u001f\u007f]/.test(a))) return null;
+  if (argv.reduce((sum, a) => sum + a.length + 1, 0) > RESUME_MAX_BYTES) return null;
+  return argv;
+}
+
+/**
+ * pi ≥ 0.99 outputSchema for the subagent tool: the `details` each action already produces, stamped
+ * with the normalized action. Codemode scripts (and any structured consumer) read this instead of
+ * parsing the prose reply; the text content stays authoritative for the transcript. Hard failures
+ * throw (toolError), so every returned value is a success and always carries structuredContent.
+ */
+export const SUBAGENT_OUTPUT_SCHEMA = Type.Object({
+  action: Type.Union([
+    Type.Literal('spawn'), Type.Literal('resume'), Type.Literal('list'),
+    Type.Literal('send'), Type.Literal('interrupt'), Type.Literal('output'), Type.Literal('role'), Type.Literal('help'),
+  ]),
+  paneId: Type.Optional(Type.String()),
+  taskId: Type.Optional(Type.String()),
+  role: Type.Optional(Type.String()),
+  background: Type.Optional(Type.Boolean()),
+  alreadyRunning: Type.Optional(Type.Boolean()),
+}, { additionalProperties: true });
+
+export function attachSubagentStructuredContent(action: string, result: unknown): unknown {
+  if (result === null || typeof result !== 'object' || Array.isArray(result)) return result;
+  const record = result as Record<string, unknown>;
+  const details = record.details !== null && typeof record.details === 'object' && !Array.isArray(record.details)
+    ? record.details as Record<string, unknown>
+    : {};
+  return { ...record, structuredContent: { action, ...details } };
+}
+
 /** Bounds concurrent delegation spawns (SUBAGENT_CONCURRENCY). */
 export class Semaphore {
   private active = 0;
@@ -87,6 +195,14 @@ export interface AliveProbe {
   foregroundCwd?: string | null;
 }
 
+/** Trailing line for isolate spawn results: the branch (`pier/<slug>`) reads like a directory and
+ *  masters have cd'd into `<repo>/pier/<slug>`; only the worktree path is an actual directory. */
+export function formatIsolateLocation(
+  isolate: Pick<NonNullable<SubEntry['isolate']>, 'worktreePath' | 'branch'> | null | undefined,
+): string {
+  return isolate ? `\nWorktree: ${isolate.worktreePath} (branch ${isolate.branch})` : '';
+}
+
 /**
  * A subagent outlives its "no output" result: a working/blocked agent is alive regardless of session
  * age, otherwise recent session writes decide. `paneExists: false` is death — an unavailable probe is
@@ -116,7 +232,7 @@ export function buildAliveNotice(
     return [
       `Subagent "${description}" is still running in pane ${paneId} (agent_status=${status}${activity}).`,
       'The foreground wait has moved it to background so this call returns now.',
-      'Do NOT redo its work. When it settles you will receive a notification with its closing output.',
+      'Do NOT redo its work and do NOT sleep or poll: when it settles, its result is delivered automatically as a settlement notice at your next turn boundary.',
       'Use subagent(action: "list") to check its live state; subagent(action: "send") to give it follow-up work.',
     ].join(' ');
   }
@@ -147,6 +263,9 @@ export interface SubEntry {
   /** 'task' or a role name; only a display label for GC. */
   kind: string;
   paneId: string;
+  /** Phase 2 task slug (kebab-case of description; RFC rfc-delegation-identity §3.1): tool args
+   * accept `slug@paneId` or the bare slug; allocated once at spawn and stable across revives. */
+  slug?: string;
   tabId: string;
   tabName: string;
   cwd: string;
@@ -163,6 +282,9 @@ export interface SubEntry {
   userTakeover?: boolean;
   observationStartedAt?: number | null;
   lastAgentStatus?: string | null;
+  /** The final report `subagent output` already returned (tail fingerprint + time): the settlement
+   *  notice then points at that delivery instead of repeating the report. Durable across resume. */
+  reportDelivered?: { fingerprint: string; at: number } | null;
   /** D98: isolate worktree metadata; `releasedAt` set once the worktree is removed. */
   isolate?: {
     worktreePath: string;
@@ -173,6 +295,64 @@ export interface SubEntry {
   };
 }
 
+/* ── task slugs (RFC rfc-delegation-identity §3.1) ───────────────── */
+
+/** Slug cap: short enough for tool args and list rows, long enough to stay distinctive. */
+const SLUG_MAX = 24;
+
+/** Kebab-case a task description; non-ASCII (CJK descriptions) sanitizes to '' — the allocator
+ * then falls back to a taskId-derived ascii slug, because tool args must stay typeable. */
+export function slugifyTask(description: string): string {
+  return description
+    .toLowerCase()
+    .replace(/[''']/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, SLUG_MAX)
+    .replace(/-+$/g, '');
+}
+
+/** Allocate a unique slug among live rows: base, then base-2, base-3, …; a description that
+ * sanitizes to nothing (CJK, emoji-only) falls back to `task-<taskId prefix>`. */
+export function allocateSubSlug(description: string, taskId: string, taken: ReadonlySet<string>): string {
+  const base = slugifyTask(description) || `task-${taskId.slice(0, 6)}`;
+  if (!taken.has(base)) return base;
+  for (let n = 2; ; n++) {
+    const next = `${base}-${n}`;
+    if (!taken.has(next)) return next;
+  }
+}
+
+/** Stable display/argument form for a subagent row: `slug@paneId` when a slug exists. */
+export function subRef(sub: { paneId: string; slug?: string }): string {
+  return sub.slug ? `${sub.slug}@${sub.paneId}` : sub.paneId;
+}
+
+/** Identity of a final report across the output action and the settlement notice: its tail. */
+export function reportFingerprint(report: string): string {
+  return report.slice(-64);
+}
+
+/** Shorter sleeps are ordinary polling of builds/logs; from a minute up, they were waits on workers. */
+const SLEEP_NOTE_MIN_SECONDS = 60;
+
+/**
+ * Note for a master bash call that sleeps ≥ SLEEP_NOTE_MIN_SECONDS while background workers run:
+ * masters slept 660-840 s per worker although the settlement notice arrives on its own. Worded so a
+ * sleep that waits on something else (a load test, a build) is left alone.
+ */
+export function sleepWhileSubsRunningNote(
+  command: string,
+  running: ReadonlyArray<{ paneId: string; slug?: string }>,
+): string | null {
+  if (running.length === 0) return null;
+  const longest = Math.max(0, ...[...command.matchAll(/\bsleep\s+(\d+)s?\b/g)].map((m) => Number(m[1])));
+  if (longest < SLEEP_NOTE_MIN_SECONDS) return null;
+  return `[pier] ${running.length} background subagent(s) running (${running.map(subRef).join(', ')}): their settlement `
+    + 'notice arrives automatically at your next tool boundary, so do not sleep to wait for them — keep working or end '
+    + 'your turn. Sleeping is only needed for other work (builds, logs).';
+}
+
 export interface SubsRegistry {
   version: 2;
   subs: SubEntry[];
@@ -198,6 +378,7 @@ export function foldSubsRegistry(entries: ReadonlyArray<{ type?: string; customT
         taskId: typeof s.taskId === 'string' ? s.taskId : s.paneId,
         kind: normalizeEntryKind(typeof s.kind === 'string' ? s.kind : undefined),
         paneId: s.paneId,
+        slug: typeof s.slug === 'string' && s.slug ? s.slug : undefined,
         tabId: typeof s.tabId === 'string' ? s.tabId : '',
         tabName: typeof s.tabName === 'string' ? s.tabName : '',
         cwd: typeof s.cwd === 'string' ? s.cwd : '',
@@ -225,6 +406,10 @@ export function foldSubsRegistry(entries: ReadonlyArray<{ type?: string; customT
             retainNotified: s.isolate.retainNotified === true,
           }
           : undefined,
+        reportDelivered: s.reportDelivered && typeof s.reportDelivered === 'object'
+          && typeof s.reportDelivered.fingerprint === 'string' && typeof s.reportDelivered.at === 'number'
+          ? { fingerprint: s.reportDelivered.fingerprint, at: s.reportDelivered.at }
+          : undefined,
       }));
     found = { version: 2, subs };
   }
@@ -395,6 +580,12 @@ export function buildLaunchParts(
 
 const ISOLATE_SLUG_MAX = 40;
 
+/**
+ * D-3 (verified 2026-10-20): herdr 0.9.5 `worktree create --workspace <parent>` still opens a new
+ * top-level workspace, not a tab inside the parent workspace, so it cannot replace pier's isolate
+ * placement. Keep `git worktree add` + the master-workspace tab; native worktree management remains
+ * an option only for workflows that accept a separate workspace.
+ */
 export function planIsolateWorktree(opts: {
   description: string;
   taskHex: string;
@@ -553,7 +744,7 @@ export function planForegroundTick(input: {
 
 /* ── task-id resolution ─────────────────────────────────────────── */
 
-type TaskIdResolutionResult =
+export type TaskIdResolutionResult =
   | { kind: 'resolved'; taskId: string }
   | { kind: 'ambiguous'; query: string; candidates: string[] }
   | { kind: 'too_short'; query: string }
@@ -583,13 +774,28 @@ export function resolveTaskIdPrefix(
   return { kind: 'not_found', query: trimmed };
 }
 
+/** Error text for a non-resolved `resolveTaskIdPrefix` outcome; null for `resolved` (each caller owns
+ * its success path) and `not_found` (each caller words its own unknown-id hint). `rawQuery` keeps
+ * the caller's original string in the message even though matching works on the trimmed form. */
+export function taskIdResolutionError(
+  res: TaskIdResolutionResult,
+  label: 'task id' | 'subagent id',
+  rawQuery: string,
+): string | null {
+  if (res.kind === 'too_short') return `Error: ${label} prefix "${rawQuery}" is too short (minimum 4 characters).`;
+  if (res.kind === 'ambiguous') return ambiguousIdError(label, rawQuery, res.candidates);
+  return null;
+}
+
 /* ── outbound port (composition root → plugin) ──────────────────── */
 
 /** Bound atomically at session_start: consumers read `current` and must tolerate null. */
 export interface SubagentPort {
   applyReplySession(paneId: string, sessionFile: string | null): void;
   reconcileOnReply(paneId: string): string[];
-  listRunningSubs(): Array<{ paneId: string; description: string }>;
+  listRunningSubs(): Array<{ paneId: string; slug?: string; description: string; kind: string }>;
+  /** D113: non-closed rows for the /pier-tree view (settled nodes carry their settle time). */
+  listRows(): Array<{ paneId: string; slug?: string; description: string; kind: string; status: SubEntry['status']; settledAt: number | null }>;
   settleStatLine(paneId: string): Promise<string | null>;
   /** Pipe settlement: drop the row out of listRunningSubs before the finish notice wakes the master. */
   consumeReply(paneId: string, outcome: string | null): void;

package/src/subagent-poller.ts

@@ -10,7 +10,7 @@ import { runtimePolicy, type RuntimePolicy } from './runtime-policy.ts';
 import type { JevRuntime } from './jev-client.ts';
 import { evaluateSettleVerdict, settleAskIsSafe, settleVerdictRequest } from './jev-core.ts';
 import { formatSettlementNotice, type SettlementNullReason } from './vocab.ts';
-import { buildBlockedGateNotice, sleep, type SubEntry } from './subagent-core.ts';
+import { buildBlockedGateNotice, reportFingerprint, sleep, type SubEntry } from './subagent-core.ts';
 import type { SessionIo } from './subagent-session.ts';
 import type { GitIo } from './subagent-spawn.ts';
 
@@ -70,8 +70,17 @@ export function planObservationTick(input: {
   agentStatus: string | null;
   machineInjectAgoMs: number;
   machineInjectGraceMs: number;
+  /** The transcript already holds a finalized answer (stopReason 'stop', no pending tool call). */
+  finalized?: boolean;
 }): ObservationTickPlan {
-  if (!input.observationStartedAt) return { kind: 'start-observation' };
+  if (!input.observationStartedAt) {
+    // A finalized answer on a pane that is not working settles on the detecting tick: the window
+    // would only delay the result, and the transcript cannot grow under an idle pane. A working or
+    // blocked pane keeps the window path — that is the human-takeover guard.
+    const paneBusy = input.agentStatus === 'working' || input.agentStatus === 'blocked';
+    if (input.finalized && !paneBusy) return { kind: 'settle' };
+    return { kind: 'start-observation' };
+  }
   if (input.agentStatus === 'working') {
     if (input.machineInjectAgoMs > input.machineInjectGraceMs) return { kind: 'user-takeover' };
     return { kind: 'machine-inject-reset' };
@@ -118,8 +127,9 @@ export function buildSettlementNoticeText(
   closing: string | null,
   statLine: string | null,
   nullReason: SettlementNullReason = 'silent',
+  reportDeliveredAt: number | null = null,
 ): string {
-  const base = formatSettlementNotice(agentLabel, closing, nullReason);
+  const base = formatSettlementNotice(agentLabel, closing, nullReason, reportDeliveredAt);
   return statLine ? `${base}\n${statLine}` : base;
 }
 
@@ -183,7 +193,7 @@ export interface PollerHost {
   lastMachineInjectAt: Map<string, number>;
   session: SessionIo;
   git: GitIo;
-  injectNotice(content: string): Promise<void>;
+  injectNotice(content: string, paneId?: string): Promise<void>;
   reconcileOnSettlement(description: string, outcome: 'settled' | 'failed'): string[];
   withReconcileNotes(base: string, notes: readonly string[]): string;
   claimSettleNotice(key: string): boolean;
@@ -222,6 +232,9 @@ export function createPoller(h: PollerHost): Poller {
   ): Promise<void> {
     const startedAt = now();
     let lastActivityAt = now();
+    /** Claimed settle key: on a rejected injection the claim stays ours, so the next tick retries
+     *  the notice instead of suppressing it as someone else's. */
+    let claimedKey: string | null = null;
     /** Stop watching this pane: persist + ledger first, or a restart replays a ghost running row. */
     const consume = (outcome: string | null, via: string, at: number): void => {
       const row = h.subs.get(paneId);
@@ -323,13 +336,6 @@ export function createPoller(h: PollerHost): Poller {
 
           if (isSettlementCandidate(s)) {
             const closing = s.text;
-            if (!entry.observationStartedAt) {
-              entry.observationStartedAt = now();
-              entry.lastAgentStatus = 'idle';
-              h.persistSubs();
-              await doSleep(OBSERVATION_TICK_MS);
-              continue;
-            }
             let agentStatus: string | null = null;
             try {
               agentStatus = (await h.client.listAgents()).find((a) => a.paneId === paneId)?.status ?? null;
@@ -342,7 +348,15 @@ export function createPoller(h: PollerHost): Poller {
               agentStatus,
               machineInjectAgoMs: now() - (h.lastMachineInjectAt.get(paneId) ?? 0),
               machineInjectGraceMs,
+              finalized: closing != null && !s.pendingTool,
             });
+            if (obs.kind === 'start-observation') {
+              entry.observationStartedAt = now();
+              entry.lastAgentStatus = 'idle';
+              h.persistSubs();
+              await doSleep(OBSERVATION_TICK_MS);
+              continue;
+            }
             if (obs.kind === 'user-takeover') {
               entry.userTakeover = true;
               entry.observationStartedAt = now();
@@ -375,7 +389,23 @@ export function createPoller(h: PollerHost): Poller {
                   if (tail && settleAskIsSafe(tail)) {
                     const res = await h.jev.ask(
                       settleVerdictRequest({ description: current.description, tail }),
-                      { questionId: 'settle-attribution', timeoutMs: 2500 },
+                      {
+                        questionId: 'settle-attribution',
+                        timeoutMs: 2500,
+                        // Calibration fields (D115): noul answers carry no confidence, so the
+                        // probabilities and the composed verdict are what SETTLE_*_MIN_NOUL
+                        // tuning reads from jev.jsonl.
+                        enrich: ({ ok, answers }) => {
+                          if (!ok || !answers) return {};
+                          const match = answers.tail_matches_task;
+                          const fin = answers.tail_has_final_answer;
+                          return {
+                            tailMatchesTaskNoul: match?.type === 'noul' ? match.noul : null,
+                            tailHasFinalAnswerNoul: fin?.type === 'noul' ? fin.noul : null,
+                            settleVerdict: evaluateSettleVerdict(answers) ?? 'unanswered',
+                          };
+                        },
+                      },
                     );
                     if (res.ok) {
                       const verdict = evaluateSettleVerdict(res.answers);
@@ -393,19 +423,39 @@ export function createPoller(h: PollerHost): Poller {
                 await h.session.resolveSessionFile(paneId, cwd, undefined, { minMtimeMs: current.injectTs - 2_000 }),
               );
             }
-            consume(closing, 'poll-settle', now());
+            // Claim before delivering: the pipe fast-path may already own this settlement's notice.
+            // The row is consumed only after the notice is accepted, and a claim we own is retried
+            // on the next tick — a rejected injection must not strand a finished worker as 'running'
+            // with no notice, nor consume the row while the result is still undelivered.
+            const claimKey = `${paneId}:${current.requestId}`;
+            if (claimedKey !== claimKey) {
+              if (!h.claimSettleNotice(claimKey)) {
+                consume(closing, 'poll-settle', now());
+                return;
+              }
+              claimedKey = claimKey;
+            }
             const notes = h.reconcileOnSettlement(current.description, 'settled');
             const statLine = await h.git.worktreeStatLine(entry);
+            // `subagent output` may already have returned this exact report: point there, don't repeat it.
+            const delivered = closing && entry.reportDelivered?.fingerprint === reportFingerprint(closing)
+              ? entry.reportDelivered.at
+              : null;
             const notice = h.withReconcileNotes(
-              buildSettlementNoticeText(`${paneId} (${current.description})`, closing, statLine, nullReason),
+              buildSettlementNoticeText(`${paneId} (${current.description})`, closing, statLine, nullReason, delivered),
               notes,
             );
-            if (h.claimSettleNotice(`${paneId}:${current.requestId}`)) {
-              try {
-                await h.injectNotice(notice);
-              } catch {
-              }
+            try {
+              // Tag the pane: a notice buffered during compaction must keep its row GC-exempt
+              // until the post-compaction flush actually delivers it.
+              await h.injectNotice(notice, paneId);
+            } catch {
+              // Notification refused (e.g. the master is compacting): leave the row running and
+              // re-detect the same closing text on the next tick.
+              await pace();
+              continue;
             }
+            consume(closing, 'poll-settle', now());
             return;
           }
         }

package/src/subagent-session.ts

@@ -16,7 +16,7 @@ import {
   type SessionEntryLike,
   type SubSessionState,
 } from './session-tail.ts';
-import { idParam, sleep, type AliveProbe, type SubEntry } from './subagent-core.ts';
+import { idParam, reportFingerprint, sleep, type AliveProbe, type SubEntry } from './subagent-core.ts';
 import { toolError } from './tool-error.ts';
 
 /* ── subagent output delta (pure) ───────────────────────────────── */
@@ -26,6 +26,61 @@ export const OUTPUT_HARD_CAP_CHARS = 16000;
 const OUTPUT_MIN_OVERLAP = 16;
 const OUTPUT_TAIL_CHARS = 500;
 
+const BOX_CHARS = '│┃║╭╮╰╯┌┐└┘├┤┬┴┼─━═╌╍';
+const FRAME_ONLY_LINE = new RegExp(`^[\\s${BOX_CHARS}]*[${BOX_CHARS}][\\s${BOX_CHARS}]*$`);
+const SIDE_BORDER = /^\s*[│┃║] ?|\s*[│┃║]\s*$/g;
+/** pi's status footer: `↑43k ↓13k R820k CH99.1% $0.017 …`, preceded by a `~/cwd (branch)` line. */
+const PI_FOOTER_LINE = /^↑[\d.]+[kKmM]?\s+↓[\d.]+[kKmM]?\s/;
+const PI_FOOTER_CWD_LINE = /^~?\/\S*( \([^)]*\))?$/;
+
+/**
+ * Strip TUI chrome from a worker pane read: frame-only box-drawing rows, side borders, right-padding,
+ * pi's footer, and blank-line runs. A real read was ~20% whitespace, box glyphs and footer. Applied
+ * before the delta, so the cursor tracks the same cleaned text on every call.
+ */
+export function cleanPaneChrome(text: string): string {
+  // Frame rows are judged before border stripping, which would otherwise leave them as blank lines.
+  const lines = text.split('\n')
+    .filter((line) => !FRAME_ONLY_LINE.test(line))
+    .map((line) => line.replace(SIDE_BORDER, '').trimEnd());
+  const kept: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (PI_FOOTER_LINE.test(line)) continue;
+    if (PI_FOOTER_CWD_LINE.test(line) && PI_FOOTER_LINE.test(lines[i + 1] ?? '')) continue;
+    if (line === '' && kept[kept.length - 1] === '') continue;
+    kept.push(line);
+  }
+  return kept.join('\n');
+}
+
+/** Normalized-text length of the report opening that identifies the pane's rendered copy. */
+const REPORT_KEY_CHARS = 24;
+
+/**
+ * The pane shows the final report rendered (markdown stripped, long lines cut at pane width), so it
+ * is a lossy copy of the transcript text. When the transcript report is attached, cut the pane delta
+ * where the report's opening appears (whitespace and markdown markers ignored). Null: no copy found.
+ */
+export function cutPaneReportCopy(delta: string, report: string): string | null {
+  const isNoise = (ch: string): boolean => /[\s`*_#>]/.test(ch);
+  const key = [...report].filter((ch) => !isNoise(ch)).slice(0, REPORT_KEY_CHARS).join('');
+  if (key.length < REPORT_KEY_CHARS) return null;
+  let normalized = '';
+  const origin: number[] = [];
+  for (let i = 0; i < delta.length; i++) {
+    if (isNoise(delta[i]!)) continue;
+    normalized += delta[i];
+    origin.push(i);
+  }
+  const at = normalized.indexOf(key);
+  if (at < 0) return null;
+  const lineStart = delta.lastIndexOf('\n', origin[at]!) + 1;
+  const before = delta.slice(0, lineStart).trimEnd();
+  const marker = '(the pane\'s rendered copy of the final report is omitted — full text in the Subagent Report section below)';
+  return before ? `${before}\n${marker}` : marker;
+}
+
 export type SubagentStatus = 'running' | 'idle' | 'blocked' | 'settled';
 
 export interface SubagentOutputCursor {
@@ -440,6 +495,8 @@ export async function executeSubagentOutput(
     /** Last finalized assistant text from the worker's transcript: the pane read alone cannot
      * recover it when the fullscreen TUI shows only the status overlay. Optional for tests. */
     readFinalReport?: (paneId: string, entryCwd: string) => Promise<string | null>;
+    /** Persists `entry.reportDelivered` so the settlement notice can skip a report already shown. */
+    persistSubs?: () => void;
   },
 ) {
   const rawId = idParam(params, 'agentId', 'taskId');
@@ -472,8 +529,9 @@ export async function executeSubagentOutput(
   const maxChars = typeof params?.max_chars === 'number'
     ? params.max_chars
     : typeof params?.maxChars === 'number' ? params.maxChars : undefined;
-  const deltaResult = computeSubagentOutputDelta(prevCursor, rawRead.text, { maxChars });
-  deltaResult.nextCursor.reportTail ??= prevCursor?.reportTail;
+  const deltaResult = computeSubagentOutputDelta(prevCursor, cleanPaneChrome(rawRead.text), { maxChars });
+  // A resumed process has no cursor; the durable delivery record keeps the report from repeating.
+  deltaResult.nextCursor.reportTail ??= prevCursor?.reportTail ?? entry.reportDelivered?.fingerprint;
 
   // Transcript fallback: the terminal delta can be empty (or footer-only) while the finished
   // report exists only in the session file. Surface it once per distinct report.
@@ -481,11 +539,16 @@ export async function executeSubagentOutput(
   if ((status === 'settled' || status === 'idle') && deps.readFinalReport) {
     try {
       const report = await deps.readFinalReport(entry.paneId, entry.cwd);
-      const fingerprint = report ? report.slice(-64) : '';
+      const fingerprint = report ? reportFingerprint(report) : '';
       if (report && fingerprint && fingerprint !== deltaResult.nextCursor.reportTail) {
         const bounded = boundText(report, Math.max(1, Math.min(maxChars ?? OUTPUT_DEFAULT_MAX_CHARS, OUTPUT_HARD_CAP_CHARS)));
         reportSection = `[Subagent Report | latest finalized message from session transcript${bounded.truncated ? ' | truncated' : ''}]\n${bounded.text}`;
         deltaResult.nextCursor.reportTail = fingerprint;
+        deltaResult.delta = cutPaneReportCopy(deltaResult.delta, report) ?? deltaResult.delta;
+        if (!bounded.truncated) {
+          entry.reportDelivered = { fingerprint, at: Date.now() };
+          deps.persistSubs?.();
+        }
       }
     } catch {
     }