pi-pier 0.1.2 → 0.1.3

package/README.md

@@ -1,22 +1,40 @@
 # pi-pier
 
+> [!IMPORTANT]
+> **This npm package is only the pi-extension half of pier.** pier is a two-half system — this extension plus a **herdr plugin** (`pier.workbench`). Without the herdr side you still get `todo_write` / `ask_user_question`, but subagents, pane integration, notifications, and the workspace bootstrap all require herdr. See [Install the herdr half](#install-the-herdr-half-companion-plugin) below.
+
 **pier** = **pi** × h**erdr** — a [pi](https://pi.dev/) extension that fuses coding agent sessions with the [herdr](https://herdr.dev/) pane/tab orchestrator.
 
-`pi-pier` is the **pi extension half** of the [pier monorepo](https://github.com/July24/pier). It fills two gaps pi deliberately leaves open — the **todo list loop** and **interactive subagents** — using herdr panes/tabs as the visual and interaction substrate. It degrades gracefully outside herdr.
+`pi-pier` fills two gaps pi deliberately leaves open — the **todo list loop** and **interactive subagents** — using herdr panes/tabs as the visual and interaction substrate. It degrades gracefully outside herdr.
 
-## Install
+## Install (this pi half)
 
 ```sh
 pi install npm:pi-pier
 ```
 
-Or from git:
+Or from git (monorepo root, same content):
 
 ```sh
 pi install git:github.com/July24/pier
 ```
 
-> The companion **herdr plugin half** (`pier.workbench`: main-tab bootstrap, blocked-gate notifications, focus-heat layout) is installed separately via `herdr plugin install July24/pier/packages/pier-workbench`, or all at once with the one-shot installer in the [repo](https://github.com/July24/pier): `node install.mjs`.
+## Install the herdr half (companion plugin)
+
+The herdr plugin `pier.workbench` provides the other half: main-tab bootstrap (auto-start a pi master session per workspace), blocked-gate notifications (system notifications when a subagent waits for a human), and the focus-heat layout (focused pane grows in place). Install it from the same repo:
+
+```sh
+herdr plugin install July24/pier/packages/pier-workbench --yes
+```
+
+Or install **both halves at once** with the one-shot installer from the monorepo:
+
+```sh
+git clone https://github.com/July24/pier && cd pier
+node install.mjs        # user mode: installs both halves + generates local bootstrap config
+```
+
+The installer also verifies node / pi / herdr versions, probes local paths, and writes the workbench bootstrap config (`boot-config.json`) into herdr's plugin config dir.
 
 ## What you get
 
@@ -45,7 +63,7 @@ Outside a herdr environment the extension auto-degrades: herdr reporting costs n
 
 - Node ≥ 22
 - pi ≥ 0.84 (`@earendil-works/pi-coding-agent`)
-- herdr ≥ 0.8.0 for the full pane experience (optional)
+- **herdr ≥ 0.8.0** — required for subagents / pane integration / notifications (see the IMPORTANT note above); without it only `todo_write` / `ask_user_question` work
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pier",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "pier: pi extension that fuses pi agent sessions with the herdr pane/tab orchestrator — todo_write loop closure + interactive subagents in isolated panes",
   "license": "MIT",
   "type": "module",

package/src/core/subagent.ts

@@ -21,7 +21,7 @@ import type { PiSurface } from '../pi-surface.ts';
 import type { HerdrClientLike, HerdrAgentState } from '../herdr-client.ts';
 import type { TodosService } from '../todos-service.ts';
 import { mountSubagentScope } from '../subagent-scope.ts';
-import { Semaphore, SUBS_CUSTOM_TYPE, buildLaunchLine, classifyWorktreeZone, foldSubsRegistry, formatSubagentResult, isPathUnder, makeProgressUpdate, makeRegistry, planTabPlacement, tabNameForTask, type SubEntry, type SubagentSpec, type TabPlacementPlan, type WorktreeZone } from '../subagent-core.ts';
+import { Semaphore, SUBS_CUSTOM_TYPE, agoText, buildAliveNotice, buildBlockedGateNotice, buildLaunchLine, classifyWorktreeZone, foldSubsRegistry, formatSubagentResult, isAlive, isPathUnder, makeProgressUpdate, makeRegistry, planTabPlacement, psQuote, tabNameForTask, type AliveProbe, type SubEntry, type SubagentSpec, type TabPlacementPlan, type WorktreeZone } from '../subagent-core.ts';
 import { hasAssistantAfter, hasPendingToolCall, lastAssistantText, listSessionFiles, readSessionFile, sessionFileById } from '../session-tail.ts';
 import { appendHistory, applyReportedSessionFile, historyFilePath, latestGeneration, normalizeEntryKind, readHistory, type HistoryEntry } from '../history-store.ts';
 import { execFile } from 'node:child_process';
@@ -130,6 +130,9 @@ export default function subagentPlugin(ctx: Context): void {
     }
   }
 
+  /** E2：已发过闸门通知的 pane（blocked 期间去重；解除后移除，二次 ask 可再通知）。 */
+  const blockedGateNotified = new Set<string>();
+
   // slots 回填：common 段 pipe reply 消费
   slots.applyReplySession = (paneId, sessionFile) => {
     const entry = subs.get(paneId);
@@ -169,6 +172,35 @@ export default function subagentPlugin(ctx: Context): void {
     rebuildSubs(eventCtx);
   });
 
+  /* ── B1（用户实证修复）：subagent isError 结果的探活改写 ──────────────
+   * 实测事故：前台误判 no-output → 模型读裸错误文案 → "failed, 我自己干" 抢活。
+   * pi 的 tool_result 事件官方语义 "Can modify result"——在文本进模型上下文前，
+   * 当场探活（agent.list + 会话 mtime）；判活则改写为统一存活通知（buildAliveNotice
+   * 与 A2 转后台同一出口）。hook 层硬保障，纯 prompt 防不住的自作主张在此物理拦截。 */
+  scoped.on('tool_result', async (event: { toolName?: string; toolCallId?: string; isError?: boolean; content?: Array<{ type: string; text?: string }> }) => {
+    if (event?.toolName !== 'subagent' || !event.isError) return;
+    // 从错误文本里取 pane id（我们自己的错误文案都带 pane）；取不到则不改写
+    const errText = (event.content ?? []).map((c) => c.text ?? '').join(' ');
+    const paneId = [...subs.keys()].find((id) => errText.includes(id))
+      ?? (errText.match(/\bw[A-Za-z0-9]+:p\d+\b/) ?? [])[0];
+    if (!paneId) return;
+    const entry = subs.get(paneId);
+    if (!entry || entry.status === 'settled' || entry.status === 'consumed') return;
+    const probe = await probeAlive(paneId, entry.cwd);
+    if (!isAlive(probe, Date.now())) return; // 真死了 → 保留原错误，模型可重做
+    // 活着 → 转 poller（若尚未在跑）并改写结果文本
+    if (!pollers.has(paneId)) {
+      entry.background = true;
+      startPoller(paneId, entry.cwd, entry.createdAt, entry.createdAt, entry.description, lastRequestIdByPane.get(paneId) ?? `probe-${paneId}`);
+      persistSubs();
+    }
+    const notice = buildAliveNotice(
+      { paneId, description: entry.description, scenario: 'error-alive', probe },
+      Date.now(),
+    );
+    return { content: [{ type: 'text', text: notice }] };
+  });
+
   /* ── D41：stop 未完成提醒（仅主控；子代理不注册本块） ── */
 
   let todoReminders = 0;
@@ -253,6 +285,39 @@ export default function subagentPlugin(ctx: Context): void {
     return null;
   }
 
+  /** E1/E2：读子 pane 的人类闸门问题（tokens['pi-ask']；子扩展 reportAskFlag 上报）。 */
+  async function readAskFlag(paneId: string): Promise<string | null> {
+    try {
+      const a = (await client.listAgents()).find((x) => x.paneId === paneId);
+      const v = a?.tokens?.['pi-ask'];
+      return typeof v === 'string' && v ? v : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** A2/B1 探活：pane 实时状态 + 会话候选最新 mtime（毫秒级，失败字段为 null）。 */
+  async function probeAlive(paneId: string, cwd: string): Promise<AliveProbe> {
+    const probe: AliveProbe = { paneExists: false, agentStatus: null, lastActivityMs: null };
+    try {
+      const agents = await client.listAgents();
+      const a = agents.find((x) => x.paneId === paneId);
+      probe.paneExists = a != null;
+      probe.agentStatus = a?.status ?? null;
+    } catch {
+      /* agent.list 失败 → 状态未知，靠会话活动判定 */
+    }
+    for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
+      try {
+        const mtime = (await statAsync(file)).mtimeMs;
+        if (probe.lastActivityMs == null || mtime > probe.lastActivityMs) probe.lastActivityMs = mtime;
+      } catch {
+        /* 文件消失跳过 */
+      }
+    }
+    return probe;
+  }
+
   /**
    * 子会话结算状态（v1.3 M8 结算竞态修复）：
    *  herdr 的 idle/done 在"注入瞬间"也是真，不能当结算信号；
@@ -275,21 +340,6 @@ export default function subagentPlugin(ctx: Context): void {
     return { text: null, pendingTool: false, activity: false };
   }
 
-  /** 等待结算：idle/done=settled、blocked=人类闸门、超时切片循环。 */
-  async function waitSubSettled(
-    paneId: string,
-    timeoutMs: number,
-  ): Promise<'settled' | 'blocked' | 'timeout'> {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-      const state = await client.waitAgent(paneId, ['idle', 'done', 'blocked'], 30000);
-      if (state === 'idle' || state === 'done') return 'settled';
-      if (state === 'blocked') return 'blocked';
-      // null = 30s 切片超时（working 中或异常），继续
-    }
-    return 'timeout';
-  }
-
   /** D92：结算通知统一出口——经 deps 缓冲（忙时 turn_end 折叠注入），缺省回退旧 followUp 直投。 */
   const injectNotice = (content: string): Promise<void> =>
     d.deliverNotice ? d.deliverNotice(content)
@@ -360,7 +410,22 @@ export default function subagentPlugin(ctx: Context): void {
         } catch {
           state = null;
         }
-        if (state === 'blocked') continue; // 人类闸门：保持 running，通知钩子已触发
+        if (state === 'blocked') {
+          // E2（人类闸门）：blocked 时 master 对话流里也要知道（此前只有 herdr 系统
+          // 通知发给人类，master 毫不知情 → 可能自作主张揽活）。一次性 gate 通知注入；
+          // 解除（idle）后重置，二次 ask 新问题可再通知。
+          if (!blockedGateNotified.has(paneId)) {
+            blockedGateNotified.add(paneId);
+            const question = await readAskFlag(paneId);
+            try {
+              await injectNotice(buildBlockedGateNotice({ paneId, description, question }));
+            } catch {
+              /* 注入失败静默（下次 turn 可 list_agents 自查） */
+            }
+          }
+          continue; // 人类闸门：保持 running
+        }
+        if (state !== null) blockedGateNotified.delete(paneId); // 闸门解除（working/idle）
         if (state === 'idle' || state === 'done') {
           const s = await subSessionState(paneId, cwd, injectTs);
           if (s.text || (!s.pendingTool && s.activity)) {
@@ -961,52 +1026,69 @@ export default function subagentPlugin(ctx: Context): void {
         entry.sessionFile = await resolveSessionFile(paneId, cwd);
         subs.set(paneId, entry);
         persistSubs();
-        writeHistory(entry);
-        onUpdate?.(makeProgressUpdate(`subagent ready in pane ${paneId}; injecting prompt via pipe…`));
         // M11（D45/D46）：注入走扩展管道 → 子扩展 sendUserMessage(followUp)；
-        // PTY 键盘通道 100% 归人（无软锁窗口、无混行）。
-        const injectTs = Date.now();
-        const injected = await pipeRequest(pipeNameFor(cwd, paneId), {
-          type: 'prompt',
-          id: `prompt-${taskId}`,
-          text: spec.prompt,
-          from: pipeNameFor(cwd, env?.paneId ?? ''),
-          push: background,
-        });
-        if (injected.type !== 'ok') {
-          throw new Error(`pipe prompt rejected: ${injected.type === 'error' ? injected.message : 'unknown response'}`);
-        }
-
-        if (background) {
-          lastRequestIdByPane.set(paneId, `prompt-${taskId}`);
-          startPoller(paneId, cwd, spawnedAt, injectTs, spec.description, `prompt-${taskId}`);
-          return {
-            content: [{ type: 'text', text: `started subagent ${paneId} (task ${taskId})` }],
-            details: { paneId, taskId, background: true, role: kind },
-          };
-        }
-
-        let settled = await waitSubSettled(paneId, SUBAGENT_TIMEOUT_MS);
-        let text = await collectFinalText(paneId, cwd, injectTs);
-        // v1.3 M8：早结算竞态（注入瞬间 herdr 仍是 idle）→ 无文本时再等真实结算（最多 90s）
-        if (settled === 'settled' && !text) {
-          const reDeadline = Date.now() + 90000;
-          while (Date.now() < reDeadline) {
-            await new Promise((r) => setTimeout(r, 3000));
-            const st = await client.waitAgent(paneId, ['idle', 'done', 'blocked'], 15000);
-            if (st === 'blocked') {
-              settled = 'blocked';
-              break;
-            }
-            if (st === 'idle' || st === 'done') {
-              text = await collectFinalText(paneId, cwd, injectTs);
-              if (text) break;
+        // A1+A2（用户实证修复）：前台等待 = 内容闸 + 耐心阈值转后台。
+        // 旧实现的 idle 即结算 + 90s 硬窗口在真实任务（working 期 4-6 分钟）上必然误判
+        // no-output（实测：3 个健康子代理 101s 时被同时 consumed，成果 4 分钟后才产出）。
+        const PATIENCE_MS = Number(process.env.PI_HERDR_FRONTIER_PATIENCE_MS ?? 300000) || 300000;
+        const patienceDeadline = Date.now() + PATIENCE_MS;
+        let text: string | null = null;
+        let settledKind: 'settled' | 'timeout' = 'timeout';
+        while (Date.now() < Math.min(patienceDeadline, spawnedAt + SUBAGENT_TIMEOUT_MS)) {
+          const state = await client.waitAgent(paneId, ['idle', 'done', 'blocked'], 30_000);
+          if (state === 'blocked') {
+            // E1（人类闸门）：blocked 不是终态——转后台 poller（人类答后续跑、结算自动通知），
+            // 返回 gate 通知：不揽活、提醒用户去 pane 答题、授权例外经 send_message 转达。
+            const question = await readAskFlag(paneId);
+            entry.background = true;
+            lastRequestIdByPane.set(paneId, `prompt-${taskId}`);
+            startPoller(paneId, cwd, spawnedAt, injectTs, spec.description, `prompt-${taskId}`);
+            persistSubs();
+            writeHistory(entry);
+            return {
+              content: [{ type: 'text', text: buildBlockedGateNotice({ paneId, description: spec.description, question }) }],
+              details: { paneId, taskId, background: true, blocked: true, role: kind },
+            };
+          }
+          if (state === 'idle' || state === 'done') {
+            // A1 内容闸：herdr idle 只是"可能是结算"——以会话内容定夺
+            const s = await subSessionState(paneId, cwd, injectTs);
+            if (s.text) { text = s.text; settledKind = 'settled'; break; }
+            if (s.pendingTool || (!s.text && !s.activity)) {
+              // 挂起 toolCall（等人类）或注入前瞬间的 idle → 不当结算，继续观察
+              await new Promise((r) => setTimeout(r, 2000));
+              continue;
             }
+            // 有活动无文本（活动已停止）→ 再给 collectFinalText 的重试窗口
+            text = await collectFinalText(paneId, cwd, injectTs, 6);
+            if (text) { settledKind = 'settled'; break; }
+            await new Promise((r) => setTimeout(r, 2000));
+            continue;
           }
+          // null = 30s 切片超时（working 中）→ 继续循环
+        }
+        // A2 耐心阈值到点仍在跑 → 探活；活着 → 转后台并返回统一存活通知
+        if (!text && settledKind !== 'blocked') {
+          const probe = await probeAlive(paneId, cwd);
+          if (isAlive(probe, Date.now())) {
+            entry.background = true;
+            lastRequestIdByPane.set(paneId, `prompt-${taskId}`);
+            startPoller(paneId, cwd, spawnedAt, injectTs, spec.description, `prompt-${taskId}`);
+            persistSubs();
+            const notice = buildAliveNotice(
+              { paneId, description: spec.description, scenario: 'moved-to-bg', probe },
+              Date.now(),
+            );
+            return {
+              content: [{ type: 'text', text: notice }],
+              details: { paneId, taskId, background: true, movedToBackground: true, role: kind },
+            };
+          }
+          // 探活失败（pane 消失且会话沉寂）→ 保留原 timeout 语义
+          settledKind = 'timeout';
         }
         const outcome =
-          settled === 'blocked' ? { kind: 'blocked' as const, text: text ?? '' }
-          : settled === 'timeout' ? { kind: 'timeout' as const, text: text ?? '' }
+          settledKind === 'timeout' ? { kind: 'timeout' as const, text: text ?? '' }
           : text ? { kind: 'completed' as const, text }
           : { kind: 'no-output' as const, text: '' };
         entry.status = 'consumed';
@@ -1138,7 +1220,7 @@ export default function subagentPlugin(ctx: Context): void {
     name: 'list_agents',
     label: 'List Subagents',
     description:
-      'List the background subagents you started, with their live state: running (working or blocked), idle (settled), plus pane ids, role (task or a role label), and descriptions. Foreground one-shot panes are transient and not listed. Covers only this session branch — for tasks from earlier sessions or collected panes, read the delegation ledger (path and format in resume_subagent) and resume by taskId.',
+      'List the background subagents you started, with their live state: running (working or blocked), idle (settled), plus pane ids, live agent status, last session activity time, role (task or a role label), and descriptions. Foreground one-shot panes are transient and not listed. Covers only this session branch — for tasks from earlier sessions or collected panes, read the delegation ledger (path and format in resume_subagent) and resume by taskId.',
     parameters: Type.Object({}),
     async execute() {
       const listed = [...subs.values()].filter((s) => s.background);
@@ -1151,6 +1233,12 @@ export default function subagentPlugin(ctx: Context): void {
         const prev = byTask.get(sub.taskId);
         if (!prev || sub.createdAt >= prev.createdAt) byTask.set(sub.taskId, sub);
       }
+      // C1：实时探活（pane 状态 + 会话活动时间）——master 能区分"在干活"vs"真卡死"
+      const probes = new Map<string, AliveProbe>();
+      await Promise.all([...byTask.values()].map(async (sub) => {
+        if (sub.status === 'closed') return;
+        try { probes.set(sub.paneId, await probeAlive(sub.paneId, sub.cwd)); } catch { /* 显示层尽力 */ }
+      }));
       const lines: string[] = [];
       for (const sub of byTask.values()) {
         const tabTag = sub.tabName ? ` [tab: ${sub.tabName}]` : '';
@@ -1162,7 +1250,16 @@ export default function subagentPlugin(ctx: Context): void {
         const state = sub.status === 'settled' ? 'idle' : 'running';
         // D94：用户接管标记
         const takeoverMark = sub.userTakeover ? ', user-controlled' : '';
-        lines.push(`${sub.paneId} [${state}${takeoverMark}] (${sub.kind})${tabTag} ${sub.description}`);
+        const probe = probes.get(sub.paneId);
+        const statusTag = probe?.agentStatus ? ` ${probe.agentStatus}` : '';
+        const activityTag = probe?.lastActivityMs != null ? `, active ${agoText(probe.lastActivityMs, Date.now())}` : '';
+        // E：blocked 时附上闸门问题摘要（提示 master 该叫用户去 pane，不是自己接手）
+        let gateTag = '';
+        if (probe?.agentStatus === 'blocked') {
+          const q = await readAskFlag(sub.paneId);
+          gateTag = q ? ` — AWAITING HUMAN: "${q}"` : ' — AWAITING HUMAN decision';
+        }
+        lines.push(`${sub.paneId} [${state}${takeoverMark}${statusTag}${activityTag}${gateTag}] (${sub.kind})${tabTag} ${sub.description}`);
       }
       return { content: [{ type: 'text', text: lines.join('\n') }], details: {} };
     },

package/src/core/todo.ts

@@ -22,8 +22,8 @@ import { makeProgressUpdate } from '../subagent-core.ts';
 import { TODO_DETAILS_KEY, TODO_TOOL_NAME, formatTodoConfirmation, type TodoItem, type TodoStatus } from '../vocab.ts';
 import {
   TODO_EDIT_CUSTOM_TYPE,
-  boundedView,
   completionTransitions,
+  countTodos,
   fuzzyFind,
   listsEqual,
   makeSnapshot,
@@ -65,17 +65,11 @@ const TODO_MARKS: Record<TodoStatus, string> = {
   abandoned: '✗',
 };
 
-function widgetLines(items: TodoItem[]): string[] {
-  if (items.length === 0) return [];
-  const counts = { pending: 0, inProgress: 0, completed: 0, blocked: 0 };
-  for (const it of items) {
-    if (it.status === 'pending') counts.pending++;
-    else if (it.status === 'in_progress') counts.inProgress++;
-    else if (it.status === 'completed') counts.completed++;
-    else if (it.status === 'blocked') counts.blocked++;
-  }
-  const lines = [`todo: ${counts.inProgress}▶ ${counts.pending}○ ${counts.blocked}■ ${counts.completed}✓`];
-  // D43 phase 分组 + D39 有界（每组预算 10 行）
+/** pi TUI widget 硬上限（interactive-mode MAX_WIDGET_LINES=10，头部截断；我们自己控制在限内）。 */
+export const WIDGET_MAX_LINES = 10;
+
+/** 分组渲染（phase 头 + 条目行；不设预算，widget 与 /todos 共用）。 */
+function renderGroups(items: readonly TodoItem[]): string[] {
   const groups = new Map<string, TodoItem[]>();
   for (const it of items) {
     const key = it.phase ?? '';
@@ -83,16 +77,44 @@ function widgetLines(items: TodoItem[]): string[] {
     arr.push(it);
     groups.set(key, arr);
   }
+  const lines: string[] = [];
   for (const [phase, list] of groups) {
     if (phase) lines.push(`  [${phase}]`);
-    const view = boundedView(list, 10);
-    for (const it of view.visible) {
+    for (const it of list) {
       const suffix = it.status === 'blocked' && it.blocker ? ` — ${it.blocker}` : '';
       lines.push(`  ${TODO_MARKS[it.status]} ${it.content}${suffix}`);
     }
-    if (view.hiddenCompleted > 0 || view.hiddenOpen > 0) {
-      lines.push(`   +${view.hiddenCompleted + view.hiddenOpen} more (${view.hiddenCompleted} completed, ${view.hiddenOpen} open)`);
-    }
+  }
+  return lines;
+}
+
+/**
+ * widget 行（全局预算版，用户实证修复）：
+ * 旧实现按分组插入序逐组渲染（每组预算 10），pi 头部截 10 行 → 老 phase 吃光窗口、
+ * 最新任务组（in_progress 所在）整组不可见。新规则：
+ *  - 全局预算 = WIDGET_MAX_LINES（含摘要行与 +N 行）；
+ *  - 超额丢弃顺序 = 最老 completed → 最老 open（尾部/当前工作永远存活）；
+ *  - +N 行指路 /todos（全量视图）。
+ */
+export function widgetLines(items: readonly TodoItem[]): string[] {
+  if (items.length === 0) return [];
+  const c = countTodos(items);
+  const summary = `todo: ${c.inProgress}▶ ${c.pending}○ ${c.blocked}■ ${c.completed}✓`;
+
+  const kept = [...items];
+  while (
+    kept.length > 0
+    && 1 + renderGroups(kept).length + (items.length > kept.length ? 1 : 0) > WIDGET_MAX_LINES
+  ) {
+    const oldestCompleted = kept.findIndex((it) => it.status === 'completed');
+    kept.splice(oldestCompleted === -1 ? 0 : oldestCompleted, 1);
+  }
+
+  const hidden = items.filter((it) => !kept.includes(it));
+  const lines = [summary, ...renderGroups(kept)];
+  if (hidden.length > 0) {
+    const hiddenCompleted = hidden.filter((it) => it.status === 'completed').length;
+    lines.push(`   +${hidden.length} hidden (${hiddenCompleted}✓) · /todos 全量`);
   }
   return lines;
 }
@@ -181,8 +203,8 @@ export default function todoPlugin(ctx: Context): void {
               Type.Literal('blocked'),
               Type.Literal('abandoned'),
             ], { description: 'pending | in_progress | completed | blocked | abandoned' }),
-            blocker: Type.Optional(Type.String({ description: 'Only when status is "blocked": what it is waiting for' })),
-            phase: Type.Optional(Type.String({ description: 'Optional group name (≤30 chars); omit for a flat list' })),
+            blocker: Type.Optional(Type.String({ description: 'Only when status is "blocked": what it is waiting for. Omit the field entirely (never an empty string) for other statuses' })),
+            phase: Type.Optional(Type.String({ description: 'Optional group name (≤30 chars); omit for a flat list (never an empty string)' })),
           },
           { additionalProperties: false },
         ),
@@ -290,9 +312,14 @@ export default function todoPlugin(ctx: Context): void {
         ui?.notify?.(`"${content}" ${verb}`, 'info');
         return;
       }
-      const lines = widgetLines(todos.items);
-      const text = lines.length ? lines.join('\n') : 'todo list is empty';
-      ui?.notify?.(text, 'info');
+      // 全量视图（/todos 不受 widget 10 行预算限制——"看整个列表"的正式入口）
+      const body = renderGroups(todos.items);
+      if (body.length === 0) {
+        ui?.notify?.('todo list is empty', 'info');
+        return;
+      }
+      const c = countTodos(todos.items);
+      ui?.notify?.([`todo: ${c.inProgress}▶ ${c.pending}○ ${c.blocked}■ ${c.completed}✓`, ...body].join('\n'), 'info');
     },
   });
 

package/src/subagent-core.ts

@@ -98,6 +98,76 @@ export function formatSubagentResult(outcome: SubagentOutcome, description: stri
   }
 }
 
+/* ── 探活 + 存活通知（A2/B1 统一出口；纯逻辑，IO 在 adapter） ────── */
+
+/** 探活快照：pane 实时状态 + 会话活动时间（毫秒 epoch；null = 未知）。 */
+export interface AliveProbe {
+  paneExists: boolean;
+  agentStatus: string | null;
+  /** 会话文件 mtime（最新候选）；无文件/不可读 = null。 */
+  lastActivityMs: number | null;
+}
+
+/** 探活判活：pane 在 +（working/blocked 或近期有会话活动）→ 视为还在干活。 */
+export function isAlive(probe: AliveProbe, nowMs: number, staleAfterMs = 120_000): boolean {
+  if (!probe.paneExists) return false;
+  if (probe.agentStatus === 'working' || probe.agentStatus === 'blocked') return true;
+  // idle/unknown：会话 2 分钟内有活动仍算活（写作间隙/刚结算未采集）
+  return probe.lastActivityMs != null && nowMs - probe.lastActivityMs < staleAfterMs;
+}
+
+/** 人话相对时间（"12s ago" / "3m ago"）。 */
+export function agoText(ms: number, nowMs: number): string {
+  const s = Math.max(0, Math.round((nowMs - ms) / 1000));
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  return `${Math.floor(s / 3600)}h ago`;
+}
+
+/**
+ * 存活通知（A2 转后台返回值 与 B1 tool_result 改写 的统一构造出口）：
+ * 两场景同一话术——"它在干活 / 别重做 / 转后台了 / 结算会通知 / list_agents 可查"。
+ * scenario: 'moved-to-bg'（耐心阈值转后台）| 'error-alive'（工具报错但探活判活，兜底改写）。
+ */
+export function buildAliveNotice(
+  opts: { paneId: string; description: string; scenario: 'moved-to-bg' | 'error-alive'; probe: AliveProbe },
+  nowMs: number,
+): string {
+  const { paneId, description, scenario, probe } = opts;
+  const status = probe.agentStatus ?? 'unknown';
+  const activity = probe.lastActivityMs != null ? `, last session activity ${agoText(probe.lastActivityMs, nowMs)}` : '';
+  if (scenario === 'moved-to-bg') {
+    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.',
+      'Use list_agents to check its live state; send_message to give it follow-up work.',
+    ].join(' ');
+  }
+  return [
+    `The subagent "${description}" is ALIVE in pane ${paneId} (agent_status=${status}${activity}) — this "no readable output" result only means its final answer could not be read yet, NOT that the task failed.`,
+    'Do NOT redo its work. It is being moved to background; you will be notified when it settles.',
+    'Use list_agents to check its live state.',
+  ].join(' ');
+}
+
+/**
+ * 人类闸门通知（E1/E2 统一出口）：subagent blocked（ask_user_question 等人类）时
+ * 给 master 的话术——不揽活、引导用户去 pane、授权例外经 send_message 转达。
+ * question 来自 herdr tokens['pi-ask']（子扩展 reportAskFlag 上报）。
+ */
+export function buildBlockedGateNotice(opts: { paneId: string; description: string; question: string | null }): string {
+  const { paneId, description, question } = opts;
+  const q = question ? ` (question: "${question}")` : '';
+  return [
+    `Subagent "${description}" is BLOCKED waiting for a HUMAN decision in pane ${paneId}${q}.`,
+    'It keeps running in background; once the human answers it resumes, and you will be notified when it settles.',
+    'Do NOT take over its work and do NOT answer on the human\'s behalf.',
+    'Tell the user to open that pane in herdr and answer directly.',
+    'Only if the user explicitly authorizes you: relay their decision to the subagent via send_message — do not redo the work yourself.',
+  ].join(' ');
+}
+
 /* ── 子代理注册表（custom 条目持久化） ────────────────────────────── */
 
 export const SUBS_CUSTOM_TYPE = 'pi-herdr.subs';

package/src/todo-core.ts

@@ -93,20 +93,31 @@ export function validateTodos(
     const item: TodoItem = { content, status: status as TodoStatus };
     if ('blocker' in entry) {
       const blocker = entry.blocker;
-      if (status !== 'blocked') {
-        return { ok: false, error: `invalid todo: \`blocker\` is only allowed when status is "blocked" (got "${status}")` };
-      }
-      if (typeof blocker !== 'string' || blocker.trim() === '') {
+      // 容忍归一（用户实证修复）：Optional 字段用空串/null 填充是常见模型行为
+      //（grok 实测 9 连拒死循环）；status 是权威——非 blocked 态的 blocker 一律视为
+      // 缺省丢弃（无论是否有值），空值同样丢弃。仅类型畸形仍硬拒。
+      if (blocker != null && typeof blocker !== 'string') {
         return { ok: false, error: 'invalid todo: `blocker` must be a non-empty string' };
       }
-      item.blocker = blocker;
+      if (status === 'blocked') {
+        if (typeof blocker !== 'string' || blocker.trim() === '') {
+          return { ok: false, error: 'invalid todo: `blocker` must be a non-empty string' };
+        }
+        item.blocker = blocker;
+      }
     }
     if ('phase' in entry) {
       const phase = entry.phase;
-      if (typeof phase !== 'string' || phase.trim() === '' || phase.length > PHASE_MAX_LEN) {
+      if (phase != null && typeof phase !== 'string') {
         return { ok: false, error: `invalid todo: \`phase\` must be a non-empty string ≤ ${PHASE_MAX_LEN} chars` };
       }
-      item.phase = phase;
+      // 空串/纯空白 = 缺省（实证循环里 phase:"" 同样是被掩盖的雷）；超长是真实约束仍硬拒
+      if (typeof phase === 'string') {
+        if (phase.length > PHASE_MAX_LEN) {
+          return { ok: false, error: `invalid todo: \`phase\` must be a non-empty string ≤ ${PHASE_MAX_LEN} chars` };
+        }
+        if (phase.trim() !== '') item.phase = phase;
+      }
     }
     if (status === 'in_progress') {
       inProgress++;
@@ -298,7 +309,7 @@ export function fuzzyFind(items: readonly TodoItem[], query: string): string[] {
   return substr.map((it) => it.content);
 }
 
-/** D39：有界视图选择——先丢 completed、再截断尾部；返回可见条目与摘要。 */
+/** D39：有界视图选择——先丢 completed、再截 open；两端都超额时保最新（尾部切片）。 */
 export interface BoundedView {
   visible: TodoItem[];
   /** 被隐藏的数量按状态计数（completed 单独计，其余合并）。 */
@@ -312,15 +323,18 @@ export function boundedView(items: readonly TodoItem[], budget: number): Bounded
   }
   const completed = items.filter((it) => it.status === 'completed');
   const open = items.filter((it) => it.status !== 'completed');
-  let visible = open.slice(0, budget);
+  // 修正（用户实证）：widget 是头部可见窗口——超预算必须隐最老（丢头部），保最新可见；
+  // 旧实现 slice(0, budget) 保最老，最新任务永远落在窗口外。
+  const visible = open.length > budget ? open.slice(-budget) : open;
   const hiddenOpen = open.length - visible.length;
   let hiddenCompleted = completed.length;
+  let final = visible;
   if (hiddenOpen === 0 && visible.length < budget) {
     const room = budget - visible.length;
-    visible = [...visible, ...completed.slice(0, room)];
+    final = [...visible, ...completed.slice(-room)];
     hiddenCompleted = completed.length - room;
   }
-  return { visible, hiddenCompleted, hiddenOpen };
+  return { visible: final, hiddenCompleted, hiddenOpen };
 }
 
 /** 当前 in_progress 中的第一条（上报 agent 状态时作为 message，供侧边栏显示"正在做什么"）。 */