pi-pier 0.3.1 → 0.4.1

package/src/settle-wake-core.ts

@@ -15,6 +15,11 @@ export interface SettleWakeInput {
   lastStopReason: string | null;
   /** True when abort was triggered intentionally by internal mechanisms like OCC. */
   intentionalAbort?: boolean;
+  /**
+   * pi ≥ 1.1 carries `aborted` on agent_settled itself: authoritative for runs cancelled without a
+   * final assistant message (ESC mid-tool), where stopReason tracking sees a stale natural reason.
+   */
+  aborted?: boolean;
   running: ReadonlyArray<{ paneId: string }>;
   lastNoticeKey: string | null;
   lastNoticeAt: number;
@@ -50,7 +55,7 @@ export function planSettleWake(input: SettleWakeInput): SettleWakePlan {
       noticeAt: input.lastNoticeAt,
     };
   }
-  if (input.intentionalAbort || input.lastStopReason === ABORT_STOP_REASON) {
+  if (input.aborted === true || input.intentionalAbort || input.lastStopReason === ABORT_STOP_REASON) {
     return {
       wake: false,
       compact: input.intentionalAbort === true,
@@ -79,10 +84,13 @@ export function planSettleWake(input: SettleWakeInput): SettleWakePlan {
  */
 export function shouldPushSettleReply(input: {
   intentionalAbort?: boolean;
+  /** pi ≥ 1.1 agent_settled.aborted: the run was cancelled — the closing message may still come after a re-run. */
+  aborted?: boolean;
   compactionInFlight?: boolean;
   lastStopReason: string | null;
 }): boolean {
   return !input.intentionalAbort
+    && input.aborted !== true
     && !input.compactionInFlight
     && input.lastStopReason !== ABORT_STOP_REASON;
 }

package/src/subagent-core.ts

@@ -3,6 +3,7 @@
  * decisions, task-id resolution, and the outbound port types. Pure: planners decide, adapters do I/O.
  */
 import { normalizeEntryKind } from './history-store.ts';
+import { Type } from 'typebox';
 
 export function sleep(ms: number): Promise<void> {
   const { promise, resolve } = Promise.withResolvers<void>();
@@ -24,6 +25,113 @@ export function buildLaunchLine(parts: readonly string[], platform: NodeJS.Platf
   return (win ? '& ' : '') + quoted.join(' ');
 }
 
+/** Shells that mean a freshly split pane is at its prompt and can accept a launch line. */
+const SHELL_PROCESS_NAMES: ReadonlySet<string> = new Set([
+  'sh', 'bash', 'zsh', 'fish', 'dash', 'ksh', 'mksh', 'tcsh', 'csh', 'nu', 'login',
+  'pwsh', 'powershell', 'cmd',
+]);
+
+/** Normalize `name` / `argv0` (`/bin/zsh`, `C:\\Windows\\System32\\cmd.exe`, `-zsh`) to a shell key. */
+export function shellProcessName(value: string | null | undefined): string {
+  const base = String(value ?? '').replace(/\\/g, '/').split('/').pop()?.toLowerCase() ?? '';
+  const stripped = base.replace(/^-/, '').replace(/\.exe$/, '');
+  return stripped;
+}
+
+/**
+ * Decide whether a pane's foreground set means its shell is ready for input. `null`/`undefined`
+ * means the probe was unavailable: return ready so an older herdr never adds spawn latency.
+ * An empty set is not proof (the shell may still be starting), so callers wait for the timeout.
+ */
+export function planShellReady(
+  foreground: ReadonlyArray<{ name?: string | null; argv0?: string | null }> | null | undefined,
+): 'ready' | 'wait' {
+  if (foreground == null) return 'ready';
+  if (foreground.length === 0) return 'wait';
+  return foreground.some((p) => SHELL_PROCESS_NAMES.has(shellProcessName(p.name)) || SHELL_PROCESS_NAMES.has(shellProcessName(p.argv0)))
+    ? 'ready'
+    : 'wait';
+}
+
+/** Flags pier passes at spawn (buildLaunchParts) that a herdr 0.9.2+ resume command must replay. */
+const RESUME_FLAG_ARITY: Record<string, number> = {
+  '-a': 0,
+  '-e': 1,
+  '--extension': 1,
+  '--tui-mode': 1,
+  '--provider': 1,
+  '--model': 1,
+  '--session': 1,
+};
+
+const RESUME_MAX_ARGS = 64;
+const RESUME_MAX_BYTES = 8 * 1024;
+
+/**
+ * herdr 0.9.2 self-report (docs "Add Herdr support to your agent"): rebuild this worker's launch
+ * line as a `resume_argv` herdr runs after a server restart. The worker's own process.argv is the
+ * source of truth — interpreter and cli.js paths are dropped, whitelisted spawn flags are mirrored
+ * (`--flag=value` splits), argv[0] becomes a plain PATH command name. herdr rules: argv[0] plain,
+ * no apostrophes/control characters, ≤64 args, ≤8 KiB; violations (or a missing `-e`, which could
+ * not restore the extension) return null and the caller skips the report — restore stays best-effort.
+ */
+export function buildResumeArgv(workerArgv: readonly string[], piBin = 'pi'): string[] | null {
+  if (!/^[A-Za-z0-9._-]+$/.test(piBin)) return null;
+  const collected: string[] = [];
+  let index = 0;
+  // Skip interpreter + cli script (everything before the first flag).
+  while (index < workerArgv.length && !workerArgv[index]!.startsWith('-')) index++;
+  for (; index < workerArgv.length; index++) {
+    const raw = workerArgv[index]!;
+    if (!raw.startsWith('-')) continue; // positional (unknown flag's value) — not pier spawn shape
+    const eq = raw.indexOf('=');
+    const flag = eq > 0 ? raw.slice(0, eq) : raw;
+    const inlineValue = eq > 0 ? raw.slice(eq + 1) : null;
+    const arity = RESUME_FLAG_ARITY[flag];
+    if (arity === undefined) continue; // pi-internal flags are not replayed
+    if (arity === 0) {
+      collected.push(flag);
+    } else if (inlineValue !== null) {
+      collected.push(flag, inlineValue);
+    } else if (index + 1 < workerArgv.length) {
+      collected.push(flag, workerArgv[++index]!);
+    }
+  }
+  if (!collected.some((f, i) => (f === '-e' || f === '--extension') && i + 1 < collected.length)) return null;
+  const argv = [piBin, ...collected];
+  if (argv.length > RESUME_MAX_ARGS) return null;
+  if (argv.some((a) => /['\u0000-\u001f\u007f]/.test(a))) return null;
+  if (argv.reduce((sum, a) => sum + a.length + 1, 0) > RESUME_MAX_BYTES) return null;
+  return argv;
+}
+
+/**
+ * pi ≥ 0.99 outputSchema for the subagent tool: the `details` each action already produces, stamped
+ * with the normalized action. Codemode scripts (and any structured consumer) read this instead of
+ * parsing the prose reply; the text content stays authoritative for the transcript. Hard failures
+ * throw (toolError), so every returned value is a success and always carries structuredContent.
+ */
+export const SUBAGENT_OUTPUT_SCHEMA = Type.Object({
+  action: Type.Union([
+    Type.Literal('spawn'), Type.Literal('resume'), Type.Literal('list'),
+    Type.Literal('send'), Type.Literal('interrupt'), Type.Literal('output'), Type.Literal('role'),
+  ]),
+  paneId: Type.Optional(Type.String()),
+  taskId: Type.Optional(Type.String()),
+  role: Type.Optional(Type.String()),
+  background: Type.Optional(Type.Boolean()),
+  alreadyRunning: Type.Optional(Type.Boolean()),
+}, { additionalProperties: true });
+
+export function attachSubagentStructuredContent(action: string, result: unknown): unknown {
+  if (result === null || typeof result !== 'object' || Array.isArray(result)) return result;
+  const record = result as Record<string, unknown>;
+  const details = record.details !== null && typeof record.details === 'object' && !Array.isArray(record.details)
+    ? record.details as Record<string, unknown>
+    : {};
+  return { ...record, structuredContent: { action, ...details } };
+}
+
 /** Bounds concurrent delegation spawns (SUBAGENT_CONCURRENCY). */
 export class Semaphore {
   private active = 0;
@@ -147,6 +255,9 @@ export interface SubEntry {
   /** 'task' or a role name; only a display label for GC. */
   kind: string;
   paneId: string;
+  /** Phase 2 task slug (kebab-case of description; RFC rfc-delegation-identity §3.1): tool args
+   * accept `slug@paneId` or the bare slug; allocated once at spawn and stable across revives. */
+  slug?: string;
   tabId: string;
   tabName: string;
   cwd: string;
@@ -173,6 +284,41 @@ export interface SubEntry {
   };
 }
 
+/* ── task slugs (RFC rfc-delegation-identity §3.1) ───────────────── */
+
+/** Slug cap: short enough for tool args and list rows, long enough to stay distinctive. */
+const SLUG_MAX = 24;
+
+/** Kebab-case a task description; non-ASCII (CJK descriptions) sanitizes to '' — the allocator
+ * then falls back to a taskId-derived ascii slug, because tool args must stay typeable. */
+export function slugifyTask(description: string): string {
+  return description
+    .toLowerCase()
+    .replace(/[''']/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, SLUG_MAX)
+    .replace(/-+$/g, '');
+}
+
+/** Allocate a unique slug among live rows: base, then base-2, base-3, …; a description that
+ * sanitizes to nothing (CJK, emoji-only) falls back to `task-<taskId prefix>`. */
+export function allocateSubSlug(description: string, taskId: string, taken: ReadonlySet<string>): string {
+  const base = slugifyTask(description) || `task-${taskId.slice(0, 6)}`;
+  if (!taken.has(base)) return base;
+  for (let n = 2; ; n++) {
+    const next = `${base}-${n}`;
+    if (!taken.has(next)) return next;
+  }
+}
+
+/** Stable display/argument form for a subagent row: `slug@paneId` when a slug exists. */
+export function subRef(sub: { paneId: string; slug?: string }): string {
+  return sub.slug ? `${sub.slug}@${sub.paneId}` : sub.paneId;
+}
+
+export const PROGRESS_CUSTOM_TYPE = 'pi-herdr.progress';
+
 export interface SubsRegistry {
   version: 2;
   subs: SubEntry[];
@@ -198,6 +344,7 @@ export function foldSubsRegistry(entries: ReadonlyArray<{ type?: string; customT
         taskId: typeof s.taskId === 'string' ? s.taskId : s.paneId,
         kind: normalizeEntryKind(typeof s.kind === 'string' ? s.kind : undefined),
         paneId: s.paneId,
+        slug: typeof s.slug === 'string' && s.slug ? s.slug : undefined,
         tabId: typeof s.tabId === 'string' ? s.tabId : '',
         tabName: typeof s.tabName === 'string' ? s.tabName : '',
         cwd: typeof s.cwd === 'string' ? s.cwd : '',
@@ -395,6 +542,12 @@ export function buildLaunchParts(
 
 const ISOLATE_SLUG_MAX = 40;
 
+/**
+ * D-3 (verified 2026-10-20): herdr 0.9.5 `worktree create --workspace <parent>` still opens a new
+ * top-level workspace, not a tab inside the parent workspace, so it cannot replace pier's isolate
+ * placement. Keep `git worktree add` + the master-workspace tab; native worktree management remains
+ * an option only for workflows that accept a separate workspace.
+ */
 export function planIsolateWorktree(opts: {
   description: string;
   taskHex: string;
@@ -553,7 +706,7 @@ export function planForegroundTick(input: {
 
 /* ── task-id resolution ─────────────────────────────────────────── */
 
-type TaskIdResolutionResult =
+export type TaskIdResolutionResult =
   | { kind: 'resolved'; taskId: string }
   | { kind: 'ambiguous'; query: string; candidates: string[] }
   | { kind: 'too_short'; query: string }
@@ -583,13 +736,28 @@ export function resolveTaskIdPrefix(
   return { kind: 'not_found', query: trimmed };
 }
 
+/** Error text for a non-resolved `resolveTaskIdPrefix` outcome; null for `resolved` (each caller owns
+ * its success path) and `not_found` (each caller words its own unknown-id hint). `rawQuery` keeps
+ * the caller's original string in the message even though matching works on the trimmed form. */
+export function taskIdResolutionError(
+  res: TaskIdResolutionResult,
+  label: 'task id' | 'subagent id',
+  rawQuery: string,
+): string | null {
+  if (res.kind === 'too_short') return `Error: ${label} prefix "${rawQuery}" is too short (minimum 4 characters).`;
+  if (res.kind === 'ambiguous') return ambiguousIdError(label, rawQuery, res.candidates);
+  return null;
+}
+
 /* ── outbound port (composition root → plugin) ──────────────────── */
 
 /** Bound atomically at session_start: consumers read `current` and must tolerate null. */
 export interface SubagentPort {
   applyReplySession(paneId: string, sessionFile: string | null): void;
   reconcileOnReply(paneId: string): string[];
-  listRunningSubs(): Array<{ paneId: string; description: string }>;
+  listRunningSubs(): Array<{ paneId: string; slug?: string; description: string; kind: string }>;
+  /** D113: non-closed rows for the /pier-tree view (settled nodes carry their settle time). */
+  listRows(): Array<{ paneId: string; slug?: string; description: string; kind: string; status: SubEntry['status']; settledAt: number | null }>;
   settleStatLine(paneId: string): Promise<string | null>;
   /** Pipe settlement: drop the row out of listRunningSubs before the finish notice wakes the master. */
   consumeReply(paneId: string, outcome: string | null): void;

package/src/subagent-poller.ts

@@ -375,7 +375,23 @@ export function createPoller(h: PollerHost): Poller {
                   if (tail && settleAskIsSafe(tail)) {
                     const res = await h.jev.ask(
                       settleVerdictRequest({ description: current.description, tail }),
-                      { questionId: 'settle-attribution', timeoutMs: 2500 },
+                      {
+                        questionId: 'settle-attribution',
+                        timeoutMs: 2500,
+                        // Calibration fields (D115): noul answers carry no confidence, so the
+                        // probabilities and the composed verdict are what SETTLE_*_MIN_NOUL
+                        // tuning reads from jev.jsonl.
+                        enrich: ({ ok, answers }) => {
+                          if (!ok || !answers) return {};
+                          const match = answers.tail_matches_task;
+                          const fin = answers.tail_has_final_answer;
+                          return {
+                            tailMatchesTaskNoul: match?.type === 'noul' ? match.noul : null,
+                            tailHasFinalAnswerNoul: fin?.type === 'noul' ? fin.noul : null,
+                            settleVerdict: evaluateSettleVerdict(answers) ?? 'unanswered',
+                          };
+                        },
+                      },
                     );
                     if (res.ok) {
                       const verdict = evaluateSettleVerdict(res.answers);

package/src/subagent-spawn.ts

@@ -8,6 +8,8 @@ import { mkdirSync, stat as statCb } from 'node:fs';
 import { basename, dirname, join, resolve as pathResolve } from 'node:path';
 import { promisify } from 'node:util';
 import type { HerdrClientLike } from './herdr-client.ts';
+import { delegationEnv } from './delegation-core.ts';
+import { bareSessionId } from './session-tail.ts';
 import { pipeNameCandidates, pipeNameFor, pipeRequest, pipeRequestTo } from './pipe-channel.ts';
 import { composeForRole } from './manifest-compose.ts';
 import { platformPaths } from './platform-paths.ts';
@@ -18,6 +20,7 @@ import type { HistoryEntry } from './history-store.ts';
 import {
   FOREGROUND_POLL_MS,
   Semaphore,
+  allocateSubSlug,
   buildAliveNotice,
   buildBlockedGateNotice,
   buildIsolatePreamble,
@@ -32,8 +35,10 @@ import {
   planForegroundTick,
   planIsolateWorktree,
   planLaunchValidation,
+  planShellReady,
   planTabPlacement,
   sleep,
+  subRef,
   type SubEntry,
   type TabPlacementPlan,
   type WorktreeZone,
@@ -45,6 +50,11 @@ import type { SessionIo } from './subagent-session.ts';
 
 const statAsync = promisify(statCb);
 
+/** Bound on waiting for a fresh pane's shell to reach its prompt. On timeout the launch line is sent
+ *  anyway: `waitSubReady` still diagnoses a failed boot, and an unsupported probe must not stall spawn. */
+export const SHELL_READY_TIMEOUT_MS = 2_000;
+const SHELL_READY_POLL_MS = 100;
+
 /* ── git adapter ────────────────────────────────────────────────── */
 
 export interface GitResult {
@@ -302,6 +312,18 @@ export function createSpawner(h: SpawnerHost): Spawner {
     return buildLaunchLine(buildLaunchParts(h.runtime, { resumeFile, roleModel, approve }));
   }
 
+  /** herdr 0.9.4 refuses over-long commands on a shell that is still starting; `pane.send_text`
+   *  has no such guard. Poll the foreground process until the shell owns the PTY (or give up). */
+  async function waitShellReady(paneId: string): Promise<void> {
+    const deadline = Date.now() + SHELL_READY_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      const info = await h.client.processInfo(paneId).catch(() => null);
+      if (info === null) return; // older server or pane already gone: keep the old best-effort path
+      if (planShellReady(info.foreground) === 'ready') return;
+      await sleep(SHELL_READY_POLL_MS);
+    }
+  }
+
   async function approveFor(cwd: string, masterCwd: string): Promise<boolean> {
     if (isPathUnder(cwd, masterCwd)) return true;
     const zone = classifyWorktreeZone({ cwd, masterCwd, worktrees: await h.git.listWorktrees(masterCwd) });
@@ -471,6 +493,7 @@ export function createSpawner(h: SpawnerHost): Spawner {
             focus: false,
             ...(ratio != null ? { ratio } : {}),
           });
+          await waitShellReady(paneId);
           await h.client.sendPaneText(paneId, launch);
           return { tabId: plan.tabId, paneId, tabName: plan.tabName };
         }
@@ -482,6 +505,7 @@ export function createSpawner(h: SpawnerHost): Spawner {
         cwd,
         env: envOver,
       });
+      await waitShellReady(created.paneId);
       await h.client.sendPaneText(created.paneId, launch);
       return { tabId: created.tabId, paneId: created.paneId, tabName: plan.tabName };
     } finally {
@@ -517,11 +541,13 @@ interface SpawnActionHost {
   writeHistory(entry: SubEntry, patch?: Partial<HistoryEntry>, via?: string): void;
   pendingIsolateBranches: Set<string>;
   lastMachineInjectAt: Map<string, number>;
-  lastRequestIdByPane: Map<string, string>;
+  lastRequestIdByPane: Map<string, number | string>;
   git: GitIo;
   session: SessionIo;
   spawn: Spawner;
   poller: Poller;
+  /** Master session id for the delegation identity handed to the worker. */
+  getSessionId: () => string;
   /** Phase 0 routing telemetry (RFC rfc-jev-role-routing §8): best-effort spawn profile; absent in tests. */
   logRouting?: (row: RoutingTelemetryRecord) => void;
 }
@@ -545,6 +571,8 @@ export function createSpawnAction(h: SpawnActionHost) {
     // Validate the role before any isolate worktree exists: this early return has no cleanup path.
     let roleManifestEnv: Record<string, string> = {};
     let roleModel: string | null = null;
+    // Delegation identity (RFC rfc-delegation-identity §2.1): the worker learns who delegated it.
+    let delegationEnvPatch: Record<string, string> = {};
     try {
       const { role, manifest } = composeForRole(manifestRole ?? 'worker-default', suggested, { loadRoleOpts: { baseDir: masterCwd } });
       roleManifestEnv = {
@@ -561,6 +589,15 @@ export function createSpawnAction(h: SpawnActionHost) {
         // Role base: /pier-role and the pipe switch resolve .pi-herdr/roles/ against the MASTER's checkout.
         PI_HERDR_ROLE_BASE: masterCwd,
       };
+      delegationEnvPatch = delegationEnv({
+        parentPaneId: env?.paneId ?? '',
+        parentSessionId: bareSessionId(h.getSessionId()),
+        // Phase 2: the master's own pipe so the worker's report_progress can dial home (D49).
+        parentPipe: pipeNameFor(masterCwd, env?.paneId ?? ''),
+        taskId,
+        description: spec.description,
+        role: role.role,
+      });
       if (typeof role.model === 'string' && role.model.trim()) roleModel = role.model.trim();
       h.logRouting?.(
         planSpawnProfileRow({
@@ -631,14 +668,24 @@ export function createSpawnAction(h: SpawnActionHost) {
       const spawned = await spawnPaneInTaskTab(
         { desiredTab: tab, description: spec.description, zone },
         cwd,
-        { PI_HERDR_SUBAGENT: '1', ...roleManifestEnv },
+        // pier owns worker state reporting (report_agent with todo/blocked badges); pi 1.1+'s own
+        // OSC 7501 program-status emission would become a second, competing source once a terminal
+        // or dashboard starts reading it. One reporter per pane.
+        { PI_HERDR_SUBAGENT: '1', PI_PROGRAM_STATUS: '0', ...roleManifestEnv, ...delegationEnvPatch },
         launchLine(null, roleModel, approve),
       );
       paneId = spawned.paneId;
+      // Phase 2: allocate once per spawn; revives/history keep the row's slug (stability beats beauty).
+      const slug = allocateSubSlug(
+        spec.description,
+        taskId,
+        new Set([...subs.values()].map((s) => s.slug ?? '').filter(Boolean)),
+      );
       const entry: SubEntry = {
         taskId,
         kind,
         paneId,
+        slug,
         tabId: spawned.tabId,
         tabName: spawned.tabName,
         cwd,
@@ -686,8 +733,8 @@ export function createSpawnAction(h: SpawnActionHost) {
       if (background) {
         handToPoller(`prompt-${taskId}`);
         return {
-          content: [{ type: 'text', text: `started subagent ${paneId} (task ${taskId})` }],
-          details: { paneId, taskId, background: true, role: kind },
+          content: [{ type: 'text', text: `started subagent ${subRef(entry)} (task ${taskId})` }],
+          details: { paneId, taskId, background: true, role: kind, slug },
         };
       }
 

package/src/terminal-core.ts

@@ -69,7 +69,9 @@ export interface TerminalEntry {
   label: string | null;
   createdAt: number;
   lastActivityAt: number;
-  /** Idle-nudge bookkeeping: set when this terminal has been nudged once (per-entry, persisted). */
+  /** Nudges delivered for this terminal (0..TERM_REMINDERS_MAX), persisted. */
+  nudges: number;
+  /** Timestamp of the last nudge; kept alongside `nudges` for legacy records and debugging. */
   nudgedAt: number | null;
   status: 'open' | 'closed';
   closedAt: number | null;
@@ -123,6 +125,7 @@ export function registerTerminal(
     label: opts.label ?? (opts.cwd ? basename(opts.cwd.replace(/\\/g, '/')) || opts.cwd : null),
     createdAt: opts.createdAt,
     lastActivityAt: opts.createdAt,
+    nudges: 0,
     nudgedAt: null,
     status: 'open',
     closedAt: null,
@@ -413,6 +416,9 @@ export function foldTerminalsRegistry(
         label: typeof t.label === 'string' ? t.label : null,
         createdAt: typeof t.createdAt === 'number' ? t.createdAt : 0,
         lastActivityAt: typeof t.lastActivityAt === 'number' ? t.lastActivityAt : 0,
+        nudges: typeof t.nudges === 'number'
+          ? Math.max(0, Math.min(TERM_REMINDERS_MAX, Math.floor(t.nudges)))
+          : (typeof t.nudgedAt === 'number' ? 1 : 0),
         nudgedAt: typeof t.nudgedAt === 'number' ? t.nudgedAt : null,
         status: t.status === 'closed' ? ('closed' as const) : ('open' as const),
         closedAt: typeof t.closedAt === 'number' ? t.closedAt : null,
@@ -426,17 +432,20 @@ export function foldTerminalsRegistry(
   return found;
 }
 
-/* ── Idle-terminal nudge: turn-end self-cleanup for shells the model forgot to close ──
- * Terminals persist by design, so a finished shell lingers as a dead split; delivery wiring mirrors
- * the todo stop-reminder in plugins/terminal. */
+/* ── Terminal nudge: turn-end self-cleanup for shells the model forgot to close ──
+ * Terminals persist by design, so a finished shell lingers as a dead split. Two notices per terminal:
+ *   1. at the end of the turn that used it ("used this turn") — or the first turn that finds it idle
+ *      past the threshold, for a shell nobody touched recently;
+ *   2. on a later settle once it has been idle past PIER_TERM_IDLE_MS.
+ * Delivery wiring mirrors the todo stop-reminder in plugins/terminal. */
 
-/** Cap idle-terminal nudges for the lifetime of the process (same shape as TODO_REMINDERS_MAX). */
+/** Per-terminal nudge cap: one after use, one after the idle threshold (goodbye-loop guard). */
 export const TERM_REMINDERS_MAX = 2;
 
-/** Idle threshold before a nudge is due; the env var is read per call so tests can use small values. */
+/** Idle threshold for the second nudge; the env var is read per call so tests can use small values. */
 export function terminalIdleMs(): number {
   // B10: canonical PIER_TERM_IDLE_MS, legacy PI_HERDR_TERM_IDLE_MS.
-  return Number(pierOption('PIER_TERM_IDLE_MS') ?? 30 * 60_000) || 30 * 60_000;
+  return Number(pierOption('PIER_TERM_IDLE_MS') ?? 5 * 60_000) || 5 * 60_000;
 }
 
 /** Grace from agent_settled to injection, letting the user read the answer and intervene; cancel on agent_start. */
@@ -446,55 +455,80 @@ export function terminalReminderGraceMs(): number {
 
 export const TERM_REMINDER_CUSTOM_TYPE = 'pi-herdr.term-reminder';
 
-export interface IdleTerminalInput {
+export interface TerminalNudgeInput {
   terminalId: string;
   cwd: string;
   label: string | null;
   lastActivityAt: number;
-  /** Set once this terminal has been nudged; a nudged terminal is never nudged again (goodbye-loop guard). */
+  /** Nudges already delivered; when absent, legacy `nudgedAt` counts as one. */
+  nudges?: number;
   nudgedAt?: number | null;
+  /** A non-shell foreground process owns the pane (dev server / running job); never nudge it. */
+  busy?: boolean;
 }
 
-export interface IdleTerminalReminderPlan {
+export interface TerminalReminderPlan {
   due: boolean;
   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. */
+  /** Terminals covered by this notice; the caller bumps each one's `nudges` at schedule time. */
   ids: string[];
 }
 
-function noIdleInject(reminders: number): IdleTerminalReminderPlan {
-  return { due: false, content: null, nextReminders: reminders, ids: [] };
+function noTerminalInject(): TerminalReminderPlan {
+  return { due: false, content: null, ids: [] };
+}
+
+function nudgesOf(t: TerminalNudgeInput): number {
+  return t.nudges ?? (t.nudgedAt != null ? 1 : 0);
+}
+
+/** `72m` / `3h12m`: the reason column reads at a glance without a timestamp. */
+function formatIdleAge(ms: number): string {
+  const minutes = Math.max(0, Math.floor(ms / 60_000));
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h${String(minutes % 60).padStart(2, '0')}m`;
 }
 
 /**
- * Due only when an OPEN terminal is idle past the threshold and never nudged; the idle filter also
- * keeps dev-server shells touched recently out of the nudge.
+ * First notice: the terminal was used by the agent run that just settled, or it is already idle past
+ * the threshold. Second notice: a terminal with one nudge is idle past the threshold again. A shell
+ * touched recently is never nudged, so a dev server in active use stays out.
  */
-export function planIdleTerminalReminder(
-  input: { open: readonly IdleTerminalInput[]; now: number; reminders: number },
-): IdleTerminalReminderPlan {
+export function planTerminalReminder(
+  input: { open: readonly TerminalNudgeInput[]; now: number; turnStartedAt?: number | null },
+): TerminalReminderPlan {
   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 rows: string[] = [];
+  const ids: string[] = [];
+  for (const t of input.open) {
+    if (t.busy) continue;
+    const nudges = nudgesOf(t);
+    if (nudges >= TERM_REMINDERS_MAX) continue;
+    const idleFor = input.now - t.lastActivityAt;
+    const sinceNudge = t.nudgedAt != null ? input.now - t.nudgedAt : Number.POSITIVE_INFINITY;
+    const usedThisTurn = input.turnStartedAt != null && t.lastActivityAt >= input.turnStartedAt;
+    // Second notice waits another full idle window after the first one, so a pane that was already
+    // idle for an hour at nudge 1 is not nudged twice back-to-back on the next settle.
+    const reason = nudges === 0 && usedThisTurn
+      ? 'used this turn'
+      : nudges === 0 && idleFor >= idleMs
+        ? `idle ${formatIdleAge(idleFor)}`
+        : nudges === 1 && idleFor >= idleMs && sinceNudge >= idleMs
+          ? `still idle ${formatIdleAge(idleFor)}`
+          : null;
+    if (reason == null) continue;
+    rows.push(`- ${t.terminalId} (${t.label ?? t.cwd}) — ${reason} · nudge ${nudges + 1}/${TERM_REMINDERS_MAX}`);
+    ids.push(t.terminalId);
   }
-  const list = idle.map((t) => `- ${t.terminalId} (${t.label ?? t.cwd})`).join('\n');
+  if (ids.length === 0) return noTerminalInject();
   const content = [
-    `<system-reminder>Open terminal(s) idle for a while (nudge ${input.reminders + 1}/${TERM_REMINDERS_MAX}):`,
-    list,
+    '<system-reminder>Open terminal(s) that may be finished:',
+    ...rows,
     '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),
-  };
+  return { due: true, content, ids };
 }

package/src/todo-read-hook.ts

@@ -13,6 +13,29 @@ import { todoMark } from './todo-window.ts';
 const EMPTY_GUARD_EVERY_N = 4;
 const TODO_READ_CUSTOM_TYPE = 'pi-herdr.todo-read';
 
+/**
+ * pi 1.2 fires `before_agent_start` for runs started by `sendMessage(..., { triggerTurn: true })`
+ * too. The todo hook wants the plan in every *user* run and after a compaction continuation (the
+ * model needs the plan to resume), but not in its own stop reminder or the config guide: those
+ * already carry their own text, and counting them as turns would advance the guard cadence.
+ * Keep this list in sync with COMPACTION_CONTINUE_TYPE in compact-coordinator.ts.
+ */
+export const TODO_READ_CUSTOM_TYPES: readonly string[] = ['pi-herdr.compaction-continue'];
+
+/** Whether this run should receive the todo read hook. Missing `messageType` is pi < 1.2, where
+ *  only user runs fired `before_agent_start`; treat it as a user run for compatibility. */
+export function shouldRunTodoRead(event: unknown): boolean {
+  if (event === null || typeof event !== 'object' || !('messageType' in event)) return true;
+  const messageType = (event as { messageType?: unknown }).messageType;
+  if (messageType === 'user') return true;
+  if (messageType !== 'custom') return false;
+  const message = (event as { message?: unknown }).message;
+  const customType = message !== null && typeof message === 'object' && 'customType' in message
+    ? (message as { customType?: unknown }).customType
+    : undefined;
+  return typeof customType === 'string' && TODO_READ_CUSTOM_TYPES.includes(customType);
+}
+
 type TodoReadEffect =
   | 'recite' // Recite normally while the list is fresh.
   | 'empty-guard' // Guard against an empty list.