pi-pier 0.2.6 → 0.3.0

package/src/index-worker.ts

@@ -16,10 +16,14 @@ export interface TodoOnlyMount {
   todos: TodosService;
   todoUi: TodoUiSlot;
   mirrorTodos: () => void;
+  /** Human-gate depth source; collapses the todo widget to one line while a gate is open. */
+  getBlockedDepth?: () => number;
   /** Master-only stop reminder; omit on worker panes. */
   stopReminder?: {
     getBlockedDepth: () => number;
     getRunningSubs: () => number;
+    isCompactionInFlight?: () => boolean;
+    isIntentionalAbort?: () => boolean;
   };
 }
 
@@ -36,6 +40,7 @@ export async function mountTodoOnly(m: TodoOnlyMount): Promise<void> {
       (m.pi as { appendEntry?: (t: string, d: unknown) => void }).appendEntry?.(customType, data);
     },
     state: m.todoUi,
+    ...(m.getBlockedDepth ? { getBlockedDepth: m.getBlockedDepth } : {}),
     ...(m.stopReminder ? { stopReminder: m.stopReminder } : {}),
   });
   await workerRoot.plugin(todoPlugin);

package/src/index.ts

@@ -15,16 +15,24 @@
  *  - tool-result 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,
+  ASK_TOOL_DESCRIPTION,
+  ASK_TOOL_NAME,
+  gateLabel,
+  hasAskUi,
+  noUiResult,
+  prepareAsk,
+  runAsk,
+} from './ask-user.ts';
 import { pipeNameFor, pipeRequest, startPipeServer } from './pipe-channel.ts';
 import {
   TODO_EDIT_CUSTOM_TYPE,
   currentActivity,
 } from './todo-core.ts';
 
-/** Tier 2: record the synthesized manifest that governed a worker session (D38-compatible and branch-replayable). */
-const ROLE_MANIFEST_CUSTOM_TYPE = 'pi-herdr.role-manifest';
-
+import { APPROVAL_NEEDED_CUSTOM_TYPE, ROLE_MANIFEST_CUSTOM_TYPE, installRenderers } from './renderers.ts';
 import { createHerdrClient } from './herdr-client.ts';
 // The subagent family moved to core/subagent.ts (loader entry, D78/D81); its history-store,
 // session-tail, and gc-core imports moved with it, leaving index.ts only the common readers.
@@ -32,6 +40,7 @@ import { lastAssistantText, readSessionFile } from './session-tail.ts';
 import { fileURLToPath } from 'node:url';
 import { TodosService } from './todos-service.ts';
 import { reconcileTodos } from './reconcile-core.ts';
