pi-pier 0.2.6 → 0.2.7

package/README.md

@@ -45,7 +45,7 @@ The installer also verifies node / pi / herdr versions, probes local paths, and
 | `todo_write` | Full-replacement todo list. Session JSONL is the single source of truth; correct rollback on branch switches. Projected live onto the pane title (`▶i ○p ■b ✓c (N/M) · current task`). `/todos` command to view/edit/unblock |
 | `subagent` | Delegate self-contained subtasks to an isolated pi session in its own herdr pane. Actions: `spawn` (default; foreground / parallel / background), `list`, `send`, `interrupt`, `resume` |
 | `terminal` | Persistent interactive shells in dedicated herdr panes. Actions: `open`, `send`, `read`, `signal`, `close`, `list` |
-| `ask_user_question` | Human gate: pane shows blocked in herdr while waiting |
+| `ask_user_question` | Human gate: structured options plus Other; pane shows blocked in herdr while waiting |
 
 ### Behaviors
 
@@ -61,7 +61,7 @@ This extension mutates the pi session even outside herdr. After `pi install npm:
 | Surface | Bare `pi` (no `HERDR_ENV`) | Inside herdr |
 |---|---|---|
 | `todo_write`, `/todos`, widget, anti-freeze, stop reminder | live | live |
-| `ask_user_question` | live (TUI input) | live + blocked marker |
+| `ask_user_question` | live (TUI select/input) | live + blocked marker |
 | Hidden inject (`before_agent_start` todo-read; settle reminder) | live | live |
 | `subagent`, `terminal` | **not registered** | live |
 | `/locks`, write-lock on `write`/`edit` | not installed | live |

package/package.json

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

package/skills/pi-herdr-workflow/SKILL.md

@@ -90,7 +90,7 @@ Call: `subagent(action: "resume", taskId: "<uuid>")`
 
 ## 3. Human gate
 
-- For a human decision (approval, tradeoff, direction), use `ask_user_question` (this plugin). While waiting, your pane is **blocked** in herdr so the human can see and intervene. The answer comes back as the tool result, then you continue.
+- For a human decision (approval, tradeoff, direction), use `ask_user_question` (this plugin). Prefer 2-5 options with short labels and tradeoffs in `description`. Do **not** author an "Other" option — the UI appends "Other (type your own)". Use `recommended` (0-based) for the default and `questions` to batch related decisions (max 4). While waiting, your pane is **blocked** in herdr so the human can see and intervene. The answer comes back as the tool result, then you continue.
 - A human can enter a subagent pane directly. Write the delegation `description` (pane label) so a human understands it at a glance.
 
 ## 4. Multi-agent engineering rules

package/src/ask-user.ts

@@ -0,0 +1,408 @@
+/**
+ * ask_user_question I/O: normalize params, select+Other dialog, result envelope.
+ *
+ * Why: the herdr gate (blocked / pi-ask / widget collapse) stays in index.ts.
+ * This module is the questionnaire — authored options plus a runtime Other row —
+ * so the model cannot forget a free-text escape and Esc is a real decline.
+ */
+import { Type } from 'typebox';
+
+export const ASK_TOOL_NAME = 'ask_user_question';
+export const OTHER_OPTION = 'Other (type your own)';
+export const OTHER_ANSWER = 'Other';
+export const RECOMMENDED_SUFFIX = ' (Recommended)';
+export const MIN_OPTIONS = 2;
+export const MAX_OPTIONS = 5;
+export const MAX_QUESTIONS = 4;
+export const MAX_LABEL_CHARS = 60;
+
+export const DECLINE_TEXT =
+  'User declined to answer the questions. Continue with your best judgment, or ask different questions.';
+export const NO_UI_TEXT =
+  'Error: UI not available (running in non-interactive mode). The user never saw the questions — do NOT treat this as a decline. Ask the questions as plain chat text instead, without using this tool.';
+
+const CUSTOM_ANSWER_TITLE = 'Type your answer:';
+const MULTI_INSTRUCTIONS =
+  'Enter the numbers of all that apply, comma-separated (e.g. "1,3"), or type a custom answer as plain text.';
+const NUMBERED_HINT = 'Enter a number, or type a custom answer.';
+
+const RESERVED_LOWER: Record<string, true> = {
+  [OTHER_OPTION.toLowerCase()]: true,
+  other: true,
+  'type something.': true,
+  next: true,
+  'next →': true,
+};
+
+const OptionSchema = Type.Object({
+  label: Type.String({ description: 'Short display label (1-5 words)' }),
+  description: Type.Optional(Type.String({ description: 'Tradeoff / meaning of this choice' })),
+});
+
+export const ASK_PARAMETERS = Type.Object({
+  question: Type.Optional(Type.String({ description: 'The question to ask the human. Required unless questions is set.' })),
+  options: Type.Optional(Type.Array(OptionSchema, {
+    description: '2-5 authored choices. Do NOT include Other; the UI appends it.',
+  })),
+  multi: Type.Optional(Type.Boolean({ description: 'Allow multiple selections (default false)' })),
+  recommended: Type.Optional(Type.Number({ description: '0-based index of the recommended option; UI adds (Recommended)' })),
+  questions: Type.Optional(Type.Array(
+    Type.Object({
+      id: Type.Optional(Type.String({ description: 'Stable id for mapping answers' })),
+      question: Type.String({ description: 'Question text' }),
+      options: Type.Array(OptionSchema, {
+        description: '2-5 authored choices. Do NOT include Other; the UI appends it.',
+      }),
+      multi: Type.Optional(Type.Boolean({ description: 'Allow multiple selections (default false)' })),
+      recommended: Type.Optional(Type.Number({ description: '0-based recommended option index' })),
+    }),
+    { description: '1-4 related questions in one call. Wins over top-level question/options when set.' },
+  )),
+});
+
+export const ASK_TOOL_DESCRIPTION = [
+  'Ask the human a question and wait for their answer.',
+  'Use this when you genuinely need a human decision (approval, direction, trade-off) — not for information you can find yourself.',
+  'While waiting, the pane shows as blocked in herdr (the human sees it and can step in).',
+  'Prefer 2-5 options with short labels; put tradeoffs in description.',
+  'Do NOT include an "Other" option — the UI appends "Other (type your own)" automatically.',
+  'Use recommended (0-based) to mark the default; "(Recommended)" is added automatically.',
+  'Use multi: true when several options can apply. Group related questions in questions (max 4) rather than calling this tool repeatedly.',
+  'The answer comes back as the tool result; then continue your work.',
+].join(' ');
+
+export const ASK_PROMPT_GUIDELINES = [
+  'Default to action. Ask only when options have materially different tradeoffs the user must decide.',
+  'Do NOT include "Other" in options; the UI appends it.',
+  'Short option labels; explanatory tradeoffs in description.',
+];
+
+export type AskOption = { label: string; description?: string };
+export type AskQuestion = {
+  id?: string;
+  question: string;
+  options: AskOption[];
+  multi: boolean;
+  recommended?: number;
+};
+export type AskSpec =
+  | { mode: 'freeform'; question: string }
+  | { mode: 'questionnaire'; questions: AskQuestion[] };
+
+export type AskAnswer = {
+  question: string;
+  id?: string;
+  kind: 'option' | 'custom' | 'multi';
+  answer: string | null;
+  selected?: string[];
+  customInput?: string;
+};
+
+export type AskDetails = {
+  answers: AskAnswer[];
+  cancelled: boolean;
+  error?: string;
+};
+
+export type AskToolResult = {
+  content: Array<{ type: 'text'; text: string }>;
+  details: AskDetails;
+};
+
+export type AskUi = {
+  select?: (title: string, options: string[], opts?: { signal?: AbortSignal }) => Promise<string | undefined>;
+  input: (title: string, placeholder?: string, opts?: { signal?: AbortSignal }) => Promise<string | undefined>;
+};
+
+export type PrepareAskResult =
+  | { ok: true; spec: AskSpec }
+  | { ok: false; result: AskToolResult };
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function fail(text: string, code: string): { ok: false; result: AskToolResult } {
+  return { ok: false, result: errorResult(text, code) };
+}
+
+function errorResult(text: string, code: string): AskToolResult {
+  return {
+    content: [{ type: 'text', text }],
+    details: { answers: [], cancelled: true, error: code },
+  };
+}
+
+function okResult(details: AskDetails): AskToolResult {
+  return {
+    content: [{ type: 'text', text: formatAskContent(details) }],
+    details,
+  };
+}
+
+export function noUiResult(): AskToolResult {
+  return errorResult(NO_UI_TEXT, 'no_ui');
+}
+
+export function hasAskUi(ui: unknown): ui is AskUi {
+  return typeof (ui as { input?: unknown } | null | undefined)?.input === 'function';
+}
+
+function parseRecommended(raw: unknown, count: number): number | undefined {
+  if (typeof raw !== 'number' || !Number.isInteger(raw) || raw < 0 || raw >= count) return undefined;
+  return raw;
+}
+
+function parseOptions(raw: unknown): { ok: true; options: AskOption[] } | { ok: false; result: AskToolResult } {
+  if (!Array.isArray(raw)) {
+    return fail('Error: `options` must be an array of 2-5 choices', 'empty_options');
+  }
+  if (raw.length < MIN_OPTIONS) {
+    return fail(`Error: each question needs ${MIN_OPTIONS}-${MAX_OPTIONS} options`, 'empty_options');
+  }
+  if (raw.length > MAX_OPTIONS) {
+    return fail(`Error: each question needs ${MIN_OPTIONS}-${MAX_OPTIONS} options`, 'too_many_options');
+  }
+  const options: AskOption[] = [];
+  const seen = new Set<string>();
+  for (const item of raw) {
+    const rec = asRecord(item);
+    const label = typeof rec?.label === 'string' ? rec.label.trim() : '';
+    if (!label) return fail('Error: each option needs a non-empty label', 'empty_options');
+    if (label.length > MAX_LABEL_CHARS) {
+      return fail(`Error: option label exceeds ${MAX_LABEL_CHARS} characters`, 'label_too_long');
+    }
+    if (RESERVED_LOWER[label.toLowerCase()]) {
+      return fail(
+        `Error: option label "${label}" is reserved — the UI appends "${OTHER_OPTION}" automatically`,
+        'reserved_label',
+      );
+    }
+    if (seen.has(label)) {
+      return fail(`Error: duplicate option label "${label}"`, 'duplicate_option_label');
+    }
+    seen.add(label);
+    const description = typeof rec?.description === 'string' ? rec.description.replace(/\s+/g, ' ').trim() : '';
+    options.push(description ? { label, description } : { label });
+  }
+  return { ok: true, options };
+}
+
+function parseQuestion(raw: unknown): { ok: true; question: AskQuestion } | { ok: false; result: AskToolResult } {
+  const rec = asRecord(raw);
+  if (!rec) return fail('Error: each questions[] entry must be an object', 'empty_question');
+  const question = typeof rec.question === 'string' ? rec.question.trim() : '';
+  if (!question) return fail('Error: `question` must be a non-empty string', 'empty_question');
+  const parsed = parseOptions(rec.options);
+  if (!parsed.ok) return parsed;
+  const recommended = parseRecommended(rec.recommended, parsed.options.length);
+  const id = typeof rec.id === 'string' && rec.id.trim() ? rec.id.trim() : undefined;
+  return {
+    ok: true,
+    question: {
+      question,
+      options: parsed.options,
+      multi: rec.multi === true,
+      ...(id ? { id } : {}),
+      ...(recommended !== undefined ? { recommended } : {}),
+    },
+  };
+}
+
+export function prepareAsk(params: unknown): PrepareAskResult {
+  const rec = asRecord(params);
+  if (!rec) return fail('Error: `question` must be a non-empty string', 'empty_question');
+
+  if ('questions' in rec && rec.questions !== undefined) {
+    if (!Array.isArray(rec.questions)) {
+      return fail('Error: `questions` must be an array of 1-4 questions', 'no_questions');
+    }
+    if (rec.questions.length < 1) {
+      return fail('Error: `questions` must contain 1-4 entries', 'no_questions');
+    }
+    if (rec.questions.length > MAX_QUESTIONS) {
+      return fail('Error: `questions` must contain 1-4 entries', 'too_many_questions');
+    }
+    const questions: AskQuestion[] = [];
+    const seen = new Set<string>();
+    for (const item of rec.questions) {
+      const parsed = parseQuestion(item);
+      if (!parsed.ok) return parsed;
+      if (seen.has(parsed.question.question)) {
+        return fail(`Error: duplicate question "${parsed.question.question}"`, 'duplicate_question');
+      }
+      seen.add(parsed.question.question);
+      questions.push(parsed.question);
+    }
+    return { ok: true, spec: { mode: 'questionnaire', questions } };
+  }
+
+  const question = typeof rec.question === 'string' ? rec.question.trim() : '';
+  if (!question) return fail('Error: `question` must be a non-empty string', 'empty_question');
+  if (rec.options === undefined) {
+    return { ok: true, spec: { mode: 'freeform', question } };
+  }
+  const parsed = parseOptions(rec.options);
+  if (!parsed.ok) return parsed;
+  const recommended = parseRecommended(rec.recommended, parsed.options.length);
+  return {
+    ok: true,
+    spec: {
+      mode: 'questionnaire',
+      questions: [{
+        question,
+        options: parsed.options,
+        multi: rec.multi === true,
+        ...(recommended !== undefined ? { recommended } : {}),
+      }],
+    },
+  };
+}
+
+export function gateLabel(spec: AskSpec): string {
+  if (spec.mode === 'freeform') return spec.question;
+  const first = spec.questions[0]?.question ?? '';
+  const extra = spec.questions.length - 1;
+  return extra > 0 ? `${first} (+${extra})` : first;
+}
+
+export function formatAuthoredLine(option: AskOption, index: number, recommended?: number): string {
+  const rec = recommended === index ? RECOMMENDED_SUFFIX : '';
+  const desc = option.description ? ` — ${option.description}` : '';
+  return `${index + 1}. ${option.label}${rec}${desc}`;
+}
+
+export function optionLines(question: AskQuestion): string[] {
+  const lines = question.options.map((option, i) => formatAuthoredLine(option, i, question.recommended));
+  lines.push(`${question.options.length + 1}. ${OTHER_OPTION}`);
+  return lines;
+}
+
+export function parseChoice(chosen: string, lines: readonly string[]): number | null {
+  const trimmed = chosen.trim();
+  const exact = lines.indexOf(trimmed);
+  if (exact >= 0) return exact;
+  const parsed = Number.parseInt(trimmed, 10);
+  if (!Number.isFinite(parsed)) return null;
+  const idx = parsed - 1;
+  return idx >= 0 && idx < lines.length ? idx : null;
+}
+
+function withId(question: AskQuestion, answer: AskAnswer): AskAnswer {
+  return question.id ? { ...answer, id: question.id } : answer;
+}
+
+async function askSingle(ui: AskUi, question: AskQuestion, signal?: AbortSignal): Promise<AskAnswer | undefined> {
+  const lines = optionLines(question);
+  const opts = signal ? { signal } : undefined;
+  const chosen = ui.select
+    ? await ui.select(question.question, lines, opts)
+    : await ui.input(`${question.question}\n\n${lines.join('\n')}\n\n${NUMBERED_HINT}`, '1', opts);
+  if (chosen == null) return undefined;
+  const trimmed = chosen.trim();
+  if (!trimmed) return undefined;
+  const idx = parseChoice(trimmed, lines);
+  if (idx != null && idx < question.options.length) {
+    return withId(question, {
+      question: question.question,
+      kind: 'option',
+      answer: question.options[idx]!.label,
+    });
+  }
+  if (idx === question.options.length) {
+    const typed = await ui.input(`${question.question}\n\n${CUSTOM_ANSWER_TITLE}`, '', opts);
+    if (typed == null || !typed.trim()) return undefined;
+    return withId(question, {
+      question: question.question,
+      kind: 'custom',
+      answer: OTHER_ANSWER,
+      customInput: typed.trim(),
+    });
+  }
+  if (!ui.select) {
+    return withId(question, {
+      question: question.question,
+      kind: 'custom',
+      answer: OTHER_ANSWER,
+      customInput: trimmed,
+    });
+  }
+  return undefined;
+}
+
+async function askMulti(ui: AskUi, question: AskQuestion, signal?: AbortSignal): Promise<AskAnswer | undefined> {
+  const list = question.options
+    .map((option, i) => formatAuthoredLine(option, i, question.recommended))
+    .join('\n');
+  const value = await ui.input(
+    `${question.question}\n\n${list}\n\n${MULTI_INSTRUCTIONS}`,
+    '1,3',
+    signal ? { signal } : undefined,
+  );
+  if (value == null) return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return withId(question, { question: question.question, kind: 'multi', answer: null, selected: [] });
+  }
+  const tokens = trimmed.split(/[,\s]+/).filter((tok) => tok.length > 0);
+  const indices = tokens.map((tok) => {
+    if (!/^\d+\.?$/.test(tok)) return null;
+    const idx = Number.parseInt(tok, 10) - 1;
+    return idx >= 0 && idx < question.options.length ? idx : null;
+  });
+  if (indices.every((i): i is number => i != null)) {
+    const selected: string[] = [];
+    for (const i of indices) {
+      const label = question.options[i]!.label;
+      if (!selected.includes(label)) selected.push(label);
+    }
+    return withId(question, { question: question.question, kind: 'multi', answer: null, selected });
+  }
+  return withId(question, {
+    question: question.question,
+    kind: 'custom',
+    answer: OTHER_ANSWER,
+    customInput: trimmed,
+  });
+}
+
+export function formatAskContent(details: AskDetails): string {
+  if (details.cancelled || details.answers.length === 0) return DECLINE_TEXT;
+  const entries = details.answers.map((answer) => {
+    if (answer.kind === 'custom' && answer.answer === OTHER_ANSWER) {
+      const notes = answer.customInput ? ` user notes: ${answer.customInput}` : '';
+      return `"${answer.question}"="${OTHER_ANSWER}"${notes}`;
+    }
+    if (answer.kind === 'multi') {
+      const labels = answer.selected?.length ? answer.selected.join(', ') : '(none)';
+      return `"${answer.question}"="${labels}"`;
+    }
+    return `"${answer.question}"="${answer.answer ?? ''}"`;
+  });
+  return `User has answered your questions: ${entries.join(', ')}. You can now continue with the user's answers in mind.`;
+}
+
+export async function runAsk(spec: AskSpec, ui: AskUi, signal?: AbortSignal): Promise<AskToolResult> {
+  if (spec.mode === 'freeform') {
+    const answer = await ui.input(spec.question, 'your answer', signal ? { signal } : undefined);
+    if (answer == null || !answer.trim()) {
+      return okResult({ answers: [], cancelled: true });
+    }
+    const trimmed = answer.trim();
+    return okResult({
+      answers: [{ question: spec.question, kind: 'custom', answer: trimmed, customInput: trimmed }],
+      cancelled: false,
+    });
+  }
+  const answers: AskAnswer[] = [];
+  for (const question of spec.questions) {
+    const answer = question.multi
+      ? await askMulti(ui, question, signal)
+      : await askSingle(ui, question, signal);
+    if (!answer) return okResult({ answers, cancelled: true });
+    answers.push(answer);
+  }
+  return okResult({ answers, cancelled: false });
+}

