pi-daddy 0.27.4 → 0.32.0

package/src/executors/activity-session.ts

@@ -0,0 +1,54 @@
+/**
+ * The activity session: a pi session file every governed child writes to, so its parent can tell working from hung.
+ *
+ * PR 3e (ADR-0038 note). A `pi --print` child gives its parent nothing on stdout until it exits, so a wall clock
+ * cannot tell a build from a hang. pi's SessionManager appends one line to its session file for every message and
+ * tool result as they happen (read from pi's `session-manager.js`: `appendFileSync` per entry), so the file's size
+ * and mtime are a progress signal that costs the child nothing and needs no output-format change. When the plan
+ * already carries `--session` (native-session retention), that file is the probe; otherwise a private temporary
+ * file is allocated for the run and removed afterwards.
+ */
+import { mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface ActivitySession {
+  /** The child argv, with `--session <file>` in place of `--no-session` when a file was allocated here. */
+  readonly args: string[];
+  /** The session file being watched. */
+  readonly path: string;
+  /** A marker that changes whenever pi appended to the file; `undefined` until the file exists. */
+  probe(): Promise<string | undefined>;
+  /** Remove the temporary file, if this run allocated one. Never removes a retention target. */
+  dispose(): Promise<void>;
+}
+
+export async function activitySessionFor(planArgs: string[], executionId: string): Promise<ActivitySession> {
+  const flag = planArgs.indexOf("--session");
+  const probeFor = (path: string) => async () => {
+    try {
+      const s = await stat(path);
+      return `${s.size}:${s.mtimeMs}`;
+    } catch {
+      return undefined;
+    }
+  };
+  if (flag >= 0 && planArgs[flag + 1]) {
+    const path = planArgs[flag + 1];
+    return { args: planArgs, path, probe: probeFor(path), dispose: async () => undefined };
+  }
+  // Private to this uid (mkdtemp is 0o700) and named by the execution so a leaked directory is attributable.
+  const directory = await mkdtemp(join(tmpdir(), `pi-daddy-${executionId.replace(/[^a-zA-Z0-9_-]/g, "_")}-`));
+  const path = join(directory, "session.jsonl");
+  const noSession = planArgs.indexOf("--no-session");
+  const args =
+    noSession >= 0
+      ? [...planArgs.slice(0, noSession), "--session", path, ...planArgs.slice(noSession + 1)]
+      : [...planArgs.slice(0, -1), "--session", path, planArgs[planArgs.length - 1]];
+  return {
+    args,
+    path,
+    probe: probeFor(path),
+    dispose: () => rm(directory, { recursive: true, force: true }).catch(() => undefined),
+  };
+}

package/src/executors/executor.ts

@@ -0,0 +1,123 @@
+/**
+ * Which executor runs a governed child — ADR-0031.
+ *
+ * `PI_DADDY_HERDR` is three-state, and **absent means probe**. That reverses ADR-0016 point 6's opt-in, and
+ * the reversal is narrower than it sounds: nothing is detected from `herdr` being on `PATH` (option C, rejected
+ * by name), only from a server that *answered*. The grant, the depth bound, the gate and `--tools` enforcement
+ * are identical either way — `planSpawn` produces one plan and both executors enforce it.
+ *
+ * **Pure on purpose.** The probe is I/O and lives in `herdr-cli.ts`; the DECISION is a table, and a table that
+ * fits on one screen is the only reason a reversal like this is reviewable at all.
+ *
+ * The disclosure string is part of the return value rather than composed at the call site, because ADR-0031's
+ * defence against "this relocates silently" is that every outcome says what it chose AND what to set instead.
+ * Two call sites composing that separately is how one of them comes to omit it (R-28).
+ */
+
+import type { HerdrProbe } from "./herdr-cli.ts";
+
+export { EXECUTOR_KINDS, type ExecutorKind } from "../kernel/delegate-types.ts";
+import type { ExecutorKind } from "../kernel/delegate-types.ts";
+import { ENV_HERDR } from "../kernel/env-names.ts";
+export { ENV_HERDR } from "../kernel/env-names.ts";
+
+export interface ExecutorChoice {
+  kind: ExecutorKind;
+  /** The operator named it: `PI_DADDY_HERDR` was exactly `0` or `1`. */
+  forced: boolean;
+  /** Whether a probe was needed at all — false only for `0`. */
+  probed: boolean;
+  /**
+   * Set ONLY when herdr was demanded and is unreachable. Every delegation must refuse with this.
+   *
+   * Note that `kind` stays `"herdr"` in that case, deliberately: nothing downstream may mistake a refusing
+   * session for a working process-executor one.
+   */
+  refusal?: string;
+  /** One line for the session banner and `/grants`. Always present. */
+  disclosure: string;
+}
+
+/** `0` is the one value that needs no probe: the operator ruled herdr out, so asking is pure cost. */
+export function needsProbe(raw: string | undefined): boolean {
+  return raw === undefined || raw === "1";
+}
+
+export function chooseExecutor(raw: string | undefined, probe: HerdrProbe | null): ExecutorChoice {
+  if (raw === "0") {
+    return {
+      kind: "process",
+      forced: true,
+      probed: false,
+      disclosure: "captured subprocess (PI_DADDY_HERDR=0) — children have no terminal",
+    };
+  }
+
+  if (raw === "1") {
+    if (probe?.ok) {
+      return { kind: "herdr", forced: true, probed: true, disclosure: "herdr panes (PI_DADDY_HERDR=1)" };
+    }
+    // Refusal, not fallback — the operator's decision of 2026-08-17, against the alternative of falling back
+    // loudly. A fallback nobody reads is R-25's shape; refusing keeps the ledger unable to name a child that
+    // ran somewhere nobody chose. A `null` probe lands here too: if the probe failed so badly it produced no
+    // result, herdr was still demanded, and failing closed means refusing.
+    const why = probe?.error ?? "the herdr probe did not succeed";
+    return {
+      kind: "herdr",
+      forced: true,
+      probed: true,
+      refusal:
+        `PI_DADDY_HERDR=1 demands the herdr executor and herdr is not answering (${why}). ` +
+        `Delegation is refused rather than quietly relocated to a captured subprocess, so this session's ` +
+        `ledger can never contain a child that ran somewhere nobody chose. Start herdr, or unset ` +
+        `PI_DADDY_HERDR to let this session probe, or set PI_DADDY_HERDR=0 to choose subprocesses.`,
+      disclosure: `herdr panes DEMANDED but unreachable (${why}) — every delegation will refuse`,
+    };
+  }
+
+  if (raw !== undefined) {
+    // Rule 8: fail closed and be loud. An unrecognised value must not relocate a run, and must not break
+    // delegation either — the operator meant *something*, and the dependency-free executor is the safe read.
+    // The empty string lands here rather than with `undefined`, which keeps absent-versus-empty
+    // distinguishable exactly as `PI_DADDY_GATED` does.
+    return {
+      kind: "process",
+      forced: false,
+      probed: probe !== null,
+      disclosure:
+        `captured subprocess — PI_DADDY_HERDR is set to an unrecognised value and was ignored. ` +
+        `Use 1 (demand herdr panes), 0 (demand subprocesses), or unset it to probe.`,
+    };
+  }
+
+  if (probe?.ok) {
+    return { kind: "herdr", forced: false, probed: true, disclosure: "herdr panes (probed — herdr is answering)" };
+  }
+  if (probe === null) {
+    // **The pre-probe seed, and it must not claim a probe happened.** `createGrantsSession` builds a choice
+    // synchronously with `probe: null` because S-5 forces the factory to run before any hook; `resolveExecutor`
+    // replaces it during `session_start`. This branch previously fell through to the one below and reported
+    // `probed: true` with the word "(probed)" in its disclosure — a fabricated observation, indistinguishable
+    // from a real negative probe.
+    //
+    // Unreachable in practice today (pi awaits the `session_start` emit before the first prompt, verified by a
+    // reviewer against real pi), which is exactly why it is worth making honest rather than leaving to be
+    // discovered: if a throw ever strands a session on this reading, the disclosure should say so.
+    return {
+      kind: "process",
+      forced: false,
+      probed: false,
+      disclosure: "not yet probed — settling at session start",
+    };
+  }
+  return {
+    kind: "process",
+    forced: false,
+    probed: true,
+    // Names the remedy on the same line as the state. The gap that produced ADR-0031 was not that the
+    // operator could not see which executor ran — it was that seeing it would not have told them what to do.
+    disclosure:
+      `captured subprocess (probed — no herdr answering${probe?.error ? `: ${probe.error}` : ""}). ` +
+      `Set PI_DADDY_HERDR=1 to demand panes.`,
+  };
+}

package/src/executors/herdr-cli.ts

@@ -0,0 +1,132 @@
+/**
+ * Talking to herdr: one command, one JSON envelope, plus the two questions ADR-0031 needs answered.
+ *
+ * Lifted out of `src/executors/run-herdr.ts`, which was at 357 of the 400-line ceiling and gains output polling under
+ * ADR-0032. But the split is not only about lines: **the probe is not an executor concern**. It runs at session
+ * start, before any delegation exists, to decide *which* executor a session will use — so leaving it inside the
+ * herdr executor would mean the session imported the thing it was deciding whether to use.
+ *
+ * Every rule here is tested against an injected `exec`, so the suite stays fast, pi-free and herdr-free. The
+ * facts the fakes reproduce were measured against real herdr 0.7.5 (`docs/probes/g16-herdr`).
+ */
+
+import { execFile } from "node:child_process";
+import { ENV_HERDR_WORKSPACE } from "../kernel/env-names.ts";
+export { ENV_HERDR_WORKSPACE } from "../kernel/env-names.ts";
+
+/** One herdr CLI invocation. Injectable so every rule below is testable without herdr installed. */
+export type HerdrExec = (args: string[]) => Promise<{ code: number | null; stdout: string; stderr: string }>;
+
+export const defaultExec: HerdrExec = (args) =>
+  new Promise((settle) => {
+    execFile("herdr", args, { maxBuffer: 32 * 1024 * 1024 }, (error, stdout, stderr) => {
+      const raw = (error as { code?: unknown } | null)?.code;
+      const code = typeof raw === "number" ? raw : error ? 1 : 0;
+      // **A string `code` is a spawn failure, and it used to be thrown away.** `ENOENT` — herdr not installed —
+      // arrives as `code: "ENOENT"`, so the numeric test failed, the message was dropped, and an operator with
+      // `PI_DADDY_HERDR=1` on a machine without herdr was told *"herdr is not answering (unparseable herdr
+      // reply: (no output))"* rather than that the binary is missing. Rule 8 wants the loud version, and this is
+      // the first diagnostic such an operator meets.
+      const spawnFailure = typeof raw === "string" ? `herdr could not be run (${raw}): ${error?.message ?? ""}` : "";
+      settle({ code, stdout: String(stdout), stderr: spawnFailure || String(stderr) });
+    });
+  });
+
+/**
+ * Parse herdr's JSON envelope. Every command replies `{id, result}` or `{id, error:{code,message}}`.
+ *
+ * `stderr` is folded into the message because the first end-to-end run failed with an EMPTY stdout and the
+ * real reason on stderr, producing the useless diagnostic "unparseable herdr reply: ". A wrapper that
+ * hides the substrate's own error message costs more time than it saves.
+ */
+export function parseReply(reply: { stdout: string; stderr: string }): {
+  result?: Record<string, unknown>;
+  error?: string;
+} {
+  try {
+    const parsed = JSON.parse(reply.stdout) as {
+      result?: Record<string, unknown>;
+      error?: { message?: string; code?: string };
+    };
+    if (parsed.error) return { error: parsed.error.message ?? parsed.error.code ?? "herdr reported an error" };
+    return { result: parsed.result };
+  } catch {
+    // A non-JSON reply is a herdr-version or PATH problem, not a governance decision. Surfaced as a spawn
+    // error so the caller reports "could not start" rather than "the child produced nothing".
+    const detail = [reply.stdout.trim(), reply.stderr.trim()].filter((t) => t.length > 0).join(" | ");
+    return { error: `unparseable herdr reply: ${detail.slice(0, 300) || "(no output)"}` };
+  }
+}
+
+/** Bound on the session-start probe. Short: it sits in front of the operator's first prompt. */
+export const PROBE_TIMEOUT_MS = 2000;
+
+export interface HerdrProbe {
+  ok: boolean;
+  /** herdr's own words when it is not reachable. Carried so the disclosure line can name the reason. */
+  error?: string;
+}
+
+/**
+ * Is there a herdr server that will answer right now? — ADR-0031's selection input.
+ *
+ * **`tab list`, not `which herdr`.** ADR-0031 rejects `PATH` detection as option C by name: a binary on `PATH`
+ * with no server behind it would make every delegation fail at `tab create`, on a path the operator never
+ * chose, and the diagnostic would arrive at the first delegation rather than at startup. Only a parsed
+ * `result` envelope counts as reachable; an `error` envelope, a non-JSON reply, a timeout and a throwing
+ * `exec` are all "not reachable" with the reason preserved.
+ *
+ * **Zero tabs is a successful answer**, deliberately: a fresh herdr with nothing open is reachable.
+ *
+ * Never throws. A probe that threw out of `session_start` would cancel every control after it, which is
+ * R-60's shape exactly — and this one runs *before* the line that discloses what it decided.
+ */
+export async function probeHerdr(options: { exec?: HerdrExec; timeoutMs?: number } = {}): Promise<HerdrProbe> {
+  const exec = options.exec ?? defaultExec;
+  const timeoutMs = options.timeoutMs ?? PROBE_TIMEOUT_MS;
+
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    return await Promise.race<HerdrProbe>([
+      exec(["tab", "list"]).then((reply) => {
+        const parsed = parseReply(reply);
+        return parsed.error ? { ok: false, error: parsed.error } : { ok: true };
+      }),
+      new Promise<HerdrProbe>((settle) => {
+        timer = setTimeout(() => settle({ ok: false, error: `probe timed out after ${timeoutMs}ms` }), timeoutMs);
+      }),
+    ]);
+  } catch (error) {
+    return { ok: false, error: String(error) };
+  } finally {
+    // Cleared whichever branch won, so a fast probe does not hold the event loop open for the timeout's
+    // remainder — which would add up to two seconds to every `node --test` run of this file.
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/** herdr's own variable, set in every pane it creates. Measured 2026-08-17; documented nowhere. */
+export const ENV_PARENT_WORKSPACE = "HERDR_WORKSPACE_ID";
+
+/** The operator's explicit override. Defined here because this is the only module that reads it. */
+
+/**
+ * Which herdr workspace a governed child's pane belongs in.
+ *
+ * **Defaults to the parent's own workspace.** herdr tells a pane which workspace it is in
+ * (`HERDR_WORKSPACE_ID`, alongside `HERDR_TAB_ID` and `HERDR_PANE_ID`), and a child placed in a *different*
+ * workspace from the pi session that spawned it turns "switch between them" into a workspace hop — which is
+ * the entire feature ADR-0032 exists to deliver. The previous behaviour was "omitted lets herdr choose",
+ * which is that failure by default on any machine with more than one workspace.
+ *
+ * `PI_DADDY_HERDR_WORKSPACE` still wins: it is the operator saying so explicitly, and an explicit answer
+ * beating an inference is this package's standing rule (ADR-0030 says it about the grant itself).
+ *
+ * Blank is treated as absent rather than passed through — `--workspace ""` is not a workspace, and it would
+ * fail `tab create` on a path nobody chose.
+ */
+export function resolveWorkspace(env: NodeJS.ProcessEnv): string | undefined {
+  const explicit = env[ENV_HERDR_WORKSPACE]?.trim();
+  if (explicit) return explicit;
+  return env[ENV_PARENT_WORKSPACE]?.trim() || undefined;
+}

package/src/executors/herdr-pi-lifecycle.ts

@@ -0,0 +1,21 @@
+/** Locate the pinned, lifecycle-only Herdr Pi integration shipped with this package. */
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Explicit `-e` survives Pi's `--no-extensions`; only this audited source is loaded for a Herdr child.
+ *
+ * Source-loaded tests resolve the adjacent vendor file. Installed builds resolve the packed `src/` copy,
+ * deliberately rather than discovering an operator's extension directory.
+ */
+export function bundledHerdrPiLifecycleExtension(): string {
+  const candidates = [
+    new URL("./vendor/herdr-pi-lifecycle.ts", import.meta.url),
+    new URL("../../src/executors/vendor/herdr-pi-lifecycle.ts", import.meta.url),
+  ];
+  for (const candidate of candidates) {
+    const path = fileURLToPath(candidate);
+    if (existsSync(path)) return path;
+  }
+  throw new Error("the bundled Herdr Pi lifecycle integration is missing from this package");
+}

package/src/executors/herdr-poll.ts

@@ -0,0 +1,305 @@
+/**
+ * Waiting for a herdr agent to settle, and reading what it printed on the way.
+ *
+ * Split out of `src/executors/run-herdr.ts` when that file hit **404 of the 400-line ceiling** adding ADR-0032's output
+ * polling. The seam was named in the plan before it was needed, and it is a real one: this module is about
+ * *observing* an agent, `run-herdr.ts` is about *starting and cleaning up after* one. Nothing here creates or
+ * destroys anything.
+ *
+ * The two facts it is built on were measured against real herdr 0.7.5 (`docs/probes/g16-herdr`) and both are
+ * counter-intuitive enough to be worth the module comment: `agent wait --until idle` matches the state the
+ * agent was **already** in, and `agent read` is the one command that does **not** return a JSON envelope.
+ */
+
+import { parseReply, type HerdrExec } from "./herdr-cli.ts";
+import { herdrSessionReference } from "../governance/native-session.ts";
+
+/**
+ * What `waitForSettled` needs from a run request.
+ *
+ * Declared here rather than importing `HerdrRunRequest`, which would make the two modules mutually dependent
+ * for no benefit. `HerdrRunRequest` satisfies it structurally, so the call site needs no adapter.
+ */
+export interface PollTarget {
+  /** herdr agent name. */
+  name: string;
+  nativePaneId?: string;
+  onSessionReference?: (reference: NonNullable<ReturnType<typeof herdrSessionReference>>) => void;
+  signal?: AbortSignal;
+  /**
+   * The pane's last few lines, re-reported on every poll — a SNAPSHOT, not a stream (ADR-0032).
+   *
+   * The consumer must **replace** what it holds rather than append. `agent read` returns a snapshot of a
+   * bounded terminal, and treating it as append-only is what produced an 89,000× amplification; see
+   * `tailLines`.
+   */
+  onSnapshot?: (lines: string[]) => void;
+  /** Reuses already-requested pane bytes; never adds an observation-only RPC. */
+  onObservation?: (bytes: Uint8Array) => void;
+  /** How many lines the display wants. Bounds the per-poll cost regardless of how big the pane is. */
+  snapshotLines?: number;
+  /** Poll cadence override. Exists so tests do not wait `POLL_INTERVAL_MS` per state transition. */
+  pollIntervalMs?: number;
+  /**
+   * Inactivity bound (PR 3e). Activity on this executor is a change in the pane's text or in what `activityProbe`
+   * returns (the child's pi session file). Undefined means the wall-clock deadline alone applies.
+   */
+  idleTimeoutMs?: number;
+  activityProbe?: () => Promise<string | number | undefined> | string | number | undefined;
+}
+
+/** Statuses herdr reports for a settled agent. `blocked` counts: it is waiting for a human, not working. */
+const TERMINAL = new Set(["idle", "done", "blocked"]);
+
+/** The pre-prompt sequence from the native start reply; absent is unknown, never zero. */
+export function observeHerdrSession(
+  agent: unknown,
+  pane: string | undefined,
+  sink: PollTarget["onSessionReference"],
+): void {
+  if (!pane || !sink) return;
+  try {
+    const reference = herdrSessionReference(agent, pane);
+    if (reference) sink(reference);
+  } catch {
+    /* optional observation */
+  }
+}
+
+export function seqOf(result: Record<string, unknown> | undefined): number {
+  const agent = (result?.agent ?? {}) as { state_change_seq?: number };
+  return typeof agent.state_change_seq === "number" ? agent.state_change_seq : -1;
+}
+
+/** How often to poll `agent get` while waiting for the child to settle. */
+export const POLL_INTERVAL_MS = 750;
+/**
+ * A prompt accepted from a terminal state must produce an observable lifecycle change promptly.
+ *
+ * Herdr 0.8's `agent prompt --wait` documents this same five-second bound. We retain polling because it
+ * supplies the bounded live pane snapshots, but refuse rather than holding a parent for the whole child timeout when
+ * the only reported state remains the pre-prompt terminal state. That is a detector/integration failure, not
+ * evidence that a child settled.
+ */
+export const FRESH_LIFECYCLE_TIMEOUT_MS = 5_000;
+/** Lines of pane tail reported per poll. Matches the status block's own tail, so nothing is fetched unused. */
+export const DEFAULT_SNAPSHOT_LINES = 3;
+
+/**
+ * Wait for the child to settle, without accepting the state it was already in.
+ *
+ * **R-33, measured.** `herdr agent wait --until idle` called right after `agent prompt` returned
+ * *immediately*, matching the agent's **pre-existing** idle state with `state_change_seq` unchanged — a
+ * reply indistinguishable from a completed run. For fan-out that is not an inconvenience but a
+ * correctness bug: an orchestrator would "collect" N children that never ran and merge N empty results
+ * into a confident summary (R-03 with a new cause).
+ *
+ * So this polls `agent get` and requires **both** that the status is terminal **and** that
+ * `state_change_seq` has advanced past the value observed before prompting. `agent wait` is deliberately
+ * not used at all: its contract cannot express "settled *after* this point".
+ */
+/**
+ * Establish the bundled Pi lifecycle reporter's idle baseline before prompt dispatch.
+ *
+ * `screen_detection_skipped` is Herdr's reported fact that a full lifecycle authority owns this pane.
+ * Waiting for it prevents the reporter's asynchronously queued initial idle report from becoming a
+ * post-prompt sequence advance. This is not completion: no prompt has been sent at this point.
+ */
+export async function waitForLifecycleBaseline(
+  exec: HerdrExec,
+  request: PollTarget,
+  deadline: number,
+): Promise<{ before?: number; aborted?: boolean; spawnError?: string }> {
+  const interval = request.pollIntervalMs ?? POLL_INTERVAL_MS;
+  for (;;) {
+    if (request.signal?.aborted) return { aborted: true };
+    if (Date.now() >= deadline)
+      return { spawnError: "Herdr did not activate the bundled Pi lifecycle reporter before prompt dispatch" };
+    const reply = parseReply(await exec(["agent", "get", request.name]));
+    if (reply.error) return { spawnError: `herdr agent get failed: ${reply.error}` };
+    const agent = (reply.result?.agent ?? reply.result ?? {}) as {
+      agent_status?: string;
+      state_change_seq?: number;
+      screen_detection_skipped?: boolean;
+    };
+    const seq = typeof agent.state_change_seq === "number" ? agent.state_change_seq : -1;
+    if (agent.screen_detection_skipped === true && agent.agent_status && TERMINAL.has(agent.agent_status) && seq >= 0)
+      return { before: seq };
+    await new Promise<void>((resolve) => setTimeout(resolve, Math.min(interval, Math.max(0, deadline - Date.now()))));
+  }
+}
+
+export async function waitForSettled(
+  exec: HerdrExec,
+  request: PollTarget,
+  before: number,
+  deadline: number,
+  maxOutputBytes: number,
+): Promise<{ status?: string; timedOut?: boolean; idle?: true; aborted?: boolean; spawnError?: string }> {
+  const interval = request.pollIntervalMs ?? POLL_INTERVAL_MS;
+  let lastActivityAt = Date.now();
+  let lastPane: string | undefined;
+  let lastMarker: string | number | undefined;
+  // ADR-0032. The pane is read on every poll so the parent can show what the child is doing, rather than the
+  // one word `delegate` for up to sixty minutes by default.
+  //
+  // No cross-poll state is kept, deliberately: the previous design remembered what it had reported so it could
+  // send a diff, and that is what broke — see `tailLines`. A snapshot needs no memory.
+  const keep = request.snapshotLines ?? DEFAULT_SNAPSHOT_LINES;
+  let staleTerminalSince: number | undefined;
+
+  for (;;) {
+    if (request.signal?.aborted) return { aborted: true };
+    if (Date.now() >= deadline) return { timedOut: true };
+    if (request.idleTimeoutMs !== undefined && Date.now() - lastActivityAt >= request.idleTimeoutMs)
+      return { timedOut: true, idle: true };
+
+    const reply = parseReply(await exec(["agent", "get", request.name]));
+    if (reply.error) return { spawnError: `herdr agent get failed: ${reply.error}` };
+
+    const agent = (reply.result?.agent ?? reply.result ?? {}) as { agent_status?: string; state_change_seq?: number };
+    if (request.idleTimeoutMs !== undefined) {
+      // The pane is read below only when a display wants it; the probe is the executor-independent signal.
+      let marker: string | number | undefined;
+      try {
+        marker = await request.activityProbe?.();
+      } catch {
+        marker = undefined; // unreadable is "no activity seen", never a control decision
+      }
+      if (marker !== undefined && marker !== lastMarker) {
+        lastMarker = marker;
+        lastActivityAt = Date.now();
+      }
+    }
+    observeHerdrSession(agent, request.nativePaneId, request.onSessionReference);
+    const status = agent.agent_status;
+    const seq = typeof agent.state_change_seq === "number" ? agent.state_change_seq : -1;
+
+    if (request.onSnapshot) {
+      // Read BEFORE the terminal check returns, so a child that settles on this iteration still has its last
+      // output shown. `readFailed` is passed so a failed read renders as such instead of silently freezing the
+      // block on the previous frame — and, crucially, is never mistaken for the child's output.
+      const read = await readPane(exec, request.name, maxOutputBytes);
+      if (!read.readFailed && read.text !== lastPane) {
+        lastPane = read.text;
+        lastActivityAt = Date.now();
+      }
+      if (!read.readFailed) {
+        try {
+          request.onObservation?.(Buffer.from(read.text));
+        } catch {
+          /* observation only */
+        }
+      }
+      try {
+        request.onSnapshot(read.readFailed ? ["[pane could not be read]"] : tailLines(read.text, keep));
+      } catch {
+        /* display only — a renderer must not break a governed run */
+      }
+    }
+
+    if (status && TERMINAL.has(status)) {
+      if (seq > before) return { status };
+      // Do not turn this pane's text into a completion signal. A known agent whose screen rule misses a new
+      // UI shape falls back to idle, precisely the state R-33 says is unsafe to accept. A stable stale
+      // terminal state for this bounded interval is instead a loud compatibility refusal (issue #43).
+      staleTerminalSince ??= Date.now();
+      if (Date.now() - staleTerminalSince >= FRESH_LIFECYCLE_TIMEOUT_MS) {
+        return {
+          spawnError:
+            `herdr reported ${status} without a post-prompt lifecycle change for ${FRESH_LIFECYCLE_TIMEOUT_MS}ms; ` +
+            "refusing to treat the pre-prompt terminal state as completion. Update Herdr's Pi detector or inspect its lifecycle reporting.",
+        };
+      }
+    } else {
+      staleTerminalSince = undefined;
+    }
+
+    await new Promise<void>((resolve) => setTimeout(resolve, Math.min(interval, Math.max(0, deadline - Date.now()))));
+  }
+}
+
+/**
+ * The last `keep` non-blank lines of a pane snapshot — what the display actually needs.
+ *
+ * **This replaces a `newSuffix` diff, and the replacement is a correction rather than a tune-up.** The old
+ * design treated `agent read` as a *stream* and tried to report only what was new, by testing whether the new
+ * text extended the old. That is wrong about the substrate: `agent read` returns a **snapshot of a bounded
+ * terminal**, and a snapshot is not an append-only log. Two ordinary things break the prefix test forever —
+ * the pane **scrolling** (its top lines are gone, so the new text is not an extension of the old) and
+ * `readPane` **truncating to the tail** past `maxOutputBytes` (each read is a different window of a growing
+ * buffer). Once either happens, every poll reported the whole buffer.
+ *
+ * Measured before the fix: **51 MiB streamed for ~600 bytes of real output — 89,000× amplification** in 37
+ * seconds, per child, with a scrolling pane also delivering the same real lines three times each. The old
+ * docstring named that exact failure as the thing it prevented.
+ *
+ * So the herdr path now reports a **bounded snapshot** and the consumer *replaces* rather than appends. There
+ * is no diff to get wrong, the per-poll cost is `keep` lines regardless of buffer size, and a scrolling pane
+ * simply shows its current tail — which is what a human looking at that pane would see.
+ */
+export function tailLines(snapshot: string, keep: number): string[] {
+  if (keep <= 0) return [];
+  const lines: string[] = [];
+  // Walked from the END, so a 1 MiB buffer costs the last few lines rather than a full split.
+  let end = snapshot.length;
+  while (end > 0 && lines.length < keep) {
+    const start = snapshot.lastIndexOf("\n", end - 1);
+    const line = snapshot
+      .slice(start + 1, end)
+      .replace(/\r/g, "")
+      .trimEnd();
+    if (line.length > 0) lines.unshift(line);
+    if (start === -1) break;
+    end = start;
+  }
+  return lines;
+}
+
+/**
+ * Read the pane's contents.
+ *
+ * `agent read` is the ONE command that does not return herdr's JSON envelope — it writes the terminal's
+ * text straight to stdout. Running it through `parseReply` turned every successful read into
+ * "unparseable herdr reply", i.e. reported the child's actual answer as a failure to read it. Found by the
+ * end-to-end run; the unit fake had been written to the envelope shape and so agreed with the bug.
+ *
+ * A JSON envelope is still accepted first, because an `error` reply here IS JSON and must not be mistaken
+ * for terminal output.
+ *
+ * **`readFailed` is separate from `text`, and that separation is the fix for an R-03 defect.** A failed read
+ * used to return its own diagnostic *as* `text` — so `runHerdrPane` returned
+ * `[grants] could not read the agent pane: pane is gone` **as the child's answer, with `code: 0`**, and the
+ * orchestrator read a failure message as a completed sub-agent's report. Measured. It mattered little when this
+ * ran once per child; ADR-0032 made it run on every poll, up to 800 times for a ten-minute child, so a
+ * transient failure went from unlikely to expected. The caller must now decide, and it cannot do so by
+ * inspecting a string.
+ */
+export async function readPane(
+  exec: HerdrExec,
+  name: string,
+  maxOutputBytes: number,
+): Promise<{ text: string; truncated: boolean; readFailed?: string }> {
+  const reply = await exec(["agent", "read", name]);
+  let text: string;
+  try {
+    const parsed = JSON.parse(reply.stdout) as { result?: Record<string, unknown>; error?: { message?: string } };
+    if (parsed.error) {
+      return { text: "", truncated: false, readFailed: parsed.error.message ?? "unknown error" };
+    }
+    const raw = parsed.result?.output ?? parsed.result?.text ?? parsed.result?.content ?? "";
+    text = typeof raw === "string" ? raw : JSON.stringify(raw);
+  } catch {
+    text = reply.stdout;
+  }
+  if (Buffer.byteLength(text) <= maxOutputBytes) return { text, truncated: false };
+  // Keep the TAIL, not the head: a terminal's useful content is its most recent output, and the head is
+  // the startup banner. `runChild` keeps the head because it streams and must stop a runaway producer;
+  // here the output is already complete, so the choice is free and the tail is the answer.
+  //
+  // Sliced by BYTES via a Buffer round trip rather than by code units, for `takeBytes`'s reason in
+  // `run-child.ts`: `slice(-maxOutputBytes)` on a CJK pane overran the cap by three times. `toString` repairs
+  // a character split at the cut by replacing it, which is the right trade for a tail — one replacement
+  // character at the boundary, versus a cap that does not hold.
+  return { text: Buffer.from(text, "utf8").subarray(-maxOutputBytes).toString("utf8"), truncated: true };
+}