pi-pier 0.3.1 → 0.4.2

package/src/todo-read-hook.ts

@@ -1,18 +1,41 @@
 /**
  * Plan the todo read hook (before_agent_start + display:false). Stale-core keeps a fully completed list
  * from being recited forever: stale (turn-based) warns with the old entries as rewrite references,
- * rate-limited and capped; archived (wall-clock) treats the list as absent, sharing the guard cadence
- * with empty lists.
+ * rate-limited and capped; archived (wall-clock) treats the list as absent — one rewrite window (its
+ * offer persisted per list identity so a resume skips it), then the terminal clear on the next run.
  */
 import { boundedView, currentActivity, type TodoItem } from './todo-core.ts';
 import { countTodos } from './vocab.ts';
 import { STALE_NOTICE_MAX, evaluateStaleness, formatAge } from './stale-core.ts';
-import { todoMark } from './todo-window.ts';
+import { todoLine } from './todo-window.ts';
 
-/** Cadence shared by empty-list guards, stale warnings, and archive notices. */
+/** Cadence shared by empty-list guards, stale warnings, and the archive rewrite window. */
 const EMPTY_GUARD_EVERY_N = 4;
 const TODO_READ_CUSTOM_TYPE = 'pi-herdr.todo-read';
 
+/**
+ * pi 1.2 fires `before_agent_start` for runs started by `sendMessage(..., { triggerTurn: true })`
+ * too. The todo hook wants the plan in every *user* run and after a compaction continuation (the
+ * model needs the plan to resume), but not in its own stop reminder or the config guide: those
+ * already carry their own text, and counting them as turns would advance the guard cadence.
+ * Keep this list in sync with COMPACTION_CONTINUE_TYPE in compact-coordinator.ts.
+ */
+export const TODO_READ_CUSTOM_TYPES: readonly string[] = ['pi-herdr.compaction-continue'];
+
+/** Whether this run should receive the todo read hook. Missing `messageType` is pi < 1.2, where
+ *  only user runs fired `before_agent_start`; treat it as a user run for compatibility. */
+export function shouldRunTodoRead(event: unknown): boolean {
+  if (event === null || typeof event !== 'object' || !('messageType' in event)) return true;
+  const messageType = (event as { messageType?: unknown }).messageType;
+  if (messageType === 'user') return true;
+  if (messageType !== 'custom') return false;
+  const message = (event as { message?: unknown }).message;
+  const customType = message !== null && typeof message === 'object' && 'customType' in message
+    ? (message as { customType?: unknown }).customType
+    : undefined;
+  return typeof customType === 'string' && TODO_READ_CUSTOM_TYPES.includes(customType);
+}
+
 type TodoReadEffect =
   | 'recite' // Recite normally while the list is fresh.
   | 'empty-guard' // Guard against an empty list.
