pi-pier 0.3.1 → 0.4.2

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,12 +20,14 @@ import type { HistoryEntry } from './history-store.ts';
 import {
   FOREGROUND_POLL_MS,
   Semaphore,
+  allocateSubSlug,
   buildAliveNotice,
   buildBlockedGateNotice,
   buildIsolatePreamble,
   buildLaunchLine,
   buildLaunchParts,
   classifyWorktreeZone,
+  formatIsolateLocation,
   formatSubagentResult,
   formatWorktreeStat,
   isAlive,
@@ -32,8 +36,10 @@ import {
   planForegroundTick,
   planIsolateWorktree,
   planLaunchValidation,
+  planShellReady,
   planTabPlacement,
   sleep,
+  subRef,
   type SubEntry,
   type TabPlacementPlan,
   type WorktreeZone,
@@ -45,6 +51,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 +313,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 +494,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 +506,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 +542,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 +572,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 +590,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()),
+        // The master's own pipe so the worker's todo_sync push 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 +669,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 +734,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})${formatIsolateLocation(isolateMeta)}` }],
+          details: { paneId, taskId, background: true, role: kind, slug },
         };
       }
 
@@ -705,7 +753,7 @@ export function createSpawnAction(h: SpawnActionHost) {
           const question = await readAskFlag(paneId);
           handToPoller(`prompt-${taskId}`);
           return {
-            content: [{ type: 'text', text: buildBlockedGateNotice({ paneId, description: spec.description, question }) }],
+            content: [{ type: 'text', text: `${buildBlockedGateNotice({ paneId, description: spec.description, question })}${formatIsolateLocation(isolateMeta)}` }],
             details: { paneId, taskId, background: true, blocked: true, role: kind },
           };
         }
@@ -729,7 +777,7 @@ export function createSpawnAction(h: SpawnActionHost) {
         if (isAlive(probe, Date.now())) {
           handToPoller(`prompt-${taskId}`);
           return {
-            content: [{ type: 'text', text: buildAliveNotice({ paneId, description: spec.description, scenario: 'moved-to-bg', probe }, Date.now()) }],
+            content: [{ type: 'text', text: `${buildAliveNotice({ paneId, description: spec.description, scenario: 'moved-to-bg', probe }, Date.now())}${formatIsolateLocation(isolateMeta)}` }],
             details: { paneId, taskId, background: true, movedToBackground: true, role: kind },
           };
         }
@@ -744,7 +792,7 @@ export function createSpawnAction(h: SpawnActionHost) {
       h.persistSubs();
       h.writeHistory(entry, { outcome: outcome.kind === 'completed' ? text : null }, 'fg-settle');
       return {
-        content: [{ type: 'text', text: formatSubagentResult(outcome, spec.description) }],
+        content: [{ type: 'text', text: `${formatSubagentResult(outcome, spec.description)}${formatIsolateLocation(isolateMeta)}` }],
         details: { paneId, taskId, background, role: kind },
       };
     } catch (err) {

package/src/terminal-core.ts

@@ -69,14 +69,17 @@ 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;
   readRevision?: number | null;
   readLen?: number;
   readTail?: string;
-  readEoTail?: string;
+  readTextLen?: number;
+  readTextHash?: number;
   initialized?: boolean;
 }
 
@@ -123,13 +126,15 @@ 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,
     readRevision: null,
     readLen: 0,
     readTail: '',
-    readEoTail: '',
+    readTextLen: 0,
+    readTextHash: 0,
   };
   return { ok: true, entries: [...entries, entry], entry };
 }
@@ -200,12 +205,61 @@ export function validateSignal(key: string): { ok: true; key: SignalKey } | { ok
   return { ok: true, key: k };
 }
 
