pi-pier 0.2.7 → 0.3.0

package/src/core/terminal.ts

@@ -10,6 +10,11 @@ import { Context } from '@deepseek-ai/cordis';
 import { Type } from 'typebox';
 import type { PiSurface } from '../pi-surface.ts';
 import type { HerdrClientLike } from '../herdr-client.ts';
+import { herdrUnavailableHint } from '../herdr-client.ts';
+import { toolError } from '../tool-error.ts'
+
+/** Raw tool arguments: every field is validated inside the action handlers. */
+type ToolParams = Record<string, unknown> | undefined;;
 import {
   READINESS_TIMEOUT_MS,
   READ_MAX_CHARS,
@@ -23,6 +28,7 @@ import {
   foldTerminalsRegistry,
   makeTerminalsRegistry,
   planIdleTerminalReminder,
+  planShellInit,
   promptStrategyFor,
   registerTerminal,
   stripAnsi,
@@ -33,6 +39,8 @@ import {
   type ReadCursor,
   type TerminalEntry,
 } from '../terminal-core.ts';
+import { swallow } from '../swallow.ts';
+import { pierOption } from '../pier-options.ts';
 
 export interface TerminalStateSlot {
   /** Lets index GC preserve panes that host active terminals. */
@@ -63,7 +71,8 @@ export default function terminalPlugin(ctx: Context): void {
   function persistTerminals(): void {
     try {
       pi.appendEntry?.(TERMINALS_CUSTOM_TYPE, makeTerminalsRegistry(terminals));
-    } catch {
+    } catch (err) {
+      swallow('terminal.persist-registry', err);
       /* Persistence is best-effort because terminal operation must not depend on session logging. */
     }
   }
@@ -170,14 +179,15 @@ export default function terminalPlugin(ctx: Context): void {
     idleReminderTimer.unref?.();
   });
 
-  const TERM_READ_MAX = Number(process.env.PI_HERDR_TERM_READ_MAX ?? READ_MAX_CHARS) || READ_MAX_CHARS;
+  const TERM_READ_MAX = Number(pierOption('PIER_TERM_READ_MAX') ?? READ_MAX_CHARS) || READ_MAX_CHARS;
   /** wait action: default and ceiling for the blocking output wait (an LLM call must not hang forever). */
   const WAIT_DEFAULT_MS = 120_000;
   const WAIT_MAX_MS = 600_000;
   /** wait action: recent-tail size handed back on timeout so the model can decide the next move. */
   const WAIT_TAIL_CHARS = 2_000;
 
-  const errText = (msg: string) => ({ content: [{ type: 'text' as const, text: `Error: ${msg}` }], details: {} });
+  /** A1: a hard failure must throw (pi sets isError only for throws); non-failures stay results. */
+  const fail = (msg: string): never => toolError(msg);
 
   scoped.registerTool({
     name: 'terminal',
@@ -191,6 +201,14 @@ export default function terminalPlugin(ctx: Context): void {
       'Long job pattern: send "cmd; echo TERM_DONE_$?" then wait with pattern "TERM_DONE_" — the sentinel also carries the exit code; redirect verbose output to a log file and read the file, because output between two reads is lost.',
       'After send, use read to confirm the command actually started; multi-line text executes line-by-line. send(wait_prompt: true) refuses to queue text while a previous command is still running.',
     ].join(' '),
+    promptSnippet: 'terminal: a persistent shell in its own pane — use for dev servers, REPLs, and multi-step shell work that must keep state between calls.',
+    promptGuidelines: [
+      'Prefer bash for one-shot commands: it is cheaper and returns output directly. Use terminal only when state must persist (server, REPL, watch loop, interactive prompt) or when you need to wait for output that appears later.',
+      'Open once, then send/read/wait against the same terminal_id; do not open a new terminal per command.',
+      'After send, read to confirm the command actually started. Multi-line text is executed line by line.',
+      'wait is for output you expect (a sentinel, a startup line); it returns the recent tail on timeout so you can decide instead of re-polling.',
+      'Close the terminal as soon as the work is done — a finished terminal keeps occupying a pane and is never auto-reclaimed.',
+    ],
     parameters: Type.Object({
       action: Type.Union([
         Type.Literal('open'),
@@ -212,7 +230,7 @@ export default function terminalPlugin(ctx: Context): void {
       max_chars: Type.Optional(Type.Number({ description: '[read] Output cap for this read (default 10000)' })),
       key: Type.Optional(Type.String({ description: '[signal] Control key: ctrl+c | ctrl+d | ctrl+z | esc | enter' })),
     }),
-    async execute(_tc, params, _sig, _upd, ctx) {
+    async execute(_tc: string, params: ToolParams, _sig: AbortSignal | undefined, _upd: unknown, ctx: unknown) {
       const action = typeof params?.action === 'string' ? params.action : '';
       switch (action) {
         case 'open': return executeTerminalOpen(params, ctx);
@@ -223,7 +241,7 @@ export default function terminalPlugin(ctx: Context): void {
         case 'close': return executeTerminalClose(params);
         case 'list': return executeTerminalList();
         default:
-          return errText(action
+          return fail(action
             ? `unknown action "${action}" (valid: open, send, wait, read, signal, close, list)`
             : 'action is required (open, send, wait, read, signal, close, list)');
       }
@@ -234,8 +252,11 @@ export default function terminalPlugin(ctx: Context): void {
   async function probeReadiness(paneId: string): Promise<'prompt' | 'silent' | 'busy'> {
     const prompt = promptStrategyFor();
     try {
-      const matched = await client.waitForOutput(paneId, { type: 'regex', value: prompt.waitPattern }, READINESS_TIMEOUT_MS);
-      if (matched) return 'prompt';
+      const waitRes = await client.waitForOutput(paneId, { type: 'regex', value: prompt.waitPattern }, READINESS_TIMEOUT_MS);
+      const isMatched = waitRes && typeof waitRes === 'object' && 'matched' in waitRes
+        ? (waitRes as { matched: boolean }).matched
+        : Boolean(waitRes);
+      if (isMatched) return 'prompt';
       const read = await client.readPane(paneId, { stripAnsi: false });
       return classifyReadiness(stripAnsi(read.text), { silentMs: 0, prompt });
     } catch {
@@ -244,8 +265,8 @@ export default function terminalPlugin(ctx: Context): void {
     }
   }
 
-  async function executeTerminalOpen(params, ctx) {
-    if (!client.available || !env) return errText('terminal tools require a herdr-managed pane');
+  async function executeTerminalOpen(params: ToolParams, ctx: unknown) {
+    if (!client.available || !env) return fail('terminal tools require a herdr-managed pane');
     const cwd = typeof params?.cwd === 'string' && params.cwd ? params.cwd
       : (ctx as { cwd?: string }).cwd ?? process.cwd();
     const r = registerTerminal(terminals, {
@@ -254,17 +275,29 @@ export default function terminalPlugin(ctx: Context): void {
       cwd,
       createdAt: Date.now(),
     });
-    if (!r.ok) return errText(r.error);
+    if (!r.ok) return fail(r.error);
     let paneId: string;
     try {
       paneId = await client.splitPane({ direction: 'right', cwd, focus: false, targetPaneId: env.paneId });
     } catch (e) {
-      return errText(`failed to split terminal pane: ${(e as Error).message}`);
+      const hint = herdrUnavailableHint(e);
+      return fail(hint ?? `failed to split terminal pane: ${(e as Error).message}`);
     }
     r.entry.paneId = paneId;
     terminals = r.entries;
     persistTerminals();
     const readiness = await probeReadiness(paneId);
+    const prompt = promptStrategyFor();
+    const init = planShellInit({ strategy: prompt, readiness });
+    if (init.shouldInit && init.command) {
+      try {
+        await client.sendPaneText(paneId, init.command);
+        r.entry.initialized = true;
+        persistTerminals();
+      } catch {
+        /* Shell init is best-effort: failure to set +H does not block terminal usage */
+      }
+    }
     const text = [
       `terminal ${r.entry.terminalId} open (pane ${paneId})`,
       `cwd: ${cwd}`,
@@ -273,18 +306,31 @@ export default function terminalPlugin(ctx: Context): void {
     return { content: [{ type: 'text', text }], details: { terminal_id: r.entry.terminalId, pane_id: paneId, readiness } };
   }
 
-  async function executeTerminalSend(params) {
+  async function executeTerminalSend(params: ToolParams) {
     const entry = findOpenTerminal(params?.terminal_id);
-    if (!entry) return errText(`unknown or closed terminal "${String(params?.terminal_id)}" (see action list)`);
+    if (!entry) return fail(`unknown or closed terminal "${String(params?.terminal_id)}" (see action list)`);
     const v = validateSendText(typeof params?.text === 'string' ? params.text : '');
-    if (!v.ok) return errText(v.error);
+    if (!v.ok) return fail(v.error);
+    if (!entry.initialized) {
+      const prompt = promptStrategyFor();
+      const init = planShellInit({ strategy: prompt });
+      if (init.shouldInit && init.command) {
+        try {
+          await client.sendPaneText(entry.paneId, init.command);
+        } catch {
+          /* Shell init is best-effort */
+        }
+      }
+      entry.initialized = true;
+      persistTerminals();
+    }
     if (params?.wait_prompt === true) {
       // Orchestration convention: read before writing. Text typed while a previous command still
       // owns the foreground gets queued and fires later, which reads as "the shell ignored me".
       // Refuse with the observed readiness instead of guessing.
       const readiness = await probeReadiness(entry.paneId);
       if (readiness !== 'prompt') {
-        return errText(
+        return fail(
           `shell is ${readiness === 'busy' ? 'busy (a previous command may still be running)' : 'silent (no prompt detected)'} — text was NOT sent. `
             + 'Use action read to inspect the pane, or omit wait_prompt to send anyway.',
         );
@@ -293,35 +339,46 @@ export default function terminalPlugin(ctx: Context): void {
     try {
       await client.sendPaneText(entry.paneId, v.text);
     } catch (e) {
-      return errText(`send failed (pane may be closed): ${(e as Error).message}`);
+      // B5: a dead herdr socket would otherwise read as "pane may be closed", which sends the
+      // model hunting for a pane that is fine. Prefer the actionable transport sentence.
+      return fail(herdrUnavailableHint(e) ?? `send failed (pane may be closed): ${(e as Error).message}`);
     }
     touchTerminal(entry);
     return { content: [{ type: 'text', text: `sent to ${entry.terminalId} (${v.text.length} chars)` }], details: { terminal_id: entry.terminalId } };
   }
 
-  async function executeTerminalWait(params) {
+  async function executeTerminalWait(params: ToolParams) {
     const entry = findOpenTerminal(params?.terminal_id);
-    if (!entry) return errText(`unknown or closed terminal "${String(params?.terminal_id)}" (see action list)`);
+    if (!entry) return fail(`unknown or closed terminal "${String(params?.terminal_id)}" (see action list)`);
     const raw = typeof params?.pattern === 'string' ? params.pattern : '';
-    if (!raw) return errText('pattern is required (literal text, or a regular expression with regex: true)');
+    if (!raw) return fail('pattern is required (literal text, or a regular expression with regex: true)');
     const useRegex = params?.regex === true;
     if (useRegex) {
       try {
         new RegExp(raw);
       } catch (e) {
-        return errText(`invalid regex: ${(e as Error).message}`);
+        return fail(`invalid regex: ${(e as Error).message}`);
       }
     }
     const requested = typeof params?.timeout_ms === 'number' && params.timeout_ms > 0 ? params.timeout_ms : WAIT_DEFAULT_MS;
     const timeoutMs = Math.min(Math.max(requested, 1000), WAIT_MAX_MS);
     const matcher = useRegex ? { type: 'regex' as const, value: raw } : { type: 'substring' as const, value: raw };
-    let matched: boolean | null;
+    let waitResult: { matched: boolean; reason?: 'timeout' | 'unavailable' };
     try {
-      matched = await client.waitForOutput(entry.paneId, matcher, timeoutMs);
+      const res = await client.waitForOutput(entry.paneId, matcher, timeoutMs);
+      if (typeof res === 'object' && res !== null && 'matched' in res) {
+        waitResult = res as { matched: boolean; reason?: 'timeout' | 'unavailable' };
+      } else if (res === true) {
+        waitResult = { matched: true };
+      } else if (res === false) {
+        waitResult = { matched: false, reason: 'timeout' };
+      } else {
+        waitResult = { matched: false, reason: 'unavailable' };
+      }
     } catch (e) {
-      return errText(`wait failed (pane may be closed): ${(e as Error).message}`);
+      return fail(herdrUnavailableHint(e) ?? `wait failed (pane may be closed): ${(e as Error).message}`);
     }
-    if (matched !== true) {
+    if (!waitResult.matched) {
       // wait-for-text convention: on timeout, hand back the recent tail so the model can decide
       // the next move instead of re-polling blind.
       let tail = '';
@@ -331,10 +388,10 @@ export default function terminalPlugin(ctx: Context): void {
       } catch {
         /* The pane is gone; the timeout text alone still tells the model it is stuck. */
       }
-      const reason = matched === false ? 'no match' : 'wait unavailable';
+      const reason = waitResult.reason === 'timeout' ? 'timeout' : 'wait unavailable';
       return {
         content: [{ type: 'text', text: `no match within ${timeoutMs}ms (${reason}).${tail ? `\nrecent output tail:\n${tail}` : ''}` }],
-        details: { terminal_id: entry.terminalId, matched: false, pattern: raw },
+        details: { terminal_id: entry.terminalId, matched: false, pattern: raw, reason },
       };
     }
     return {
@@ -343,37 +400,46 @@ export default function terminalPlugin(ctx: Context): void {
     };
   }
 
-  async function executeTerminalRead(params) {
+  async function executeTerminalRead(params: ToolParams) {
     let paneId: string | null = null;
     let entry: TerminalEntry | null = null;
     if (typeof params?.terminal_id === 'string') {
       entry = findOpenTerminal(params.terminal_id);
-      if (!entry) return errText(`unknown or closed terminal "${params.terminal_id}" (see action list)`);
+      if (!entry) return fail(`unknown or closed terminal "${params.terminal_id}" (see action list)`);
       paneId = entry.paneId;
     } else if (typeof params?.pane_id === 'string') {
       // T5 limits direct reads to this task tab or owned terminals to prevent cross-task access.
+      // A1: the guard result is carried out of the try block — a thrown tool error must not be eaten
+      // by the lookup catch below (it would be reported as a bogus "pane lookup failed").
+      let allowed = false;
+      let lookupError: unknown = null;
       try {
         const panes = await client.listPanes();
         const target = panes.find((p) => p.paneId === params.pane_id);
         const ownTab = target?.tabId && target.tabId === env?.tabId;
         const ownTerminal = activeTerminalPaneIds(terminals).has(params.pane_id);
-        if (!target || (!ownTab && !ownTerminal)) {
-          return errText('pane_id read is limited to panes in this session\'s own tab or self-created terminal panes');
-        }
-        paneId = params.pane_id;
+        allowed = Boolean(target) && Boolean(ownTab || ownTerminal);
+        if (allowed) paneId = params.pane_id;
       } catch (e) {
-        return errText(`pane lookup failed: ${(e as Error).message}`);
+        lookupError = e;
+      }
+      if (lookupError !== null) {
+        return fail(herdrUnavailableHint(lookupError) ?? `pane lookup failed: ${(lookupError as Error).message}`);
+      }
+      if (!allowed) {
+        return fail('pane_id read is limited to panes in this session\'s own tab or self-created terminal panes');
       }
     } else {
-      return errText('provide terminal_id (or pane_id for a direct own-tab read)');
+      return fail('provide terminal_id (or pane_id for a direct own-tab read)');
     }
     const maxChars = typeof params?.max_chars === 'number' && params.max_chars > 0
       ? Math.min(params.max_chars, TERM_READ_MAX) : TERM_READ_MAX;
+    if (paneId === null) return fail('no readable pane resolved (pass terminal_id, or pane_id for an own-tab pane)');
     let read: { text: string; revision: number; truncated: boolean };
     try {
       read = await client.readPane(paneId, { stripAnsi: false });
     } catch (e) {
-      return errText(`read failed (pane may be closed): ${(e as Error).message}`);
+      return fail(herdrUnavailableHint(e) ?? `read failed (pane may be closed): ${(e as Error).message}`);
     }
     // T6 inspects raw output because ANSI stripping would erase alternate-screen evidence.
     const tui = detectFullscreenTUI(read.text);
@@ -390,7 +456,7 @@ export default function terminalPlugin(ctx: Context): void {
     }
     const prev: ReadCursor | null = entry
       ? (entry.readRevision != null
-        ? { revision: entry.readRevision, len: entry.readLen, tail: entry.readTail, eoTail: entry.readEoTail }
+        ? { revision: entry.readRevision, len: entry.readLen ?? 0, tail: entry.readTail ?? '', eoTail: entry.readEoTail ?? '' }
         : null)
       : null;
     const inc = computeIncrement(prev, { text: read.text, revision: read.revision }, maxChars);
@@ -412,24 +478,24 @@ export default function terminalPlugin(ctx: Context): void {
     };
   }
 
-  async function executeTerminalSignal(params) {
+  async function executeTerminalSignal(params: ToolParams) {
     const entry = findOpenTerminal(params?.terminal_id);
-    if (!entry) return errText(`unknown or closed terminal "${String(params?.terminal_id)}" (see action list)`);
+    if (!entry) return fail(`unknown or closed terminal "${String(params?.terminal_id)}" (see action list)`);
     const v = validateSignal(typeof params?.key === 'string' ? params.key : '');
-    if (!v.ok) return errText(v.error);
+    if (!v.ok) return fail(v.error);
     try {
       await client.sendPaneKeys(entry.paneId, [v.key]);
     } catch (e) {
-      return errText(`signal failed (pane may be closed): ${(e as Error).message}`);
+      return fail(herdrUnavailableHint(e) ?? `signal failed (pane may be closed): ${(e as Error).message}`);
     }
     touchTerminal(entry);
     return { content: [{ type: 'text', text: `signal ${v.key} sent to ${entry.terminalId}` }], details: { terminal_id: entry.terminalId, key: v.key } };
   }
 
-  async function executeTerminalClose(params) {
+  async function executeTerminalClose(params: ToolParams) {
     const id = params?.terminal_id;
     const entry = terminals.find((t) => t.terminalId === id);
-    if (!entry) return errText(`unknown terminal "${String(id)}" (see action list)`);
+    if (!entry) return fail(`unknown terminal "${String(id)}" (see action list)`);
     if (entry.status === 'open') {
       try {
         await client.closePane(entry.paneId);
@@ -443,12 +509,18 @@ export default function terminalPlugin(ctx: Context): void {
   }
 
   async function executeTerminalList() {
-    let livePaneIds: string[] = [];
+    let livePanes: import('../herdr-client.ts').PaneListItem[] = [];
     try {
-      livePaneIds = (await client.listPanes()).map((p) => p.paneId);
+      livePanes = await client.listPanes();
     } catch {
       /* Treat a failed query as unknown rather than closed, because an empty live set only affects stale detection. */
     }
+    const livePaneIds = livePanes.map((p) => p.paneId);
+    const titleByPaneId = new Map<string, string>();
+    for (const p of livePanes) {
+      const cleanTitle = p.terminalTitleStripped ?? p.terminalTitle;
+      if (cleanTitle) titleByPaneId.set(p.paneId, cleanTitle);
+    }
     const s = summarizeSessions(terminals, livePaneIds);
     // T6 check 3: record vanished panes as closed across restarts rather than reviving them; tell the user to persist state.
     if (s.stalePaneIds.length > 0) {
@@ -462,9 +534,11 @@ export default function terminalPlugin(ctx: Context): void {
     if (s.terminals.length === 0) {
       return { content: [{ type: 'text', text: 'no terminals (open one with action open)' }], details: { terminals: [] } };
     }
-    const lines = s.terminals.map((t) =>
-      `- ${t.terminalId} [${t.live ? 'open' : 'closed'}] pane=${t.paneId} cwd=${t.cwd}${t.label ? ` (${t.label})` : ''}`,
-    );
+    const lines = s.terminals.map((t) => {
+      const cleanTitle = titleByPaneId.get(t.paneId);
+      const titleTag = cleanTitle && cleanTitle !== t.label ? ` title="${cleanTitle}"` : '';
+      return `- ${t.terminalId} [${t.live ? 'open' : 'closed'}] pane=${t.paneId} cwd=${t.cwd}${t.label ? ` (${t.label})` : ''}${titleTag}`;
+    });
     const note = s.stalePaneIds.length > 0
       ? '\nnote: terminal sessions do not survive pane closure/restart — persist results to files.'
       : '';

package/src/core/todo.ts

@@ -15,6 +15,10 @@ 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 { toolError } from '../tool-error.ts'
+
+/** Raw tool arguments: every field is validated inside the action handlers. */
+type ToolParams = Record<string, unknown> | undefined;;
 import { formatAge, isArchived } from '../stale-core.ts';
 import {
   TODO_EDIT_CUSTOM_TYPE,
@@ -27,12 +31,15 @@ import {
   validateTodos,
 } from '../todo-core.ts';
 import { anchorTodoRange, formatTodoSummary, renderTodoGroups } from '../todo-window.ts';
+import { swallow } from '../swallow.ts';
 
 export interface TodoUiSlot {
   /** Lets index lifecycle events render through the currently mounted plugin. */
   renderWidget: (ctx: unknown) => void;
   /** Re-render from the last seen context without a fresh event (human-gate open/close). */
   rerenderWidget?: () => void;
+  /** Cancel any pending unfinished-todo reminder timer. */
+  cancelReminder?: () => void;
 }
 
 interface TodoDeps {
@@ -49,6 +56,8 @@ interface TodoDeps {
   stopReminder?: {
     getBlockedDepth: () => number;
     getRunningSubs: () => number;
+    isCompactionInFlight?: () => boolean;
+    isIntentionalAbort?: () => boolean;
   };
 }
 
@@ -154,7 +163,6 @@ export default function todoPlugin(ctx: Context): void {
   let lastWriteTurn: number | null = null;
   let staleNotices = 0;
   let lastStaleGuardTurn: number | null = null;
-  let lastArchivedMirror = false;
 
   // Any real edit ends the current stale period because the plan is active again.
   todos.on('todo.updated', () => {
@@ -189,10 +197,12 @@ export default function todoPlugin(ctx: Context): void {
       const edits = todos.items.map((it) => ({ op: 'rm' as const, content: it.content }));
       try {
         appendEntry(TODO_EDIT_CUSTOM_TYPE, { version: 1, edits, ts: Date.now() });
-      } catch {
-        /* Persistence is best-effort because the in-memory clear must still proceed. */
+      } catch (err) {
+        // Persistence is best-effort because the in-memory clear must still proceed, but a silent
+        // failure here is exactly how the archive/replay path broke unnoticed before (SA-13).
+        swallow('todo.persist-archive', err);
       }
-      todos.replace([]);
+      todos.replace([], { source: 'archive' });
     }
     todoReadTurn += 1;
     if (!plan.inject) return;
@@ -221,6 +231,7 @@ export default function todoPlugin(ctx: Context): void {
         todoReminderTimer = null;
       }
     }
+    state.cancelReminder = cancelTodoReminder;
     scoped.on('turn_end', async (event: unknown) => {
       if (event === null || typeof event !== 'object' || !('message' in event)) return;
       const msg = (event as { message: unknown }).message;
@@ -234,8 +245,12 @@ export default function todoPlugin(ctx: Context): void {
     scoped.on('session_shutdown', () => cancelTodoReminder());
     scoped.on('agent_settled', async () => {
       cancelTodoReminder();
+      const inFlight = stopReminder.isCompactionInFlight?.() ?? false;
+      const intentional = stopReminder.isIntentionalAbort?.() ?? false;
       const plan = planStopTodoReminder({
         lastStopReason: lastAssistantStopReason,
+        intentionalAbort: intentional,
+        compactionInFlight: inFlight,
         reminders: todoReminders,
         runningSubs: stopReminder.getRunningSubs(),
         blockedDepth: stopReminder.getBlockedDepth(),
@@ -245,6 +260,7 @@ export default function todoPlugin(ctx: Context): void {
       const content = plan.content;
       todoReminderTimer = setTimeout(() => {
         todoReminderTimer = null;
+        if (stopReminder.isCompactionInFlight?.()) return;
         void (async () => {
           const send = pi.sendMessage;
           if (typeof send !== 'function') return;
@@ -291,15 +307,13 @@ export default function todoPlugin(ctx: Context): void {
         { description: 'The COMPLETE task list; this call replaces the previous list' },
       ),
     }),
-    async execute(toolCallId, params, signal, onUpdate, eventCtx) {
+    async execute(toolCallId: string, params: ToolParams, signal: AbortSignal | undefined, onUpdate: ((update: unknown) => void) | undefined, eventCtx: unknown) {
       void toolCallId;
       void signal;
       const result = validateTodos(params?.todos, allowParallelInProgress);
       if (!result.ok) {
-        return {
-          content: [{ type: 'text', text: `Error: ${result.error}` }],
-          details: {},
-        };
+        // A1: an invalid list is a hard failure — throw so pi flags isError for the model.
+        return toolError(result.error ?? 'invalid todo list');
       }
       const strictMode = todos.config.strict; // D75 phase 2 keeps policy in the service config.
       let next = result.items!;
@@ -322,7 +336,7 @@ export default function todoPlugin(ctx: Context): void {
       // D36/D37 surface completion transitions and regressions to the caller.
       const completed = completionTransitions(todos.items, next);
       const reverted = revertedCompleted(todos.items, next);
-      todos.replace(next);
+      todos.replace(next, { source: 'tool' });
       if (todos.items.length > maxItems) {
         onUpdate?.(makeProgressUpdate(`Note: list has ${todos.items.length} entries; consider keeping it under ${maxItems}.`));
       }
@@ -372,7 +386,7 @@ export default function todoPlugin(ctx: Context): void {
         const content = candidates[0];
         const edit = { op: opArg as 'done' | 'drop' | 'rm' | 'unblock', content };
         const before = todos.items;
-        todos.applyEdits([edit]);
+        todos.applyEdits([edit], { source: 'human' });
         if (listsEqual(before, todos.items)) {
           ui?.notify?.(`no change: "${content}" is already in that state`, 'info');
           return;

package/src/dashboard-command.ts

@@ -0,0 +1,89 @@
+import type { HerdrClientLike, HerdrEnv } from './herdr-client.ts';
+import type { TodoItem } from './vocab.ts';
+
+export interface DashboardCommandDeps {
+  pi: {
+    registerCommand(name: string, options: { description: string; handler: (args: unknown, ctx: unknown) => Promise<void> }): void;
+  };
+  client: HerdrClientLike;
+  env: HerdrEnv | null;
+  getTodoItems?: () => readonly TodoItem[];
+  getHeldLocks?: () => readonly string[];
+}
+
+export function formatStandaloneDashboard(opts: {
+  todos: readonly TodoItem[];
+  locks: readonly string[];
+  now?: number;
+}): string {
+  const lines: string[] = [];
+  const timeStr = new Date(opts.now ?? Date.now()).toTimeString().split(' ')[0] ?? '';
+  lines.push(`==================== PIER OPS DASHBOARD ==================== [${timeStr}] (standalone)`);
+  lines.push('Mode: Standalone (Non-Herdr / Local Session)');
+  lines.push('--------------------------------------------------------------------------------');
+
+  const todos = opts.todos;
+  if (todos.length > 0) {
+    const inProg = todos.filter((t) => t.status === 'in_progress');
+    const blocked = todos.filter((t) => t.status === 'blocked');
+    const done = todos.filter((t) => t.status === 'completed');
+    const pending = todos.filter((t) => t.status === 'pending');
+    lines.push(
+      `Todos: ${todos.length} total (${done.length} done, ${inProg.length} working, ${blocked.length} blocked, ${pending.length} pending)`,
+    );
+    if (inProg.length > 0) {
+      lines.push(`Active: ▶ ${inProg.map((t) => t.content).join(', ')}`);
+    }
+    if (blocked.length > 0) {
+      lines.push(`Blocked: ■ ${blocked.map((t) => `${t.content}${t.blocker ? ` (${t.blocker})` : ''}`).join(', ')}`);
+    }
+    if (inProg.length === 0 && blocked.length === 0 && done.length > 0) {
+      lines.push(`Completed: ✓ ${done.slice(-3).map((t) => t.content).join(', ')}`);
+    }
+  } else {
+    lines.push('Todos: (none)');
+  }
+
+  const locks = opts.locks;
+  lines.push(`Write Locks: ${locks.length > 0 ? locks.join(', ') : '(none)'}`);
+  lines.push('--------------------------------------------------------------------------------');
+  lines.push('Tip: Inside Herdr 0.9.1, /dashboard opens the interactive modal popup.');
+  lines.push('================================================================================');
+  return lines.join('\n');
+}
+
+export function installDashboardCommand(deps: DashboardCommandDeps): void {
+  deps.pi.registerCommand('dashboard', {
+    description: 'Open the Pier Ops Dashboard (modal popup in Herdr 0.9.1, tab fallback, or local TUI view)',
+    handler: async (_args, ctx) => {
+      const ui = (ctx as { ui?: { notify?: (text: string, level?: string) => void } }).ui;
+
+      // Level 1 / Level 2: Herdr environment
+      if (deps.client.available && deps.env) {
+        try {
+          const res = await deps.client.openPluginPane({
+            pluginId: 'pier.workbench',
+            entrypoint: 'dashboard',
+            placement: 'popup',
+            width: '80%',
+            height: '80%',
+            focus: true,
+          });
+          if (res.mode === 'fallback_tab') {
+            ui?.notify?.('Herdr < 0.9.1: Pier Dashboard opened in new tab', 'info');
+          }
+          return;
+        } catch {
+          // If plugin is not installed or socket error occurs, fall through to Level 3 local view
+        }
+      }
+
+      // Level 3: Standalone / Non-Herdr fallback
+      const text = formatStandaloneDashboard({
+        todos: deps.getTodoItems?.() ?? [],
+        locks: deps.getHeldLocks?.() ?? [],
+      });
+      ui?.notify?.(text, 'info');
+    },
+  });
+}