package/src/core/terminal.ts

@@ -13,6 +13,7 @@ import type { HerdrClientLike } from '../herdr-client.ts';
 import {
   READINESS_TIMEOUT_MS,
   READ_MAX_CHARS,
+  TERM_REMINDER_CUSTOM_TYPE,
   TERMINALS_CUSTOM_TYPE,
   activeTerminalPaneIds,
   classifyReadiness,
@@ -21,10 +22,12 @@ import {
   detectFullscreenTUI,
   foldTerminalsRegistry,
   makeTerminalsRegistry,
+  planIdleTerminalReminder,
   promptStrategyFor,
   registerTerminal,
   stripAnsi,
   summarizeSessions,
+  terminalReminderGraceMs,
   validateSendText,
   validateSignal,
   type ReadCursor,
@@ -95,7 +98,85 @@ export default function terminalPlugin(ctx: Context): void {
     rebuildTerminals(eventCtx);
   });
 
+  // Session teardown (quit / Ctrl+D / SIGTERM) is the last chance to reclaim resident shells:
+  // terminals are persistent by design, so a master that exits without closing them leaks live
+  // zsh panes. Session SWITCH never fires this event (only session_start/session_tree), so
+  // switching branches cannot kill shells that the registry replays on the next session_start.
+  scoped.on('session_shutdown', async () => {
+    idleReminderTimer && clearTimeout(idleReminderTimer);
+    idleReminderTimer = null;
+    const open = terminals.filter((t) => t.status === 'open');
+    if (open.length === 0) return;
+    await Promise.allSettled(open.map((t) => client.closePane(t.paneId)));
+    const now = Date.now();
+    terminals = terminals.map((t) =>
+      t.status === 'open' ? { ...t, status: 'closed' as const, closedAt: now } : t,
+    );
+    persistTerminals();
+  });
+
+  // Turn-end nudge: remind the model to close terminals idle past the threshold (wF:p7 orphan —
+  // a one-shot background compile left a dead split in the main tab forever). Same delivery
+  // shape as the todo stop reminder: grace window, cancel on agent_start, capped followUp.
+  const piSend = surface.raw as {
+    sendMessage?: (
+      message: { customType: string; content: string; display?: boolean },
+      opts?: { deliverAs?: string; triggerTurn?: boolean },
+    ) => Promise<void>;
+  };
+  let idleReminders = 0;
+  let idleReminderTimer: NodeJS.Timeout | null = null;
+  scoped.on('agent_start', () => {
+    if (idleReminderTimer !== null) {
+      clearTimeout(idleReminderTimer);
+      idleReminderTimer = null;
+    }
+  });
+  scoped.on('agent_settled', async () => {
+    if (idleReminderTimer !== null) {
+      clearTimeout(idleReminderTimer);
+      idleReminderTimer = null;
+    }
+    const plan = planIdleTerminalReminder({
+      open: terminals.filter((t) => t.status === 'open'),
+      now: Date.now(),
+      reminders: idleReminders,
+    });
+    if (!plan.due || plan.content == null) return;
+    // 01a06ae3 goodbye-loop: mark the covered terminals nudged NOW (persisted), and deliver the
+    // notice as a queued followUp WITHOUT triggerTurn — a reminder alone must never wake the
+    // agent, or a farewell exchange loops: wake → polite goodbye → settle → nudge → wake …
+    const now = Date.now();
+    const ids = new Set(plan.ids);
+    terminals = terminals.map((t) => (ids.has(t.terminalId) ? { ...t, nudgedAt: now } : t));
+    persistTerminals();
+    idleReminders += 1;
+    const content = plan.content;
+    idleReminderTimer = setTimeout(() => {
+      idleReminderTimer = null;
+      void (async () => {
+        const send = piSend.sendMessage;
+        if (typeof send !== 'function') return;
+        try {
+          await send(
+            { customType: TERM_REMINDER_CUSTOM_TYPE, content, display: true },
+            { deliverAs: 'followUp' },
+          );
+        } catch {
+          /* Delivery failure is non-fatal; the cap already bounds retries. */
+        }
+      })();
+    }, terminalReminderGraceMs());
+    idleReminderTimer.unref?.();
+  });
+
   const TERM_READ_MAX = Number(process.env.PI_HERDR_TERM_READ_MAX ?? READ_MAX_CHARS) || READ_MAX_CHARS;
+  /** wait action: default and ceiling for the blocking output wait (an LLM call must not hang forever). */
+  const WAIT_DEFAULT_MS = 120_000;
+  const WAIT_MAX_MS = 600_000;
+  /** wait action: recent-tail size handed back on timeout so the model can decide the next move. */
+  const WAIT_TAIL_CHARS = 2_000;
+
   const errText = (msg: string) => ({ content: [{ type: 'text' as const, text: `Error: ${msg}` }], details: {} });
 
   scoped.registerTool({
@@ -103,22 +184,30 @@ export default function terminalPlugin(ctx: Context): void {
     label: 'Terminal',
     description: [
       'Manage persistent interactive terminals (resident shells in dedicated herdr panes).',
-      'Operations: open (create session), send (type commands), read (capture output), signal (ctrl+c/ctrl+d/ctrl+z/esc/enter), close (kill shell), list (show all).',
+      'Operations: open (create session), send (type commands), wait (block until output matches a pattern), read (capture output), signal (ctrl+c/ctrl+d/ctrl+z/esc/enter), close (kill shell), list (show all).',
       'The shell keeps cwd, environment variables, and background processes across calls.',
       'Use for dev servers, REPLs, or multi-step shell work — not one-shot bash calls.',
+      'Close a terminal with action: "close" as soon as the work in it is done — finished terminals are never auto-reclaimed and keep occupying a pane.',
+      'Long job pattern: send "cmd; echo TERM_DONE_$?" then wait with pattern "TERM_DONE_" — the sentinel also carries the exit code; redirect verbose output to a log file and read the file, because output between two reads is lost.',
+      'After send, use read to confirm the command actually started; multi-line text executes line-by-line. send(wait_prompt: true) refuses to queue text while a previous command is still running.',
     ].join(' '),
     parameters: Type.Object({
       action: Type.Union([
         Type.Literal('open'),
         Type.Literal('send'),
+        Type.Literal('wait'),
         Type.Literal('read'),
         Type.Literal('signal'),
         Type.Literal('close'),
         Type.Literal('list'),
       ], { description: 'Terminal operation to perform' }),
       cwd: Type.Optional(Type.String({ description: '[open] Working directory for the shell (defaults to session cwd)' })),
-      terminal_id: Type.Optional(Type.String({ description: '[send|read|signal|close] Terminal id returned by open action' })),
+      terminal_id: Type.Optional(Type.String({ description: '[send|wait|read|signal|close] Terminal id returned by open action' })),
       text: Type.Optional(Type.String({ description: '[send] Command text to type and run (Enter appended automatically)' })),
+      wait_prompt: Type.Optional(Type.Boolean({ description: '[send] Verify the shell is back at a prompt before sending; refuses with the detected readiness instead of queueing text behind a running command' })),
+      pattern: Type.Optional(Type.String({ description: '[wait] Literal text or regular expression to wait for in pane output' })),
+      regex: Type.Optional(Type.Boolean({ description: '[wait] Treat pattern as a regular expression (default: literal substring)' })),
+      timeout_ms: Type.Optional(Type.Number({ description: '[wait] Give up after this many ms (default 120000, max 600000)' })),
       pane_id: Type.Optional(Type.String({ description: '[read] Direct pane read (limited to own tab panes only)' })),
       max_chars: Type.Optional(Type.Number({ description: '[read] Output cap for this read (default 10000)' })),
       key: Type.Optional(Type.String({ description: '[signal] Control key: ctrl+c | ctrl+d | ctrl+z | esc | enter' })),
@@ -128,18 +217,33 @@ export default function terminalPlugin(ctx: Context): void {
       switch (action) {
         case 'open': return executeTerminalOpen(params, ctx);
         case 'send': return executeTerminalSend(params);
+        case 'wait': return executeTerminalWait(params);
         case 'read': return executeTerminalRead(params);
         case 'signal': return executeTerminalSignal(params);
         case 'close': return executeTerminalClose(params);
         case 'list': return executeTerminalList();
         default:
           return errText(action
-            ? `unknown action "${action}" (valid: open, send, read, signal, close, list)`
-            : 'action is required (open, send, read, signal, close, list)');
+            ? `unknown action "${action}" (valid: open, send, wait, read, signal, close, list)`
+            : 'action is required (open, send, wait, read, signal, close, list)');
       }
     },
   });
 
+  /** Probe whether the shell sits at its interactive prompt (advisory: probe failures degrade to 'busy'). */
+  async function probeReadiness(paneId: string): Promise<'prompt' | 'silent' | 'busy'> {
+    const prompt = promptStrategyFor();
+    try {
+      const matched = await client.waitForOutput(paneId, { type: 'regex', value: prompt.waitPattern }, READINESS_TIMEOUT_MS);
+      if (matched) return 'prompt';
+      const read = await client.readPane(paneId, { stripAnsi: false });
+      return classifyReadiness(stripAnsi(read.text), { silentMs: 0, prompt });
+    } catch {
+      /* Readiness is advisory, so probe failures still leave a usable terminal. */
+      return 'busy';
+    }
+  }
+
   async function executeTerminalOpen(params, ctx) {
     if (!client.available || !env) return errText('terminal tools require a herdr-managed pane');
     const cwd = typeof params?.cwd === 'string' && params.cwd ? params.cwd
@@ -160,18 +264,7 @@ export default function terminalPlugin(ctx: Context): void {
     r.entry.paneId = paneId;
     terminals = r.entries;
     persistTerminals();
-    const prompt = promptStrategyFor();
-    let readiness: 'prompt' | 'silent' | 'busy' = 'busy';
-    try {
-      const matched = await client.waitForOutput(paneId, { type: 'regex', value: prompt.waitPattern }, READINESS_TIMEOUT_MS);
-      if (matched) readiness = 'prompt';
-      else {
-        const read = await client.readPane(paneId, { stripAnsi: false });
-        readiness = classifyReadiness(stripAnsi(read.text), { silentMs: 0, prompt });
-      }
-    } catch {
-      /* Readiness is advisory, so probe failures still leave a usable terminal. */
-    }
+    const readiness = await probeReadiness(paneId);
     const text = [
       `terminal ${r.entry.terminalId} open (pane ${paneId})`,
       `cwd: ${cwd}`,
@@ -185,6 +278,18 @@ export default function terminalPlugin(ctx: Context): void {
     if (!entry) return errText(`unknown or closed terminal "${String(params?.terminal_id)}" (see action list)`);
     const v = validateSendText(typeof params?.text === 'string' ? params.text : '');
     if (!v.ok) return errText(v.error);
+    if (params?.wait_prompt === true) {
+      // Orchestration convention: read before writing. Text typed while a previous command still
+      // owns the foreground gets queued and fires later, which reads as "the shell ignored me".
+      // Refuse with the observed readiness instead of guessing.
+      const readiness = await probeReadiness(entry.paneId);
+      if (readiness !== 'prompt') {
+        return errText(
+          `shell is ${readiness === 'busy' ? 'busy (a previous command may still be running)' : 'silent (no prompt detected)'} — text was NOT sent. `
+            + 'Use action read to inspect the pane, or omit wait_prompt to send anyway.',
+        );
+      }
+    }
     try {
       await client.sendPaneText(entry.paneId, v.text);
     } catch (e) {
@@ -194,6 +299,50 @@ export default function terminalPlugin(ctx: Context): void {
     return { content: [{ type: 'text', text: `sent to ${entry.terminalId} (${v.text.length} chars)` }], details: { terminal_id: entry.terminalId } };
   }
 
+  async function executeTerminalWait(params) {
+    const entry = findOpenTerminal(params?.terminal_id);
+    if (!entry) return errText(`unknown or closed terminal "${String(params?.terminal_id)}" (see action list)`);
+    const raw = typeof params?.pattern === 'string' ? params.pattern : '';
+    if (!raw) return errText('pattern is required (literal text, or a regular expression with regex: true)');
+    const useRegex = params?.regex === true;
+    if (useRegex) {
+      try {
+        new RegExp(raw);
+      } catch (e) {
+        return errText(`invalid regex: ${(e as Error).message}`);
+      }
+    }
+    const requested = typeof params?.timeout_ms === 'number' && params.timeout_ms > 0 ? params.timeout_ms : WAIT_DEFAULT_MS;
+    const timeoutMs = Math.min(Math.max(requested, 1000), WAIT_MAX_MS);
+    const matcher = useRegex ? { type: 'regex' as const, value: raw } : { type: 'substring' as const, value: raw };
+    let matched: boolean | null;
+    try {
+      matched = await client.waitForOutput(entry.paneId, matcher, timeoutMs);
+    } catch (e) {
+      return errText(`wait failed (pane may be closed): ${(e as Error).message}`);
+    }
+    if (matched !== true) {
+      // wait-for-text convention: on timeout, hand back the recent tail so the model can decide
+      // the next move instead of re-polling blind.
+      let tail = '';
+      try {
+        const read = await client.readPane(entry.paneId, { stripAnsi: false });
+        tail = stripAnsi(read.text).slice(-WAIT_TAIL_CHARS);
+      } catch {
+        /* The pane is gone; the timeout text alone still tells the model it is stuck. */
+      }
+      const reason = matched === false ? 'no match' : 'wait unavailable';
+      return {
+        content: [{ type: 'text', text: `no match within ${timeoutMs}ms (${reason}).${tail ? `\nrecent output tail:\n${tail}` : ''}` }],
+        details: { terminal_id: entry.terminalId, matched: false, pattern: raw },
+      };
+    }
+    return {
+      content: [{ type: 'text', text: `matched in ${entry.terminalId} — output is ready, use action read to inspect it` }],
+      details: { terminal_id: entry.terminalId, matched: true, pattern: raw },
+    };
+  }
+
   async function executeTerminalRead(params) {
     let paneId: string | null = null;
     let entry: TerminalEntry | null = null;

package/src/core/todo.ts

@@ -31,6 +31,8 @@ import { anchorTodoRange, formatTodoSummary, renderTodoGroups } from '../todo-wi
 export interface TodoUiSlot {
   /** Lets index lifecycle events render through the currently mounted plugin. */
   renderWidget: (ctx: unknown) => void;
+  /** Re-render from the last seen context without a fresh event (human-gate open/close). */
+  rerenderWidget?: () => void;
 }
 
 interface TodoDeps {
@@ -41,6 +43,8 @@ interface TodoDeps {
   mirrorTodos: () => void;
   appendEntry: (customType: string, data: unknown) => void;
   state: TodoUiSlot;
+  /** Human-gate depth (ask_user_question / herdr:blocked); >0 collapses the widget to one line. */
+  getBlockedDepth?: () => number;
   /** Master-only unfinished-todo reminder; omitted on worker panes. */
   stopReminder?: {
     getBlockedDepth: () => number;
@@ -67,8 +71,18 @@ export const WIDGET_MAX_LINES = 10;
  * completions. A +N line points to /todos when the full plan cannot fit. This fixes 01a03c0d,
  * where active work scrolled out while only the final entries remained visible.
  */
-export function widgetLines(items: readonly TodoItem[], opts?: { archivedAgeMs?: number | null }): string[] {
+export function widgetLines(
+  items: readonly TodoItem[],
+  opts?: { archivedAgeMs?: number | null; blockedDepth?: number | null },
+): string[] {
   if (items.length === 0) return [];
+  // Human gate open (ask_user_question waiting): the question + editor own the fixed area, so the
+  // widget collapses to the one-line summary — /todos still reaches the full list. Without this,
+  // a 10-line widget plus a multi-line question leaves almost no scrollable transcript
+  // (user-reported: both blocks visible ⇒ history range too small).
+  if ((opts?.blockedDepth ?? 0) > 0) {
+    return [`${formatTodoSummary(items)} · /todos 全量`];
+  }
   // Collapse archived plans to two lines so stale work cannot monopolize the widget.
   if (opts?.archivedAgeMs != null) {
     return [
@@ -95,7 +109,7 @@ export function widgetLines(items: readonly TodoItem[], opts?: { archivedAgeMs?:
 
 export default function todoPlugin(ctx: Context): void {
   const surface = ctx.get('pi-herdr.surface') as PiSurface<object>;
-  const { todos, allowParallelInProgress, maxItems, mirrorTodos, appendEntry, state, stopReminder } =
+  const { todos, allowParallelInProgress, maxItems, mirrorTodos, appendEntry, state, stopReminder, getBlockedDepth } =
     ctx.get('pi-herdr.todo-deps') as TodoDeps;
   const scoped = surface.forModule(import.meta.url);
 
@@ -115,9 +129,15 @@ export default function todoPlugin(ctx: Context): void {
       : undefined;
   }
 
+  /** Gate transitions fire outside lifecycle events; remember one ctx so rerenderWidget can target the live ui. */
+  let lastEventCtx: unknown = null;
   function renderWidget(eventCtx: unknown): void {
+    if (eventCtx !== null && eventCtx !== undefined) lastEventCtx = eventCtx;
     try {
-      widgetUi(eventCtx)?.setWidget?.('todos', widgetLines(todos.items, { archivedAgeMs: archivedAgeMs() }));
+      widgetUi(eventCtx)?.setWidget?.('todos', widgetLines(todos.items, {
+        archivedAgeMs: archivedAgeMs(),
+        blockedDepth: getBlockedDepth?.() ?? 0,
+      }));
     } catch {
       /* Older pi versions may omit widget support without disabling todo tracking. */
     }
@@ -125,6 +145,7 @@ export default function todoPlugin(ctx: Context): void {
 
   // Let index lifecycle hooks call the current plugin implementation.
   state.renderWidget = renderWidget;
+  state.rerenderWidget = () => renderWidget(lastEventCtx);
 
   /* ── Read hook: D39 reminders and stale-plan thawing ────────────── */
   let todoReadTurn = 0;

package/src/index-master.ts

@@ -86,9 +86,10 @@ export async function mountMasterPlugins(m: MasterPluginMount): Promise<void> {
     maxItems: 15,
     mirrorTodos: m.mirrorTodos,
     appendEntry: (customType: string, data: unknown) => {
-      (m.pi as { appendEntry?: (t: string, d: unknown) => void }).appendEntry?.(customType, data);
+      (m.pi as { appendEntry?: (t: string, d: unknown) => void }).appendEntry?.(customType, d);
     },
     state: m.todoUi,
+    getBlockedDepth: m.getBlockedDepth,
     stopReminder: {
       getBlockedDepth: m.getBlockedDepth,
       getRunningSubs: () => m.port.current?.listRunningSubs().length ?? 0,

package/src/index-worker.ts

@@ -16,6 +16,8 @@ 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;
@@ -33,9 +35,10 @@ export async function mountTodoOnly(m: TodoOnlyMount): Promise<void> {
     maxItems: 15,
     mirrorTodos: m.mirrorTodos,
     appendEntry: (customType: string, data: unknown) => {
-      (m.pi as { appendEntry?: (t: string, d: unknown) => void }).appendEntry?.(customType, data);
+      (m.pi as { appendEntry?: (t: string, d: unknown) => void }).appendEntry?.(customType, d);
     },
     state: m.todoUi,
+    ...(m.getBlockedDepth ? { getBlockedDepth: m.getBlockedDepth } : {}),
     ...(m.stopReminder ? { stopReminder: m.stopReminder } : {}),
   });
   await workerRoot.plugin(todoPlugin);

package/src/index.ts

@@ -15,7 +15,17 @@
  *  - 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,
@@ -32,6 +42,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,
@@ -237,7 +248,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. */ },
   };
 
@@ -388,6 +399,8 @@ export default async function (pi: ExtensionAPI) {
     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?.();
   }
   function exitBlocked(): void {
     blockedDepth = Math.max(0, blockedDepth - 1);
@@ -396,6 +409,8 @@ export default async function (pi: ExtensionAPI) {
       // D95: gate released → clear marker.
       void client.reportAskFlag(null).catch(() => {});
     }
+    // Gate closed → restore the full widget window.
+    todoUi.rerenderWidget?.();
   }
 
   // emit() is synchronous; this flag stops our own listener from double-counting depth.
@@ -429,36 +444,24 @@ export default async function (pi: ExtensionAPI) {
   /* ── Tool: ask_user_question (v1.3 M8 human gate, available to master and subagents) ── */
 
   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);
+    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);
       // 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);
+      const hb = setInterval(() => { reportAgent('blocked', label); }, 5000);
       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);
@@ -589,6 +592,7 @@ export default async function (pi: ExtensionAPI) {
       todos,
       todoUi,
       mirrorTodos,
+      getBlockedDepth: () => blockedDepth,
       ...(isSubagent
         ? {}
         : {

package/src/slim-frame.ts

@@ -21,6 +21,10 @@
  * (done() is never called, leaving the Promise pending, swallowing rejection, and never awaiting it). If switching
  * pi sessions removes the overlay (resetExtensionUI), the static frame naturally exits without affecting the main
  * flow. PI_HERDR_SLIM_FRAME=0 is the escape hatch.
+ * Resize watchdog (D98): the component owns a SIGWINCH listener plus a 1s size poll that call tui.requestRender() on
+ * any PTY size change. Why: long-running sessions stop re-rendering on resize (observed in herdr — an idle master
+ * shrunk by heat reflow froze on a stale clipped frame: no todo, no title), so pi's own resize wiring cannot be relied
+ * on; columns/rows are read live per render, so one render is the whole fix. Stopped in dispose().
  */
 
 import { isArchived } from './stale-core.ts';
@@ -38,6 +42,8 @@ export const SLIM_TODO_MIN_ROWS = 3;
 export const SLIM_TODO_MIN_COLS = 16;
 /** Empty-list copy: the pane is alive but has no plan yet (replaces a lone ·). */
 export const SLIM_EMPTY_COPY = 'no todos yet';
+/** D98: watchdog poll period — SIGWINCH covers the delivered signal; the poll covers lost ones (e.g. after suspend). */
+export const RESIZE_WATCHDOG_MS = 1_000;
 
 /** Visibility predicate (overlayOptions.visible invokes it on every render frame). */
 export function isSlimFrame(cols: number, rows: number): boolean {
@@ -227,6 +233,11 @@ class SlimFrameComponent {
   private cache: { width: number; lines: string[] } | null = null;
   private readonly tui: FrameTui;
   private readonly colorize: (s: string) => string;
+  /** D98 watchdog: last PTY size seen by onMaybeResized (re-seeded at watchdog start). */
+  private seenCols = 0;
+  private seenRows = 0;
+  private sigwinch: (() => void) | null = null;
+  private poll: NodeJS.Timeout | null = null;
 
   constructor(tui: FrameTui, colorize: (s: string) => string) {
     this.tui = tui;
@@ -271,13 +282,56 @@ class SlimFrameComponent {
 
   /** Reclaim the module singleton when pi tears down the overlay (session switch/exit), allowing re-registration. */
   dispose(): void {
+    this.stopResizeWatchdog();
     if (active === this) active = null;
   }
+
+  /** Live PTY size (pi-tui reads the same source on every render; an instance method so tests can stub it). */
+  viewportSize(): { cols: number; rows: number } {
+    return { cols: process.stdout.columns ?? 0, rows: process.stdout.rows ?? 0 };
+  }
+
+  /** D98: SIGWINCH handler and poll tick — exactly one requestRender per actual size change; the next render reads live sizes. */
+  readonly onMaybeResized = (): void => {
+    const { cols, rows } = this.viewportSize();
+    if (cols === this.seenCols && rows === this.seenRows) return;
+    this.seenCols = cols;
+    this.seenRows = rows;
+    this.tui.requestRender();
+  };
+
+  /** Start the D98 watchdog (idempotent). SIGWINCH covers the delivered signal; the poll covers lost ones. */
+  startResizeWatchdog(): void {
+    if (this.poll) return;
+    const size = this.viewportSize();
+    this.seenCols = size.cols;
+    this.seenRows = size.rows;
+    try {
+      process.on('SIGWINCH', this.onMaybeResized);
+      this.sigwinch = this.onMaybeResized;
+    } catch {
+      /* Platforms without a SIGWINCH mapping keep the poll only. */
+    }
+    this.poll = setInterval(this.onMaybeResized, RESIZE_WATCHDOG_MS);
+    this.poll.unref?.();
+  }
+
+  private stopResizeWatchdog(): void {
+    if (this.sigwinch) {
+      process.removeListener('SIGWINCH', this.sigwinch);
+      this.sigwinch = null;
+    }
+    if (this.poll) {
+      clearInterval(this.poll);
+      this.poll = null;
+    }
+  }
 }
 
 
-/** Test injection point (reset module state). */
+/** Test injection point (reset module state); dispose first so an undisposed component's watchdog cannot leak. */
 export function resetForTest(): void {
+  active?.dispose();
   active = null;
 }
 
@@ -302,6 +356,7 @@ export function registerSlimFrame(eventCtx: unknown): void {
     const pending = custom(
       (tui, theme) => {
         const comp = new SlimFrameComponent(tui, (s) => theme.fg('accent', s));
+        comp.startResizeWatchdog();
         active = comp;
         return comp;
       },

package/src/terminal-core.ts

@@ -57,13 +57,10 @@ export interface TerminalEntry {
   label: string | null;
   createdAt: number;
   lastActivityAt: number;
+  /** Idle-nudge bookkeeping: set when this terminal has been nudged once (per-entry, persisted). */
+  nudgedAt: number | null;
   status: 'open' | 'closed';
   closedAt: number | null;
-  /** Why: Preserve the established compatibility and safety behavior. */
-  readRevision: number | null;
-  readLen: number;
-  readTail: string;
-  readEoTail: string;
 }
 
 export interface TerminalsRegistry {
@@ -107,6 +104,7 @@ export function registerTerminal(
     label: opts.label ?? (opts.cwd ? basename(opts.cwd.replace(/\\/g, '/')) || opts.cwd : null),
     createdAt: opts.createdAt,
     lastActivityAt: opts.createdAt,
+    nudgedAt: null,
     status: 'open',
     closedAt: null,
     readRevision: null,
@@ -322,9 +320,90 @@ export function foldTerminalsRegistry(entries: readonly BranchEntryLike3[]): Ter
         closedAt: typeof t.closedAt === 'number' ? t.closedAt : null,
         readRevision: typeof t.readRevision === 'number' ? t.readRevision : null,
         readLen: typeof t.readLen === 'number' ? t.readLen : 0,
-        readTail: typeof t.readTail === 'string' ? t.readTail : '',
-        readEoTail: typeof t.readEoTail === 'string' ? t.readEoTail : '',
+        lastActivityAt: typeof t.lastActivityAt === 'number' ? t.lastActivityAt : 0,
+        nudgedAt: typeof t.nudgedAt === 'number' ? t.nudgedAt : null,
+        status: t.status === 'closed' ? ('closed' as const) : ('open' as const),
       }));
   }
   return found;
 }
+
+/* ── Idle-terminal nudge: turn-end self-cleanup for shells the model forgot to close ──
+ * Observed (wF:p7 orphan): a master opened a resident terminal for a one-shot background
+ * compile, the job finished, and nothing ever closed the pane — terminals are persistent by
+ * design, so the shell lingered as a dead split in the main tab. Decision core mirrors the
+ * todo stop-reminder: pure plan here, delivery wiring in core/terminal. */
+
+/** Cap idle-terminal nudges for the lifetime of the process (same shape as TODO_REMINDERS_MAX). */
+export const TERM_REMINDERS_MAX = 2;
+
+/** Idle threshold before a nudge is due; PI_HERDR_TERM_IDLE_MS is read per call so tests can use small values. */
+export function terminalIdleMs(): number {
+  return Number(process.env.PI_HERDR_TERM_IDLE_MS ?? 30 * 60_000) || 30 * 60_000;
+}
+
+/** Grace from agent_settled to injection, letting the user read the answer and intervene; cancel on agent_start. */
+export function terminalReminderGraceMs(): number {
+  return Number(process.env.PI_HERDR_TERM_GRACE_MS ?? 30_000) || 30_000;
+}
+
+/** Custom message type for the idle-terminal nudge (registerMessageRenderer may restyle it). */
+export const TERM_REMINDER_CUSTOM_TYPE = 'pi-herdr.term-reminder';
+
+export interface IdleTerminalInput {
+  terminalId: string;
+  cwd: string;
+  label: string | null;
+  lastActivityAt: number;
+  /** Set once this terminal has been nudged; a nudged terminal is never nudged again (01a06ae3 goodbye-loop guard). */
+  nudgedAt?: number | null;
+}
+
+export interface IdleTerminalReminderPlan {
+  /** Whether a nudge should be injected. */
+  due: boolean;
+  /** Complete injected content, or null when due is false. */
+  content: string | null;
+  /** Nudge count after successful injection, or the original count when due is false. */
+  nextReminders: number;
+  /** Terminal ids this nudge covers; the caller marks them nudged at schedule time. */
+  ids: string[];
+}
+
+function noIdleInject(reminders: number): IdleTerminalReminderPlan {
+  return { due: false, content: null, nextReminders: reminders, ids: [] };
+}
+
+/**
+ * Due only when an OPEN terminal is idle past the threshold AND has never been nudged
+ * (01a06ae3: a per-process counter alone let nudges resume after restarts and looped a
+ * farewell exchange 52 times — a nudged terminal must stay nudged, persisted in the ledger).
+ * Shells still hosting long-running work were touched recently, so the idle filter is what
+ * keeps legitimate dev-server terminals out of the nudge.
+ */
+export function planIdleTerminalReminder(
+  input: { open: readonly IdleTerminalInput[]; now: number; reminders: number },
+): IdleTerminalReminderPlan {
+  const idleMs = terminalIdleMs();
+  const idle = input.open.filter(
+    (t) => !t.nudgedAt && input.now - t.lastActivityAt >= idleMs,
+  );
+  if (idle.length === 0 || input.reminders >= TERM_REMINDERS_MAX) {
+    return noIdleInject(input.reminders);
+  }
+  const list = idle.map((t) => `- ${t.terminalId} (${t.label ?? t.cwd})`).join('\n');
+  const content = [
+    `<system-reminder>Open terminal(s) idle for a while (nudge ${input.reminders + 1}/${TERM_REMINDERS_MAX}):`,
+    list,
+    'This is an internal housekeeping notice — do NOT reply to the user and do NOT send any farewell on this notice.',
+    'If the work in them is done, close them now with terminal(action: "close", terminal_id: "…").',
+    'Keep a terminal only if a long-running process still needs that shell.',
+    '</system-reminder>',
+  ].join('\n');
+  return {
+    due: true,
+    content,
+    nextReminders: input.reminders + 1,
+    ids: idle.map((t) => t.terminalId),
+  };
+}