pi-pier 0.3.0 → 0.4.1

package/src/todo-window.ts

@@ -1,11 +1,8 @@
 /**
- * Activity-anchored todo window used by the pi widget and the slim overlay.
- *
- * Why: both surfaces must keep the in-progress row visible instead of a fixed
- * head/tail slice. The widget budgets unwrapped render lines; the overlay
- * supplies its own `fits` so wrapping can consume extra rows.
+ * Activity-anchored todo window for the pi widget and the slim overlay: the widget passes a budget of
+ * unwrapped render lines, the overlay supplies its own `fits`; the in-progress row stays visible.
  */
-import { countTodos, type TodoItem, type TodoStatus } from './vocab.ts';
+import { countTodos, isTodoStatus, type TodoItem, type TodoStatus } from './vocab.ts';
 
 export const TODO_MARKS: Record<TodoStatus, string> = {
   pending: '○',
@@ -15,12 +12,15 @@ export const TODO_MARKS: Record<TodoStatus, string> = {
   abandoned: '✗',
 };
 
+/** Mark for a snapshot's status, tolerating corrupt data (`?` instead of a prototype member). */
+export const todoMark = (status: unknown): string => (isTodoStatus(status) ? TODO_MARKS[status] : '?');
+
 export function formatTodoSummary(items: readonly TodoItem[]): string {
-  const c = countTodos(items as TodoItem[]);
+  const c = countTodos(items);
   return `todo: ${c.inProgress}▶ ${c.pending}○ ${c.blocked}■ ${c.completed}✓`;
 }
 
-/** Share phase rendering so widget and overlay order entries identically. */
+/** Shared phase rendering so widget and overlay order entries identically. */
 export function renderTodoGroups(items: readonly TodoItem[]): string[] {
   const groups = new Map<string, TodoItem[]>();
   for (const it of items) {
@@ -34,16 +34,15 @@ export function renderTodoGroups(items: readonly TodoItem[]): string[] {
     if (phase) lines.push(`  [${phase}]`);
     for (const it of list) {
       const suffix = it.status === 'blocked' && it.blocker ? ` — ${it.blocker}` : '';
-      lines.push(`  ${TODO_MARKS[it.status]} ${it.content}${suffix}`);
+      lines.push(`  ${todoMark(it.status)} ${it.content}${suffix}`);
     }
   }
   return lines;
 }
 
 /**
- * Expand around the active anchor while `fits(start, end)` remains true.
- * Prefers upcoming work; the anchor stays visible. All-completed lists keep
- * the original head-shrink (widget-compatible).
+ * Expand around the active anchor while `fits(start, end)` holds: the first in_progress item, else the
+ * last open one, growing toward the tail first. All-completed lists shrink from the head instead.
  */
 export function anchorTodoRange(
   items: readonly TodoItem[],

package/src/todos-service.ts

@@ -1,13 +1,6 @@
-/** Why: Preserve the established compatibility and safety behavior (D65, D75). */
+/** Single owner of todo state; every mutation path (tool, human edit, M17 reconcile, archive) lands here (D65, D75). */
 import { EventEmitter } from 'node:events';
-import {
-  applyTodoEdits,
-  foldLatestTodosMeta,
-  listsEqual,
-  type TodoEdit,
-  type TodoItem,
-} from './todo-core.ts';
-import { countCompletedTransitions } from './progress-core.ts';
+import { applyTodoEdits, completionTransitions, foldLatestTodosMeta, listsEqual, type TodoEdit, type TodoItem } from './todo-core.ts';
 import type { RuntimeRoleManifest } from './tool-gate.ts';
 
 export interface TodosConfig {
@@ -17,21 +10,13 @@ export interface TodosConfig {
 
 export type TodoCompletionSource = 'tool' | 'reconcile' | 'human' | 'archive';
 
-export interface TodoCompletedEvent {
-  count: number;
-  at: number;
-  source: TodoCompletionSource;
-}
-
 export class TodosService extends EventEmitter {
   private _items: TodoItem[] = [];
-  /**
-   * Live list (read-only). Mutations must go through replace/applyEdits/rebuild.
-   */
+  /** Live list (read-only). Mutations must go through replace/applyEdits/rebuild. */
   get items(): readonly TodoItem[] {
     return this._items;
   }
-  /** Why: Preserve the established compatibility and safety behavior. */
+  /** Clock anchor for staleness/archiving; null until the first write. */
   lastWriteAt: number | null = null;
   readonly config: TodosConfig;
 
@@ -40,17 +25,14 @@ export class TodosService extends EventEmitter {
     this.config = config;
   }
 
-  /** Why: Preserve the established compatibility and safety behavior (D75). */
+  /** D75: subagents are strict (one in_progress); the role manifest may force parallel mode. */
   static configFromRuntime(manifest: RuntimeRoleManifest | null, isSubagent: boolean): TodosConfig {
     const strict = isSubagent;
     const mode = manifest?.services?.todos?.mode;
-    const allowParallelInProgress = mode === 'parallel' || mode === 'serial' ? mode === 'parallel' : !strict;
-    return { strict, allowParallelInProgress };
-  }
-
-  /** Defensive copy for callers that must not mutate service state. */
-  getSnapshot(): TodoItem[] {
-    return this._items.map((it) => ({ ...it }));
+    return {
+      strict,
+      allowParallelInProgress: mode === 'parallel' || mode === 'serial' ? mode === 'parallel' : !strict,
+    };
   }
 
   replace(items: readonly TodoItem[], opts?: { source?: TodoCompletionSource }): { changed: boolean } {
@@ -76,24 +58,22 @@ export class TodosService extends EventEmitter {
     return { changed: true };
   }
 
-  /** Why: Preserve the established compatibility and safety behavior (M16). */
+  /** M16: ETA and compaction boundaries feed off this single completion diff (same rule as the tool's D36 report). */
   private emitCompletedTransitions(
     before: readonly TodoItem[],
     after: readonly TodoItem[],
     source: TodoCompletionSource = 'tool',
   ): void {
-    const count = countCompletedTransitions(before, after);
+    const count = completionTransitions(before, after).length;
     if (count > 0) this.emit('todo.completed', { count, at: Date.now(), source });
   }
 
+  /** Branch replay: fold the JSONL to the authoritative list. A branch with no snapshot (/new, or /tree
+   *  back before the first todo_write) has no list, so the previous session's items must not survive. */
   rebuild(entries: readonly unknown[]): void {
-    // Why: Preserve the established compatibility and safety behavior.
-    // Why: Preserve the established compatibility and safety behavior.
     const folded = foldLatestTodosMeta(entries as Parameters<typeof foldLatestTodosMeta>[0]);
-    if (folded) {
-      this._items = folded.items;
-      this.lastWriteAt = folded.writtenAt;
-    }
+    this._items = folded ? folded.items : [];
+    this.lastWriteAt = folded ? folded.writtenAt : null;
     this.emit('todo.updated', { items: this._items, reason: 'rebuild' });
   }
 }

package/src/tool-error.ts

@@ -1,17 +1,11 @@
 /**
- * A1: pi only marks a tool result as failed when `execute()` throws — "Returning a value never sets
- * the error flag regardless of what properties you include in the return object"
- * (pi docs/extensions.md, "Signaling errors").
+ * pi only marks a tool result as failed when `execute()` throws; returning a value never sets the
+ * error flag (pi docs/extensions.md, "Signaling errors"). Every hard failure goes through
+ * `toolError()`, while deliberate non-failures (empty result set, "no match within Xms", a pane that
+ * has not produced output yet) stay normal results.
  *
- * The round-2 audit found 20+ real failures in pier's tools returned as plain text, so neither the
- * model nor pi's own hooks keyed on `event.isError` could see them (pier's B1 "subagent alive but
- * reported no output" self-heal was dead code for exactly that reason). Every hard failure now goes
- * through `toolError()`; deliberate non-failures (empty result set, "no match within Xms", a pane
- * that simply has not produced output yet) stay normal results.
- *
- * The "Error: " prefix the old text returns carried is dropped: the provider's tool-result error
- * channel and pi's red rendering already mark it, and keeping it would double the prefix once pi
- * formats a thrown error.
+ * The leading "Error: " text is stripped: the provider's tool-result error channel and pi's red
+ * rendering already mark it, and keeping it would double the prefix once pi formats a thrown error.
  */
 export class ToolError extends Error {
   constructor(message: string) {
@@ -20,7 +14,6 @@ export class ToolError extends Error {
   }
 }
 
-/** Throw a tool failure (never returns). */
 export function toolError(message: string): never {
   throw new ToolError(message);
 }

package/src/tool-gate.ts

@@ -1,31 +1,40 @@
-/** Why: Preserve the established compatibility and safety behavior (C7, D76, D77, D79, WS-D6). */
+/**
+ * Worker execution enforcement (C7, D76/D77/D82) — pure. RuntimeRoleManifest is THE runtime manifest
+ * shape; the file format lives in role-manifest.ts and the composed/persisted shapes derive from it
+ * (manifest-compose.ts, role-state.ts).
+ */
 import type { PermissionAction, UnknownToolStance } from './role-manifest.ts';
 
-/** Why: Preserve the established compatibility and safety behavior. */
 export interface RuntimeRoleManifest {
   role: string;
   version?: string;
   tools: string[];
   permissions: Record<string, PermissionAction>;
-  /** Why: Preserve the established compatibility and safety behavior (D82). */
+  /** Stance for tools outside `tools`; 'allow' keeps user-installed extensions visible (D82). */
   unknownTools?: UnknownToolStance;
   services?: {
     todos?: {
       mode?: 'serial' | 'parallel';
     };
   };
+  /** P0 per-role guidelines (RFC §4.6): injected as a `pier-role` prompt section each turn. */
+  guidelines?: string[];
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
+/** Parse the env-carried manifest; malformed input is null (fail-open: no gate) rather than a crash. */
 export function parseRuntimeManifest(envValue: string | undefined): RuntimeRoleManifest | null {
   if (!envValue) return null;
   try {
     const m = JSON.parse(envValue) as RuntimeRoleManifest;
     if (!m || typeof m.role !== 'string' || !Array.isArray(m.tools)) return null;
-    // Why: Preserve the established compatibility and safety behavior (D82).
     if (m.unknownTools !== undefined && m.unknownTools !== 'allow' && m.unknownTools !== 'deny') {
       m.unknownTools = 'deny';
     }
+    if (m.guidelines !== undefined) {
+      m.guidelines = Array.isArray(m.guidelines)
+        ? m.guidelines.filter((g) => typeof g === 'string' && g.trim() !== '')
+        : undefined;
+    }
     return m;
   } catch {
     return null;
@@ -43,7 +52,6 @@ export function planToolGate(toolName: string, manifest: RuntimeRoleManifest | n
   const perm = manifest.permissions[toolName] ?? manifest.permissions['*'] ?? 'allow';
   const known = manifest.tools.includes(toolName);
   const stance = manifest.unknownTools ?? 'deny';
-  // Why: Preserve the established compatibility and safety behavior (D82).
   if (perm === 'deny' || (!known && stance === 'deny')) {
     return {
       kind: 'deny',
@@ -59,27 +67,36 @@ export function planToolGate(toolName: string, manifest: RuntimeRoleManifest | n
   return { kind: 'allow' };
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D77, D82). */
-export function planActiveTools(
-  manifestTools: string[],
-  currentActive: string[],
+/**
+ * 'allow' keeps every tool but the explicit deny rules (D82 user-installed-extension axis); 'deny'
+ * intersects with the manifest. Shared by planActiveTools (visibility) and role-state's switch
+ * planning (all-tools universe).
+ */
+export function filterToolsByStance(
+  manifestTools: readonly string[],
+  universe: readonly string[],
   opts?: { unknownTools?: UnknownToolStance; permissions?: Record<string, PermissionAction> },
-): { next: string[]; changed: boolean } | null {
-  if (manifestTools.length === 0 || currentActive.length === 0) return null;
+): string[] {
   if ((opts?.unknownTools ?? 'deny') === 'allow') {
     const denied = new Set(
       Object.entries(opts?.permissions ?? {})
-        .filter(([, v]) => v === 'deny')
-        .map(([k]) => k),
+        .filter(([, action]) => action === 'deny')
+        .map(([name]) => name),
     );
-    const next = currentActive.filter((t) => !denied.has(t));
-    if (next.length === 0) return null;
-    return { next, changed: next.length !== currentActive.length };
+    return universe.filter((name) => !denied.has(name));
   }
   const wanted = new Set(manifestTools);
-  const next = currentActive.filter((t) => wanted.has(t));
-  if (next.length === 0) return null;
-  const changed = next.length !== currentActive.length;
-  return { next, changed };
+  return universe.filter((name) => wanted.has(name));
 }
 
+/** Null means "keep the current active set": an empty result must never clear every tool (D77). */
+export function planActiveTools(
+  manifestTools: readonly string[],
+  currentActive: readonly string[],
+  opts?: { unknownTools?: UnknownToolStance; permissions?: Record<string, PermissionAction> },
+): { next: string[]; changed: boolean } | null {
+  if (manifestTools.length === 0 || currentActive.length === 0) return null;
+  const next = filterToolsByStance(manifestTools, currentActive, opts);
+  if (next.length === 0) return null;
+  return { next, changed: next.length !== currentActive.length };
+}

package/src/tree-view.ts

@@ -0,0 +1,162 @@
+/**
+ * Unified TUI status surface (RFC docs/rfc-unified-widget.md, D113): the resident widget shows one
+ * line per agent — self plus every running subagent — each reduced to its CURRENT item and a
+ * done/total suffix; the full todo × subagent tree lives behind /pier-tree. Pure builders only.
+ */
+import { formatAge } from './stale-core.ts';
+import { formatTodoSummary, renderTodoGroups } from './todo-window.ts';
+import type { TodoItem } from './vocab.ts';
+
+/** Minimal todo shape carried over the pipe (todo_sync); status matches TodoStatus strings. */
+export interface TodoLikeItem {
+  content: string;
+  status: string;
+  blocker?: string;
+}
+
+/** What the master caches per worker: the pushed full list, or a summary fallback after a resume. */
+export interface WorkerTodoSnapshot {
+  items?: readonly TodoLikeItem[];
+  summary?: string;
+  ts?: number;
+}
+
+/** One running worker row as the widget/tree consumes it. */
+export interface WorkerWidgetRow {
+  paneId: string;
+  slug?: string;
+  description: string;
+  kind?: string;
+  todos?: WorkerTodoSnapshot | null;
+}
+
+/** A settled (delivered) worker row for the tree view only — never in the resident widget. */
+export interface SettledWidgetRow {
+  paneId: string;
+  slug?: string;
+  description: string;
+  settledAt?: number | null;
+}
+
+const CONTENT_CLIP = 60;
+
+function clip(text: string, max = CONTENT_CLIP): string {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+
+function countsOf(items: readonly TodoLikeItem[]): string {
+  const done = items.filter((it) => it.status === 'completed').length;
+  return `✓${done}/${items.length}`;
+}
+
+function currentOf(items: readonly TodoLikeItem[]): TodoLikeItem | undefined {
+  return items.find((it) => it.status === 'in_progress')
+    ?? items.find((it) => it.status === 'blocked')
+    ?? items.find((it) => it.status === 'pending');
+}
+
+/** `↳ <ref> ▶ <current> ✓d/n` — blocked names the waiting TASK (the actionable identity) with the
+ * blocker as a parenthetical reason; a cold cache falls back to the summary token. */
+export function workerLine(row: WorkerWidgetRow): string {
+  const ref = row.slug ?? `${row.paneId} · ${clip(row.description, 30)}`;
+  const items = row.todos?.items;
+  if (items && items.length > 0) {
+    const cur = currentOf(items);
+    const counts = countsOf(items);
+    if (!cur) return `↳ ${ref} ${counts}`;
+    if (cur.status === 'blocked') {
+      const why = cur.blocker && cur.blocker !== cur.content ? `（${clip(cur.blocker, 24)}）` : '';
+      return `↳ ${ref} ■ ${clip(cur.content, 40)}${why} ${counts}`;
+    }
+    return `↳ ${ref} ▶ ${clip(cur.content)} ${counts}`;
+  }
+  const summary = row.todos?.summary;
+  if (summary) return `↳ ${ref} · ${clip(summary, 50)}`;
+  return `↳ ${ref}`;
+}
+
+
+/** Self line: the current item with a done/total suffix — the anchored multi-line window is retired.
+ * A finished plan (no in_progress / blocked / pending item) has no actionable row, so it renders
+ * nothing at all: a bare `✓8/8` is noise that the human cannot act on. */
+export function selfLine(items: readonly TodoItem[]): string | null {
+  if (items.length === 0) return null;
+  const cur = currentOf(items);
+  if (!cur) return null;
+  const counts = countsOf(items);
+  if (cur.status === 'blocked') return `■ 等人: ${clip(cur.blocker || cur.content, 40)} ${counts}`;
+  return `▶ ${clip(cur.content)} ${counts}`;
+}
+
+/** pi caps the resident widget at ten lines; overflow workers fold into a count tail. */
+export const WIDGET_MAX_LINES = 10;
+
+export function unifiedWidgetLines(
+  items: readonly TodoItem[],
+  workers: readonly WorkerWidgetRow[],
+  opts?: { archivedAgeMs?: number | null; blockedDepth?: number | null },
+): string[] {
+  // Human gate open: the question owns the fixed area (unchanged discipline from the old widget).
+  if ((opts?.blockedDepth ?? 0) > 0) {
+    return workers.length === 0 || items.length === 0
+      ? [`${formatTodoSummary(items)} · /todos 全量`]
+      : [`${formatTodoSummary(items)} · ↳×${workers.length} · /todos 全量`];
+  }
+  if (items.length === 0 && workers.length === 0) return [];
+  // Archived plans keep their degraded two-line form; workers stay visible underneath.
+  const self = items.length > 0 ? selfLine(items) : null;
+  const head = opts?.archivedAgeMs != null && items.length > 0
+    ? [`${formatTodoSummary(items)} · archived ${formatAge(opts.archivedAgeMs)}`]
+    : self ? [self] : [];
+  if (head.length === 0 && workers.length === 0) return [];
+  const rows = workers.map(workerLine);
+  const budget = WIDGET_MAX_LINES - head.length - 1;
+  const shown = rows.slice(0, Math.max(budget, 0));
+  const hidden = rows.length - shown.length;
+  return [...head, ...shown, ...(hidden > 0 ? [`…另 ${hidden} 个子代理 · /pier-tree`] : [])];
+}
+
+/** Full delegation tree for /pier-tree: self todos in full + per-worker full lists + settled nodes. */
+export function formatDelegationTree(opts: {
+  selfItems: readonly TodoItem[];
+  workers: readonly WorkerWidgetRow[];
+  settled?: readonly SettledWidgetRow[];
+  now?: number;
+}): string[] {
+  const now = opts.now ?? Date.now();
+  const lines: string[] = ['==================== PIER DELEGATION TREE ===================='];
+  lines.push(`● master（本 pane）· ${opts.selfItems.length} 项`);
+  lines.push(...renderTodoGroups(opts.selfItems).map((l) => `  ${l}`));
+  if (opts.workers.length > 0 || (opts.settled?.length ?? 0) > 0) lines.push('  │');
+  for (const w of opts.workers) {
+    const ref = w.slug ?? w.paneId;
+    const items = w.todos?.items;
+    const headSuffix = items && items.length > 0
+      ? `· ${items.length} 项`
+      : w.todos?.summary ? `· ${clip(w.todos.summary, 40)}` : '· todo 未同步';
+    lines.push(`  ├─ ↳ ${ref} (${w.paneId} · running${w.kind && w.kind !== 'task' ? ` · ${w.kind}` : ''}) ${headSuffix}`);
+    if (items && items.length > 0) {
+      lines.push(...renderTodoGroups(toTodoItems(items)).map((l) => `  │    ${l}`));
+    }
+  }
+  for (const s of opts.settled ?? []) {
+    const ref = s.slug ?? s.paneId;
+    const age = s.settledAt ? ` · settled ${formatAge(Math.max(now - s.settledAt, 0))} ago` : ' · settled';
+    lines.push(`  └─ ✓ ${ref} (${s.paneId}${age}) — 结果已注入结算通知`);
+  }
+  lines.push('----------------------------------------------------------------');
+  lines.push('提示: /todos 编辑自己的清单 · subagent list 交互子代理 · /dashboard ops 面板');
+  return lines;
+}
+
+/** Narrow a pipe-pushed item list back to TodoItem for the shared group renderer. */
+function toTodoItems(items: readonly TodoLikeItem[]): TodoItem[] {
+  return items.map((it) => ({
+    content: it.content,
+    status: (['pending', 'in_progress', 'blocked', 'completed', 'abandoned'].includes(it.status)
+      ? it.status
+      : 'pending') as TodoItem['status'],
+    ...(it.blocker ? { blocker: it.blocker } : {}),
+  }));
+}

package/src/vocab.ts

@@ -1,20 +1,17 @@
 /**
- * pi-herdr bridge vocabulary (M22: title is the board).
- *
- * DESIGN.md §4.2: no new transport. Wire = herdr NDJSON; todo authority = pi
- * session JSONL; display = pane.report_metadata title / state_labels.
+ * pi-herdr bridge vocabulary. DESIGN.md §4.2: no new transport — wire = herdr NDJSON, todo authority
+ * = pi session JSONL, display = pane.report_metadata title / state_labels.
  */
 
-/** Todo five-state (D34: three-state + blocked/abandoned, aligned with OMP). */
+/** Five states (D34): three-state + blocked/abandoned, aligned with OMP. */
 export type TodoStatus = 'pending' | 'in_progress' | 'completed' | 'blocked' | 'abandoned';
 
 export const TODO_STATUSES: readonly TodoStatus[] = ['pending', 'in_progress', 'completed', 'blocked', 'abandoned'];
 
-/** Todo item: content + status; optional blocker (blocked only) and phase (D43). No stable id (last-write-wins). */
+/** Todo item: content + status; blocker only when blocked; optional phase groups (D43). No id (last-write-wins). */
 export interface TodoItem {
   content: string;
   status: TodoStatus;
-  /** Non-empty string only when status==='blocked' (D34). */
   blocker?: string;
   /** Optional group name (D43); non-empty, ≤30 chars. */
   phase?: string;
@@ -27,58 +24,88 @@ export interface TodoSnapshot {
   items: TodoItem[];
 }
 
-/** Snapshot counts (confirmation copy and title projection). */
 export interface TodoCounts {
   pending: number;
   inProgress: number;
   completed: number;
-  /** D91: blocked as its own column (title quartet ▶○■✓). */
+  /** D91: blocked is its own column (title quartet ▶○■✓). */
   blocked: number;
 }
 
 /** Source name for pane.report-agent. */
 export const REPORT_AGENT_SOURCE = 'pi-herdr';
 
-/** First-upgrade key used to clear the old 16-key chunked tokens (M13b leftover). */
+/** First-upgrade key used to clear the old 16-key chunked tokens (M13b). */
 export const PI_HERDR_META_KEY = 'pi-herdr';
 
-/** Model-facing todo tool name (DSH-compatible). */
 export const TODO_TOOL_NAME = 'todo_write';
 
 /** Snapshot key in tool-result details (persisted in session JSONL). */
 export const TODO_DETAILS_KEY = 'pi-herdr.todo';
 
-/** Confirmation copy (byte-aligned with DSH so model vocab transfers; blocked is appended only when present). */
+/** Confirmation copy (byte-aligned with DSH so model vocab transfers). */
 export function formatTodoConfirmation(items: readonly TodoItem[]): string {
   const c = countTodos(items);
   const base = `Updated todo list: ${c.pending} pending, ${c.inProgress} in progress, ${c.completed} completed.`;
-  // A4: blocked items used to be invisible here (the model read "nothing pending" while items sat
-  // blocked waiting on a human). Appending only when non-zero keeps the DSH-aligned wording intact.
+  // Append blocked only when non-zero — the model must not read "nothing pending" while items sit
+  // blocked on a human. Zero keeps the DSH-aligned wording intact.
   return c.blocked > 0 ? `${base.slice(0, -1)}, ${c.blocked} blocked.` : base;
 }
 
+/** Every status the todo model knows; anything else in a snapshot is corrupt data (D34). */
+const STATUS_LOOKUP: Readonly<Record<TodoStatus, true>> = {
+  pending: true,
+  in_progress: true,
+  completed: true,
+  blocked: true,
+  abandoned: true,
+};
+
+/**
+ * Corrupt snapshots carry arbitrary JSON as `status` (`extractSnapshotFromDetails` does not validate),
+ * so every table lookup keyed by status must pass through this first — `TODO_MARKS['constructor']`
+ * would otherwise render a function, and `groups['constructor'].push` would throw.
+ */
+export const isTodoStatus = (value: unknown): value is TodoStatus =>
+  typeof value === 'string' && Object.hasOwn(STATUS_LOOKUP, value);
+
+const COUNTED_STATUSES = {
+  pending: 'pending',
+  in_progress: 'inProgress',
+  completed: 'completed',
+  blocked: 'blocked',
+} as const satisfies Partial<Record<TodoStatus, keyof TodoCounts>>;
+
+/** The four states that occupy a count column (`abandoned` is terminal and deliberately uncounted). */
+const isCountedStatus = (status: TodoStatus): status is keyof typeof COUNTED_STATUSES =>
+  Object.hasOwn(COUNTED_STATUSES, status);
+
 export function countTodos(items: readonly TodoItem[]): TodoCounts {
-  let pending = 0;
-  let inProgress = 0;
-  let completed = 0;
-  let blocked = 0;
+  const counts: TodoCounts = { pending: 0, inProgress: 0, completed: 0, blocked: 0 };
   for (const it of items) {
-    if (it.status === 'pending') pending++;
-    else if (it.status === 'in_progress') inProgress++;
-    else if (it.status === 'completed') completed++;
-    else if (it.status === 'blocked') blocked++;
-    // abandoned is omitted (D34); blocked is its own column (D91)
+    const status = it?.status;
+    if (isTodoStatus(status) && isCountedStatus(status)) counts[COUNTED_STATUSES[status]] += 1;
   }
-  return { pending, inProgress, completed, blocked };
+  return counts;
 }
 
+/** Why a settlement carried no closing text (p24-class mis-attribution vs a truly silent worker). */
+export type SettlementNullReason = 'silent' | 'attribution-suspect' | 'extraction-failed';
+
+const NULL_CLOSING_SENTENCE: Record<SettlementNullReason, string> = {
+  'attribution-suspect': 'Its closing message could NOT be read — the session attribution is suspect (a wrong transcript may have been read). Check `subagent action output` / the ledger sessionFile before assuming it produced nothing; its work may be complete.',
+  'extraction-failed': 'It appears to have ended with a final report, but the closing text could not be extracted — read it from the session transcript.',
+  silent: 'It left no closing message.',
+};
+
 /** Subagent settlement notice (aligned with DSH). */
 export function formatSettlementNotice(
   agentId: string,
   closingMessage: string | null,
+  nullReason: SettlementNullReason = 'silent',
 ): string {
   const head = `Background subagent ${agentId} finished and will do no further work unless you send it more.`;
   return closingMessage
     ? `${head} Its closing message: ${closingMessage}`
-    : `${head} It left no closing message.`;
+    : `${head} ${NULL_CLOSING_SENTENCE[nullReason]}`;
 }

package/src/worker-marker.ts

@@ -0,0 +1,76 @@
+/**
+ * Worker identity marker: a herdr 0.9.2 server restart reopens a worker pane by running pier's
+ * self-reported resume_argv — WITHOUT the spawn env (`PI_HERDR_SUBAGENT`, role manifest env). The
+ * marker file lets the restored boot re-derive worker mode from the session itself, so it mounts
+ * todo-only instead of the master composition (no subagent pipe, no stop reminders) and replays its
+ * role from the transcript as usual. Masters never write a marker; a stale marker for a dead session
+ * is inert (it is only consulted when pi boots with that exact session file).
+ */
+import type { DelegationContext } from './delegation-core.ts';
+import { delegationFromRecord } from './delegation-core.ts';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { bareSessionId } from './session-tail.ts';
+import { isValidSessionId } from './efficiency-store.ts';
+
+export interface WorkerMarker {
+  readonly v: 1;
+  readonly ts: number;
+  readonly role?: string;
+  readonly delegation?: DelegationContext;
+}
+
+/** `<sessionDir>/herdr-pi/<sessionId>/worker.json` — same per-session root as the efficiency store. */
+export function workerMarkerPath(sessionFile: string | null | undefined): string | null {
+  if (!sessionFile || typeof sessionFile !== 'string') return null;
+  const id = bareSessionId(sessionFile);
+  if (!isValidSessionId(id)) return null;
+  return join(dirname(sessionFile), 'herdr-pi', id, 'worker.json');
+}
+
+export function readWorkerMarker(sessionFile: string | null | undefined): WorkerMarker | null {
+  const file = workerMarkerPath(sessionFile);
+  if (!file) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8')) as { v?: unknown; ts?: unknown; role?: unknown; delegation?: unknown };
+    if (parsed && parsed.v === 1 && typeof parsed.ts === 'number') {
+      const delegation = delegationFromRecord(parsed.delegation);
+      return {
+        v: 1,
+        ts: parsed.ts,
+        ...(typeof parsed.role === 'string' ? { role: parsed.role } : {}),
+        ...(delegation ? { delegation } : {}),
+      };
+    }
+  } catch {
+    /* missing or torn write: no marker → boot stays env-driven */
+  }
+  return null;
+}
+
+/** Idempotent; best-effort — a failed write only loses server-restart worker detection. */
+export function writeWorkerMarker(
+  sessionFile: string | null | undefined,
+  role?: string,
+  delegation?: DelegationContext,
+): void {
+  const file = workerMarkerPath(sessionFile);
+  if (!file) return;
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify({
+      v: 1,
+      ts: Date.now(),
+      ...(role ? { role } : {}),
+      ...(delegation ? { delegation } : {}),
+    })}\n`);
+  } catch {
+    /* read-only checkout or full disk: the live session is unaffected */
+  }
+}
+
+/** Boot-time probe over env.PI_SESSION_FILE; false negatives simply keep today's behavior. */
+export function hasWorkerMarker(sessionFile: string | null | undefined): boolean {
+  const file = workerMarkerPath(sessionFile);
+  return file !== null && existsSync(file);
+}