pi-pier 0.2.5 → 0.2.7

package/src/index.ts

@@ -7,10 +7,7 @@
  * Capabilities:
  *  - `todo_write`: replace the complete todo list; the current pi session JSONL is authoritative,
  *    and branches automatically roll back in DSH-aligned semantics.
- *  - `subagent`: foreground/background delegation plus resume/list/send/interrupt actions.
- *    Each child pane is an interactive pi TUI with an independent session/context that humans
- *    can enter directly; the controller uses herdr for state-gated injection (idle only),
- *    waiting (agent.wait), and JSONL result reads.
+ *  - `subagent` / `terminal`: herdr-master only. Bare pi does not register them.
  *  - `/todos`, TUI widget, and herdr title projection with graceful degradation without herdr.
  *
  * pi 0.84.2 contract (validated):
@@ -18,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,
@@ -35,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,
@@ -231,14 +239,16 @@ export default async function (pi: ExtensionAPI) {
     }
   });
 
-  installWriteLocks(pi, {
-    client,
-    env,
-    hard: process.env[WRITE_LOCK_ENV] === '1',
-  });
+  if (env) {
+    installWriteLocks(pi, {
+      client,
+      env,
+      hard: process.env[WRITE_LOCK_ENV] === '1',
+    });
+  }
 
   /* ── 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. */ },
   };
 
@@ -389,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);
@@ -397,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.
@@ -430,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);
@@ -560,8 +562,10 @@ export default async function (pi: ExtensionAPI) {
     }
   });
 
-  /* subagent tools are master-only (depth 1). C3: worker never loads bootstrap. */
-  if (!isSubagent) {
+  /* Workbench plugins (subagent/terminal + cordis) are herdr-master only.
+   * Bare pi and worker panes mount todo only so unused tools never appear.
+   * Dynamic import: worker/bare-pi must never load bootstrap/subagent-scope (C3). */
+  if (mode.composeMaster) {
     const { mountMasterPlugins } = await import('./index-master.ts');
     await mountMasterPlugins({
       pi,
@@ -582,7 +586,21 @@ export default async function (pi: ExtensionAPI) {
       claimSettleNotice,
     });
   } else {
-    const { mountWorkerTodo } = await import('./index-worker.ts');
-    await mountWorkerTodo({ pi, todos, todoUi, mirrorTodos });
+    const { mountTodoOnly } = await import('./index-worker.ts');
+    await mountTodoOnly({
+      pi,
+      todos,
+      todoUi,
+      mirrorTodos,
+      getBlockedDepth: () => blockedDepth,
+      ...(isSubagent
+        ? {}
+        : {
+            stopReminder: {
+              getBlockedDepth: () => blockedDepth,
+              getRunningSubs: () => subagentPort.current?.listRunningSubs().length ?? 0,
+            },
+          }),
+    });
   }
 }

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),
+  };
+}