pi-daddy 0.28.0 → 0.32.0

package/src/grant-store.ts

@@ -1,235 +0,0 @@
-/**
- * The init choice for a directory, stored **outside** it: its grant and, in v2, explicit project-ledger
- * consent.
- *
- * `PI_GRANTS_GRANT` and `PI_GRANTS_LEDGER` remain the propagation channel to children — a parent writes them
- * and every child inherits them. The store is a root-session source only, so an operator does not have to
- * `source` a file and restart pi after making the project choice.
- *
- * **Outside the workspace, and that is the whole design.** A grant is a ceiling; a ceiling a governed child
- * can rewrite is not a ceiling. `<cwd>/.pi/grants.env` is writable by any child holding `tool:write`, so
- * storing the live grant there would let a child widen the *next* session's ceiling — ADR-0014's
- * self-defeating case verbatim, which is why persisted approvals were moved out of the workspace in the
- * first place. This reuses that pattern exactly: `$PI_CODING_AGENT_DIR/grants/<slug>-<hash>.json`, keyed by
- * the directory, unwritable by a narrowed child because a narrowed child holds no write access to `$HOME`.
- *
- * **It does not defend against a child holding `bash`** (ADR-0012). Nothing here does.
- *
- * `.pi/grants.env` is still written by `init` and is still worth committing — it is the *reviewable record*
- * of the decision, diffable in a PR. It is simply no longer the thing the enforcer reads.
- */
-
-import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { mkdir, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
-import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
-import { withFileLock, LockTimeoutError } from "./file-lock.ts";
-import type { Capability } from "./resolve.ts";
-
-interface GrantFileV1 {
-  version: 1;
-  /** The directory this grant is for. Checked on read — an entry copied elsewhere is refused (R-27). */
-  cwd: string;
-  grant: Capability[];
-  /** When `/grants init` wrote it. Informational; nothing expires. */
-  writtenAt: string;
-}
-
-interface GrantFileV2 {
-  version: 2;
-  cwd: string;
-  grant: Capability[];
-  /** Explicit consent from ADR-0037's `/grants init`; never inferred from a legacy file merely existing. */
-  projectLedger: true;
-  writtenAt: string;
-}
-
-export interface StoredGrant {
-  grant: Capability[];
-  /** Whether a root session defaults to `<cwd>/.pi/grants.jsonl`. False for every legacy v1 store. */
-  projectLedger: boolean;
-}
-
-export type GrantStoreRefusalReason = "malformed" | "unsupported-version" | "unreadable" | "wrong-cwd";
-export type StoredGrantState =
-  | { state: "absent" }
-  | { state: "valid"; stored: StoredGrant }
-  | { state: "refuse"; reason: GrantStoreRefusalReason };
-
-export interface SaveGrantOptions {
-  projectLedger?: boolean;
-}
-
-/** `$PI_CODING_AGENT_DIR`, or pi's default. Same resolution as the approval store. */
-function agentDir(): string {
-  return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
-}
-
-/**
- * Where this directory's grant lives.
- *
- * Slug plus a 64-bit hash, exactly as `approvalsPath` does it and for the same two reasons: the basename
- * keeps the directory legible to a human reading it, and the hash is what makes it unambiguous, since two
- * checkouts can share a basename.
- */
-export function grantStorePath(cwd: string): string {
-  const slug = (basename(cwd) || "root").replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 40);
-  const hash = createHash("sha256").update(cwd, "utf8").digest("hex").slice(0, 16);
-  return join(agentDir(), "grants", `${slug}-${hash}.json`);
-}
-
-/**
- * Parse a store file's text into its versioned project choice, or null.
- *
- * Split out from the readers so the **one** validation lives in one place: both the sync and async paths
- * must agree, and two parsers is how they come to disagree.
- *
- * Rejects every doubt at this parser boundary — it never constructs a partial ceiling. The session currently
- * treats absent and invalid stores alike (R-175), so do not call that wider behavior fail-closed. The `cwd`
- * check is R-27's: a copied file describes a directory nobody authorised it for.
- */
-export function parseStoredGrantState(text: string, cwd: string): StoredGrantState {
-  let parsed: { version?: unknown; cwd?: unknown; grant?: unknown; projectLedger?: unknown };
-  try {
-    parsed = JSON.parse(text) as typeof parsed;
-  } catch {
-    return { state: "refuse", reason: "malformed" };
-  }
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    return { state: "refuse", reason: "malformed" };
-  }
-  if (parsed.version !== 1 && parsed.version !== 2) {
-    return { state: "refuse", reason: "unsupported-version" };
-  }
-  if (parsed.cwd !== cwd) return { state: "refuse", reason: "wrong-cwd" };
-  if (!Array.isArray(parsed.grant)) return { state: "refuse", reason: "malformed" };
-  if (!parsed.grant.every((c) => typeof c === "string" && c.length > 0)) {
-    return { state: "refuse", reason: "malformed" };
-  }
-  if (parsed.version === 2 && parsed.projectLedger !== true) {
-    return { state: "refuse", reason: "malformed" };
-  }
-  return {
-    state: "valid",
-    stored: { grant: parsed.grant as Capability[], projectLedger: parsed.version === 2 },
-  };
-}
-
-export function parseStoredGrant(text: string, cwd: string): StoredGrant | null {
-  const result = parseStoredGrantState(text, cwd);
-  return result.state === "valid" ? result.stored : null;
-}
-
-/** Compatibility view for callers that need only the capability ceiling. */
-export function parseGrantFile(text: string, cwd: string): Capability[] | null {
-  return parseStoredGrant(text, cwd)?.grant ?? null;
-}
-
-/**
- * Read this directory's stored grant, synchronously.
- *
- * **Sync on purpose, and this is the constraint that shapes the feature.** Whether `delegate` is registered
- * at all is decided when the extension factory runs (S-5: a session without `tool:delegate` must not be
- * offered the tool), and that is before any `await` is possible. An async read would resolve after the
- * decision it exists to inform, so the store would silently fail to grant delegation — the exact class of
- * defect R-38 and R-39 were.
- */
-export function loadStoredGrantStateSync(cwd: string): StoredGrantState {
-  try {
-    return parseStoredGrantState(readFileSync(grantStorePath(cwd), "utf8"), cwd);
-  } catch (error) {
-    return (error as NodeJS.ErrnoException).code === "ENOENT"
-      ? { state: "absent" }
-      : { state: "refuse", reason: "unreadable" };
-  }
-}
-
-export function loadStoredGrantSync(cwd: string): StoredGrant | null {
-  const result = loadStoredGrantStateSync(cwd);
-  return result.state === "valid" ? result.stored : null;
-}
-
-export function loadGrantSync(cwd: string): Capability[] | null {
-  return loadStoredGrantSync(cwd)?.grant ?? null;
-}
-
-/** Async twin, for callers that already have one. Same parser, so they cannot disagree. */
-export async function loadStoredGrantState(cwd: string): Promise<StoredGrantState> {
-  try {
-    return parseStoredGrantState(await readFile(grantStorePath(cwd), "utf8"), cwd);
-  } catch (error) {
-    return (error as NodeJS.ErrnoException).code === "ENOENT"
-      ? { state: "absent" }
-      : { state: "refuse", reason: "unreadable" };
-  }
-}
-
-export async function loadStoredGrant(cwd: string): Promise<StoredGrant | null> {
-  const result = await loadStoredGrantState(cwd);
-  return result.state === "valid" ? result.stored : null;
-}
-
-export async function loadGrant(cwd: string): Promise<Capability[] | null> {
-  return (await loadStoredGrant(cwd))?.grant ?? null;
-}
-
-/** The one project-local default ADR-0037 binds to an explicit v2 init choice. */
-export function projectLedgerPath(cwd: string): string {
-  return resolve(cwd, ".pi", "grants.jsonl");
-}
-
-export type SaveOutcome = "saved" | "failed" | "busy";
-
-/**
- * Write this directory's grant and optional project-ledger consent as one atomic choice.
- *
- * Locked with the same lock the ledger and the approval store use, for the same reason: two sessions in one
- * directory running `/grants init` concurrently must not interleave. A lock this cannot take yields `busy`
- * and changes nothing — the caller reports it and the operator retries, which is the honest outcome for a
- * write that never looked at the file (R-68).
- *
- * `wx` on the temp file refuses to follow a pre-existing symlink, and `rename` is atomic within a
- * filesystem, so a reader never sees a half-written grant. Both copied from `writeFileSafely`, deliberately
- * — a second, subtly different atomic-write is how the two come to disagree about what "safe" meant.
- */
-export async function saveGrant(
-  cwd: string,
-  grant: Capability[],
-  options: SaveGrantOptions = {},
-): Promise<SaveOutcome> {
-  const path = grantStorePath(cwd);
-  const common = { cwd, grant: [...grant].sort(), writtenAt: new Date().toISOString() };
-  const file: GrantFileV1 | GrantFileV2 = options.projectLedger
-    ? { version: 2, ...common, projectLedger: true }
-    : { version: 1, ...common };
-  try {
-    await mkdir(dirname(path), { recursive: true });
-    return await withFileLock(path, "grant store", async () => {
-      const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
-      try {
-        await writeFile(temp, `${JSON.stringify(file, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
-        await rename(temp, path);
-        return "saved" as const;
-      } catch {
-        await unlink(temp).catch(() => undefined);
-        return "failed" as const;
-      }
-    });
-  } catch (error) {
-    return error instanceof LockTimeoutError ? "busy" : "failed";
-  }
-}
-
-/** Remove this directory's stored grant. True when a file was there to remove. */
-export async function clearGrant(cwd: string): Promise<boolean> {
-  const path = grantStorePath(cwd);
-  try {
-    await readFile(path, "utf8");
-  } catch {
-    return false;
-  }
-  await rm(path, { force: true }).catch(() => undefined);
-  return true;
-}

package/src/herdr-cli.ts

@@ -1,125 +0,0 @@
-/**
- * Talking to herdr: one command, one JSON envelope, plus the two questions ADR-0031 needs answered.
- *
- * Lifted out of `src/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";
-
-/** 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_GRANTS_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. */
-export const ENV_HERDR_WORKSPACE = "PI_GRANTS_HERDR_WORKSPACE";
-
-/**
- * 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_GRANTS_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/herdr-pi-lifecycle.ts

@@ -1,21 +0,0 @@
-/** 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/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/herdr-poll.ts

@@ -1,253 +0,0 @@
-/**
- * Waiting for a herdr agent to settle, and reading what it printed on the way.
- *
- * Split out of `src/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 "./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;
-}
-
-/** 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 twenty minutes 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; aborted?: boolean; spawnError?: string }> {
-  const interval = request.pollIntervalMs ?? POLL_INTERVAL_MS;
-  // 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 twenty 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 };
-
-    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 };
-    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) { 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 };
-}