pi-daddy 0.28.0 → 0.32.1

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 (probe `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 (probe `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 };
+}

package/src/executors/herdr-stage.ts

@@ -0,0 +1,55 @@
+/**
+ * Staging a definition's instructions to a file, because herdr cannot carry them in argv.
+ *
+ * Split out of `src/executors/run-herdr.ts` at the 400-line ceiling. A real seam rather than an arbitrary cut: this is
+ * the one place that works around a **herdr encoding limit**, and it is the only part of the herdr path that
+ * touches the filesystem. `run-herdr.ts` starts and reaps agents; this prepares one argument.
+ */
+
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Move a multi-line `--append-system-prompt` out of argv, because herdr cannot encode it.
+ *
+ * **Measured.** `herdr agent start` types the argv into the pane's shell, so a value containing newlines
+ * is rejected outright: `invalid_agent_argument — agent arguments cannot be encoded safely for the target
+ * shell`. A definition's `SKILL.md` body is always multi-line, so every `delegate({agent})` spawn would
+ * fail on this path.
+ *
+ * pi accepts a **file path** there as readily as literal text (`resolvePromptInput` + `existsSync` in
+ * `dist/core/resource-loader.js`), so the fix is to write the body to a temp file and pass its path — one
+ * short, shell-safe argument.
+ *
+ * The split lives here rather than in `planSpawn` because the constraint is **herdr's**, not pi's: the
+ * direct executor passes the same text inline with no trouble, and a plan builder that pre-emptively wrote
+ * temp files for everybody would be paying one executor's tax on both paths.
+ */
+export function splitSystemPrompt(args: string[]): { args: string[]; systemPrompt?: string } {
+  const at = args.indexOf("--append-system-prompt");
+  if (at === -1 || at + 1 >= args.length) return { args };
+  return { args: [...args.slice(0, at), ...args.slice(at + 2)], systemPrompt: args[at + 1] };
+}
+
+/**
+ * Move a multi-line system prompt into a temp file and return argv pointing at it.
+ *
+ * Returns the directory so the caller can remove it — and **every** early return on the herdr path must, because
+ * nothing else can: a reviewer measured a permanent `/tmp/grants-herdr-*` per failed `tab create`, unreachable by
+ * either pane sweep because the pane it belonged to never existed.
+ */
+export async function stageSystemPrompt(
+  args: string[],
+): Promise<{ args: string[]; promptDir?: string; error?: string }> {
+  const split = splitSystemPrompt(args);
+  if (split.systemPrompt === undefined) return { args: split.args };
+  try {
+    const promptDir = await mkdtemp(join(tmpdir(), "grants-herdr-"));
+    const file = join(promptDir, "system-prompt.md");
+    await writeFile(file, split.systemPrompt, "utf8");
+    return { args: [...split.args, "--append-system-prompt", file], promptDir };
+  } catch (error) {
+    return { args: split.args, error: `could not stage the system prompt for herdr: ${String(error)}` };
+  }
+}

package/src/executors/native-session-target.ts

@@ -0,0 +1,31 @@
+import { lstat, realpath, mkdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, parse, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { ENV_NATIVE_SESSION_ROOT } from "../governance/native-session.ts";
+import { ENV_RETAIN_NATIVE_SESSIONS } from "../kernel/env-names.ts";
+export { ENV_RETAIN_NATIVE_SESSIONS } from "../kernel/env-names.ts";
+export interface NativeSessionHost {
+  /** Explicit host opt-in captured once, not model-supplied. */ readonly nativeSessionRoot?: string;
+}
+export const nativeSessionRootFromEnv = (env: NodeJS.ProcessEnv) =>
+  env[ENV_RETAIN_NATIVE_SESSIONS] === "1" ? (env[ENV_NATIVE_SESSION_ROOT] ?? "") : undefined;
+/** Explicit ordinary-host opt-in only. Never read a destination from tool/model parameters.
+ * Allocate a fresh per-occurrence directory; no scan, existing-session takeover or transcript creation. */
+export async function allocateNativeSessionTarget(root: string, executionId: string): Promise<string> {
+  if (!isAbsolute(root) || resolve(root) !== root || !/^[a-zA-Z0-9:_-]{1,128}$/.test(executionId))
+    throw new Error("explicit native root/execution identity required");
+  for (let p = root; ; p = dirname(p)) {
+    const s = await lstat(p);
+    if (!s.isDirectory() || s.isSymbolicLink()) throw new Error("native target ancestor changed");
+    if (p === parse(p).root) break;
+  }
+  const before = await lstat(root);
+  if ((await realpath(root)) !== root || before.mode & 0o077 || before.uid !== process.getuid?.())
+    throw new Error("private owned native target root required");
+  const directory = join(root, "execution-" + createHash("sha256").update(executionId).digest("hex"));
+  await mkdir(directory, { mode: 0o700 }); // EEXIST is a refusal, never permission to append an old occurrence.
+  const after = await lstat(root);
+  if (before.dev !== after.dev || before.ino !== after.ino || (await realpath(directory)) !== directory)
+    throw new Error("native target root replaced");
+  return join(directory, "session.jsonl");
+}