+import type { TodoUiSlot } from './core/todo.ts';
 import {
   estimateEta,
   formatProgressSuffix,
@@ -50,6 +59,50 @@ import { emptySubagentPortBox } from './subagent-port.ts';
 import { createNoticeBuffer } from './index-notices.ts';
 import { handlePipeRequest } from './index-pipe.ts';
 import { installWriteLocks } from './index-locks.ts';
+import { installDashboardCommand } from './dashboard-command.ts';
+import { registerObservationPack, createCompactionBatchPackHook, type PickMiddleExcerpt } from './core/observation.ts';
+import { createJevRuntime } from './jev-client.ts';
+import {
+  NOTICE_RANK_MIN_CONFIDENCE,
+  buildExcerptWindows,
+  composeNoticeRanking,
+  evaluateExcerptPick,
+  excerptPickRequest,
+  noticeRankRequest,
+} from './jev-core.ts';
+import { completeLineExcerpt } from './observation-core.ts';
+import { installConfigCommand } from './config-command.ts';
+import { CompactCoordinator } from './compact-coordinator.ts';
+import { handleReducerToolResult, type ToolResultEventLike } from './reducer-invoker.ts';
+import {
+  pruneSessionObjects,
+  resolveSessionRoot,
+} from './efficiency-store.ts';
+import {
+  loadEfficiencyConfigFromDisk,
+  resolveEfficiencyConfig,
+  type EfficiencyConfig,
+} from './efficiency-config-core.ts';
+import {
+  resolveDefaultFocusPollMs,
+  parseFocusSample,
+  spawnReflow,
+  startFocusPoller,
+  type FocusPoller,
+} from './focus-poller.ts';
+
+/**
+ * D-4: focus sampling cadence. `PIER_FOCUS_POLL_MS=0` disables the poller (heat layout then only
+ * reacts to herdr events). Invalid values fall back to the version default: 1500ms on Herdr <0.9.1,
+ * 0 (event-first) on 0.9.1+ where native pane.focused is authoritative.
+ */
+function focusPollIntervalMs(env: NodeJS.ProcessEnv = process.env, herdrVersion?: string | null): number {
+  const defaultMs = resolveDefaultFocusPollMs(herdrVersion);
+  const raw = env.PIER_FOCUS_POLL_MS;
+  if (raw === undefined || raw.trim() === '') return defaultMs;
+  const ms = Number(raw);
+  return Number.isFinite(ms) && ms >= 0 ? ms : defaultMs;
+}
 
 /**
  * WS-D7: apply the master-pane manifest to itself through the same mandatory chain as subagents
@@ -87,6 +140,47 @@ export default async function (pi: ExtensionAPI) {
     (mode.composeMaster ? composeMasterRuntime() : null);
   const todos = new TodosService(TodosService.configFromRuntime(runtimeManifest, isSubagent));
   const { client, env } = createHerdrClient();
+  let effConfig: EfficiencyConfig = resolveEfficiencyConfig();
+  const coordinator = new CompactCoordinator();
+  let sessionRoot: string | null = null;
+
+  /* ── Jev decision layer (RFC docs/rfc-jev-integration.md): direct HTTP, total-budget abort,
+   * fail-open at every site. Disabled or keyless => behavior is byte-identical to before. ── */
+  const jevRuntime = createJevRuntime(() => effConfig.jev, {
+    getSessionRoot: () => sessionRoot,
+  });
+  const jevMinConfidence = (): number => effConfig.jev.minConfidence;
+  /** P0-3: candidate windows are generated in code; jev only picks (rerank pattern). */
+  const pickMiddleExcerpt: PickMiddleExcerpt = async (text, excerptBudgetBytes) => {
+    if (!jevRuntime.available) return null;
+    const halfBudget = Math.floor(excerptBudgetBytes / 2);
+    const windows = buildExcerptWindows(text, halfBudget);
+    if (windows.length === 0) return null; // no failure-signal lines -> keep halves, no API call
+    const request = excerptPickRequest(
+      windows,
+      completeLineExcerpt(text, halfBudget, false),
+      completeLineExcerpt(text, excerptBudgetBytes - halfBudget, true),
+    );
+    if (!request) return null;
+    const result = await jevRuntime.ask(request, {
+      questionId: 'obs-excerpt-window',
+      extra: { site: 'obs-excerpt', candidates: windows.map((w) => w.id) },
+      enrich: ({ answers }) => {
+        if (!answers || answers.window === undefined || answers.window.type !== 'choice') return {};
+        return { picked: answers.window.choice, confidence: answers.window.confidence };
+      },
+    });
+    if (!result.ok) return null;
+    const picked = evaluateExcerptPick(result.answers, jevMinConfidence());
+    const window = picked === null ? undefined : windows.find((w) => w.id === picked);
+    return window ? { text: window.text, label: window.label } : null;
+  };
+  // Transcript polish for pier's own custom entries and reminder messages; display-only and
+  // best-effort (older pi builds without the renderer API simply keep the raw rows).
+  const rendererTypes = installRenderers(pi);
+  if (process.env.PI_HERDR_TRACE) {
+    console.error(`[pi-herdr] transcript renderers: ${rendererTypes.length ? rendererTypes.join(', ') : 'none'}`);
+  }
 
   let sessionId: string = process.env.PI_SESSION_FILE ?? process.env.PI_SESSION_ID ?? '';
   /** M16: completion timestamps used as rate-estimation input, appended with todo.completed events. */
@@ -99,6 +193,7 @@ export default async function (pi: ExtensionAPI) {
       const entries = (ctx as { sessionManager?: { getBranch?: () => readonly unknown[] } })
         ?.sessionManager?.getBranch?.() ?? [];
       todos.rebuild(entries);
+      coordinator.rebuildFromBranch(entries);
     } catch {
       // A reconstruction failure must not disrupt the main flow; the next todo_write re-anchors state.
     }
@@ -120,11 +215,6 @@ export default async function (pi: ExtensionAPI) {
     client.reportAgent(state, message).catch(() => {});
   }
 
-  function reportSession(path: string): void {
-    if (!client.available) return;
-    client.reportAgentSession(path).catch(() => {});
-  }
-
   /** Session identity: sessionManager is authoritative (env may be unset in print/RPC mode), with env as fallback. */
   function resolveSessionId(ctx: unknown): string {
     try {
@@ -183,7 +273,7 @@ export default async function (pi: ExtensionAPI) {
         } catch {
           /* Best effort persistence; in-memory state still advances. */
         }
-        todos.applyEdits(plan.edits);
+        todos.applyEdits(plan.edits, { source: 'reconcile' });
         mirrorTodos();
       }
       return plan.noteLines;
@@ -199,8 +289,9 @@ export default async function (pi: ExtensionAPI) {
 
   /* ── M16: progress and tool badges (title suffix + report_agent.message; no new protocol) ── */
 
-  todos.on('todo.completed', (e: { count: number; at: number }) => {
+  todos.on('todo.completed', (e: { count: number; at: number; source?: import('./todos-service.ts').TodoCompletionSource }) => {
     for (let i = 0; i < e.count; i++) completedStamps.push(e.at);
+    coordinator.recordBoundaryCompleted(e.count, e.source);
     mirrorTodos();
   });
 
@@ -228,8 +319,19 @@ export default async function (pi: ExtensionAPI) {
     }
   });
 
+  /* ── D102: Evidence-Preserving Reducer (runs before append-handlers like write-locks) ── */
+  pi.on('tool_result', async (event, ctx) => {
+    if (!effConfig.evidencePreservingReducer.enabled) return;
+    if (!event || typeof event !== 'object') return;
+    return handleReducerToolResult(event as unknown as ToolResultEventLike, ctx, effConfig.evidencePreservingReducer, {
+      epoch: coordinator.state.epoch,
+      jev: { ask: jevRuntime.ask, getMinConfidence: jevMinConfidence },
+    });
+  });
+
+  let locksHandle = { getHeldLocks: () => [] as readonly string[] };
   if (env) {
-    installWriteLocks(pi, {
+    locksHandle = installWriteLocks(pi, {
       client,
       env,
       hard: process.env[WRITE_LOCK_ENV] === '1',
@@ -237,7 +339,7 @@ export default async function (pi: ExtensionAPI) {
   }
 
   /* ── todo family slot (core/todo.ts fills the plugin hook; widget rendering moved with the family) ── */
-  const todoUi: { renderWidget: (ctx: unknown) => void } = {
+  const todoUi: TodoUiSlot = {
     renderWidget: () => { /* No-op before plugin mounting; filled after mounting. */ },
   };
 
@@ -245,6 +347,16 @@ export default async function (pi: ExtensionAPI) {
 
   pi.on('session_start', async (event, ctx) => {
     sessionId = resolveSessionId(ctx);
+    const cwd = (ctx as { cwd?: string }).cwd ?? process.cwd();
+    const isTrusted =
+      typeof (ctx as { isProjectTrusted?: () => boolean }).isProjectTrusted === 'function'
+        ? (ctx as { isProjectTrusted: () => boolean }).isProjectTrusted()
+        : false;
+    effConfig = loadEfficiencyConfigFromDisk({ cwd, isProjectTrusted: isTrusted });
+    sessionRoot = resolveSessionRoot(
+      (ctx as { sessionManager?: { getSessionDir?: () => string | undefined } })?.sessionManager?.getSessionDir?.(),
+      sessionId,
+    );
     rebuildFromBranch(ctx);
     // v1.3 M9 fix (observed): on resume pi restores widget state from the session;
     // calling setWidget again breaks the TUI '/' command-panel route ('/' would be sent to the model as message text).
@@ -254,7 +366,9 @@ export default async function (pi: ExtensionAPI) {
     // and the heatmap amplification provides the exit path. Re-register on resume because session switching resets the overlay.
     if (env) registerSlimFrame(ctx);
     mirrorTodos();
-    reportSession(sessionId);
+    // D-2: the session path is NOT reported here. herdr's own pi integration publishes it
+    // (agent.list/agent.pane show `session_source: "herdr:pi"` on every pi pane, incl. pier subagents),
+    // so pier's pane.report_agent_session was a pure duplicate write of the same field by a second source.
     // D93: sidebar identity is the role name (display_agent takes precedence over detected agent, actions.rs:563 in 0.8.2).
     // master → 'master'; worker → manifest.role (prettify worker-default as worker).
     // A bare pi without a manifest does not report, so ordinary pi sessions remain undisturbed.
@@ -294,6 +408,10 @@ export default async function (pi: ExtensionAPI) {
       }
     }
     reportAgent('idle', null);
+    // Self-healing: a gate does not survive a process restart, but the ask marker lives in herdr
+    // with a 24h TTL, so a session killed while a dialog was open would otherwise keep the pane
+    // looking blocked forever. Depth is 0 on session_start, so this cannot race a live gate.
+    void client.reportAskFlag(null).catch(() => {});
   });
 
   /* ── Tier 2 Weeks 4–5: worker execution enforcement (the manifest's final gate) ──
@@ -305,14 +423,16 @@ export default async function (pi: ExtensionAPI) {
     const tool = typeof event?.toolName === 'string' ? event.toolName : '';
     const gate = planToolGate(tool, runtimeManifest);
     if (gate.kind === 'deny') {
-      return { block: true, reason: gate.reason };
+      // terminate (pi 0.84.1+) stops a batch whose results are all terminating without another
+      // model call, so a blocked worker tool no longer costs an extra round trip.
+      return { block: true, reason: gate.reason, terminate: true };
     }
     if (gate.kind === 'ask') {
       console.error(`${gate.notice} (v1 soft-approval: allowed, hard gate lands in v2)`);
       // Durable trace (V56 anchor): TUI redraw erases stderr, so the session custom entry is authoritative.
       try {
         (pi as { appendEntry?: (customType: string, data: unknown) => void }).appendEntry?.(
-          'pi-herdr.approval-needed',
+          APPROVAL_NEEDED_CUSTOM_TYPE,
           { role: runtimeManifest.role, tool, ts: Date.now() },
         );
       } catch {
@@ -340,9 +460,32 @@ export default async function (pi: ExtensionAPI) {
   let lastStopReason: string | null = null;
   pi.on('turn_start', async () => {
     agentActive = true;
+    // Why (A11): Reset lastStopReason on turn_start so a previous turn's abort
+    // does not taint subsequent turns or suppress settlement wake / notice flush.
+    lastStopReason = null;
+    // Safety fallback: if previous compaction finished without clean callback settlement,
+    // ensure flags are reset. Pi core prohibits prompts while compaction is active, so this is safe.
+    coordinator.compactionInFlight = false;
+    coordinator.intentionalAbort = false;
     reportAgent('working', currentActivity(todos.items));
   });
-  pi.on('turn_end', async (event: unknown) => {
+
+  pi.on('before_provider_request', (_event: unknown, ctx: unknown) => {
+    const usage = (ctx as { getContextUsage?: () => { tokens?: number | null } })?.getContextUsage?.();
+    if (typeof usage?.tokens === 'number') {
+      coordinator.onBeforeProviderRequest(usage.tokens);
+    }
+  });
+
+  pi.on('input', (event: unknown) => {
+    if (event && typeof event === 'object') {
+      coordinator.onInput(event as { text?: string; source?: string; streamingBehavior?: string });
+    }
+  });
+
+  pi.on('session_before_tree', () => (coordinator.compactionInFlight ? { cancel: true } : undefined));
+
+  pi.on('turn_end', async (event: unknown, ctx) => {
     if (event === null || typeof event !== 'object' || !('message' in event)) return;
     const msg = (event as { message: unknown }).message; // 'message' in has been guarded.
     if (msg === null || typeof msg !== 'object') return;
@@ -350,13 +493,22 @@ export default async function (pi: ExtensionAPI) {
     if (role === 'assistant' && typeof stopReason === 'string') {
       lastStopReason = stopReason;
     }
+    if (ctx && typeof ctx === 'object') {
+      coordinator.onTurnEnd({
+        ctx,
+        todos: todos.items,
+        config: effConfig.onlineContextCompact,
+        cancelReminder: todoUi.cancelReminder,
+      });
+    }
   });
 
-  pi.on('agent_settled', async () => {
+  pi.on('agent_settled', async (_event: unknown, ctx) => {
     agentActive = false;
     reportAgent('idle', null);
     const plan = planSettleWake({
       lastStopReason,
+      intentionalAbort: coordinator.intentionalAbort,
       running: subagentPort.current?.listRunningSubs() ?? [],
       lastNoticeKey: d96NoticeKey,
       lastNoticeAt: d96NoticeAt,
@@ -376,6 +528,21 @@ export default async function (pi: ExtensionAPI) {
       const notice = `注意：仍有 ${running.length} 个后台 subagent 在运行：${brief}。若你的任务依赖它们，请等待其结算（subagent list 查看状态）；若不等待，请说明放弃原因。`;
       void sendUserMessageIn(notice);
     }
+    if (ctx && typeof ctx === 'object') {
+      void coordinator.onAgentSettled({
+        ctx,
+        todos: todos.items,
+        pi,
+        config: effConfig.onlineContextCompact,
+        cancelReminder: todoUi.cancelReminder,
+        onBeforeCompact: createCompactionBatchPackHook({
+          getObsConfig: () => effConfig.observationPack,
+          getManifest: () => runtimeManifest,
+          getSessionId: () => sessionId,
+          pickMiddleExcerpt,
+        }),
+      });
+    }
   });
 
   // Official herdr:pi is full-lifecycle authority when installed: it reports blocked
@@ -383,28 +550,42 @@ export default async function (pi: ExtensionAPI) {
   // pane.report_agent is ignored while that authority is live
   // (screen_detection_skip_reason=full_lifecycle_hook_authority). Emit the event so
   // herdr:pi publishes blocked; keep report_agent as fallback when it is absent.
-  function enterBlocked(label: string | null): void {
+  /**
+   * Open one human gate. Nested gates (pier's ask tool plus pi's own ctx.ui prompt, or an
+   * external herdr:blocked producer) are coalesced: only the 0→1 transition reports blocked,
+   * marks the ask flag and folds the widget. Returns true when this call opened the outer gate.
+   */
+  function enterBlocked(label: string | null): boolean {
     blockedDepth += 1;
+    if (blockedDepth > 1) return false;
     reportAgent('blocked', label);
     // D95: human-gate marker lets the workbench heatmap distinguish ask from block.
     if (label) void client.reportAskFlag(label).catch(() => {});
+    // Gate open collapses the todo widget to one line — the question owns the fixed area.
+    todoUi.rerenderWidget?.();
+    return true;
   }
-  function exitBlocked(): void {
-    blockedDepth = Math.max(0, blockedDepth - 1);
-    if (blockedDepth === 0) {
-      reportAgent(agentActive ? 'working' : 'idle', agentActive ? currentActivity(todos.items) : null);
-      // D95: gate released → clear marker.
-      void client.reportAskFlag(null).catch(() => {});
-    }
+  /** Close one gate; only the 1→0 transition restores the pre-gate state. Returns true when closed.
+   *  An unmatched release (no gate open) is ignored rather than reported, so a stray
+   *  ui_prompt_end cannot emit a false "no longer blocked" edge. */
+  function exitBlocked(): boolean {
+    if (blockedDepth === 0) return false;
+    blockedDepth -= 1;
+    // Gate closed → restore the full widget window.
+    todoUi.rerenderWidget?.();
+    if (blockedDepth > 0) return false;
+    reportAgent(agentActive ? 'working' : 'idle', agentActive ? currentActivity(todos.items) : null);
+    // D95: gate released → clear marker.
+    void client.reportAskFlag(null).catch(() => {});
+    return true;
   }
 
   // emit() is synchronous; this flag stops our own listener from double-counting depth.
   let publishingHerdrBlocked = false;
-  function publishHerdrBlocked(active: boolean, label: string | null): void {
+  /** Publish the herdr:blocked edge for pi-herdr's own gates; no-op re-entry is prevented by the flag. */
+  function emitHerdrBlocked(active: boolean, label: string | null): void {
     publishingHerdrBlocked = true;
     try {
-      if (active) enterBlocked(label);
-      else exitBlocked();
       pi.events.emit(
         'herdr:blocked',
         active ? { active: true, ...(label ? { label } : {}) } : { active: false },
@@ -413,6 +594,11 @@ export default async function (pi: ExtensionAPI) {
       publishingHerdrBlocked = false;
     }
   }
+  function publishHerdrBlocked(active: boolean, label: string | null): void {
+    if (active) enterBlocked(label);
+    else exitBlocked();
+    emitHerdrBlocked(active, label);
+  }
   pi.events.on('herdr:blocked', (data) => {
     if (publishingHerdrBlocked) return;
     if (!data || typeof data !== 'object') {
@@ -426,47 +612,96 @@ export default async function (pi: ExtensionAPI) {
     enterBlocked('label' in data && typeof data.label === 'string' ? data.label : null);
   });
 
+  /* ── Generic human-gate reporting (pi 0.84.4+) ─────────────────────────
+   * Why: `ui_prompt_start` / `ui_prompt_end` fire around blocking ctx.ui dialogs.
+   * Scope: only the inherently human-blocking kinds (select / confirm / input / editor).
+   * `custom` is deliberately excluded: pi routes both modals and *persistent overlays*
+   * through ctx.ui.custom, and pier itself registers a resident slim-frame overlay that
+   * never calls done() — treating it as a gate left the pane blocked (and the ask marker
+   * set) for the entire session while the agent kept working. Note that a resident overlay
+   * also holds pi's own prompt span open, so these events generally stop firing in herdr
+   * panes anyway; pier's ask tool opens its gate explicitly and is the reliable path there.
+   * Probed through a structural type because the events postdate our pinned pi devDependency. */
+  const uiPromptEvents = pi as unknown as {
+    on?: (name: 'ui_prompt_start' | 'ui_prompt_end', handler: (event: unknown) => void) => void;
+  };
+  const GATING_PROMPT_KINDS = new Set(['select', 'confirm', 'input', 'editor']);
+  uiPromptEvents.on?.('ui_prompt_start', (event) => {
+    const rec = (event ?? {}) as { kind?: unknown; title?: unknown };
+    const title = typeof rec.title === 'string' && rec.title.trim() ? rec.title.trim() : null;
+    const kind = typeof rec.kind === 'string' ? rec.kind : 'prompt';
+    if (!GATING_PROMPT_KINDS.has(kind)) return;
+    // Normalize once so the gate report and the published edge carry the same label.
+    const label = title ?? kind;
+    // The ask tool opens its own gate first, so this is usually a nested (no-op) transition;
+    // prompts from other extensions or pi core open the gate here.
+    if (enterBlocked(label)) emitHerdrBlocked(true, label);
+  });
+  uiPromptEvents.on?.('ui_prompt_end', () => {
+    if (exitBlocked()) emitHerdrBlocked(false, null);
+  });
+
   /* ── Tool: ask_user_question (v1.3 M8 human gate, available to master and subagents) ── */
 
+  /* ── D101: ObservationPack (obs_recall tool & context projector) ── */
+  registerObservationPack({
+    pi,
+    getConfig: () => effConfig,
+    getRuntimeManifest: () => runtimeManifest,
+    pickMiddleExcerpt,
+    getRemainingHorizon: () => {
+      const usage = (latestCtx as { getContextUsage?: () => { contextWindow?: number } })?.getContextUsage?.();
+      return coordinator.getRemainingHorizon(3, usage?.contextWindow ?? null);
+    },
+  });
+
+  /* ── D104: /pier-config (read-only config guide + guided-change handoff) ──
+   * Supersedes the former /efficiency command: the index line reports OCC/OBS/EPR state and
+   * `show efficiency` lists every D100-D103 knob with its effective value and source. */
+
+  installConfigCommand({ pi });
+  installDashboardCommand({
+    pi,
+    client,
+    env,
+    getTodoItems: () => todos.items,
+    getHeldLocks: () => locksHandle.getHeldLocks(),
+  });
+
   pi.registerTool({
-    name: 'ask_user_question',
+    name: ASK_TOOL_NAME,
     label: 'Ask User',
-    description: [
-      'Ask the human a question and wait for their typed answer.',
-      'Use this when you genuinely need a human decision (approval, direction, trade-off choice) — not for information you can find yourself.',
-      'While waiting, the pane shows as blocked in herdr (the human sees it and can step in).',
-      'The answer comes back as the tool result; then continue your work.',
-    ].join(' '),
-    parameters: Type.Object({
-      question: Type.String({ description: 'The question to ask the human' }),
-    }),
-    async execute(_tc, params, _sig, _upd, ctx) {
-      const question = String(params?.question ?? '').trim();
-      if (!question) {
-        return { content: [{ type: 'text', text: 'Error: `question` must be a non-empty string' }], details: {} };
-      }
-      const ui = (ctx as {
-        ui?: { input?: (title: string, placeholder?: string) => Promise<string | undefined> };
-      }).ui;
-      publishHerdrBlocked(true, question);
-      // Fallback when herdr:pi is absent: a one-shot pi-herdr blocked report can lose
-      // to later working reports; refresh while the gate is open. Do not re-emit
-      // herdr:blocked here — official blockedCount is edge-triggered.
-      const hb = setInterval(() => { reportAgent('blocked', question); }, 5000);
+    description: ASK_TOOL_DESCRIPTION,
+    promptGuidelines: ASK_PROMPT_GUIDELINES,
+    parameters: ASK_PARAMETERS,
+    async execute(_tc, params, signal, _upd, ctx) {
+      const prepared = prepareAsk(params);
+      if (!prepared.ok) return prepared.result;
+      const ui = ctx && typeof ctx === 'object' && 'ui' in ctx ? ctx.ui : undefined;
+      if (!hasAskUi(ui)) return noUiResult();
+      const label = gateLabel(prepared.spec);
+      publishHerdrBlocked(true, label);
+      // The gate stays reported for the whole wait: reportAgent() drops working/idle reports while
+      // blockedDepth > 0, and pi's ui_prompt_start/end events keep the depth honest for prompts
+      // that do not come from this tool. (The old 5s refresh interval is obsolete.)
       try {
-        const answer = await ui?.input?.(question, 'your answer');
-        return {
-          content: [{ type: 'text', text: `The human answered: ${answer ?? '(no answer given)'}` }],
-          details: { question, answer: answer ?? null },
-        };
+        return await runAsk(prepared.spec, ui, signal instanceof AbortSignal ? signal : undefined);
       } finally {
-        clearInterval(hb);
         publishHerdrBlocked(false, null);
       }
     },
   });
 
   pi.on('session_shutdown', async () => {
+    coordinator.compactionInFlight = false;
+    coordinator.intentionalAbort = false;
+    if (sessionRoot) {
+      try {
+        await pruneSessionObjects(sessionRoot);
+      } catch {
+        /* ignore shutdown pruning errors */
+      }
+    }
     client.close();
   });
 
@@ -480,20 +715,56 @@ export default async function (pi: ExtensionAPI) {
     return true;
   }
   const pipeServerBox: { current: ReturnType<typeof startPipeServer> | null } = { current: null };
+  /** D-4: focus sampler for this pane (started on session_start, stopped on session_shutdown). */
+  const sessionFocusPoller: { current: FocusPoller | null } = { current: null };
   let pendingMachineRequest: { id: string; from: string | null; push: boolean; sinceTs: number } | null = null;
   let latestCtx: { abort?: () => void } | null = null;
 
   // triggerTurn:true — idle followUp must start a new turn or settlement is lost.
   const sendUserMessageIn = (content: string): Promise<void> =>
-    (pi as { sendUserMessage?: (content: string, opts?: { deliverAs?: string; triggerTurn?: boolean }) => Promise<void> })
+    (pi as unknown as { sendUserMessage?: (content: string, opts?: { deliverAs?: string; triggerTurn?: boolean }) => Promise<void> })
       .sendUserMessage?.(content, { deliverAs: 'followUp', triggerTurn: true }) ?? Promise.resolve();
   const sendUserMessageAs = (content: string, mode: 'steer' | 'followUp'): Promise<void> =>
-    (pi as { sendUserMessage?: (content: string, opts?: { deliverAs?: string; triggerTurn?: boolean }) => Promise<void> })
+    (pi as unknown as { sendUserMessage?: (content: string, opts?: { deliverAs?: string; triggerTurn?: boolean }) => Promise<void> })
       .sendUserMessage?.(content, { deliverAs: mode, triggerTurn: true }) ?? Promise.resolve();
 
   const notices = createNoticeBuffer({
     isBusy: () => agentActive || lastStopReason === ABORT_STOP_REASON,
     send: sendUserMessageAs,
+    // P0-2: rank collapsed batches by relevance to the master's in-progress work
+    rank: async (contents) => {
+      if (!jevRuntime.available) return null;
+      const inProgressTodos = todos.items
+        .filter((item) => item.status === 'in_progress')
+        .map((item) => item.content);
+      let rankedOrder: number[] | null | undefined;
+      const result = await jevRuntime.ask(
+        noticeRankRequest({ inProgressTodos, notices: [...contents] }),
+        {
+          questionId: 'notice-rank',
+          sessionId,
+          extra: { site: 'notice-rank', noticeCount: contents.length },
+          enrich: ({ answers }) => {
+            if (!answers) return {};
+            rankedOrder = composeNoticeRanking(
+              contents.length,
+              answers,
+              Math.max(effConfig.jev.minConfidence, NOTICE_RANK_MIN_CONFIDENCE),
+            );
+            const values = Array.from({ length: contents.length }, (_, i) => {
+              const rank = answers[`notice_${i}_rank`];
+              const fail = answers[`notice_${i}_fail`];
+              return rank !== undefined && fail !== undefined && rank.type === 'score' && fail.type === 'noul'
+                ? `${rank.score.toFixed(2)}:${rank.confidence.toFixed(2)}:${fail.noul.toFixed(2)}`
+                : '?';
+            });
+            return { order: rankedOrder === null ? 'fallback' : rankedOrder.join(','), values };
+          },
+        },
+      );
+      if (!result.ok) return null;
+      return rankedOrder === undefined || rankedOrder === null ? null : rankedOrder.map((index) => contents[index]!);
+    },
   });
   const deliverNotice = notices.deliverNotice;
   pi.on('turn_end', () => {
@@ -508,6 +779,28 @@ export default async function (pi: ExtensionAPI) {
     latestCtx = ctx as { abort?: () => void } | null;
     const cwd = (ctx as { cwd?: string }).cwd ?? process.cwd();
     const paneId = env?.paneId ?? '';
+    // D-4: herdr 0.9.0 never delivered pane.focused to plugins; 0.9.1+ does. Poller is a
+    // fallback for old servers (see resolveDefaultFocusPollMs). One poller per pane, self-scoped.
+    if (sessionFocusPoller.current) {
+      sessionFocusPoller.current.stop();
+      sessionFocusPoller.current = null;
+    }
+    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 that field (older herdr)
+          // the tick stays silent instead of guessing focus from the tree.
+          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 (!paneId) return;
     const name = pipeNameFor(cwd, paneId);
     if (pipeServerBox.current) {
@@ -530,6 +823,8 @@ export default async function (pi: ExtensionAPI) {
     }
   });
   pi.on('session_shutdown', () => {
+    sessionFocusPoller.current?.stop();
+    sessionFocusPoller.current = null;
     if (pipeServerBox.current) {
       try { pipeServerBox.current.close(); } catch { /* Already closed. */ }
       pipeServerBox.current = null;
@@ -581,6 +876,8 @@ export default async function (pi: ExtensionAPI) {
       reconcileOnSettlement,
       withReconcileNotes,
       claimSettleNotice,
+      isCompactionInFlight: () => coordinator.compactionInFlight,
+      isIntentionalAbort: () => coordinator.intentionalAbort,
     });
   } else {
     const { mountTodoOnly } = await import('./index-worker.ts');
@@ -589,12 +886,15 @@ export default async function (pi: ExtensionAPI) {
       todos,
       todoUi,
       mirrorTodos,
+      getBlockedDepth: () => blockedDepth,
       ...(isSubagent
         ? {}
         : {
             stopReminder: {
               getBlockedDepth: () => blockedDepth,
               getRunningSubs: () => subagentPort.current?.listRunningSubs().length ?? 0,
+              isCompactionInFlight: () => coordinator.compactionInFlight,
+              isIntentionalAbort: () => coordinator.intentionalAbort,
             },
           }),
     });