@@ -28,6 +51,8 @@ interface TodoReadPlan {
   /** Clear the in-memory list when injecting the archive notice (the caller persists the empty JSONL);
    * a kept dead list would suppress the empty guard that resumes tracking after an idle gap. */
   clearArchived: boolean;
+  /** This injection is the one-window rewrite offer; the caller persists the marker so a resume skips it. */
+  offerArchiveWindow: boolean;
   message: {
     customType: string;
     content: string;
@@ -45,6 +70,9 @@ export function planTodoReadHook(opts: {
   now: number;
   staleNotices: number;
   lastStaleGuardTurn: number | null;
+  /** Whether the near-archive rewrite window was already offered for this exact list (in-process or
+   *  folded from the persisted marker). The terminal clear no longer waits for the shared cadence. */
+  archiveWindowOffered: boolean;
 }): TodoReadPlan {
   const msg = (content: string) => ({
     customType: TODO_READ_CUSTOM_TYPE,
@@ -60,6 +88,7 @@ export function planTodoReadHook(opts: {
       effect: 'empty-guard',
       clearArchived: false,
       archived: false,
+      offerArchiveWindow: false,
       message: msg(
         guardDue
           ? 'Your todo list is empty. If the current work needs tracking, call todo_write before stopping.'
@@ -79,30 +108,36 @@ export function planTodoReadHook(opts: {
     const c = countTodos(opts.items);
     const age = st.ageMs == null ? '' : ` ${formatAge(st.ageMs)} ago`;
     // Idle periods do not consume turns, so give one rewrite window with the old entries as reference
-    // before the terminal notice.
-    if (opts.staleNotices === 0 && guardDue) {
-      const lines = opts.items.map((it) => `  ${todoMark(it.status)} ${it.content}`);
+    // before the terminal notice. The offer is keyed to the list identity and persisted (in-process it
+    // rides TodosService.archiveWindowOffered), so a resumed session goes straight to the clear.
+    if (!opts.archiveWindowOffered) {
+      if (!guardDue) {
+        return { inject: false, effect: 'none', archived: true, clearArchived: false, offerArchiveWindow: false, message: msg('') };
+      }
+      const lines = opts.items.map((it) => `  ${todoLine(it)}`);
       const head = `todos ✓${c.completed} (all completed, last updated${age}) — about to be archived`;
-      const warn = 'One rewrite window before archiving: if the work you are doing now is multi-step, rewrite the full list with todo_write to track it (old entries below as reference — reuse what still applies). Single-step Q&A may skip tracking. If the list stays untouched, it will be archived and cleared on the next reminder.';
+      const warn = 'One rewrite window before archiving: if the work you are doing now is multi-step, rewrite the full list with todo_write to track it (old entries below as reference — reuse what still applies). Single-step Q&A may skip tracking. If the list stays untouched, it will be archived and cleared on your next message.';
       return {
         inject: true,
         effect: 'stale-notice',
         archived: true,
         clearArchived: false,
+        offerArchiveWindow: true,
         message: msg([head, ...lines, warn].join('\n')),
       };
     }
     // The terminal notice carries no details and no "skip tracking" escape hatch — multi-step work
-    // must get a fresh list, single-step Q&A may proceed untracked.
+    // must get a fresh list, single-step Q&A may proceed untracked. It fires on the very next run:
+    // the near-archive already consumed the shared cadence tick, and waiting 4 more runs leaves the
+    // dead list authoritative with no todo guidance at all.
     return {
-      inject: guardDue,
+      inject: true,
       effect: 'archive-notice',
       archived: true,
-      clearArchived: guardDue,
+      clearArchived: true,
+      offerArchiveWindow: false,
       message: msg(
-        guardDue
-          ? `Your previous todo list (${c.completed} completed entries, last updated${age}) has been archived and cleared from tracking; the list is now empty. If the current work is multi-step, call todo_write with a fresh list now — multi-step work must be tracked. Single-step answers may proceed without a list.`
-          : '',
+        `Your previous todo list (${c.completed} completed entries, last updated${age}) has been archived and cleared from tracking; the list is now empty. If the current work is multi-step, call todo_write with a fresh list now — multi-step work must be tracked. Single-step answers may proceed without a list.`,
       ),
     };
   }
@@ -111,18 +146,19 @@ export function planTodoReadHook(opts: {
     const staleDue = opts.lastStaleGuardTurn == null
       || opts.turn - opts.lastStaleGuardTurn >= EMPTY_GUARD_EVERY_N;
     if (!staleDue || opts.staleNotices >= STALE_NOTICE_MAX) {
-      return { inject: false, effect: 'none', archived: false, clearArchived: false, message: msg('') };
+      return { inject: false, effect: 'none', archived: false, clearArchived: false, offerArchiveWindow: false, message: msg('') };
     }
     const c = countTodos(opts.items);
     const head = `todos ▶${c.inProgress} ○${c.pending} ■${c.blocked} ✓${c.completed}`
       + ` · unchanged for ${opts.turnsSinceWrite} turns, nothing open`;
-    const lines = opts.items.map((it) => `  ${todoMark(it.status)} ${it.content}`);
+    const lines = opts.items.map((it) => `  ${todoLine(it)}`);
     const warn = 'This list no longer reflects the work you are doing. Rewrite the full list with todo_write to match current work, or send [] to clear it.';
     return {
       inject: true,
       effect: 'stale-notice',
       clearArchived: false,
       archived: false,
+      offerArchiveWindow: false,
       message: msg([head, ...lines, warn].join('\n')),
     };
   }
@@ -130,7 +166,7 @@ export function planTodoReadHook(opts: {
   // Fresh lists are recited every turn to keep current work visible.
   const c = countTodos(opts.items);
   const view = boundedView(opts.items, 6);
-  const lines = view.visible.map((it) => `${todoMark(it.status)} ${it.content}`);
+  const lines = view.visible.map((it) => todoLine(it));
   const activity = currentActivity(opts.items);
   const head = `todos ▶${c.inProgress} ○${c.pending} ■${c.blocked} ✓${c.completed}`
     + (activity ? ` · ${activity}` : '');
@@ -139,6 +175,7 @@ export function planTodoReadHook(opts: {
     effect: 'recite',
     clearArchived: false,
     archived: false,
+    offerArchiveWindow: false,
     message: msg([head, ...lines].join('\n')),
   };
 }

package/src/todo-reminder-core.ts

@@ -1,10 +1,10 @@
 /**
  * Reminders about unfinished todos when stopping go out as sendMessage(custom) and ask for
  * reconciliation rather than continuation, so human-blocked items are a first-class outcome. Guards:
- * suppress on abort, cap reminders, skip while a subagent runs, a human gate is blocked, or no open
- * item remains.
+ * suppress on abort or provider error, cap reminders, skip while a subagent runs, a human gate is
+ * blocked, or no open item remains.
  */
-import { ABORT_STOP_REASON } from './settle-wake-core.ts';
+import { ABORT_STOP_REASON, ERROR_STOP_REASON } from './settle-wake-core.ts';
 import { pierOption } from './pier-options.ts';
 
 /** Cap reminders for the lifetime of the process. */
@@ -25,6 +25,8 @@ export function todoReminderGraceMs(): number {
 interface TodoReminderInput {
   /** Stop reason of the last assistant turn (null = natural completion). */
   lastStopReason: string | null;
+  /** agent_settled.aborted: authoritative for ESC mid-tool, where no final assistant message set the reason. */
+  aborted?: boolean;
   intentionalAbort?: boolean;
   compactionInFlight?: boolean;
   reminders: number;
@@ -48,8 +50,10 @@ interface TodoReminderPlan {
  */
 export function planStopTodoReminder(input: TodoReminderInput): TodoReminderPlan {
   const noInject: TodoReminderPlan = { due: false, content: null, nextReminders: input.reminders };
-  if (input.intentionalAbort || input.compactionInFlight) return noInject;
-  if (input.lastStopReason === ABORT_STOP_REASON) return noInject;
+  if (input.intentionalAbort || input.compactionInFlight || input.aborted) return noInject;
+  // An error stop is an upstream/provider failure that pi retries; the reminder's triggerTurn would
+  // fire another request into the failing window (observed: 3 reminders during one outage).
+  if (input.lastStopReason === ABORT_STOP_REASON || input.lastStopReason === ERROR_STOP_REASON) return noInject;
   if (input.reminders >= REMINDERS_MAX) return noInject;
   if (input.runningSubs > 0) return noInject;
   if (input.blockedDepth > 0) return noInject;

package/src/todo-window.ts

@@ -20,6 +20,13 @@ export function formatTodoSummary(items: readonly TodoItem[]): string {
   return `todo: ${c.inProgress}▶ ${c.pending}○ ${c.blocked}■ ${c.completed}✓`;
 }
 
+/** One item line shared by the widget/tree renderer and the read-hook recitation: the blocker text is
+ *  part of the item (D43), not a widget-only decoration, so a resumed model keeps the reason. */
+export function todoLine(it: TodoItem): string {
+  const suffix = it.status === 'blocked' && it.blocker ? ` — ${it.blocker}` : '';
+  return `${todoMark(it.status)} ${it.content}${suffix}`;
+}
+
 /** Shared phase rendering so widget and overlay order entries identically. */
 export function renderTodoGroups(items: readonly TodoItem[]): string[] {
   const groups = new Map<string, TodoItem[]>();
@@ -32,10 +39,7 @@ export function renderTodoGroups(items: readonly TodoItem[]): string[] {
   const lines: string[] = [];
   for (const [phase, list] of groups) {
     if (phase) lines.push(`  [${phase}]`);
-    for (const it of list) {
-      const suffix = it.status === 'blocked' && it.blocker ? ` — ${it.blocker}` : '';
-      lines.push(`  ${todoMark(it.status)} ${it.content}${suffix}`);
-    }
+    for (const it of list) lines.push(`  ${todoLine(it)}`);
   }
   return lines;
 }

package/src/todos-service.ts

@@ -18,6 +18,15 @@ export class TodosService extends EventEmitter {
   }
   /** Clock anchor for staleness/archiving; null until the first write. */
   lastWriteAt: number | null = null;
+  /** True when the anti-freeze rewrite window was offered for the current list (reached through the
+   *  persisted marker on rebuild, so a resumed session skips straight to the terminal clear). */
+  private _archiveWindowOffered = false;
+  get archiveWindowOffered(): boolean {
+    return this._archiveWindowOffered;
+  }
+  markArchiveWindowOffered(): void {
+    this._archiveWindowOffered = true;
+  }
   readonly config: TodosConfig;
 
   constructor(config: TodosConfig) {
@@ -40,6 +49,7 @@ export class TodosService extends EventEmitter {
     if (listsEqual(this._items, next)) return { changed: false };
     const before = this._items;
     this._items = next;
+    this._archiveWindowOffered = false;
     this.lastWriteAt = Date.now();
     this.emitCompletedTransitions(before, this._items, opts?.source ?? 'tool');
     this.emit('todo.updated', { items: this._items });
@@ -51,6 +61,7 @@ export class TodosService extends EventEmitter {
     const next = applyTodoEdits(this._items, edits);
     if (listsEqual(before, next)) return { changed: false };
     this._items = next;
+    this._archiveWindowOffered = false;
     this.lastWriteAt = Date.now();
     this.emitCompletedTransitions(before, this._items, opts?.source ?? 'reconcile');
     this.emit('todo.edited', { edits, items: this._items });
@@ -74,6 +85,7 @@ export class TodosService extends EventEmitter {
     const folded = foldLatestTodosMeta(entries as Parameters<typeof foldLatestTodosMeta>[0]);
     this._items = folded ? folded.items : [];
     this.lastWriteAt = folded ? folded.writtenAt : null;
+    this._archiveWindowOffered = folded ? folded.archiveWindowOffered : false;
     this.emit('todo.updated', { items: this._items, reason: 'rebuild' });
   }
 }

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

@@ -98,13 +98,19 @@ const NULL_CLOSING_SENTENCE: Record<SettlementNullReason, string> = {
   silent: 'It left no closing message.',
 };
 
-/** Subagent settlement notice (aligned with DSH). */
+/** Subagent settlement notice (aligned with DSH). `reportDeliveredAt`: the master already received
+ *  this exact closing message through `subagent output`, so the notice points there instead. */
 export function formatSettlementNotice(
   agentId: string,
   closingMessage: string | null,
   nullReason: SettlementNullReason = 'silent',
+  reportDeliveredAt: number | null = null,
 ): string {
   const head = `Background subagent ${agentId} finished and will do no further work unless you send it more.`;
+  if (closingMessage && reportDeliveredAt !== null) {
+    const at = new Date(reportDeliveredAt).toTimeString().slice(0, 8);
+    return `${head} Its closing message is the report subagent(action:"output") already returned at ${at}; it is not repeated here.`;
+  }
   return closingMessage
     ? `${head} Its closing message: ${closingMessage}`
     : `${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);
+}