pi-pier 0.3.1 → 0.4.1

package/src/index.ts

@@ -10,6 +10,7 @@
  * details persist in session JSONL and getBranch() replay implements branch rollback.
  */
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
 import {
   ASK_PARAMETERS,
   ASK_PROMPT_GUIDELINES,
@@ -28,6 +29,8 @@ import { createHerdrClient } from './herdr-client.ts';
 import { bareSessionId, lastAssistantText, readSessionFile, resolveSessionFileValue } from './session-tail.ts';
 import { fileURLToPath } from 'node:url';
 import { join } from 'node:path';
+import { mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { platformPaths } from './platform-paths.ts';
 import { TodosService, type TodoCompletionSource } from './todos-service.ts';
 import { reconcileTodos } from './reconcile-core.ts';
@@ -38,12 +41,23 @@ import { ABORT_STOP_REASON, planSettleWake, shouldPushSettleReply } from './sett
 import { parseRuntimeManifest } from './tool-gate.ts';
 import { formatPaneTitle } from './pane-title.ts';
 import { registerSlimFrame, updateSlimFrame } from './slim-frame.ts';
-import { planIndexMode } from './index-runtime.ts';
-import { emptySubagentPortBox } from './subagent-core.ts';
+import { applyRestoredWorkerMode, planIndexMode } from './index-runtime.ts';
+import { buildResumeArgv, emptySubagentPortBox, PROGRESS_CUSTOM_TYPE } from './subagent-core.ts';
+import { hasWorkerMarker, writeWorkerMarker, readWorkerMarker } from './worker-marker.ts';
+import {
+  DELEGATION_CUSTOM_TYPE,
+  applyWorkerTag,
+  buildDelegationSection,
+  foldDelegation,
+  parseDelegationContext,
+  type DelegationContext,
+} from './delegation-core.ts';
+import { formatDelegationTree, type WorkerTodoSnapshot, type WorkerWidgetRow } from './tree-view.ts';
 import { createNoticeBuffer } from './index-notices.ts';
 import { handlePipeRequest, type MachineRequest } from './index-pipe.ts';
 import { installWriteLocks } from './index-locks.ts';
 import { installDashboardCommand } from './dashboard-command.ts';
+import { openPierPanel } from './panel-open.ts';
 import { registerObservationPack, createCompactionBatchPackHook, type PickMiddleExcerpt } from './plugins/observation.ts';
 import { createJevRuntime } from './jev-client.ts';
 import {
@@ -62,25 +76,15 @@ import { handleReducerToolResult, type ToolResultEventLike } from './reducer-inv
 import { appendEfficiencyLog, efficiencyLogPath, pruneSessionObjects, resolveSessionRoot } from './efficiency-store.ts';
 import type { RoutingTelemetryRecord, RoutingTelemetryRow } from './routing-telemetry.ts';
 import { loadEfficiencyConfigFromDisk, resolveEfficiencyConfig, type EfficiencyConfig } from './efficiency-config-core.ts';
-import { resolveDefaultFocusPollMs, parseFocusSample, spawnReflow, startFocusPoller, type FocusPoller } from './focus-poller.ts';
 import { composeMasterRuntime, createRoleRuntime } from './index-roles.ts';
 import { createGateRuntime } from './index-gates.ts';
 
-/** D-4: PIER_FOCUS_POLL_MS=0 disables the poller; invalid values fall back to the version default. */
-function focusPollIntervalMs(env: NodeJS.ProcessEnv = process.env, herdrVersion?: string | null): number {
-  const defaultMs = resolveDefaultFocusPollMs(herdrVersion);
-  const ms = Number(env.PIER_FOCUS_POLL_MS);
-  return env.PIER_FOCUS_POLL_MS !== undefined && env.PIER_FOCUS_POLL_MS.trim() !== '' && Number.isFinite(ms) && ms >= 0
-    ? ms
-    : defaultMs;
-}
-
 function agentSessionsDir(): string {
   return process.env.PI_CODING_AGENT_DIR ? join(process.env.PI_CODING_AGENT_DIR, 'sessions') : platformPaths.sessionsDir;
 }
 
 export default async function (pi: ExtensionAPI) {
-  const mode = planIndexMode();
+  const mode = applyRestoredWorkerMode(planIndexMode(), process.env.PI_SESSION_FILE ?? null, hasWorkerMarker);
   const isSubagent = mode.isSubagent;
   const roleBase = process.env.PI_HERDR_ROLE_BASE || process.cwd();
 
@@ -89,7 +93,8 @@ export default async function (pi: ExtensionAPI) {
   let effConfig: EfficiencyConfig = resolveEfficiencyConfig();
   const coordinator = new CompactCoordinator();
   const { client, env } = createHerdrClient();
-
+  /** RFC rfc-delegation-identity §2.1: resolved env → marker → branch fold; worker panes only. */
+  let delegation: DelegationContext | null = parseDelegationContext(process.env.PI_HERDR_DELEGATION);
   const initialManifest =
     parseRuntimeManifest(process.env.PI_HERDR_ROLE_MANIFEST) ??
     (mode.composeMaster ? composeMasterRuntime() : null);
@@ -189,16 +194,87 @@ export default async function (pi: ExtensionAPI) {
     const p = progressOf(todos.items);
     const eta = estimateEta({ completedAt: completedStamps, total: p.total, now: Date.now() });
     const suffix = formatProgressSuffix({ completed: p.completed, total: p.total, eta });
-    const title = formatPaneTitle(todos.items, null, { progressSuffix: suffix, lastWriteAt: todos.lastWriteAt });
+    const title = applyWorkerTag(
+      formatPaneTitle(todos.items, null, { progressSuffix: suffix, lastWriteAt: todos.lastWriteAt }),
+      delegation?.description ?? null,
+    );
     updateSlimFrame({ title, items: todos.items, lastWriteAt: todos.lastWriteAt });
     client.reportMetadata({
       session: label,
       items: todos.items,
       progressSuffix: suffix,
       lastWriteAt: todos.lastWriteAt,
+      workerTag: delegation?.description ?? null,
     }).catch(() => {});
+    // D113: delegated workers also push the full list to the master's pipe so its resident widget
+    // and /pier-tree stay live without polling. Best effort — a lost push self-heals on the next write.
+    if (isSubagent && delegation?.parentPipe) {
+      void pipeRequest(delegation.parentPipe, {
+        type: 'todo_sync',
+        id: `tsync-${Date.now()}`,
+        paneId: env?.paneId ?? '',
+        items: todos.items.map((it) => ({ content: it.content, status: it.status, ...(it.blocker ? { blocker: it.blocker } : {}) })),
+        summary: title ?? delegation.description,
+      }, 3000).catch(() => {});
+    }
+  }
+
+  /** D113: per-worker todo cache (pipe pushes; summary fallback after a master resume). */
+  const workerTodos = new Map<string, WorkerTodoSnapshot>();
+  function applyWorkerTodos(workerPaneId: string, items: WorkerTodoSnapshot['items'], summary: string): void {
+    if (!workerPaneId) return;
+    workerTodos.set(workerPaneId, { items, summary, ts: Date.now() });
+    todoUi.rerenderWidget?.();
+    refreshTreeSnapshot();
+  }
+  /** Running rows joined with their cached todos — feeds the unified widget and /pier-tree. */
+  function widgetWorkers(): WorkerWidgetRow[] {
+    return (subagentPort.current?.listRunningSubs() ?? []).map((s) => ({
+      ...s,
+      todos: workerTodos.get(s.paneId) ?? null,
+    }));
   }
 
+  /* ── /pier-tree panel: the pi process owns the data, the popup/overlay owns the surface. ── */
+  /** Set while a panel is open; todo/worker updates republish the snapshot it polls. */
+  let treeSnapshot: { path: string } | null = null;
+
+  function renderTreeLines(): string[] {
+    const rows = subagentPort.current?.listRows() ?? [];
+    return formatDelegationTree({
+      selfItems: todos.items,
+      workers: widgetWorkers(),
+      settled: rows
+        .filter((r) => r.status === 'settled' || r.status === 'consumed')
+        .map((r) => ({ paneId: r.paneId, slug: r.slug, description: r.description, settledAt: r.settledAt })),
+      now: Date.now(),
+    });
+  }
+
+  function treeSnapshotPath(): string {
+    const id = (sessionId || (env ? `pane-${env.paneId}` : 'session')).replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 80);
+    return join(tmpdir(), 'pier-tree', `${id}.txt`);
+  }
+
+  function publishTreeSnapshot(): string {
+    const path = treeSnapshotPath();
+    mkdirSync(join(tmpdir(), 'pier-tree'), { recursive: true });
+    writeFileSync(path, `${renderTreeLines().join('\n')}\n`);
+    treeSnapshot = { path };
+    return path;
+  }
+
+  function refreshTreeSnapshot(): void {
+    if (!treeSnapshot) return;
+    try {
+      writeFileSync(treeSnapshot.path, `${renderTreeLines().join('\n')}\n`);
+    } catch {
+      /* The panel may have been closed and its temp dir swept; the next command republishes. */
+    }
+  }
+
+  todos.on('todo.updated', () => refreshTreeSnapshot());
+
   /** M17 settlement reconciliation: auto-complete settled todos / unblock on failure notes (idempotent). */
   function reconcileOnSettlement(description: string, outcome: 'settled' | 'failed'): string[] {
     if (!description) return [];
@@ -246,10 +322,24 @@ export default async function (pi: ExtensionAPI) {
       reportToolBadge();
     }
   });
-  pi.on('tool_execution_end', async (event: { toolCallId?: string }) => {
-    if (typeof event?.toolCallId === 'string') {
-      runningTools.delete(event.toolCallId);
-      reportToolBadge();
+  pi.on('tool_execution_end', async (event: { toolCallId?: string; toolName?: string; durationMs?: number }) => {
+    if (typeof event?.toolCallId !== 'string') return;
+    const tool = typeof event.toolName === 'string' ? event.toolName : runningTools.get(event.toolCallId) ?? null;
+    runningTools.delete(event.toolCallId);
+    reportToolBadge();
+    // pi ≥ 1.1 records the real execution time on the event; the tools ledger replaces wall-clock
+    // estimates in the efficiency trial with measured numbers. Absent on older pi — nothing logged.
+    if (typeof event.durationMs === 'number' && sessionRoot) {
+      try {
+        await appendEfficiencyLog(efficiencyLogPath(sessionRoot, 'tools'), {
+          sessionId: sessionId || 'unknown',
+          ts: Date.now(),
+          tool,
+          durationMs: event.durationMs,
+        });
+      } catch {
+        /* ledger is observability only */
+      }
     }
   });
 
@@ -274,6 +364,18 @@ export default async function (pi: ExtensionAPI) {
       .sendUserMessage?.(content, { deliverAs: mode, triggerTurn: true });
     return Promise.resolve();
   };
+
+  /** Phase 2 (RFC rfc-delegation-identity §3.2): a worker's progress note enters master context as
+   * a display-less custom message — no turn, no visible chat line; renderers.ts gives it a card. */
+  const deliverProgress = (workerPaneId: string, text: string): Promise<void> => {
+    (pi as unknown as {
+      sendMessage?: (msg: { customType: string; content: string; display: boolean; details?: Record<string, unknown> }, opts?: { triggerTurn?: boolean }) => void;
+    }).sendMessage?.(
+      { customType: PROGRESS_CUSTOM_TYPE, content: text.slice(0, 2000), display: false, details: { paneId: workerPaneId } },
+      { triggerTurn: false },
+    );
+    return Promise.resolve();
+  };
   const notices = createNoticeBuffer({
     isBusy: () => agentActive || lastStopReason === ABORT_STOP_REASON,
     send: sendUserMessageAs,
@@ -341,13 +443,15 @@ export default async function (pi: ExtensionAPI) {
         abort: () => { latestCtx?.abort?.(); },
         setPendingMachineRequest: (next) => { pendingMachineRequest = next; },
         applyRoleSwitch: roles.applyRoleSwitch,
+        deliverProgress,
+        applyWorkerTodos,
       }));
     } catch {
       /* Pipe name collision (rare): this session has no channel; callers report after ping timeout. */
     }
   }
 
-  async function pushSettleReply(): Promise<void> {
+  async function pushSettleReply(aborted = false): Promise<void> {
     const req = pendingMachineRequest;
     if (!req || !req.push || !req.from) return;
     // An aborted settle is not a settlement: OCC's abort means the continuation turn is coming, and
@@ -356,6 +460,7 @@ export default async function (pi: ExtensionAPI) {
     // request armed; the post-compaction settle pushes it (settle-wake-core.ts).
     if (!shouldPushSettleReply({
       intentionalAbort: coordinator.intentionalAbort,
+      aborted,
       compactionInFlight: coordinator.compactionInFlight,
       lastStopReason,
     })) {
@@ -383,8 +488,6 @@ export default async function (pi: ExtensionAPI) {
     }
   }
 
-  const sessionFocusPoller: { current: FocusPoller | null } = { current: null };
-
   pi.on('session_start', async (event, ctx) => {
     sessionId = resolveSessionId(ctx);
     latestCtx = ctx as { abort?: () => void } | null;
@@ -412,31 +515,57 @@ export default async function (pi: ExtensionAPI) {
     // Self-healing: the ask marker lives in herdr with a 24h TTL; a session killed
     // while a dialog was open must not keep the pane looking blocked forever.
     void client.reportAskFlag(null).catch(() => {});
-
-    // D-4 focus sampling: herdr <0.9.1 never delivered pane.focused to plugins;
-    // 0.9.1+ is event-first (pollMs 0). One poller per pane, self-scoped.
-    if (sessionFocusPoller.current) sessionFocusPoller.current.stop();
-    sessionFocusPoller.current = null;
-    const paneId = env?.paneId ?? '';
-    const serverVer = await client.getServerVersion();
-    const pollMs = focusPollIntervalMs(process.env, serverVer);
-    if (paneId && client.available && pollMs > 0) {
-      sessionFocusPoller.current = startFocusPoller({
-        myPaneId: paneId,
-        intervalMs: pollMs,
-        sample: async () => {
-          // layout.export reports the focused pane of our own tab; without the
-          // field (older herdr) the tick stays silent instead of guessing.
-          const layout = await client.exportLayout({ paneId });
-          const sample = parseFocusSample(layout);
-          return sample && sample.focusedPaneId !== null ? sample : null;
-        },
-        fire: (focusedPaneId, cause) => spawnReflow({ paneId: focusedPaneId, cause }),
-      });
+    if (isSubagent) {
+      // herdr 0.9.2 restore identity: the marker re-derives worker mode for the resumed boot
+      // (resume_argv cannot carry spawn env), and the self-reported command replays this exact
+      // session — extension, role model, approve, fullscreen — instead of a bare `pi --resume`.
+      const sm = typeof ctx === 'object' && ctx !== null && 'sessionManager' in ctx ? ctx.sessionManager : undefined;
+      const sessionFile = (typeof sm?.getSessionFile === 'function' ? sm.getSessionFile() : undefined)
+        ?? process.env.PI_SESSION_FILE ?? null;
+      // RFC rfc-delegation-identity §2.1: env (spawn) > marker (herdr restart) > branch fold (/resume).
+      if (!delegation) delegation = readWorkerMarker(sessionFile)?.delegation ?? null;
+      const branchEntries = (ctx as { sessionManager?: { getBranch?: () => readonly unknown[] } })
+        ?.sessionManager?.getBranch?.() ?? [];
+      const folded = foldDelegation(branchEntries as Parameters<typeof foldDelegation>[0]);
+      if (!delegation && folded) delegation = folded;
+      if (delegation && !folded) {
+        // First-frame card: write once — the entry doubles as the /resume replay source.
+        try {
+          pi.appendEntry(DELEGATION_CUSTOM_TYPE, { version: 1, ...delegation, ts: Date.now() });
+        } catch {
+          /* Best effort; the marker already carries the identity. */
+        }
+      }
+      if (delegation) void client.reportDelegationTokens(delegation).catch(() => {});
+      if (sessionRoot) {
+        writeWorkerMarker(sessionFile, roles.state.manifest?.role, delegation ?? undefined);
+        const resumeArgv = buildResumeArgv(process.argv);
+        if (resumeArgv && client.available) {
+          void client.reportAgentSessionResume(sessionId, resumeArgv).catch(() => {});
+        }
+      }
     }
+
+    // Focus heat is event-driven on herdr 0.9.5+: the workbench receives pane.focused directly,
+    // so no per-pane layout sampler is started here.
     startPipeServerFor(cwd);
   });
 
+  /* RFC rfc-delegation-identity §2.2: worker identity + delivery contract ride the prompt
+   * sections each turn (same diff discipline as pier-role; removal cleans up). */
+  if (isSubagent) {
+    pi.on('before_agent_start', async (event) => {
+      const sections = event.systemPromptOptions?.sections;
+      if (!sections) return;
+      if (delegation) {
+        const text = buildDelegationSection(delegation, env?.paneId ?? '');
+        if (sections['pier-delegation'] !== text) sections['pier-delegation'] = text;
+      } else {
+        delete sections['pier-delegation'];
+      }
+    });
+  }
+
   pi.on('session_tree', async (_event, ctx) => {
     sessionId = resolveSessionId(ctx);
     rebuildFromBranch(ctx);
@@ -447,6 +576,12 @@ export default async function (pi: ExtensionAPI) {
     mirrorTodos();
   });
 
+  /* pi 1.2 counts the run as busy from `before_agent_start`, not `turn_start`: a settlement
+   * notice arriving in that window must enter the D92 buffer instead of being sent immediately. */
+  pi.on('before_agent_start', async () => {
+    agentActive = true;
+  });
+
   pi.on('turn_start', async () => {
     agentActive = true;
     // A11: reset so a previous turn's abort cannot taint this one.
@@ -493,12 +628,16 @@ export default async function (pi: ExtensionAPI) {
     void notices.flush('steer');
   });
 
-  pi.on('agent_settled', async (_event: unknown, ctx) => {
+  pi.on('agent_settled', async (event: unknown, ctx) => {
     agentActive = false;
     gates.report('idle', null);
+    // pi ≥ 1.1 stamps cancelled runs on the event itself; stopReason tracking misses ESC mid-tool
+    // (no final assistant message), so the event field is authoritative when present.
+    const aborted = event !== null && typeof event === 'object' && 'aborted' in event && event.aborted === true;
     const plan = planSettleWake({
       lastStopReason,
       intentionalAbort: coordinator.intentionalAbort,
+      aborted,
       compactionPending: coordinator.selectedCompaction !== null || coordinator.compactionInFlight,
       running: subagentPort.current?.listRunningSubs() ?? [],
       lastNoticeKey: d96NoticeKey,
@@ -529,8 +668,8 @@ export default async function (pi: ExtensionAPI) {
         }),
       });
     }
-    if (lastStopReason !== ABORT_STOP_REASON) void notices.flush('followUp');
-    void pushSettleReply();
+    if (lastStopReason !== ABORT_STOP_REASON && !aborted) void notices.flush('followUp');
+    void pushSettleReply(aborted);
   });
 
   /* ── D101 ObservationPack (obs_recall tool & context projector) ── */
@@ -552,6 +691,7 @@ export default async function (pi: ExtensionAPI) {
     env,
     getTodoItems: () => todos.items,
     getHeldLocks: () => locksHandle.getHeldLocks(),
+    prepareTree: () => publishTreeSnapshot(),
   });
 
   /* ── ask_user_question (v1.3 M8 human gate; master and subagents) ── */
@@ -577,11 +717,52 @@ export default async function (pi: ExtensionAPI) {
     },
   });
 
+  /* ── report_progress (Phase 2, RFC rfc-delegation-identity §3.2): worker → master checkpoint ── */
+  if (isSubagent) {
+    pi.registerTool({
+      name: 'report_progress',
+      label: 'Report Progress',
+      description:
+        'Send the delegating master a short progress update without finishing the task. Use at meaningful checkpoints (a module done, a test went green, a blocker found) — the master sees it in its context but is not interrupted.',
+      promptSnippet: 'report_progress: mid-task checkpoint to the delegating master (does not end the task).',
+      promptGuidelines: [
+        'Call at meaningful checkpoints only — a milestone reached, a risk discovered, a decision the master should know early — not after every tool call.',
+        'One or two sentences per call; the final answer still goes in your normal closing message when the task finishes.',
+      ],
+      parameters: Type.Object({
+        message: Type.String({ description: 'Short checkpoint update for the delegating master.' }),
+      }),
+      async execute(_tc, params) {
+        const parentPipe = delegation?.parentPipe;
+        const message = typeof (params as { message?: unknown })?.message === 'string'
+          ? (params as { message: string }).message.trim()
+          : '';
+        if (!message) {
+          return { content: [{ type: 'text', text: 'Error: `message` is required (one or two sentences).' }], details: {} };
+        }
+        if (!parentPipe) {
+          return { content: [{ type: 'text', text: 'Error: no delegating master pipe is known to this session; progress cannot be delivered.' }], details: {} };
+        }
+        try {
+          const res = await pipeRequest(parentPipe, {
+            type: 'progress',
+            id: `prog-${Date.now()}`,
+            paneId: env?.paneId ?? '',
+            text: message,
+          }, 5000);
+          return res.type === 'ok'
+            ? { content: [{ type: 'text', text: 'Progress delivered to the master (visible in its context, no interruption).' }], details: {} }
+            : { content: [{ type: 'text', text: `Error: master rejected progress report: ${res.message}` }], details: {} };
+        } catch (err) {
+          return { content: [{ type: 'text', text: `Error: could not reach the master pipe: ${(err as Error)?.message ?? err}` }], details: {} };
+        }
+      },
+    });
+  }
+
   pi.on('session_shutdown', async () => {
     coordinator.compactionInFlight = false;
     coordinator.intentionalAbort = false;
-    sessionFocusPoller.current?.stop();
-    sessionFocusPoller.current = null;
     if (pipeServerBox.current) {
       try { pipeServerBox.current.close(); } catch { /* Already closed. */ }
       pipeServerBox.current = null;
@@ -592,6 +773,14 @@ export default async function (pi: ExtensionAPI) {
       } catch {
       }
     }
+    if (treeSnapshot) {
+      try {
+        unlinkSync(treeSnapshot.path);
+      } catch {
+        /* Already swept. */
+      }
+      treeSnapshot = null;
+    }
     client.close();
   });
 
@@ -612,6 +801,7 @@ export default async function (pi: ExtensionAPI) {
       noticePending: notices.noticePending,
       getSessionId: () => sessionId,
       getBlockedDepth: () => gates.depth(),
+      getWorkers: widgetWorkers,
       reconcileOnSettlement,
       withReconcileNotes,
       claimSettleNotice,
@@ -620,6 +810,66 @@ export default async function (pi: ExtensionAPI) {
       jev: { ask: (request, meta) => jevRuntime.ask(request, meta), getMinConfidence: () => effConfig.jev.minConfidence },
       appendRoutingLog,
     });
+
+    /* ── /pier-tree (D113): full todo × subagent delegation tree; the resident widget is minimal ── */
+    pi.registerCommand('pier-tree', {
+      description: 'Show the full delegation tree: your todos plus every subagent\'s todos and settled nodes',
+      handler: async (args: unknown, ctx: unknown) => {
+        const ui = (ctx as { ui?: { notify?: (text: string, level?: string) => void } }).ui;
+        const lines = renderTreeLines();
+        const overlay = typeof args === 'string' && args.trim().toLowerCase() === 'overlay';
+
+        if (client.available && env) {
+          const treeFile = publishTreeSnapshot();
+          if (overlay) {
+            try {
+              const res = await client.openPluginPane({
+                pluginId: 'pier.workbench',
+                entrypoint: 'tree',
+                placement: 'overlay',
+                focus: true,
+                env: { PIER_PANEL: 'tree', PIER_TREE_FILE: treeFile },
+              });
+              if (res.mode === 'pane') return;
+            } catch {
+              // Plugin missing / older herdr: fall back to the in-pane notify view below.
+            }
+          } else {
+            const res = await openPierPanel({ client, env }, { panel: 'tree', treeFile });
+            if (res === 'popup') return;
+            if (res === 'tab') {
+              ui?.notify?.('Herdr < 0.9.1: Pier Tree opened in new tab', 'info');
+              return;
+            }
+            if (res === 'busy') {
+              ui?.notify?.('Another popup is already open — close it and run /pier-tree again.', 'warning');
+              return;
+            }
+          }
+          // 'unavailable' / failed overlay → the old in-pane view.
+        }
+        treeSnapshot = null;
+        ui?.notify?.(lines.join('\n'), 'info');
+      },
+    });
+
+    /** D113 resync: a resumed master rebuilds worker summaries from herdr pi-todo tokens until the
+     * next live push replaces them with full lists. */
+    const resyncWorkerTodos = async (): Promise<void> => {
+      try {
+        const agents = await client.listAgents();
+        for (const a of agents) {
+          const summary = a.tokens?.['pi-todo'];
+          if (typeof summary === 'string' && summary && !workerTodos.has(a.paneId)) {
+            workerTodos.set(a.paneId, { summary, ts: Date.now() });
+          }
+        }
+        todoUi.rerenderWidget?.();
+      } catch {
+        /* herdr absent or unreachable: live pushes remain the source */
+      }
+    };
+    pi.on('session_start', () => { void resyncWorkerTodos(); });
   } else {
     const { mountTodoOnly } = await import('./index-worker.ts');
     await mountTodoOnly({

package/src/jev-core.ts

@@ -8,6 +8,7 @@
  * question needs; instructions are English (CJK is weaker, hence the stricter P0-2 gate); and any
  * answer below its confidence gate counts as unanswered so callers fail open.
  */
+import { isPlainObject } from './guards.ts';
 import { containsLikelySecret, FAILURE_SIGNAL } from './reducer-core.ts';
 
 /* ── Request/response shapes (closed set) ── */
@@ -36,9 +37,6 @@ export type JevParsed =
   | { readonly ok: true; readonly answers: Record<string, JevAnswer>; readonly model: string; readonly usage: JevUsage }
   | { readonly ok: false; readonly reason: string };
 
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
 
 function finiteNumber(v: unknown): number | undefined {
   return typeof v === 'number' && Number.isFinite(v) ? v : undefined;

package/src/panel-open.ts

@@ -0,0 +1,47 @@
+/** Shared Pier panel opening: `/dashboard` and `/pier-tree` both render through one popup entrypoint.
+ *
+ * Herdr popups are a singleton session resource (`popup.close` has no id) and are session-modal, so
+ * the human cannot invoke another slash command while one is open. The command therefore chooses
+ * the initial tab via env; tabs are switched inside the panel (`1`/`2`/`Tab`). A `ui_busy` result is
+ * surfaced instead of silently retrying as a tab. */
+import type { HerdrClientLike, HerdrEnv } from './herdr-client.ts';
+
+export type PierPanel = 'dashboard' | 'tree';
+export type PierPanelOpenResult = 'popup' | 'busy' | 'tab' | 'unavailable';
+
+export interface PierPanelOpenDeps {
+  client: HerdrClientLike;
+  env: HerdrEnv | null;
+}
+
+/**
+ * Open the shared popup on the requested tab. `busy` means another popup/modal owns the session;
+ * the caller should tell the human to close it.
+ */
+export async function openPierPanel(
+  deps: PierPanelOpenDeps,
+  opts: { panel: PierPanel; treeFile?: string | null },
+): Promise<PierPanelOpenResult> {
+  const { client, env } = deps;
+  if (!client.available || !env) return 'unavailable';
+
+  try {
+    const res = await client.openPluginPane({
+      pluginId: 'pier.workbench',
+      entrypoint: 'panel',
+      placement: 'popup',
+      width: '90%',
+      height: '80%',
+      focus: true,
+      env: {
+        PIER_PANEL: opts.panel,
+        ...(opts.treeFile ? { PIER_TREE_FILE: opts.treeFile } : {}),
+      },
+    });
+    if (res.mode === 'fallback_tab') return 'tab';
+    if (res.mode === 'busy') return 'busy';
+    return 'popup';
+  } catch {
+    return 'unavailable';
+  }
+}

package/src/pier-options.ts

@@ -47,11 +47,10 @@ export const PIER_OPTIONS: readonly OptionSpec[] = [
   { name: 'PIER_SETTLEMENT_WINDOW_MS', legacy: 'PI_HERDR_SETTLEMENT_WINDOW_MS', fallback: '60000', min: 0, policy: 'settlementWindowMs', description: 'settlement notice window / machine-inject grace / takeover idle' },
   { name: 'PIER_FOREGROUND_PATIENCE_MS', legacy: 'PI_HERDR_FOREGROUND_PATIENCE_MS', fallback: '300000', min: 0, policy: 'foregroundPatienceMs', description: 'foreground patience before demoting a subagent to background' },
   { name: 'PIER_SESSION_TTL_SECONDS', legacy: 'PI_HERDR_SESSION_TTL_SECONDS', fallback: '600', min: 0, policy: 'sessionTtlSeconds', description: 'session retention after a subagent exits, before GC' },
-  { name: 'PIER_FOCUS_POLL_MS', fallback: '1500', min: 0, description: 'pane-focus sampling cadence for the heat layout (0 disables; event-first on herdr 0.9.1+)' },
   { name: 'PIER_TERMINAL_PROMPT', legacy: 'PI_HERDR_TERMINAL_PROMPT', fallback: '(auto from $SHELL)', description: 'prompt strategy for terminal readiness: bash|zsh|powershell|pwsh' },
   { name: 'PIER_SLIM_FRAME', legacy: 'PI_HERDR_SLIM_FRAME', fallback: '1', description: 'mutation frame around todo-tool cards (0 disables)' },
   { name: 'PIER_TRACE', legacy: 'PI_HERDR_TRACE', fallback: '', description: 'write diagnostics (renderers, swallowed errors) to stderr (or to this file when it is a path)' },
-  { name: 'PIER_TERM_IDLE_MS', legacy: 'PI_HERDR_TERM_IDLE_MS', fallback: '1800000', min: 1, description: 'idle time before pier nudges about an open terminal (0/NaN falls back to the default)' },
+  { name: 'PIER_TERM_IDLE_MS', legacy: 'PI_HERDR_TERM_IDLE_MS', fallback: '300000', min: 1, description: 'idle time before the second cleanup nudge for an open terminal (per-terminal max 2; 0/NaN falls back to the default)' },
   { name: 'PIER_TERM_GRACE_MS', legacy: 'PI_HERDR_TERM_GRACE_MS', fallback: '30000', min: 1, description: 'settle grace before the terminal idle nudge (0/NaN falls back to the default)' },
   { name: 'PIER_TERM_READ_MAX', legacy: 'PI_HERDR_TERM_READ_MAX', fallback: '8000', min: 1, description: 'characters returned per terminal read (0/NaN falls back to the default)' },
   { name: 'PIER_TODO_GRACE_MS', legacy: 'PI_HERDR_TODO_GRACE_MS', fallback: '30000', min: 1, description: 'settle grace before the unfinished-todo reminder (0/NaN falls back to the default)' },

package/src/pipe-channel.ts

@@ -58,6 +58,23 @@ export type PipeRequest =
       id: string;
       role: string;
     }
+  | {
+      /** Phase 2 (RFC rfc-delegation-identity §3.2): worker → master progress report. The master
+       * injects it as a display-less custom message (no turn, no visible chat noise). */
+      type: 'progress';
+      id: string;
+      paneId: string;
+      text: string;
+    }
+  | {
+      /** D113 (RFC rfc-unified-widget): worker → master full todo push on every todo_write, so the
+       * master's resident widget and /pier-tree render live worker state without polling herdr. */
+      type: 'todo_sync';
+      id: string;
+      paneId: string;
+      items: Array<{ content: string; status: string; blocker?: string }>;
+      summary: string;
+    }
   | {
       /** D50: fast-path settlement reply from child to requester, with summary and session path for progressive disclosure. */
       type: 'reply';