pi-pier 0.1.2 → 0.1.4

package/src/core/subagent.ts

@@ -21,9 +21,9 @@ 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, buildLaunchParts, 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 { appendHistory, applyReportedSessionFile, historyFilePath, inheritOutcome, latestGeneration, normalizeEntryKind, readHistory, type HistoryEntry } from '../history-store.ts';
 import { execFile } from 'node:child_process';
 import { stat as statCb } from 'node:fs';
 import { resolve as pathResolve } from 'node:path';
@@ -33,7 +33,7 @@ import { pingUntilReady, pipeNameFor, pipeRequest } from '../pipe-channel.ts';
 import { shouldClosePane, shouldCloseTaskTab } from '../gc-core.ts';
 import { composeForRole } from '../manifest-compose.ts';
 import { formatSettlementNotice } from '../vocab.ts';
-import { parseShapeTree, pickGridSplit } from './grid-shape.ts';
+import { ABORT_STOP_REASON } from '../settle-wake-core.ts';
 
 export interface SubagentEnv {
   paneId: string;
@@ -66,9 +66,10 @@ export interface SubagentDeps {
    * D92 结算通知注入器（index.ts 提供）：忙时入缓冲、turn_end 折叠 steer 批量注入。
    * 缺省回退 pi.sendUserMessage(followUp)（旧路径——整个 run 结束才回填，测试桩用）。
    */
-  deliverNotice?: (content: string) => Promise<void>;
+  deliverNotice?: (content: string, paneId?: string) => Promise<void>;
+  /** B2：结算通知尚在缓冲未送达的 pane 集合（GC 豁免——先送达再回收）。 */
+  noticePending?: () => ReadonlySet<string>;
   /** terminal 族 GC 豁免槽。 */
-  terminalState: { activePaneIds: () => Set<string> };
   todos: TodosService;
 }
 
@@ -84,10 +85,18 @@ const SUBAGENT_DESCRIPTION = [
 
 /** 子代理并发上限（D10）。 */
 const SUBAGENT_CONCURRENCY = 4;
-/** 单子代理等待上限（内部 marker PI_HERDR_SUBAGENT_TIMEOUT_MS 可调，默认 10 分钟）。 */
+/** B1：观察超时 = 无活动时长预算（非总墙钟）——working 切片持续续命；marker
+ * PI_HERDR_SUBAGENT_TIMEOUT_MS 沿用旧名，语义已从「poller 起算总墙钟」改为
+ * 「距最近一次活动」——>10min 的健康长任务不再被误杀（session 01a03c0d 实证）。 */
 const SUBAGENT_TIMEOUT_MS = Number(process.env.PI_HERDR_SUBAGENT_TIMEOUT_MS ?? 600000) || 600000;
 /** 就绪等待上限（TUI 启动 + herdr 检测）。 */
 const SUB_READY_TIMEOUT_MS = 30000;
+/** D94/B4：结算观察窗（此期内 working 默认视为用户接管）。 */
+const OBSERVE_WINDOW_MS = Number(process.env.PI_HERDR_OBSERVE_MS ?? 30000) || 30000;
+/** B4：机器注入宽限——观察窗内的 working 若由自己的 prompt/follow_up 触发，不算接管。 */
+const MACHINE_INJECT_GRACE_MS = Number(process.env.PI_HERDR_INJECT_GRACE_MS ?? 30000) || 30000;
+/** D94：接管态归还阈值（持续 idle 即归还）。 */
+const TAKEOVER_IDLE_MS = Number(process.env.PI_HERDR_TAKEOVER_IDLE_MS ?? 60000) || 60000;
 
 function defaultAgentSessionsDir(): string {
   const base = process.env.PI_CODING_AGENT_DIR || join(homedir(), '.pi', 'agent');
@@ -114,7 +123,9 @@ export default function subagentPlugin(ctx: Context): void {
     extPath: d.extPath,
   };
   const subSemaphore = new Semaphore(SUBAGENT_CONCURRENCY);
-
+  /** B4：每 pane 最近一次机器注入（prompt/follow_up pipe 投递成功）时间——观察窗内的
+   * working 若发生在宽限期内，是自己的注入在被处理，不是用户接管。 */
+  const lastMachineInjectAt = new Map<string, number>();
   /* 子代理注册表（custom 条目持久化，分支正确；parent 重启后可从分支重建） */
   const subs = new Map<string, SubEntry>();
   const pollers = new Set<string>();
@@ -122,13 +133,22 @@ export default function subagentPlugin(ctx: Context): void {
   /** D50：每 pane 最近一次机器请求 id（interrupt 按轮次占位、pollLoop 去重用）。 */
   const lastRequestIdByPane = new Map<string, string>();
 
+  /** O1：上次落盘快照（内容哈希门控——01a03c0d 实证 48% session 行是心跳期重复快照）。 */
+  let lastSubsSnapshot = '';
+
   function persistSubs(): void {
     try {
-      pi.appendEntry?.(SUBS_CUSTOM_TYPE, makeRegistry([...subs.values()]));
+      const reg = makeRegistry([...subs.values()]);
+      const snap = JSON.stringify(reg);
+      if (snap === lastSubsSnapshot) return; // 内容未变不落（1s 观察窗/5s 接管循环的重复心跳）
+      lastSubsSnapshot = snap;
+      pi.appendEntry?.(SUBS_CUSTOM_TYPE, reg);
     } catch {
       /* 持久化尽力而为 */
     }
   }
+  /** E2：已发过闸门通知的 pane（blocked 期间去重；解除后移除，二次 ask 可再通知）。 */
+  const blockedGateNotified = new Set<string>();
 
   // slots 回填：common 段 pipe reply 消费
   slots.applyReplySession = (paneId, sessionFile) => {
@@ -138,7 +158,7 @@ export default function subagentPlugin(ctx: Context): void {
     if (next === entry.sessionFile) return;
     entry.sessionFile = next;
     persistSubs();
-    writeHistory(entry);
+    writeHistory(entry, undefined, 'session-report');
   };
   slots.reconcileOnReply = (paneId) => {
     const entry = subs.get(paneId);
@@ -157,23 +177,88 @@ export default function subagentPlugin(ctx: Context): void {
         ?.sessionManager?.getBranch?.() ?? [];
       const reg = foldSubsRegistry(entries as Parameters<typeof foldSubsRegistry>[0]);
       for (const sub of reg.subs) subs.set(sub.paneId, sub);
+      lastSubsSnapshot = ''; // 分支回放改变了状态 → 下次 persistSubs 强制落盘
     } catch {
       /* 重建失败不影响主流程 */
     }
   }
 
+  /** B6：master 崩溃遗留的 running 行——按 herdr 实况补 closed（pane 没了才关，
+   * pane 还在的真在跑则保留）。01a03c0d 台账实证：p6/p7 永久 running 无回收。 */
+  async function sweepZombieRunning(): Promise<void> {
+    if (!client.available || subs.size === 0) return;
+    let livePaneIds: ReadonlySet<string>;
+    try {
+      livePaneIds = new Set((await client.listPanes()).map((p) => p.paneId));
+    } catch {
+      return; // 查询失败不误关
+    }
+    let changed = false;
+    for (const [paneId, e] of subs) {
+      if (e.status !== 'running' || livePaneIds.has(paneId)) continue;
+      e.status = 'closed';
+      writeHistory(e, { status: 'closed', closedAt: Date.now() }, 'zombie-sweep');
+      changed = true;
+    }
+    if (changed) persistSubs();
+  }
+
   scoped.on('session_start', async (_event: unknown, eventCtx: unknown) => {
     rebuildSubs(eventCtx);
+    await sweepZombieRunning();
   });
   scoped.on('session_tree', async (_event: unknown, eventCtx: unknown) => {
     rebuildSubs(eventCtx);
+    await sweepZombieRunning();
+  });
+
+  /* ── 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;
   const TODO_REMINDERS_MAX = 3;
+  // 反唤醒风暴：用户 ESC 中止后的 settled 不催（否则 abort → 提醒 → 新 run → 再 abort
+  // 死循环；与 index 的 D96/结算缓冲同款守卫，session 01a03bf0 实证）。
+  let lastAssistantStopReason: string | null = null;
+  scoped.on('turn_end', async (event: unknown) => {
+    if (event === null || typeof event !== 'object' || !('message' in event)) return;
+    const msg = (event as { message: unknown }).message; // 'message' in 已守卫
+    if (msg === null || typeof msg !== 'object') return;
+    const { role, stopReason } = msg as { role?: unknown; stopReason?: unknown };
+    if (role === 'assistant' && typeof stopReason === 'string') {
+      lastAssistantStopReason = stopReason;
+    }
+  });
   scoped.on('agent_settled', async () => {
+    if (lastAssistantStopReason === ABORT_STOP_REASON) return;
     if (todoReminders >= TODO_REMINDERS_MAX) return;
     if (pollers.size > 0) return; // 有在途子代理 → 主控本来就在等，不催
     if (d.getBlockedDepth() > 0) return; // 等人类回答 → 不催
@@ -253,6 +338,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 在"注入瞬间"也是真，不能当结算信号；
@@ -266,8 +384,8 @@ export default function subagentPlugin(ctx: Context): void {
   ): Promise<{ text: string | null; pendingTool: boolean; activity: boolean }> {
     for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
       const entries = readSessionFile(file);
-      if (!entries) continue;
-      const r = lastAssistantText(entries, { sinceTs });
+      if (entries.length === 0) continue;
+      const r = lastAssistantText(entries, sinceTs);
       if (r?.text) return { text: r.text, pendingTool: false, activity: true };
       if (hasPendingToolCall(entries, sinceTs)) return { text: null, pendingTool: true, activity: true };
       if (hasAssistantAfter(entries, sinceTs)) return { text: null, pendingTool: false, activity: true };
@@ -275,21 +393,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)
@@ -305,7 +408,11 @@ export default function subagentPlugin(ctx: Context): void {
     requestId: string,
   ): Promise<void> {
     void spawnedAt;
+    // B1：无活动预算锚点——working 切片（waitAgent 超时 null）即心跳（O3）：每次续命；
+    // 只有「不 working 也无结算进展」的真空期才消耗预算（01a03c0d：27min 健康长任务
+    // 被旧总墙钟 10min 误杀两次）。startedAt 保留供通知文案诊断。
     const startedAt = Date.now();
+    let lastActivityAt = Date.now();
     try {
       while (true) {
         const entry = subs.get(paneId);
@@ -360,7 +467,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)) {
@@ -380,17 +502,29 @@ export default function subagentPlugin(ctx: Context): void {
               // 已在观察期
               const elapsed = Date.now() - entry.observationStartedAt;
 
-              // 检测用户介入：查询当前状态是否变为 working
+              // 检测用户介入：查询当前状态是否变为 working。
+              // B4：观察窗内 working ≠ 必然用户接管——自己的 follow_up 注入也呈现
+              // working。距最近机器注入 < MACHINE_INJECT_GRACE_MS 的 working 视为
+              // 注入被处理（取消结算继续观察），否则才判接管（01a03c0d：契约消息
+              // 20min 后投递，恰好撞进观察窗）。
               try {
                 const agents = await client.listAgents();
                 const agent = agents.find((a) => a.paneId === paneId);
                 if (agent && agent.status === 'working') {
-                  // 用户介入！标记接管，取消结算
-                  entry.userTakeover = true;
+                  const injectedAgo = Date.now() - (lastMachineInjectAt.get(paneId) ?? 0);
+                  if (injectedAgo > MACHINE_INJECT_GRACE_MS) {
+                    // 用户介入！标记接管，取消结算
+                    entry.userTakeover = true;
+                    entry.observationStartedAt = Date.now();
+                    entry.lastAgentStatus = 'working';
+                    persistSubs();
+                    continue; // 跳过结算，进入用户接管模式
+                  }
+                  // 机器注入在处理中 → 归零观察窗，等这轮 run 收尾再判结算
                   entry.observationStartedAt = Date.now();
-                  entry.lastAgentStatus = 'working';
                   persistSubs();
-                  continue; // 跳过结算，进入用户接管模式
+                  await new Promise((resolve) => setTimeout(resolve, 1000));
+                  continue;
                 }
               } catch {
                 // listAgents 失败静默
@@ -405,7 +539,6 @@ export default function subagentPlugin(ctx: Context): void {
               // 观察期结束（30s 无用户介入），正常结算
               entry.observationStartedAt = null; // 清除观察期标记
             }
-
             // 正常结算逻辑
             // O6：reply 已写的 sessionFile 是权威；poll 只在缺失时用扫描补，绝不反向覆盖
             if (!entry.sessionFile) {
@@ -416,15 +549,13 @@ export default function subagentPlugin(ctx: Context): void {
             }
             entry.status = 'consumed';
             entry.consumedAt = Date.now();
-            persistSubs();
-            writeHistory(entry, { outcome: closing });
+            writeHistory(entry, { outcome: closing }, 'poll-settle');
             // M17：结算自动对账（先于通知；与 reply 快路径幂等双跑）
             const notes = d.reconcileOnSettlement(description, 'settled');
             const notice = d.withReconcileNotes(
               formatSettlementNotice(`${paneId} (${description})`, closing),
               notes,
             );
-            // D50：push 快路径可能已发过通知 → 按轮次（paneId+请求id）去重，只发一条
             if (d.claimSettleNotice(`${paneId}:${requestId}`)) {
               try {
                 await injectNotice(notice);
@@ -436,6 +567,8 @@ export default function subagentPlugin(ctx: Context): void {
           }
           // 挂起 toolCall（等人类输入）或还没开工 → 继续等
         }
+        // B1/O3：state=null（30s 切片超时）= working 中的心跳 → 续命无活动预算。
+        if (state === null) lastActivityAt = Date.now();
         // 切片超时：检查 pane 存活与总预算
         let alive = false;
         try {
@@ -447,7 +580,7 @@ export default function subagentPlugin(ctx: Context): void {
           entry.status = 'consumed';
           entry.consumedAt = Date.now(); // O8：提前退出路径必须置消费时间，否则 tab TTL 被卡住
           persistSubs();
-          writeHistory(entry, { outcome: 'pane closed before settling' });
+          writeHistory(entry, { outcome: 'pane closed before settling' }, 'poll-pane-closed');
           const notes = d.reconcileOnSettlement(description, 'failed');
           const notice = d.withReconcileNotes(
             `Background subagent ${paneId} (${description}) stopped before settling (its pane closed).`,
@@ -460,14 +593,19 @@ export default function subagentPlugin(ctx: Context): void {
           }
           return;
         }
-        if (Date.now() - startedAt > SUBAGENT_TIMEOUT_MS) {
+        // B1：无活动预算超时——working 心跳持续续命，此处只在「pane 活着但
+        // 既不 working、也无结算进展」真空期超预算时触发（旧总墙钟 10min 误杀
+        // 27min 健康长任务 ×2，01a03c0d 实证）。
+        if (Date.now() - lastActivityAt > SUBAGENT_TIMEOUT_MS) {
           entry.status = 'consumed';
           entry.consumedAt = Date.now(); // O8：observation timeout 同样置消费时间
           persistSubs();
-          writeHistory(entry, { outcome: 'observation timeout' });
+          writeHistory(entry, { outcome: 'observation timeout' }, 'poll-timeout');
           const notes = d.reconcileOnSettlement(description, 'failed');
+          // O2：给行动钩子——list_agents 看活态；真在跑就让它跑完（结算会自动通知），
+          // 别 sleep 盲等（01a03c0d 实证 master 收到旧文案后连 sleep 90/120/180）。
           const notice = d.withReconcileNotes(
-            `Background subagent ${paneId} (${description}) stopped being observed before settling; check its pane.`,
+            `Background subagent ${paneId} (${description}) has shown no progress for ${Math.round((Date.now() - lastActivityAt) / 1000)}s (observed since ${new Date(startedAt).toISOString()}). Run list_agents to check its live state; if it is working, let it run — its settlement notice will arrive automatically. Do not sleep-wait.`,
             notes,
           );
           try {
@@ -509,7 +647,7 @@ export default function subagentPlugin(ctx: Context): void {
     return historyFilePath(agentRootDir(), cwd);
   }
 
-  function toHistory(e: SubEntry): HistoryEntry {
+  function toHistory(e: SubEntry, outcome: string | null): HistoryEntry {
     return {
       taskId: e.taskId,
       kind: e.kind,
@@ -522,7 +660,7 @@ export default function subagentPlugin(ctx: Context): void {
       sessionFile: e.sessionFile,
       launchCommand: e.launchCommand,
       status: e.status,
-      outcome: null,
+      outcome,
       createdAt: e.createdAt,
       consumedAt: e.consumedAt ?? null,
       closedAt: null,
@@ -530,8 +668,14 @@ export default function subagentPlugin(ctx: Context): void {
     };
   }
 
-  function writeHistory(e: SubEntry, patch?: Partial<HistoryEntry>): void {
-    appendHistory(histFile(e.cwd), { ...toHistory(e), ...(patch ?? {}) });
+  /** B5：每 taskId 最近非空 outcome（closed 补记行继承——latestGeneration 取最新行，
+   * 旧实现 closed 行恒 outcome:null → 结算成果在「最新行」语义下丢失）。 */
+  const lastOutcomeByTask = new Map<string, string>();
+
+  function writeHistory(e: SubEntry, patch?: Partial<HistoryEntry>, via?: string): void {
+    const outcome = inheritOutcome(lastOutcomeByTask.get(e.taskId), patch?.outcome);
+    if (typeof outcome === 'string' && outcome.length > 0) lastOutcomeByTask.set(e.taskId, outcome);
+    appendHistory(histFile(e.cwd), { ...toHistory(e, outcome), ...(patch ?? {}), ...(via ? { via } : {}) });
   }
 
   /** 存活任务 tab（本 workspace；herdr 为权威，tab.rename/自动关后自动纠正）。 */
@@ -600,7 +744,7 @@ export default function subagentPlugin(ctx: Context): void {
         mainTabId,
       });
       if (plan.mode === 'append' && plan.tabId) {
-        // D91 网格形态：目标格 = tab 内面积最大的格子（沿长轴分裂，自然铺成方格）；
+        // D97 网格形态：目标格 = tab 内面积最大的格子，一律 down（全宽横条，title 静帧横读）；
         // board 等无 agent 常驻 shell（agentStatus=unknown）不入候选，避免被 worker 蚕食。
         const exclude = new Set(
           allPanes.filter((p) => p.tabId === plan.tabId && p.agentStatus === 'unknown').map((p) => p.paneId),
@@ -617,7 +761,7 @@ export default function subagentPlugin(ctx: Context): void {
           ?? allPanes.find((p) => p.tabId === plan.tabId)?.paneId;
         if (anchorPaneId) {
           const paneId = await client.splitPane({
-            direction: pick?.direction ?? 'right',
+            direction: pick?.direction ?? 'down',
             cwd,
             env: envOver,
             targetPaneId: anchorPaneId,
@@ -643,12 +787,8 @@ export default function subagentPlugin(ctx: Context): void {
 
   function launchLine(resumeFile?: string | null, roleModel?: string | null, approve = false): string {
     // 裸 argv → 平台 shell 语法（win32=PowerShell `&`，POSIX=sh）；引号转义在 buildLaunchLine
-    const parts = [runtime.nodePath, runtime.cliPath];
-    if (approve) parts.push('-a');
-    parts.push('-e', runtime.extPath);
-    if (roleModel) parts.push('--provider', roleModel.split('/')[0], '--model', roleModel.split('/')[1] ?? roleModel);
-    if (resumeFile) parts.push('--session', resumeFile);
-    return buildLaunchLine(parts);
+    // argv 构造在 buildLaunchParts（D97：默认 --tui-mode fullscreen，PI_HERDR_TUI=regular 逃生）
+    return buildLaunchLine(buildLaunchParts(runtime, { resumeFile, roleModel, approve }));
   }
 
   /**
@@ -677,9 +817,10 @@ export default function subagentPlugin(ctx: Context): void {
     } catch {
       return;
     }
-    const statuses = new Map(panesList.map((p) => [p.paneId, p.agentStatus]));
     // D71：有活跃终端会话的 pane 豁免回收（tab 级与 pane 级两处）
     const termPaneIds = terminalState.activePaneIds();
+    // B2：结算通知未送达的 pane 豁免（先送达再回收）——pD/pC 实证被 GC 抢关。
+    const pendingNoticeIds = d.noticePending?.() ?? new Set<string>();
 
     // 任务 tab 分组（含 closed 条目：closed 工作 pane 也算完成）
     const byTab = new Map<string, SubEntry[]>();
@@ -702,7 +843,7 @@ export default function subagentPlugin(ctx: Context): void {
         for (const e of entries) {
           if (e.status !== 'closed') {
             e.status = 'closed';
-            writeHistory(e, { status: 'closed', closedAt: Date.now() });
+            writeHistory(e, { status: 'closed', closedAt: Date.now() }, 'gc');
           }
         }
         continue;
@@ -714,7 +855,8 @@ export default function subagentPlugin(ctx: Context): void {
         now: Date.now(),
       });
       if (!autoCloseTabs || !should) continue;
-      if (tabPanes.some((p) => termPaneIds.has(p.paneId))) continue; // 活跃终端豁免
+      // B2：结算通知未送达的 pane 豁免（先送达再回收）
+      if (tabPanes.some((p) => termPaneIds.has(p.paneId) || pendingNoticeIds.has(p.paneId))) continue;
       try {
         await client.tabClose(tabId);
       } catch {
@@ -723,7 +865,7 @@ export default function subagentPlugin(ctx: Context): void {
       for (const e of entries) {
         if (e.status !== 'closed') {
           e.status = 'closed';
-          writeHistory(e, { status: 'closed', closedAt: Date.now() });
+          writeHistory(e, { status: 'closed', closedAt: Date.now() }, 'gc');
         }
       }
       await new Promise((r) => setTimeout(r, 300)); // 串行关闭（#1358 同类风险护栏）
@@ -736,7 +878,7 @@ export default function subagentPlugin(ctx: Context): void {
       (e) => e.status === 'consumed' && !(e.tabId && closableTaskTabIds.has(e.tabId)),
     );
     for (const e of candidates) {
-      if (termPaneIds.has(e.paneId)) continue; // 活跃终端豁免（D71）
+      if (termPaneIds.has(e.paneId) || pendingNoticeIds.has(e.paneId)) continue; // 活跃终端（D71）/未送达通知（B2）豁免
       if (!shouldClosePane({
         consumedAt: e.consumedAt ?? null,
         herdrStatus: statuses.get(e.paneId),
@@ -745,7 +887,7 @@ export default function subagentPlugin(ctx: Context): void {
       if (statuses.get(e.paneId) === undefined) {
         // pane 已消失（随 tab 被关）→ 补记 closed
         e.status = 'closed';
-        writeHistory(e, { status: 'closed', closedAt: Date.now() });
+        writeHistory(e, { status: 'closed', closedAt: Date.now() }, 'gc');
         continue;
       }
       try {
@@ -754,7 +896,7 @@ export default function subagentPlugin(ctx: Context): void {
         /* pane 已消失 */
       }
       e.status = 'closed';
-      writeHistory(e, { status: 'closed', closedAt: Date.now() });
+      writeHistory(e, { status: 'closed', closedAt: Date.now() }, 'gc');
       await new Promise((r) => setTimeout(r, 300));
     }
     persistSubs();
@@ -831,7 +973,7 @@ export default function subagentPlugin(ctx: Context): void {
     entry.revivedFrom = latest.paneId;
     entry.launchCommand = [launchLine(resumeFile, null, approve)];
     entry.createdAt = Date.now();
-    writeHistory(entry);
+    writeHistory(entry, undefined, 'revive');
     return entry;
   }
 
@@ -931,7 +1073,6 @@ export default function subagentPlugin(ctx: Context): void {
       const release = await subSemaphore.acquire();
       let paneId = '';
       try {
-        onUpdate?.(makeProgressUpdate(`spawning ${kind !== 'task' ? `${kind} ` : ''}${background ? 'background ' : ''}subagent pane…`));
         const spawnedAt = Date.now();
         const taskId = randomUUID();
         const spawned = await spawnPaneInTaskTab(
@@ -961,10 +1102,12 @@ 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% 归人（无软锁窗口、无混行）。
+        // 回归修复（session 01a03bf0 实证）：ecc0bc4 重写前台等待时误删本块——
+        // prompt 永不注入 + injectTs 未定义（ReferenceError → spawn-failed，
+        // 台账留幽灵 running 条目）。任何后续重构不得把注入与 injectTs 拆开。
         const injectTs = Date.now();
         const injected = await pipeRequest(pipeNameFor(cwd, paneId), {
           type: 'prompt',
@@ -976,48 +1119,87 @@ export default function subagentPlugin(ctx: Context): void {
         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;
+        lastMachineInjectAt.set(paneId, injectTs); // B4：观察窗内 working 归因判据
+        // 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') {
+            // 返回 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, undefined, 'to-background');
+            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';
         entry.consumedAt = Date.now();
         persistSubs();
-        writeHistory(entry, { outcome: outcome.kind === 'completed' ? text : null });
+        writeHistory(entry, { outcome: outcome.kind === 'completed' ? text : null }, 'fg-settle');
         return {
           content: [{ type: 'text', text: formatSubagentResult(outcome, spec.description) }],
           details: { paneId, taskId, background, role: kind },
         };
       } catch (err) {
+        // 回归修复（session 01a03bf0）：spawn 中途失败必须回收台账 + 关 pane——
+        // 否则幽灵 running 条目永不结算 → D96 提醒风暴 + send_message 打到
+        // 无任务上下文的空会话。pane 关闭尽力而为（board pane 例外场景由 GC 兜底）。
+        if (paneId) {
+          subs.delete(paneId);
+          persistSubs();
+          void client.closePane(paneId).catch(() => { /* 尽力而为 */ });
+        }
         return {
           content: [{
             type: 'text',
@@ -1083,7 +1265,7 @@ export default function subagentPlugin(ctx: Context): void {
           };
           subs.set(entry.paneId, entry);
           persistSubs();
-          writeHistory(entry);
+          writeHistory(entry, undefined, 'resume');
           return {
             content: [{
               type: 'text',
@@ -1138,7 +1320,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 +1333,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,19 +1350,28 @@ 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: {} };
     },
   });
 
-  /* ── 工具：send_message（followUp 队列语义） ── */
+  /* ── 工具：send_message（steer 间隙投递） ── */
 
   scoped.registerTool({
     name: 'send_message',
     label: 'Send to Subagent',
     description:
-      'Send a follow-up message to a background subagent. If it is working, the message is queued and delivered after it finishes (pi followUp queue); if it is idle, it wakes the subagent for a new turn. `agentId` is the id returned by the subagent tool or shown by list_agents.',
+      'Send a follow-up message to a background subagent. If it is working, the message is delivered at its next tool-call gap (steer, seconds); if it is idle, it wakes the subagent for a new turn. `agentId` is the id returned by the subagent tool or shown by list_agents.',
     parameters: Type.Object({
       agentId: Type.String({ description: 'The subagent id (herdr pane id)' }),
       message: Type.String({ description: 'The follow-up message' }),
@@ -1192,7 +1389,9 @@ export default function subagentPlugin(ctx: Context): void {
           subs.set(entry.paneId, entry);
           persistSubs();
         }
-        // M11（D46）：follow_up 走扩展管道（sendUserMessage(followUp) 队列语义）
+        // M11（D46）：follow_up 走扩展管道。B3：带 steer——worker 长跑中途的补充
+        // 指令在 tool-call 间隙秒级到达（旧 followUp 队列语义 = 整个 run 结束才投，
+        // 01a03c0d 实证 20min 延迟致 worker 按旧契约返工）。
         const ready = await waitSubReady(entry.cwd, entry.paneId);
         if (!ready) throw new Error(`subagent pane ${entry.paneId} pipe not ready`);
         const fuId = `fu-${Date.now()}`;
@@ -1202,10 +1401,12 @@ export default function subagentPlugin(ctx: Context): void {
           text: String(params?.message ?? ''),
           from: pipeNameFor(entry.cwd, env?.paneId ?? ''),
           push: true,
+          steer: true,
         });
         if (res.type !== 'ok') {
           throw new Error(`pipe follow_up rejected: ${res.type === 'error' ? res.message : 'unknown response'}`);
         }
+        lastMachineInjectAt.set(entry.paneId, Date.now()); // B4：观察窗内 working 归因判据
         entry.status = 'running';
         persistSubs();
         lastRequestIdByPane.set(entry.paneId, fuId);