+/** Compile a wait pattern with line semantics: herdr matches per line, so `^`/`$` anchors must bind
+ *  to line starts/ends, not only the start/end of the whole pane buffer. */
+export function compilePattern(pattern: string): RegExp {
+  return new RegExp(pattern, 'm');
+}
+
+/** The literal prefix of a regex source (leading `^` ignored, stops at the first metacharacter).
+ *  Lets the echo guard notice `DONE_[0-9]` in a command that echoes `DONE_$?`, which the full regex
+ *  cannot match even though the sentinel is plainly present in the typed text. */
+export function regexLiteralPrefix(pattern: string): string {
+  let prefix = '';
+  for (let i = 0; i < pattern.length; i += 1) {
+    const ch = pattern[i]!;
+    if (ch === '^' && prefix.length === 0) continue;
+    if (ch === '\\') {
+      const next = pattern[i + 1];
+      if (next == null || /[dDwWsSbBAZzG]/.test(next)) break;
+      prefix += next;
+      i += 1;
+      continue;
+    }
+    if ('.*+?^${}()|[]'.includes(ch)) break;
+    prefix += ch;
+  }
+  return prefix;
+}
+
+/** A concrete, echo-safe wait pattern derived from the literal prefix: anchored at a line start and
+ *  expecting the numeric sentinel suffix (`APN_BUILD2_EXIT_$?` → `^APN_BUILD2_EXIT_[0-9]`). Trailing
+ *  digits after a separator are dropped so a literal `..._0` still derives `..._[0-9]`; digits glued
+ *  to a name (`step2`) stay, because they are part of the marker. */
+export function echoSafeWaitSuggestion(literal: string): string | null {
+  const base = literal.replace(/([^A-Za-z0-9])\d+$/, '$1');
+  if (!base) return null;
+  return `^${base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[0-9]`;
+}
+
+/**
+ * A `cmd; echo RUN_EXIT_$? >> /tmp/run.log` sentinel lands in the log file, never in the pane a
+ * plain wait watches: one session slept 240-420 s at a time polling such a log with bash. Returns
+ * the sentinel's literal prefix and the file it is redirected into, or null.
+ */
+export function redirectedSentinel(text: string): { prefix: string; file: string } | null {
+  const m = /\becho\s+["']?([A-Za-z][A-Za-z0-9_]*?)\$\?["']?\s*>>?\s*(["']?)([^\s;&|"']+)\2/.exec(text);
+  return m ? { prefix: m[1]!, file: m[3]! } : null;
+}
+
 /**
  * Whether a wait pattern would match the terminal's own echoed input: the shell echoes typed
  * commands into the pane, so a pattern contained in the last sent text (`…; echo TERM_DONE_$?`
  * waited on as literal `TERM_DONE_`) matches its own echo and returns "matched" before the job
- * has produced anything. Detection is per terminal and best-effort: no send in this process
- * lifetime → no hazard known → the wait proceeds unchanged.
+ * has produced anything. A regex whose literal prefix occurs in the echo is also a hazard: the
+ * sentinel `DONE_$?` becomes `DONE_<status>` only after the command runs.
+ * Detection is per terminal and best-effort: no send in this process lifetime → no hazard known →
+ * the wait proceeds unchanged.
  */
 export function sentinelEchoHazard(opts: {
   pattern: string;
@@ -216,7 +270,13 @@ export function sentinelEchoHazard(opts: {
   if (!sent) return false;
   if (opts.regex) {
     try {
-      return new RegExp(opts.pattern).test(sent);
+      const re = compilePattern(opts.pattern);
+      if (re.test(sent)) return true;
+      // An anchored pattern is already safe when the echo cannot start a line with its literal
+      // prefix (`^DONE_[0-9]` vs `cmd; echo DONE_$?`); only unanchored patterns need the substring check.
+      const prefix = regexLiteralPrefix(opts.pattern);
+      if (!opts.pattern.startsWith('^') && prefix.length >= 3 && sent.includes(prefix)) return true;
+      return sent.includes('$?') && re.test(sent.replace(/\$\?/g, '0'));
     } catch {
       return false; // invalid regex is rejected by the caller before this runs
     }
@@ -239,11 +299,29 @@ export function stripAnsi(raw: string): string {
     .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
 }
 
+/** Secondary prompts (`dquote>`, `heredoc>`, `cmdand>`, …) mean the shell is still collecting input:
+ *  the command was incomplete (unbalanced quote, open block, …) and every later line types into it.
+ *  Only the last non-empty line is inspected, so `>` in ordinary output cannot trip the check. */
+const CONTINUATION_PROMPT_RE = /^(?:quote|dquote|bquote|heredoc|cmdand|cmdor|cmdsubst|subsh|then|else|elif|do|done|for|while|if|fi|case|esac|select|repeat|function|math|brace|foreach|cond)>$/i;
+
+export function detectContinuationPrompt(text: string): string | null {
+  const lines = text.split('\n');
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i]!.trim();
+    if (!line) continue;
+    return CONTINUATION_PROMPT_RE.test(line) ? line : null;
+  }
+  return null;
+}
+
 export interface ReadCursor {
   revision: number;
   len: number;
   tail: string;
-  eoTail: string;
+  /** Full pane-text length and FNV-1a hash: herdr's screen window can rewrite earlier lines while
+   *  the last characters stay identical, so a tail comparison alone is not a change detector. */
+  textLen: number;
+  textHash: number;
 }
 
 export interface ReadIncrement {
@@ -255,24 +333,36 @@ export interface ReadIncrement {
 
 const CURSOR_TAIL_CHARS = 64;
 
+/** FNV-1a 32-bit: change detection for the read cursor, not a security primitive. */
+export function hashPaneText(text: string): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
 export function computeIncrement(
   prev: ReadCursor | null,
   next: { text: string; revision: number },
   maxChars: number,
 ): ReadIncrement {
   const stableLen = next.text.lastIndexOf('\n') + 1;
+  const textHash = hashPaneText(next.text);
   const cursor: ReadCursor = {
     revision: next.revision,
     len: stableLen,
     tail: next.text.slice(Math.max(0, stableLen - CURSOR_TAIL_CHARS), stableLen),
-    eoTail: next.text.slice(-CURSOR_TAIL_CHARS).trimEnd(),
+    textLen: next.text.length,
+    textHash,
   };
-  if (prev && next.text.slice(-CURSOR_TAIL_CHARS).trimEnd() === prev.eoTail) {
+  if (prev && prev.textLen === next.text.length && prev.textHash === textHash) {
     return { mode: 'none', text: '', cursor: prev, hardCapped: false };
   }
   if (
     prev &&
-    next.text.length >= prev.len &&
+    next.text.length > prev.textLen &&
     next.text.slice(Math.max(0, prev.len - prev.tail.length), prev.len).trimEnd() === prev.tail.trimEnd()
   ) {
     const suffix = next.text.slice(prev.len);
@@ -290,7 +380,7 @@ export function excerptAroundMatch(text: string, pattern: string, regex: boolean
   let index = -1;
   let hitLen = pattern.length;
   if (regex) {
-    const found = new RegExp(pattern).exec(text);
+    const found = compilePattern(pattern).exec(text);
     index = found?.index ?? -1;
     hitLen = found?.[0].length ?? pattern.length;
   } else {
@@ -312,7 +402,7 @@ export function classifyWaitMatch(
   pattern: string,
   regex: boolean,
 ): { kind: 'fresh'; excerpt: string } | { kind: 'stale' } | { kind: 'absent' } {
-  const match = (text: string) => regex ? new RegExp(pattern).test(text) : text.includes(pattern);
+  const match = (text: string) => regex ? compilePattern(pattern).test(text) : text.includes(pattern);
   const inc = computeIncrement(prev, { text: paneText, revision: prev?.revision ?? 0 }, paneText.length + 1);
   const unread = inc.mode === 'append' ? inc.text : inc.mode === 'reset' ? paneText : '';
   if (match(unread)) return { kind: 'fresh', excerpt: excerptAroundMatch(unread, pattern, regex) };
@@ -375,10 +465,15 @@ export interface ShellInitPlan {
   readonly command: string | null;
 }
 
+/** History expansion off in both managed shells: bash honours `set +H`, zsh requires
+ *  `setopt NO_BANG_HIST` (`set +H` leaves `!` expansion on and an unbalanced `"…$!"` wedges the
+ *  shell at `dquote>`). Both shells parse this one-liner; only the matching branch runs. */
+export const SHELL_INIT_COMMAND = 'if [ -n "$ZSH_VERSION" ]; then setopt NO_BANG_HIST; else set +H; fi';
+
 /**
- * Plan the shell init command: `set +H` disables history expansion in managed bash/zsh shells, where `!`
- * in ordinary commands (`!|`, `if [ ! -f ... ]`, `!$`) otherwise triggers `zsh: event not found: \|` and
- * wedges the shell. PowerShell rejects the syntax and has no `!` history expansion, so it is skipped.
+ * Plan the shell init command: disable history expansion, where `!` in ordinary commands (`!|`,
+ * `if [ ! -f ... ]`, `!$`) otherwise triggers `zsh: event not found: \|` and wedges the shell.
+ * PowerShell rejects the syntax and has no `!` history expansion, so it is skipped.
  * Limit: the top-level shell only — a nested `bash -i` re-enables its own defaults; init is only worth
  * sending once the shell is at its prompt and has not been initialized yet.
  */
@@ -392,7 +487,7 @@ export function planShellInit(opts: {
   if (opts.readiness !== undefined && opts.readiness !== 'prompt') {
     return { shouldInit: false, command: null };
   }
-  return { shouldInit: true, command: 'set +H' };
+  return { shouldInit: true, command: SHELL_INIT_COMMAND };
 }
 
 export function foldTerminalsRegistry(
@@ -413,30 +508,37 @@ 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,
         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 : '',
+        readTextLen: typeof t.readTextLen === 'number' ? t.readTextLen : 0,
+        readTextHash: typeof t.readTextHash === 'number' ? t.readTextHash : 0,
         initialized: t.initialized === true,
       }));
   }
   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 +548,81 @@ 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` when the notice is
+   *  actually delivered (a cancelled grace timer must not consume a nudge). */
   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-core.ts

@@ -9,6 +9,17 @@ const PHASE_MAX_LEN = 30;
 /** Session entry type for human/automated edits, replayed during branch rebuild (D38). */
 export const TODO_EDIT_CUSTOM_TYPE = 'pi-herdr.todo-edit';
 
+/** Session entry type recording that the near-archive rewrite window was already offered for one
+ *  list; folded on rebuild so a resumed session proceeds to the terminal clear instead of re-warning. */
+export const TODO_ARCHIVE_WINDOW_CUSTOM_TYPE = 'pi-herdr.todo-archive-window';
+
+export interface ArchiveWindowMarker {
+  version: 1;
+  /** Ordered list identity at offer time. The marker only applies after the last snapshot, so any
+   *  rewrite (new snapshot) or edit (list mutation) invalidates it without a timestamp comparison. */
+  itemsHash: string;
+}
+
 export type TodoEditOp = 'done' | 'drop' | 'rm' | 'unblock';
 
 export interface TodoEdit {
@@ -115,6 +126,20 @@ export function listsEqual(a: readonly TodoItem[], b: readonly TodoItem[]): bool
   return true;
 }
 
+/** Stable list identity (FNV-1a over content/status/blocker/phase): keys the archive-window marker
+ *  so it never applies to a list that was edited after the window was offered. */
+export function todoListHash(items: readonly TodoItem[]): string {
+  let hash = 0x811c9dc5;
+  for (const it of items) {
+    const text = `${it.content}\u0000${it.status}\u0000${it.blocker ?? ''}\u0000${it.phase ?? ''}\u0001`;
+    for (let i = 0; i < text.length; i++) {
+      hash ^= text.charCodeAt(i);
+      hash = Math.imul(hash, 0x01000193);
+    }
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
 /** Items completed by this write (D36: surfaced back to the caller). */
 export function completionTransitions(prev: readonly TodoItem[], next: readonly TodoItem[]): string[] {
   const prevMap = new Map(prev.map((it) => [it.content, it.status]));
@@ -123,8 +148,11 @@ export function completionTransitions(prev: readonly TodoItem[], next: readonly
     .map((it) => it.content);
 }
 
-/** Completed items pushed back to open by this write (D37: reversible, but warn). */
+/** Completed items pushed back to open by this write (D37: reversible, but warn). A previous list
+ *  with no open item was a finished plan, and a new plan legitimately reuses generic task names, so
+ *  content-keyed reversion is meaningless there: warn only while the same plan is still in flight. */
 export function revertedCompleted(prev: readonly TodoItem[], next: readonly TodoItem[]): string[] {
+  if (!prev.some((it) => it.status === 'pending' || it.status === 'in_progress')) return [];
   const nextMap = new Map(next.map((it) => [it.content, it.status]));
   return prev
     .filter((it) => {
@@ -206,6 +234,15 @@ export interface FoldedTodos {
   items: TodoItem[];
   /** Timestamp of the last write that shaped these items; null when the entry carried none. */
   writtenAt: number | null;
+  /** True when the anti-freeze rewrite window was already offered for exactly this untouched list. */
+  archiveWindowOffered: boolean;
+}
+
+function extractArchiveWindowMarker(data: unknown): ArchiveWindowMarker | null {
+  if (typeof data !== 'object' || data === null) return null;
+  const raw = data as Partial<ArchiveWindowMarker>;
+  if (raw.version !== 1 || typeof raw.itemsHash !== 'string') return null;
+  return { version: 1, itemsHash: raw.itemsHash };
 }
 
 function entryTimestamp(entry: BranchEntryLike): number | null {
@@ -222,6 +259,9 @@ function entryTimestamp(entry: BranchEntryLike): number | null {
 export function foldLatestTodosMeta(entries: readonly BranchEntryLike[]): FoldedTodos | null {
   let found: TodoItem[] | null = null;
   let writtenAt: number | null = null;
+  // The marker applies only when it follows the last snapshot; a later snapshot resets it, and any
+  // edit that actually changes the list makes the hash mismatch (a no-op edit leaves it untouched).
+  let windowMarker: ArchiveWindowMarker | null = null;
   for (const entry of entries) {
     if (entry.type === 'message') {
       const msg = entry.message as { role?: unknown; toolName?: unknown; details?: unknown } | null | undefined;
@@ -231,6 +271,7 @@ export function foldLatestTodosMeta(entries: readonly BranchEntryLike[]): Folded
       if (snapshot) {
         found = snapshot.items.map((it) => ({ ...it }));
         writtenAt = entryTimestamp(entry);
+        windowMarker = null;
       }
     } else if (entry.type === 'custom' && entry.customType === TODO_EDIT_CUSTOM_TYPE) {
       const payload = extractEditPayload(entry.data);
@@ -238,9 +279,13 @@ export function foldLatestTodosMeta(entries: readonly BranchEntryLike[]): Folded
         found = applyTodoEdits(found, payload.edits);
         writtenAt = entryTimestamp(entry) ?? (payload.ts > 0 ? payload.ts : writtenAt);
       }
+    } else if (entry.type === 'custom' && entry.customType === TODO_ARCHIVE_WINDOW_CUSTOM_TYPE && found) {
+      windowMarker = extractArchiveWindowMarker(entry.data);
     }
   }
-  return found ? { items: found, writtenAt } : null;
+  if (!found) return null;
+  const archiveWindowOffered = windowMarker != null && windowMarker.itemsHash === todoListHash(found);
+  return { items: found, writtenAt, archiveWindowOffered };
 }
 
 function extractSnapshotFromDetails(details: unknown): TodoSnapshot | null {