pi-pier 0.2.5 → 0.2.6

package/README.md

@@ -1,11 +1,11 @@
 # pi-pier
 
 > [!IMPORTANT]
-> **This npm package is only the pi-extension half of pier.** pier is a two-half system — this extension plus a **herdr plugin** (`pier.workbench`). Without the herdr side you still get `todo_write` / `ask_user_question`, but subagents, pane integration, notifications, and the workspace bootstrap all require herdr. See [Install the herdr half](#install-the-herdr-half-companion-plugin) below.
+> **This npm package is only the pi-extension half of pier.** pier is a two-half system — this extension plus a **herdr plugin** (`pier.workbench`). Without the herdr side you still get `todo_write` / `ask_user_question`; `subagent` / `terminal` are not registered. Pane integration, notifications, and workspace bootstrap all require herdr. See [Install the herdr half](#install-the-herdr-half-companion-plugin) below.
 
 **pier** = **pi** × h**erdr** — a [pi](https://pi.dev/) extension that fuses coding agent sessions with the [herdr](https://herdr.dev/) pane/tab orchestrator.
 
-`pi-pier` fills two gaps pi deliberately leaves open — the **todo list loop** and **interactive subagents** — using herdr panes/tabs as the visual and interaction substrate. It degrades gracefully outside herdr.
+`pi-pier` fills two gaps pi deliberately leaves open — the **todo list loop** and **interactive subagents** — using herdr panes/tabs as the visual and interaction substrate. Outside herdr it loads only the todo loop.
 
 ## Install (this pi half)
 
@@ -56,13 +56,43 @@ The installer also verifies node / pi / herdr versions, probes local paths, and
 
 ## Scope & degradation
 
-Outside a herdr environment the extension auto-degrades: herdr reporting costs nothing, `subagent` / terminal tools return "requires a herdr-managed pane" hints, while `todo_write` / `ask_user_question` keep working (session JSONL as authority, no herdr dependency).
+This extension mutates the pi session even outside herdr. After `pi install npm:pi-pier`:
+
+| 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 |
+| 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 |
+| slim-frame overlay, pane title, pipe, isolate worktree | off | live |
+| `setActiveTools` role visible layer | off | on (herdr master) |
+
+Session JSONL custom types (`pi-herdr.todo-edit`, `.subs`, `.terminals`, `.todo-read`, `.todo-reminder`, …) persist across `/resume` even without herdr.
+
+## Plugin conflicts
+
+pi overwrites tools/commands by name; event listeners stack.
+
+**Do not install alongside** (same-name overwrite → wrong handler, split JSONL):
+
+- [`@nguyenquangthai/pi-todo`](https://pi.dev/packages/@nguyenquangthai/pi-todo) — `todo_write` + overlay
+- [`@josephyoung/pi-ask-user-question`](https://pi.dev/packages/@josephyoung/pi-ask-user-question) — `ask_user_question`
+- [`pi-herdr-subagents`](https://pi.dev/packages/pi-herdr-subagents) — `subagent` + herdr panes
+
+**Soft conflict** (two orchestrators / two injectors — the agent “talks to itself”):
+
+- [`@tintinweb/pi-subagents`](https://pi.dev/packages/@tintinweb/pi-subagents) (`Agent`)
+- [`@minhduydev/pi-subagents`](https://pi.dev/packages/@minhduydev/pi-subagents) (`task`)
+- any other extension that calls `setActiveTools`, `ui.custom` overlay, `before_agent_start`, or `sendUserMessage`/`sendMessage` followUp
+
+**Designed coexistence:** herdr’s official `herdr:pi` reporter. Keep it. pier emits `herdr:blocked` so that plugin remains lifecycle authority.
 
 ## Requirements
 
 - Node ≥ 22
 - pi ≥ 0.84 (`@earendil-works/pi-coding-agent`)
-- **herdr ≥ 0.8.0** — required for subagents / pane integration / notifications (see the IMPORTANT note above); without it only `todo_write` / `ask_user_question` work
+- **herdr ≥ 0.8.0** — required for subagents / pane integration / notifications (see the IMPORTANT note above); without it only the todo loop and `ask_user_question` load
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pier",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "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/src/core/subagent.ts

@@ -11,7 +11,6 @@ import { randomUUID } from 'node:crypto';
 import { basename, join, dirname } from 'node:path';
 import type { PiSurface } from '../pi-surface.ts';
 import type { HerdrClientLike } from '../herdr-client.ts';
-import type { TodosService } from '../todos-service.ts';
 import { Semaphore, SUBS_CUSTOM_TYPE, agoText, buildAliveNotice, buildBlockedGateNotice, buildIsolatePreamble, classifyWorktreeZone, foldSubsRegistry, formatSubagentResult, isAlive, isPathUnder, makeProgressUpdate, makeRegistry, planIsolateWorktree, tabNameForTask, type AliveProbe, type SubEntry } from '../subagent-core.ts';
 import { applyReportedSessionFile, appendHistory, preferredHistoryFile, inheritOutcome, latestGeneration, readHistory, type HistoryEntry } from '../history-store.ts';
 import { runtimePolicy } from '../runtime-policy.ts';
@@ -30,7 +29,6 @@ import { promisify } from 'node:util';
 const statAsync = promisify(statCb);
 import { pipeNameFor, pipeRequestTo } from '../pipe-channel.ts';
 import { composeForRole } from '../manifest-compose.ts';
-import { TODO_REMINDER_CUSTOM_TYPE, planStopTodoReminder, todoReminderGraceMs } from '../todo-reminder-core.ts';
 import type { TerminalStateSlot } from './terminal.ts';
 import { createGitIo } from '../subagent-git-io.ts';
 import { createSessionIo } from '../subagent-session-io.ts';
@@ -54,7 +52,6 @@ interface SubagentDeps {
   sessionRoot: Context;
   port: SubagentPortBox;
   getSessionId: () => string;
-  getBlockedDepth: () => number;
   reconcileOnSettlement: (description: string, outcome: 'settled' | 'failed') => string[];
   withReconcileNotes: (base: string, notes: readonly string[]) => string;
   claimSettleNotice: (key: string) => boolean;
@@ -67,7 +64,6 @@ interface SubagentDeps {
   noticePending?: () => ReadonlySet<string>;
   /** Terminal-family GC exemption (live terminal panes are not collected). */
   terminalState: TerminalStateSlot;
-  todos: TodosService;
 }
 
 const SUBAGENT_DESCRIPTION = [
@@ -103,14 +99,10 @@ function agentRootDir(): string {
 export default function subagentPlugin(ctx: Context): void {
   const surface = ctx.get('pi-herdr.surface') as PiSurface<object>;
   const d = ctx.get('pi-herdr.subagent-deps') as SubagentDeps;
-  const { client, env, sessionRoot, port, terminalState, todos } = d;
+  const { client, env, sessionRoot, port, terminalState } = d;
   const pi = surface.raw as {
     appendEntry?: (customType: string, data: unknown) => void;
     sendUserMessage?: (content: string, opts?: { deliverAs?: string }) => Promise<void>;
-    sendMessage?: (
-      message: { customType: string; content: string; display?: boolean; details?: Record<string, unknown> },
-      opts?: { deliverAs?: string; triggerTurn?: boolean },
-    ) => Promise<void>;
   };
   const scoped = surface.forModule(import.meta.url);
 
@@ -244,68 +236,6 @@ export default function subagentPlugin(ctx: Context): void {
     return { content: [{ type: 'text', text: notice }] };
   });
 
-  /* ── D41 safe reminders for unfinished todos ─────────────────────
-   * 01a040cc showed that a user-role reminder overrode model judgment and executed work reserved
-   * for the user. Use a distinguishable custom message, request reconciliation rather than action,
-   * and delay delivery so any new agent start cancels it. Preserve the ESC guard from 01a03bf0 to
-   * avoid wake-up storms after explicit interruption. */
-
-  let todoReminders = 0;
-  let lastAssistantStopReason: string | null = null;
-  let todoReminderTimer: NodeJS.Timeout | null = null;
-
-  function cancelTodoReminder(): void {
-    if (todoReminderTimer !== null) {
-      clearTimeout(todoReminderTimer);
-      todoReminderTimer = null;
-    }
-  }
-
-  scoped.on('turn_end', async (event: unknown) => {
-    if (event === null || typeof event !== 'object' || !('message' in event)) return;
-    const msg = (event as { message: unknown }).message; // Safe after the property guard above.
-    if (msg === null || typeof msg !== 'object') return;
-    const { role, stopReason } = msg as { role?: unknown; stopReason?: unknown };
-    if (role === 'assistant' && typeof stopReason === 'string') {
-      lastAssistantStopReason = stopReason;
-    }
-  });
-
-  // B3 cancels the reminder when any source resumes work during the grace window.
-  scoped.on('agent_start', () => cancelTodoReminder());
-  scoped.on('session_shutdown', () => cancelTodoReminder());
-
-  scoped.on('agent_settled', async () => {
-    cancelTodoReminder(); // Cancel any timer left from the previous settlement.
-    const plan = planStopTodoReminder({
-      lastStopReason: lastAssistantStopReason,
-      reminders: todoReminders,
-      runningSubs: pollers.size,
-      blockedDepth: d.getBlockedDepth(),
-      items: todos.items,
-    });
-    if (!plan.due || plan.content == null) return;
-    const content = plan.content;
-    todoReminderTimer = setTimeout(() => {
-      todoReminderTimer = null;
-      void (async () => {
-        // Without sendMessage, skip the reminder rather than impersonating the user channel.
-        const send = pi.sendMessage;
-        if (typeof send !== 'function') return;
-        try {
-          await send(
-            { customType: TODO_REMINDER_CUSTOM_TYPE, content, display: true },
-            { deliverAs: 'followUp', triggerTurn: true },
-          );
-          todoReminders += 1; // Count only delivered reminders so cancellation and failure do not consume the cap.
-        } catch {
-          /* Delivery failure is non-fatal. */
-        }
-      })();
-    }, todoReminderGraceMs());
-    todoReminderTimer.unref?.(); // Do not keep tests or headless processes alive for a reminder.
-  });
-
   function histFile(cwd: string): string {
     return preferredHistoryFile(agentRootDir(), cwd);
   }

package/src/core/todo.ts

@@ -3,15 +3,16 @@
  *
  * A Cordis plugin keeps the master surface hot-swappable while allowing workers to mount the
  * one-shot subset directly. Injected services preserve the D79 registration boundary and keep
- * session-owned todo state in index. This module owns the tool, command, widget, and read hook;
- * reconciliation, mirroring, and agent reporting stay with the session state layer to avoid a
- * dependency cycle.
+ * session-owned todo state in index. This module owns the tool, command, widget, read hook,
+ * and master stop reminder; reconciliation, mirroring, and agent reporting stay with the
+ * session state layer to avoid a dependency cycle.
  */
 import { Context } from '@deepseek-ai/cordis';
 import { Type } from 'typebox';
 import type { PiSurface } from '../pi-surface.ts';
 import type { TodosService } from '../todos-service.ts';
 import { planTodoReadHook } from '../todo-read-hook.ts';
+import { TODO_REMINDER_CUSTOM_TYPE, planStopTodoReminder, todoReminderGraceMs } from '../todo-reminder-core.ts';
 import { makeProgressUpdate } from '../subagent-core.ts';
 import { TODO_DETAILS_KEY, TODO_TOOL_NAME, formatTodoConfirmation, type TodoItem } from '../vocab.ts';
 import { formatAge, isArchived } from '../stale-core.ts';
@@ -40,6 +41,11 @@ interface TodoDeps {
   mirrorTodos: () => void;
   appendEntry: (customType: string, data: unknown) => void;
   state: TodoUiSlot;
+  /** Master-only unfinished-todo reminder; omitted on worker panes. */
+  stopReminder?: {
+    getBlockedDepth: () => number;
+    getRunningSubs: () => number;
+  };
 }
 
 const TOOL_DESCRIPTION = [
@@ -89,7 +95,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 } =
+  const { todos, allowParallelInProgress, maxItems, mirrorTodos, appendEntry, state, stopReminder } =
     ctx.get('pi-herdr.todo-deps') as TodoDeps;
   const scoped = surface.forModule(import.meta.url);
 
@@ -178,6 +184,64 @@ export default function todoPlugin(ctx: Context): void {
     };
   });
 
+  if (stopReminder) {
+    const pi = surface.raw as {
+      sendMessage?: (
+        message: { customType: string; content: string; display?: boolean; details?: Record<string, unknown> },
+        opts?: { deliverAs?: string; triggerTurn?: boolean },
+      ) => Promise<void>;
+    };
+    let todoReminders = 0;
+    let lastAssistantStopReason: string | null = null;
+    let todoReminderTimer: NodeJS.Timeout | null = null;
+    function cancelTodoReminder(): void {
+      if (todoReminderTimer !== null) {
+        clearTimeout(todoReminderTimer);
+        todoReminderTimer = null;
+      }
+    }
+    scoped.on('turn_end', async (event: unknown) => {
+      if (event === null || typeof event !== 'object' || !('message' in event)) return;
+      const msg = (event as { message: unknown }).message;
+      if (msg === null || typeof msg !== 'object') return;
+      const { role, stopReason } = msg as { role?: unknown; stopReason?: unknown };
+      if (role === 'assistant' && typeof stopReason === 'string') {
+        lastAssistantStopReason = stopReason;
+      }
+    });
+    scoped.on('agent_start', () => cancelTodoReminder());
+    scoped.on('session_shutdown', () => cancelTodoReminder());
+    scoped.on('agent_settled', async () => {
+      cancelTodoReminder();
+      const plan = planStopTodoReminder({
+        lastStopReason: lastAssistantStopReason,
+        reminders: todoReminders,
+        runningSubs: stopReminder.getRunningSubs(),
+        blockedDepth: stopReminder.getBlockedDepth(),
+        items: todos.items,
+      });
+      if (!plan.due || plan.content == null) return;
+      const content = plan.content;
+      todoReminderTimer = setTimeout(() => {
+        todoReminderTimer = null;
+        void (async () => {
+          const send = pi.sendMessage;
+          if (typeof send !== 'function') return;
+          try {
+            await send(
+              { customType: TODO_REMINDER_CUSTOM_TYPE, content, display: true },
+              { deliverAs: 'followUp', triggerTurn: true },
+            );
+            todoReminders += 1;
+          } catch {
+            /* Delivery failure is non-fatal. */
+          }
+        })();
+      }, todoReminderGraceMs());
+      todoReminderTimer.unref?.();
+    });
+  }
+
   /* ── todo_write tool ───────────────────────────────────────────── */
   scoped.registerTool({
     name: TODO_TOOL_NAME,

package/src/index-master.ts

@@ -89,6 +89,10 @@ export async function mountMasterPlugins(m: MasterPluginMount): Promise<void> {
       (m.pi as { appendEntry?: (t: string, d: unknown) => void }).appendEntry?.(customType, data);
     },
     state: m.todoUi,
+    stopReminder: {
+      getBlockedDepth: m.getBlockedDepth,
+      getRunningSubs: () => m.port.current?.listRunningSubs().length ?? 0,
+    },
   });
   await loadEntry(sessionRoot, useLoader, './core/todo.ts', todoPlugin);
 
@@ -101,12 +105,10 @@ export async function mountMasterPlugins(m: MasterPluginMount): Promise<void> {
     deliverNotice: m.deliverNotice,
     noticePending: m.noticePending,
     getSessionId: m.getSessionId,
-    getBlockedDepth: m.getBlockedDepth,
     reconcileOnSettlement: m.reconcileOnSettlement,
     withReconcileNotes: m.withReconcileNotes,
     claimSettleNotice: m.claimSettleNotice,
     terminalState: terminalDeps.state,
-    todos: m.todos,
   });
   await loadEntry(sessionRoot, useLoader, './core/subagent.ts', subagentPlugin);
 

package/src/index-runtime.ts

@@ -10,14 +10,18 @@ import { detectHerdrEnv } from './herdr-client.ts';
 export interface IndexMode {
   /** PI_HERDR_SUBAGENT=1 → worker pane (no subagent tools, no cordis loader). */
   readonly isSubagent: boolean;
-  /** herdr pane that is not a worker → apply builtin master manifest. */
+  /** HERDR_ENV + socket + pane are present. */
+  readonly hasHerdr: boolean;
+  /** herdr pane that is not a worker → apply builtin master manifest and mount workbench plugins. */
   readonly composeMaster: boolean;
 }
 
 export function planIndexMode(env: NodeJS.ProcessEnv = process.env): IndexMode {
   const isSubagent = env.PI_HERDR_SUBAGENT === '1';
+  const hasHerdr = Boolean(detectHerdrEnv(env));
   return {
     isSubagent,
-    composeMaster: Boolean(detectHerdrEnv(env)) && !isSubagent,
+    hasHerdr,
+    composeMaster: hasHerdr && !isSubagent,
   };
 }

package/src/index-worker.ts

@@ -1,8 +1,8 @@
 /**
- * Worker-process todo plugin mount (bare cordis root, no loader/hmr).
+ * Todo-only plugin mount (bare cordis root, no loader/hmr).
  *
- * Why: short-lived worker panes only need the todo coordination plugin.
- * Dynamically imported from the worker branch so bootstrap/loader stay out.
+ * Used by worker panes and by standalone pi outside herdr, so bootstrap/subagent/terminal
+ * stay out of those processes.
  */
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Context } from '@deepseek-ai/cordis';
@@ -11,14 +11,19 @@ import todoPlugin from './core/todo.ts';
 import type { TodosService } from './todos-service.ts';
 import type { TodoUiSlot } from './core/todo.ts';
 
-export interface WorkerPluginMount {
+export interface TodoOnlyMount {
   pi: ExtensionAPI;
   todos: TodosService;
   todoUi: TodoUiSlot;
   mirrorTodos: () => void;
+  /** Master-only stop reminder; omit on worker panes. */
+  stopReminder?: {
+    getBlockedDepth: () => number;
+    getRunningSubs: () => number;
+  };
 }
 
-export async function mountWorkerTodo(m: WorkerPluginMount): Promise<void> {
+export async function mountTodoOnly(m: TodoOnlyMount): Promise<void> {
   const workerRoot = new Context();
   const workerSurface = new PiSurface(m.pi as unknown as object);
   workerRoot.provide('pi-herdr.surface', workerSurface);
@@ -31,6 +36,7 @@ export async function mountWorkerTodo(m: WorkerPluginMount): Promise<void> {
       (m.pi as { appendEntry?: (t: string, d: unknown) => void }).appendEntry?.(customType, data);
     },
     state: m.todoUi,
+    ...(m.stopReminder ? { stopReminder: m.stopReminder } : {}),
   });
   await workerRoot.plugin(todoPlugin);
   m.pi.on('session_shutdown', () => {

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):
@@ -231,11 +228,13 @@ 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 } = {
@@ -560,8 +559,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 +583,20 @@ 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,
+      ...(isSubagent
+        ? {}
+        : {
+            stopReminder: {
+              getBlockedDepth: () => blockedDepth,
+              getRunningSubs: () => subagentPort.current?.listRunningSubs().length ?? 0,
+            },
+          }),
+    });
   }
 }