pi-pier 0.3.1 → 0.4.1

package/src/plugins/subagent.ts

@@ -7,12 +7,13 @@
 import { Context } from '@deepseek-ai/cordis';
 import { Type } from 'typebox';
 import { basename, dirname, join } from 'node:path';
-import type { PiSurface } from '../pi-surface.ts';
+import { cordisGet } from '../cordis-services.ts';
 import type { HerdrClientLike } from '../herdr-client.ts';
 import {
   Semaphore,
+  SUBAGENT_OUTPUT_SCHEMA,
   agoText,
-  ambiguousIdError,
+  attachSubagentStructuredContent,
   buildAliveNotice,
   idParam,
   flattenToolParams,
@@ -20,7 +21,9 @@ import {
   newestPerTaskId,
   rekeySub,
   resolveTaskIdPrefix,
+  taskIdResolutionError,
   tabNameForTask,
+  subRef,
   type AliveProbe,
   type SubEntry,
   type SubagentPort,
@@ -41,8 +44,9 @@ import { toolError, ToolError } from '../tool-error.ts';
 import { pipeNameFor, pipeRequestTo, type PipeRequest, type PipeResponse } from '../pipe-channel.ts';
 import type { TerminalStateSlot } from './terminal.ts';
 import { bareSessionId, resolveSessionFileValue } from '../session-tail.ts';
-import { createGitIo, createSpawnAction, createSpawner } from '../subagent-spawn.ts';
+import { DELEGATION_ENV, type DelegationContext } from '../delegation-core.ts';
 import type { JevRuntime } from '../jev-client.ts';
+import { createGitIo, createSpawnAction, createSpawner } from '../subagent-spawn.ts';
 import { createPoller } from '../subagent-poller.ts';
 import { createGcController, createSubagentRegistry } from '../subagent-gc.ts';
 import { createSessionIo, executeSubagentOutput, type SubagentOutputCursor } from '../subagent-session.ts';
@@ -106,8 +110,8 @@ function defaultAgentSessionsDir(): string {
 }
 
 export default function subagentPlugin(ctx: Context): void {
-  const surface = ctx.get('pi-herdr.surface') as PiSurface<object>;
-  const d = ctx.get('pi-herdr.subagent-deps') as SubagentDeps;
+  const surface = cordisGet(ctx, 'pi-herdr.surface');
+  const d = cordisGet(ctx, 'pi-herdr.subagent-deps');
   const { client, env, sessionRoot, port, terminalState } = d;
   const pi = surface.raw as {
     appendEntry?: (customType: string, data: unknown) => void;
@@ -141,6 +145,7 @@ export default function subagentPlugin(ctx: Context): void {
       taskId: e.taskId,
       kind: e.kind,
       paneId: e.paneId,
+      ...(e.slug ? { slug: e.slug } : {}),
       tabId: e.tabId,
       tabName: e.tabName,
       workspaceId: env?.workspaceId ?? '',
@@ -187,7 +192,19 @@ export default function subagentPlugin(ctx: Context): void {
     listRunningSubs() {
       return [...subs.values()]
         .filter((s) => s.background && s.status === 'running')
-        .map((s) => ({ paneId: s.paneId, description: s.description }));
+        .map((s) => ({ paneId: s.paneId, slug: s.slug, description: s.description, kind: s.kind }));
+    },
+    listRows() {
+      return [...subs.values()]
+        .filter((s) => s.status !== 'closed')
+        .map((s) => ({
+          paneId: s.paneId,
+          slug: s.slug,
+          description: s.description,
+          kind: s.kind,
+          status: s.status,
+          settledAt: s.consumedAt ?? null,
+        }));
     },
     async settleStatLine(paneId) {
       const entry = subs.get(paneId);
@@ -331,7 +348,18 @@ export default function subagentPlugin(ctx: Context): void {
     const spawned = await spawnPaneInTaskTab(
       { desiredTab: entry.tabName || latest.tabName || null, description: entry.description },
       entry.cwd,
-      { PI_HERDR_SUBAGENT: '1' },
+      {
+        PI_HERDR_SUBAGENT: '1',
+        [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.
+          parentPipe: pipeNameFor(process.cwd(), env?.paneId ?? ''),
+          taskId: entry.taskId,
+          description: entry.description,
+          role: entry.kind === 'task' ? 'worker-default' : entry.kind,
+        } satisfies DelegationContext),
+      },
       launchLine(resumeFile, null, approve),
     );
     const ready = await waitSubReady(entry.cwd, spawned.paneId);
@@ -358,6 +386,7 @@ export default function subagentPlugin(ctx: Context): void {
       taskId: h.taskId,
       kind: h.kind,
       paneId: h.paneId,
+      ...(h.slug ? { slug: h.slug } : {}),
       tabId: h.tabId,
       tabName: h.tabName ?? '',
       cwd: h.cwd,
@@ -377,12 +406,23 @@ export default function subagentPlugin(ctx: Context): void {
     if (!rawId) return { error: 'Error: unknown subagent id "" (see action list)' };
     const direct = subs.get(rawId);
     if (direct) return { entry: direct };
+    // Phase 2 slug reference: exact match against live rows (paneId stays first for back-compat).
+    // `slug@paneId` accepts both parts; a revived row changed its paneId, so the slug part wins then.
+    const at = rawId.indexOf('@');
+    const slugPart = at > 0 ? rawId.slice(0, at) : rawId;
+    const panePart = at > 0 ? rawId.slice(at + 1) : null;
+    const combined = panePart !== null
+      ? (subs.get(panePart) ?? [...subs.values()].find((s) => s.slug === slugPart && s.paneId === panePart) ?? null)
+      : null;
+    if (combined) return { entry: combined };
+    const bySlug = [...subs.values()].find((s) => s.slug === slugPart);
+    if (bySlug) return { entry: bySlug };
 
     const byTaskId = newestPerTaskId(subs.values());
     const res = resolveTaskIdPrefix(rawId, byTaskId.keys());
     if (res.kind === 'resolved') return { entry: byTaskId.get(res.taskId)! };
-    if (res.kind === 'ambiguous') return { error: ambiguousIdError('subagent id', rawId, res.candidates) };
-    if (res.kind === 'too_short') return { error: `Error: subagent id prefix "${rawId}" is too short (minimum 4 characters).` };
+    const resError = taskIdResolutionError(res, 'subagent id', rawId);
+    if (resError) return { error: resError };
 
     if (cwd) {
       const hist = readHistory(histFile(cwd));
@@ -395,7 +435,8 @@ export default function subagentPlugin(ctx: Context): void {
           return { entry };
         }
       }
-      if (histRes.kind === 'ambiguous') return { error: ambiguousIdError('subagent id', rawId, histRes.candidates) };
+      const histError = taskIdResolutionError(histRes, 'subagent id', rawId);
+      if (histError) return { error: histError };
     }
     return { error: `Error: unknown subagent id "${rawId}" (see action list)` };
   }
@@ -415,16 +456,14 @@ export default function subagentPlugin(ctx: Context): void {
     persistSubs();
   }
 
-  async function executeSubagentResume(params: ToolParams, toolCtx: unknown) {
+  async function executeSubagentResume(params: ToolParams) {
     if (!client.available) return toolError('requires a herdr-managed pane.');
     const rawTaskId = idParam(params, 'taskId', 'agentId');
     if (!rawTaskId) return toolError('missing taskId for resume (see action list or delegation ledger).');
     const running = newestPerTaskId([...subs.values()].filter((s) => s.background && s.status === 'running'));
     const live = resolveTaskIdPrefix(rawTaskId, running.keys());
-    if (live.kind === 'too_short') {
-      return toolError(`Error: task id prefix "${rawTaskId}" is too short (minimum 4 characters).`);
-    }
-    if (live.kind === 'ambiguous') return toolError(ambiguousIdError('task id', rawTaskId, live.candidates));
+    const liveError = taskIdResolutionError(live, 'task id', rawTaskId);
+    if (liveError) return toolError(liveError);
     if (live.kind === 'resolved') {
       const entry = running.get(live.taskId)!;
       return {
@@ -434,12 +473,9 @@ export default function subagentPlugin(ctx: Context): void {
     }
     const history = readHistoryTree(dirname(defaultAgentSessionsDir()));
     const resolution = resolveTaskIdPrefix(rawTaskId, history.map((e) => e.taskId));
-    if (resolution.kind === 'too_short') {
-      return toolError(`Error: task id prefix "${rawTaskId}" is too short (minimum 4 characters).`);
-    }
-    if (resolution.kind === 'ambiguous') return toolError(ambiguousIdError('task id', rawTaskId, resolution.candidates));
-    if (resolution.kind === 'not_found') {
-      return toolError(`Error: no history for task "${rawTaskId}" in this workspace or its spawned checkouts.`);
+    if (resolution.kind !== 'resolved') {
+      return toolError(taskIdResolutionError(resolution, 'task id', rawTaskId)
+        ?? `Error: no history for task "${rawTaskId}" in this workspace or its spawned checkouts.`);
     }
     const taskId = resolution.taskId;
     const latest = latestGeneration(history, taskId);
@@ -477,7 +513,7 @@ export default function subagentPlugin(ctx: Context): void {
         ? 'reused existing pane with same session; pi still running there'
         : entry.sessionFile ? 'session restored' : 'session file missing; fresh conversation';
       return {
-        content: [{ type: 'text', text: `resumed subagent ${entry.paneId} from task ${taskId} (${how}).` }],
+        content: [{ type: 'text', text: `resumed subagent ${subRef(entry)} from task ${taskId} (${how}).` }],
         details: { paneId: entry.paneId, taskId },
       };
     } catch (err) {
@@ -548,7 +584,7 @@ export default function subagentPlugin(ctx: Context): void {
           persistSubs();
           throw inner;
         }
-        return { content: [{ type: 'text', text: `Message sent to subagent ${entry.paneId}.` }], details: { paneId: entry.paneId } };
+        return { content: [{ type: 'text', text: `Message sent to subagent ${subRef(entry)}.` }], details: { paneId: entry.paneId } };
       },
     });
   }
@@ -556,7 +592,7 @@ export default function subagentPlugin(ctx: Context): void {
   async function executeSubagentInterrupt(params: ToolParams, toolCtx: unknown) {
     const { entry } = targetOf(params, toolCtx);
     if (entry.status === 'closed') {
-      return { content: [{ type: 'text', text: `Interrupt accepted for subagent ${entry.paneId} (already idle/closed; no-op).` }], details: {} };
+      return { content: [{ type: 'text', text: `Interrupt accepted for subagent ${subRef(entry)} (already idle/closed; no-op).` }], details: {} };
     }
     return pipeAction(entry, {
       ready: false,
@@ -565,7 +601,7 @@ export default function subagentPlugin(ctx: Context): void {
         // No settlement notice for an interrupted turn: the requester already knows.
         const lastId = lastRequestIdByPane.get(entry.paneId);
         if (lastId) d.claimSettleNotice(`${entry.paneId}:${lastId}`);
-        return { content: [{ type: 'text', text: `Interrupt accepted for subagent ${entry.paneId} (fire-and-return).` }], details: { paneId: entry.paneId } };
+        return { content: [{ type: 'text', text: `Interrupt accepted for subagent ${subRef(entry)} (fire-and-return).` }], details: { paneId: entry.paneId } };
       },
     });
   }
@@ -608,7 +644,7 @@ export default function subagentPlugin(ctx: Context): void {
         continue;
       }
       if (sub.status === 'consumed' || sub.status === 'settled') {
-        lines.push(`${sub.paneId} [idle] (${sub.kind}, settled; action send revives)${tabTag}${wtTag} ${sub.description}`);
+        lines.push(`${subRef(sub)} [idle] (${sub.kind}, settled; action send revives)${tabTag}${wtTag} ${sub.description}`);
         continue;
       }
       const state = 'running';
@@ -624,7 +660,7 @@ export default function subagentPlugin(ctx: Context): void {
       const cwdTag = probe?.foregroundCwd && probe.foregroundCwd !== sub.cwd
         ? ` [cwd: ${basename(probe.foregroundCwd) || probe.foregroundCwd}]`
         : '';
-      lines.push(`${sub.paneId} [${state}${takeoverMark}${statusTag}${activityTag}${gateTag}] (${sub.kind})${tabTag}${wtTag}${cwdTag} ${sub.description}`);
+      lines.push(`${subRef(sub)} [${state}${takeoverMark}${statusTag}${activityTag}${gateTag}] (${sub.kind})${tabTag}${wtTag}${cwdTag} ${sub.description}`);
     }
     return { content: [{ type: 'text', text: lines.join('\n') }], details: {} };
   }
@@ -643,6 +679,7 @@ export default function subagentPlugin(ctx: Context): void {
     session,
     spawn,
     poller,
+    getSessionId: d.getSessionId,
     ...(d.logRouting ? { logRouting: d.logRouting } : {}),
   });
 
@@ -659,7 +696,7 @@ export default function subagentPlugin(ctx: Context): void {
 
   const ACTIONS: Record<string, (params: ToolParams, toolCtx: unknown, onUpdate?: (u: unknown) => void) => Promise<unknown>> = {
     spawn: (params, toolCtx, onUpdate) => executeSubagentSpawn(params, toolCtx, onUpdate),
-    resume: (params, toolCtx) => executeSubagentResume(params, toolCtx),
+    resume: (params) => executeSubagentResume(params),
     list: () => executeSubagentList(),
     send: (params, toolCtx) => executeSubagentSend(params, toolCtx),
     interrupt: (params, toolCtx) => executeSubagentInterrupt(params, toolCtx),
@@ -702,10 +739,11 @@ export default function subagentPlugin(ctx: Context): void {
       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 id (herdr pane id)' })),
+      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)' })),
     }),
+    outputSchema: SUBAGENT_OUTPUT_SCHEMA,
     // B2: `action` is optional in the schema; normalize it so the validated arguments and the
     // code path never disagree and `spawn` is explicit in logs.
     prepareArguments: (args: unknown) => {
@@ -722,7 +760,7 @@ export default function subagentPlugin(ctx: Context): void {
       if (!handler) {
         return toolError(`Error: unknown action "${action}" (valid: ${Object.keys(ACTIONS).join(', ')})`);
       }
-      return handler(flat, toolCtx, onUpdate);
+      return attachSubagentStructuredContent(action, await handler(flat, toolCtx, onUpdate));
     },
   });
 }

package/src/plugins/terminal.ts

@@ -6,7 +6,7 @@
  */
 import { Context } from '@deepseek-ai/cordis';
 import { Type } from 'typebox';
-import type { PiSurface } from '../pi-surface.ts';
+import { cordisGet } from '../cordis-services.ts';
 import type { HerdrClientLike } from '../herdr-client.ts';
 import { herdrUnavailableHint } from '../herdr-client.ts';
 import { toolError } from '../tool-error.ts'
@@ -23,7 +23,7 @@ import {
   detectFullscreenTUI,
   foldTerminalsRegistry,
   makeTerminalsRegistry,
-  planIdleTerminalReminder,
+  planTerminalReminder,
   planShellInit,
   promptStrategyFor,
   registerTerminal,
@@ -52,15 +52,15 @@ export interface TerminalStateSlot {
   activePaneIds: () => Set<string>;
 }
 
-interface TerminalDeps {
+export interface TerminalDeps {
   client: HerdrClientLike;
   env: { paneId: string; tabId: string } | null;
   state: TerminalStateSlot;
 }
 
 export default function terminalPlugin(ctx: Context): void {
-  const surface = ctx.get('pi-herdr.surface') as PiSurface<object>;
-  const { client, env, state } = ctx.get('pi-herdr.terminal-deps') as TerminalDeps;
+  const surface = cordisGet(ctx, 'pi-herdr.surface');
+  const { client, env, state } = cordisGet(ctx, 'pi-herdr.terminal-deps');
   const pi = surface.raw as {
     appendEntry?: (customType: string, data: unknown) => void;
   };
@@ -129,17 +129,20 @@ export default function terminalPlugin(ctx: Context): void {
     persistTerminals();
   });
 
-  // Turn-end nudge: remind the model to close terminals idle past the threshold. Same delivery
-  // shape as the todo stop reminder: grace window, cancel on agent_start, capped followUp.
+  // Turn-end nudge: remind the model to close terminals it just used, then once more after the idle
+  // threshold. Same delivery shape as the todo stop reminder: grace window, cancel on agent_start,
+  // capped per terminal.
   const piSend = surface.raw as {
     sendMessage?: (
       message: { customType: string; content: string; display?: boolean },
       opts?: { deliverAs?: string; triggerTurn?: boolean },
     ) => void;
   };
-  let idleReminders = 0;
+  /** Start of the current agent run; terminals touched since then count as "used this turn". */
+  let turnStartedAt: number | null = null;
   let idleReminderTimer: NodeJS.Timeout | null = null;
   scoped.on('agent_start', () => {
+    turnStartedAt = Date.now();
     if (idleReminderTimer !== null) {
       clearTimeout(idleReminderTimer);
       idleReminderTimer = null;
@@ -150,19 +153,33 @@ export default function terminalPlugin(ctx: Context): void {
       clearTimeout(idleReminderTimer);
       idleReminderTimer = null;
     }
-    const plan = planIdleTerminalReminder({
-      open: terminals.filter((t) => t.status === 'open'),
+    const open = await Promise.all(
+      terminals
+        .filter((t) => t.status === 'open')
+        .map(async (t) => {
+          // A pane running a foreground job (dev server, REPL, load test) is in use even when the
+          // last tool interaction is old: nudge only after it is back at a shell prompt.
+          const info = await client.processInfo(t.paneId).catch(() => null);
+          const busy = info?.shellPid != null
+            && info.foreground.some((p) => p.pid != null && p.pid !== info.shellPid);
+          return { ...t, busy };
+        }),
+    );
+    const plan = planTerminalReminder({
+      open,
       now: Date.now(),
-      reminders: idleReminders,
+      turnStartedAt,
     });
+    turnStartedAt = null;
     if (!plan.due || plan.content == null) return;
-    // Goodbye-loop guard: mark the covered terminals nudged NOW (persisted), and deliver the notice as a
-    // queued followUp WITHOUT triggerTurn — a reminder must never wake the agent, or the loop never ends.
+    // Goodbye-loop guard: bump each covered terminal's nudge count NOW (persisted), and deliver the
+    // notice as a queued followUp WITHOUT triggerTurn — a reminder must never wake the agent.
     const now = Date.now();
     const ids = new Set(plan.ids);
-    terminals = terminals.map((t) => (ids.has(t.terminalId) ? { ...t, nudgedAt: now } : t));
+    terminals = terminals.map((t) => (ids.has(t.terminalId)
+      ? { ...t, nudges: (t.nudges ?? (t.nudgedAt != null ? 1 : 0)) + 1, nudgedAt: now }
+      : t));
     persistTerminals();
-    idleReminders += 1;
     const content = plan.content;
     idleReminderTimer = setTimeout(() => {
       idleReminderTimer = null;
@@ -345,6 +362,8 @@ export default function terminalPlugin(ctx: Context): void {
   async function executeTerminalWait(params: ToolParams) {
     const entry = findOpenTerminal(params?.terminal_id);
     if (!entry) return fail(`unknown or closed terminal "${String(params?.terminal_id)}" (see action list)`);
+    // Waiting on a pane is use: keep it out of the "used this turn" cleanup nudge at settle.
+    touchTerminal(entry);
     const raw = typeof params?.pattern === 'string' ? params.pattern : '';
     if (!raw) return fail('pattern is required (literal text, or a regular expression with regex: true)');
     const useRegex = params?.regex === true;

package/src/plugins/todo.ts

@@ -7,16 +7,17 @@
  */
 import { Context } from '@deepseek-ai/cordis';
 import { Type } from 'typebox';
-import type { PiSurface } from '../pi-surface.ts';
+import { cordisGet } from '../cordis-services.ts';
 import type { TodosService } from '../todos-service.ts';
-import { planTodoReadHook } from '../todo-read-hook.ts';
+import { planTodoReadHook, shouldRunTodoRead } from '../todo-read-hook.ts';
 import { TODO_REMINDER_CUSTOM_TYPE, planStopTodoReminder, todoReminderGraceMs } from '../todo-reminder-core.ts';
 import { makeProgressUpdate } from '../subagent-core.ts';
 import { TODO_DETAILS_KEY, TODO_STATUSES, TODO_TOOL_NAME, formatTodoConfirmation, type TodoItem } from '../vocab.ts';
 import { toolError } from '../tool-error.ts';
 import { formatAge, isArchived } from '../stale-core.ts';
 import { TODO_EDIT_CUSTOM_TYPE, completionTransitions, fuzzyFind, listsEqual, makeSnapshot, normalizeStrict, revertedCompleted, validateTodos, type TodoEditOp } from '../todo-core.ts';
-import { anchorTodoRange, formatTodoSummary, renderTodoGroups } from '../todo-window.ts';
+import { formatTodoSummary, renderTodoGroups } from '../todo-window.ts';
+import { unifiedWidgetLines, type WorkerWidgetRow } from '../tree-view.ts';
 import { swallow } from '../swallow.ts';
 
 type ToolParams = Record<string, unknown> | undefined;
@@ -29,7 +30,7 @@ export interface TodoUiSlot {
   cancelReminder?: () => void;
 }
 
-interface TodoDeps {
+export interface TodoDeps {
   todos: TodosService;
   allowParallelInProgress: boolean;
   /** Warn above this size without rejecting otherwise valid plans. */
@@ -39,6 +40,8 @@ interface TodoDeps {
   state: TodoUiSlot;
   /** Human-gate depth (ask_user_question / herdr:blocked); >0 collapses the widget to one line. */
   getBlockedDepth?: () => number;
+  /** D113: running subagent rows for the unified widget; master mounts only. */
+  getWorkers?: () => readonly WorkerWidgetRow[];
   /** Master-only unfinished-todo reminder; omitted on worker panes. */
   stopReminder?: {
     getBlockedDepth: () => number;
@@ -58,8 +61,6 @@ const TOOL_DESCRIPTION = [
   'Delegated work belongs on this list too. When you hand an entry to a subagent, append ` <sub>` to its content (the subagent is doing it, not you); when the subagent settles, a matching entry is auto-completed — you will see "Reconciled:" in the settlement note. If no auto-match fired, update the entry yourself.',
 ].join(' ');
 
-/** pi interactive mode renders at most ten widget lines. */
-const WIDGET_MAX_LINES = 10;
 
 /** `/todos <op> <query>` verbs; the value is the user-facing past-tense feedback. */
 const OP_VERBS: Record<TodoEditOp, string> = {
@@ -69,48 +70,21 @@ const OP_VERBS: Record<TodoEditOp, string> = {
   rm: 'removed',
 };
 
-/**
- * Keep the active task visible within WIDGET_MAX_LINES rather than truncating to a fixed head or tail:
- * the window anchors on the first in-progress item, then the last open item, then recent completions.
- */
+/** D113 unified resident widget (see tree-view.ts for the line rules). */
 export function widgetLines(
   items: readonly TodoItem[],
-  opts?: { archivedAgeMs?: number | null; blockedDepth?: number | null },
+  opts?: { archivedAgeMs?: number | null; blockedDepth?: number | null; workers?: readonly WorkerWidgetRow[] },
 ): string[] {
-  if (items.length === 0) return [];
-  // Human gate open (ask_user_question waiting): the question and editor own the fixed area, so the widget
-  // collapses to one summary line — a 10-line widget plus a multi-line question would leave no scrollable transcript.
-  if ((opts?.blockedDepth ?? 0) > 0) {
-    return [`${formatTodoSummary(items)} · /todos 全量`];
-  }
-  // Collapse archived plans to two lines so stale work cannot monopolize the widget.
-  if (opts?.archivedAgeMs != null) {
-    return [
-      `${formatTodoSummary(items)} · archived ${formatAge(opts.archivedAgeMs)}`,
-      '  archived — /todos 全量',
-    ];
-  }
-
-  // Reserve summary and overflow lines; phase headers consume the budget too, hence the shrink loop.
-  const renderBudget = WIDGET_MAX_LINES - 2;
-  const [start, end] = anchorTodoRange(
-    items,
-    (s, e) => renderTodoGroups(items.slice(s, e)).length <= renderBudget,
-  );
-  const kept = items.slice(start, end);
-  const hidden = items.filter((_, i) => i < start || i >= end);
-  const lines = [formatTodoSummary(items), ...renderTodoGroups(kept)];
-  if (hidden.length > 0) {
-    const hiddenCompleted = hidden.filter((it) => it.status === 'completed').length;
-    lines.push(`   +${hidden.length} hidden (${hiddenCompleted}✓) · /todos 全量`);
-  }
-  return lines;
+  return unifiedWidgetLines(items, opts?.workers ?? [], {
+    archivedAgeMs: opts?.archivedAgeMs,
+    blockedDepth: opts?.blockedDepth,
+  });
 }
 
 export default function todoPlugin(ctx: Context): void {
-  const surface = ctx.get('pi-herdr.surface') as PiSurface<object>;
-  const { todos, allowParallelInProgress, maxItems, mirrorTodos, appendEntry, state, stopReminder, getBlockedDepth } =
-    ctx.get('pi-herdr.todo-deps') as TodoDeps;
+  const surface = cordisGet(ctx, 'pi-herdr.surface');
+  const { todos, allowParallelInProgress, maxItems, mirrorTodos, appendEntry, state, stopReminder, getBlockedDepth, getWorkers } =
+    cordisGet(ctx, 'pi-herdr.todo-deps');
   const scoped = surface.forModule(import.meta.url);
 
   /** Share one archive-age decision between the widget and /todos. */
@@ -129,6 +103,7 @@ export default function todoPlugin(ctx: Context): void {
       ui?.setWidget?.('todos', widgetLines(todos.items, {
         archivedAgeMs: archivedAgeMs(),
         blockedDepth: getBlockedDepth?.() ?? 0,
+        workers: getWorkers?.() ?? [],
       }));
     } catch {
       /* Older pi versions may omit widget support without disabling todo tracking. */
@@ -152,6 +127,9 @@ export default function todoPlugin(ctx: Context): void {
   });
 
   scoped.on('before_agent_start', async (eventCtx?: unknown) => {
+    // pi 1.2+ also fires this for extension-triggered runs; skip the ones that would double-inject
+    // or consume the guard cadence (stop reminder, config guide, third-party custom runs).
+    if (!shouldRunTodoRead(eventCtx)) return;
     const plan = planTodoReadHook({
       items: todos.items,
       turn: todoReadTurn,

package/src/reducer-core.ts

@@ -1,5 +1,6 @@
 /** D102 Evidence-Preserving Reducer core: diagnostic-command recognition, secret filtering, receipt
  * schema checking, byte-for-byte quote verification (storage I/O lives in efficiency-store.ts). */
+import { isPlainObject } from './guards.ts';
 
 import { createHash } from 'node:crypto';
 
@@ -104,9 +105,6 @@ function stripReceiptJsonFences(raw: string): string {
   return fenced?.[1]?.trim() ?? trimmed;
 }
 
-function isRecord(v: unknown): v is Record<string, unknown> {
-  return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
 
 function lineNumberOf(body: string, quote: string): number | undefined {
   const index = body.indexOf(quote);
@@ -168,7 +166,7 @@ export function validateReceipt(
     return { ok: false, reason: 'invalid-json' };
   }
 
-  if (!isRecord(parsed)) {
+  if (!isPlainObject(parsed)) {
     return { ok: false, reason: 'schema-mismatch' };
   }
 
@@ -189,7 +187,7 @@ export function validateReceipt(
   const seen = new Set<string>();
 
   for (const item of parsed.evidence) {
-    if (!isRecord(item)) {
+    if (!isPlainObject(item)) {
       return { ok: false, reason: 'schema-mismatch' };
     }
     const kind = item.kind;

package/src/renderers.ts

@@ -4,7 +4,8 @@
  * needed and older pi builds degrade to "no renderer".
  */
 import { TODO_EDIT_CUSTOM_TYPE, type TodoEditPayload } from './todo-core.ts';
-import { SUBS_CUSTOM_TYPE, type SubsRegistry } from './subagent-core.ts';
+import { SUBS_CUSTOM_TYPE, PROGRESS_CUSTOM_TYPE, subRef, type SubsRegistry } from './subagent-core.ts';
+import { DELEGATION_CUSTOM_TYPE } from './delegation-core.ts';
 import { TERMINALS_CUSTOM_TYPE, TERM_REMINDER_CUSTOM_TYPE, type TerminalsRegistry } from './terminal-core.ts';
 import { TODO_REMINDER_CUSTOM_TYPE } from './todo-reminder-core.ts';
 
@@ -94,10 +95,31 @@ function subsLines(data: unknown, theme: RenderTheme, expanded: boolean): string
     label: 'subagents',
     unit: 'tracked',
     ...(running ? { badge: `${running} running` } : {}),
-    row: (sub) => `  ${sub.status === 'running' ? '●' : '○'} ${sub.paneId} · ${sub.status} · ${clip(String(sub.description ?? ''), 70)}`,
+    // Every registry row IS a delegated worker (↳ marks the delegation edge; status text carries state).
+    row: (sub) => `  ↳ ${subRef(sub)} · ${sub.status} · ${clip(String(sub.description ?? ''), 70)}`,
   });
 }
 
+/** First-frame delegation card in the worker's own transcript (RFC rfc-delegation-identity §2.3). */
+function delegationLines(data: unknown, theme: RenderTheme, expanded: boolean): string[] {
+  const rec = (data ?? {}) as {
+    parentPaneId?: unknown;
+    parentSessionId?: unknown;
+    taskId?: unknown;
+    description?: unknown;
+    role?: unknown;
+  };
+  const parent = typeof rec.parentPaneId === 'string' && rec.parentPaneId ? rec.parentPaneId : '?';
+  const head = `${theme.fg('accent', '⟵ delegated')} ${theme.fg('dim', `by master ${parent} · ${clip(String(rec.description ?? ''), 60)}`)}`;
+  if (!expanded) return [head];
+  const session = typeof rec.parentSessionId === 'string' && rec.parentSessionId ? rec.parentSessionId : '?';
+  const role = typeof rec.role === 'string' && rec.role ? rec.role : '?';
+  return [
+    head,
+    theme.fg('dim', `  task ${typeof rec.taskId === 'string' ? rec.taskId : '?'} · role ${role} · parent session ${session}`),
+  ];
+}
+
 function terminalsLines(data: unknown, theme: RenderTheme, expanded: boolean): string[] {
   const terminals = (data as TerminalsRegistry | undefined)?.terminals;
   return registryLines(Array.isArray(terminals) ? terminals : undefined, theme, expanded, {
@@ -137,6 +159,17 @@ function approvalLines(data: unknown, theme: RenderTheme): string[] {
   return [`${theme.fg('warning', '⚠ approval needed')} ${theme.fg('dim', `· ${tool} (${role})`)}`];
 }
 
+/** Phase 2: worker progress note (display-less custom message) as a one-line card — the sender
+ * pane rides `details.paneId`; keep it recognizable without flooding the transcript. */
+function progressLines(message: unknown, theme: RenderTheme, expanded: boolean): string[] {
+  const rec = (message ?? {}) as { content?: unknown; details?: { paneId?: unknown } };
+  const from = typeof rec.details?.paneId === 'string' && rec.details.paneId ? rec.details.paneId : '?';
+  const content = typeof rec.content === 'string' ? rec.content : '';
+  const head = `${theme.fg('accent', '⤴ progress')} ${theme.fg('dim', `· ${from}: ${clip(content, 100)}`)}`;
+  if (!expanded) return [head];
+  return [head, ...content.split('\n').map((line) => theme.fg('dim', line))];
+}
+
 /** Reminder custom messages carry the full injected text; restyle without altering it. */
 function reminderLines(message: unknown, theme: RenderTheme, label: string, expanded: boolean): string[] {
   const content = typeof (message as { content?: unknown } | undefined)?.content === 'string'
@@ -179,8 +212,10 @@ export function installRenderers(pi: unknown): string[] {
   entry(TODO_EDIT_CUSTOM_TYPE, todoEditLines);
   entry(SUBS_CUSTOM_TYPE, subsLines);
   entry(TERMINALS_CUSTOM_TYPE, terminalsLines);
+  entry(DELEGATION_CUSTOM_TYPE, delegationLines);
   entry(ROLE_MANIFEST_CUSTOM_TYPE, (data, theme) => roleManifestLines(data, theme));
   entry(APPROVAL_NEEDED_CUSTOM_TYPE, (data, theme) => approvalLines(data, theme));
+  message(PROGRESS_CUSTOM_TYPE, progressLines);
   message(TODO_REMINDER_CUSTOM_TYPE, (msg, theme, expanded) => reminderLines(msg, theme, 'todo reminder', expanded));
   message(TERM_REMINDER_CUSTOM_TYPE, (msg, theme, expanded) => reminderLines(msg, theme, 'terminal nudge', expanded));
   return registered;

package/src/role-manifest.ts

@@ -4,6 +4,8 @@
  * top-level keys are reported (a typo like "rulez" must not silently fail) and every issue is
  * collected in one pass so a manifest can be repaired in one go.
  */
+import { isPlainObject } from './guards.ts';
+
 export type PermissionAction = 'allow' | 'ask' | 'deny';
 export type TodosMode = 'serial' | 'parallel';
 /** D82: stance for unknown tools—visibility is a trust relationship (user→master via install; master→delegated via mirror). */
@@ -47,9 +49,6 @@ const SEMVER_RE = /^\d+\.\d+\.\d+$/;
 const TOOL_KEY_RE = /^[a-z0-9_*-]+$/;
 const ACTIONS: readonly PermissionAction[] = ['allow', 'ask', 'deny'];
 
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
 
 export function validateRoleManifest(input: unknown): ValidateResult {
   const issues: string[] = [];

package/src/roles/worker-default.json

@@ -1,11 +1,11 @@
 {
   "role": "worker-default",
-  "version": "1.4.0",
-  "description": "默认worker角色（D83 继承制）：镜像 master.tools 减 subagent/terminal（禁嵌套、资源归属）；排除族显式 deny——在 D82 unknownTools=allow 姿态下仍持禁令；todos serial。v1.4.0: 工具合并后更新 deny 列表",
+  "version": "1.5.0",
+  "description": "默认worker角色（D83 继承制）：镜像 master.tools 减 subagent/terminal（禁嵌套、资源归属）；排除族显式 deny——在 D82 unknownTools=allow 姿态下仍持禁令；todos serial。v1.5.0: Phase 2 显式放行 report_progress（worker→master 检查点上报）；v1.4.0: 工具合并后更新 deny 列表",
   "manifest": {
     "unknownTools": "allow",
     "tools": [
-      "todo_write", "ask_user_question",
+      "todo_write", "ask_user_question", "report_progress",
       "read", "grep", "glob", "bash", "pwsh", "edit", "write",
       "web_search"
     ],