pi-daddy 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -93,6 +93,97 @@ resolution, enforcement, approvals or the ledger changed — this is the part be
   defect as the `exports` map that worked in the tree and threw for every consumer, and the second time that
   script has caught it.
 
+## 0.16.0 — children you can watch, in panes chosen for you
+
+**If herdr is running, your sub-agents now run in herdr panes without you configuring anything — and the
+parent shows what each one is doing while it works.** Two ADRs, shipped together.
+
+### `PI_GRANTS_HERDR` is three-state, and unset now means *probe* (ADR-0031)
+
+| Value | Behaviour |
+| :--- | :--- |
+| unset | Probe once at session start (`herdr tab list`, 2s bound). A server that **answers** ⇒ herdr panes; anything else ⇒ captured subprocess. |
+| `1` | Demand herdr. **Every delegation refuses** if it is unreachable — no fallback. |
+| `0` | Demand the captured subprocess. No probe. |
+
+**Not a `PATH` check.** A binary with no server behind it would make every delegation fail at `tab create`, on
+a path nobody chose — so only a *reachable* server counts. This reverses part of ADR-0016 point 6, which
+refused auto-detection on the grounds that a run must not "silently relocate"; the answer to *silently* is that
+the executor is now named at session start, in `/grants`, and per child in the ledger.
+
+**What to do about it:** nothing, unless you relied on an unset variable meaning subprocesses. If you did, set
+`PI_GRANTS_HERDR=0`.
+
+A stale `PI_GRANTS_HERDR=1` in a shell profile still breaks delegation on a machine without herdr — **as it did in
+0.15.0**, where every child failed at `tab create`. There was never a fallback to lose. What changed is that the
+failure is reported at session start, names the variable, and says what to set instead, rather than surfacing as a
+per-delegation spawn error.
+
+### A running delegation is visible (ADR-0032)
+
+Both tools discarded pi's `onUpdate`, so a delegation showed the bare word `delegate` from the call until the
+result — up to ten minutes, and the same one word for all eight children of a `delegate_all`. Now there is one
+status block per call, redrawn in place, with a three-line tail per child and its herdr agent and pane id:
+
+```
+2 children · herdr panes
+
+review   agent review-d0.1   pane w7:t12   running  0:42
+  3 findings so far: unchecked nil at
+  session.ts:88, missing expiry compare…
+```
+
+Both executors stream. The block is a **display, never the result** — the answer is still what the child
+returned.
+
+### Panes live until you get your prompt back
+
+A pane used to be destroyed the instant its child settled, so a twenty-second child's pane was gone before
+anyone could switch to it. Panes now belong to the **agent run** and are swept at `agent_settled`, capped at 8
+at once, with process `exit` as the backstop. `PI_GRANTS_HERDR_KEEP_PANE=1` still means *not even then*.
+
+A child's pane also defaults to the **parent's own herdr workspace** now, so switching to one is a tab away
+rather than a workspace away.
+
+### Fixed before release — eighteen defects from six independent reviewers
+
+Everything above was implemented, then attacked by six reviewers with one written hypothesis each. Two were
+shipping blockers, and they change what the herdr path guarantees:
+
+- **`herdr agent stop` does not exist.** Measured against herdr 0.7.5. Three call sites issued it for nothing, and
+  `docs/probes/g16-herdr` asserted it worked — from a rerun block that was never run. Closing the tab is the only
+  kill herdr offers, so an unsettled child now loses its tab at once; leaving it would have left a governed child
+  working with its grant after its result was reported.
+- **herdr binds an agent name to its tab.** With panes outliving their calls, the **second `delegate` of every
+  turn** failed with `agent_name_taken`. Names are now unique per spawn.
+- **The 8-pane cap killed live siblings**, because pi runs tool calls in parallel by default. Only *settled* panes
+  are reclaimable now; if they are all live the cap yields rather than enforcing.
+- **The pane reader amplified output 89,000×** once a pane scrolled or passed the output cap: `agent read` returns
+  a snapshot of a bounded terminal and was being diffed as an append-only stream.
+- **The output cap counted bytes but truncated by UTF-16 code units** — 2048 bytes through the 1024 default on
+  non-ASCII — and a multi-byte character split across a pipe boundary became U+FFFD **in the child's answer**.
+  Both pre-existing, both fixed.
+- **A failed pane read came back as the child's successful answer**, and a truncated pane never said so.
+- **The session-start executor line never reached pi's TUI**, because consecutive `info` notifies overwrite each
+  other — which also means `holding [...]` has been silently overwritten since the spawnable summary was added.
+  All info lines are now one message.
+- **The approval dialog ran before the refusal**, so a demanded-but-unreachable herdr could bank a 30-day approval
+  for a delegation it then refused.
+
+Six tests that could not fail were rewritten, each re-verified by re-applying the mutation that had defeated it,
+and coverage was added where it was simply absent — including that nothing verified a real spawn records
+`executor: "herdr"`. 461 unit tests, up from 442.
+
+### Also
+
+- **`/grants ledger` tallies executors**, so "which children ran in panes?" no longer needs `jq`.
+- **The tripwire names `delegate_all`.** It said only *"Use `delegate` instead"*, and a request for parallel
+  work was answered with a single sequential call as a result.
+- **The ledger records `executor` per child** — required, not optional. The executor is decided by a probe now,
+  so nothing outside the record preserves which one ran, and the two paths do not produce the same argv.
+- **R-62 re-rated L×L → M×L.** Its "low severity" rested on the herdr executor being opt-in, which is no
+  longer true. The failure is unchanged; how often anyone meets it is not.
+
 ## 0.15.0 — `/grants init`, a grant that survives without an env var, and a setup that was wrong
 
 **Setup is two steps instead of five, and one of the five was wrong.**

package/README.md

@@ -183,11 +183,19 @@ delegate_all({ children: [ {…}, {…}, {…} ] })                  // several
 
 ### Two executors, one plan
 
-Default is a captured child process. `PI_GRANTS_HERDR=1` runs each child in a visible, attachable **herdr**
-pane instead — the same governed argv, the same `--tools` enforcement, somewhere you can watch it.
+Either a captured child process, or a visible, attachable **herdr** pane — the same governed argv, the same
+`--tools` enforcement, somewhere you can watch it.
 
-Opt-in and never auto-detected: where a governed child executes is an operator decision, not a consequence
-of what happens to be on `PATH`. Constraints found by building it are in `docs/probes/g16-herdr` — herdr has
+**Which one runs is decided by a probe (ADR-0031).** `PI_GRANTS_HERDR` is three-state: **unset** probes once at
+session start (`herdr tab list`, 2s bound) and uses panes if a server *answers*; **`1`** demands herdr and
+**refuses every delegation** if it is unreachable, rather than quietly relocating; **`0`** demands subprocesses and
+skips the probe. Which one was chosen is printed at session start, shown by `/grants`, and recorded per child in
+the ledger.
+
+Still **never auto-detected from `herdr` being on `PATH`** — a binary with no server behind it would make every
+delegation fail at `tab create`, on a path nobody chose. Only a reachable server counts.
+
+A child's pane goes in **your own herdr workspace** by default, so switching to one is a tab away. Constraints found by building it are in `docs/probes/g16-herdr` — herdr has
 no `--env` (the grant rides on the pane, which the agent's shell inherits), `agent start` types argv into a
 shell so a multi-line argument must be staged to a file, and `agent wait --until idle` matches the state the
 agent was *already* in, so settling requires a state counter to advance.
@@ -461,9 +469,9 @@ everything below it.
 | `PI_GRANTS_CHILD_TIMEOUT` | `600` (seconds) | Wall-clock limit for a child. Inherited by descendants — an operator preference, deliberately *not* attenuating state. |
 | `PI_GRANTS_FANOUT` | `8` | **Subtree budget**: total descendants this session may create. Attenuates downward like depth. Malformed or `0` falls back to the default — a bound a typo can switch off is not a bound. |
 | `PI_GRANTS_PARENT_ID` | `d0` | This session's ledger id; set by the parent. Makes sibling records joinable into a tree. |
-| `PI_GRANTS_HERDR` | unset | `1` runs children in visible **herdr** panes instead of captured processes. Opt-in, never auto-detected: where a governed child executes is an operator decision, not a consequence of what is on `PATH`. |
-| `PI_GRANTS_HERDR_WORKSPACE` | unset | herdr workspace for spawned panes. |
-| `PI_GRANTS_HERDR_KEEP_PANE` | unset | `1` keeps each child's pane for inspection. Off by default: a fan-out would flood the workspace. |
+| `PI_GRANTS_HERDR` | unset ⇒ **probe** | Three-state. Unset probes for a reachable herdr and uses panes if one answers; `1` demands panes and refuses every delegation if herdr is unreachable; `0` demands captured subprocesses. Never detected from `herdr` merely being on `PATH`. |
+| `PI_GRANTS_HERDR_WORKSPACE` | the parent's `HERDR_WORKSPACE_ID` | herdr workspace for spawned panes. Defaults to the workspace this session is in, so a child is a tab away rather than a workspace away. |
+| `PI_GRANTS_HERDR_KEEP_PANE` | unset | `1` keeps each child's pane for inspection, and no sweep closes it. Off by default: a fan-out would flood the workspace. |
 | `PI_CODING_AGENT_DIR` | `~/.pi/agent` | pi's own variable, not ours — but it decides where persisted approvals live, so it is listed here. |
 
 **A malformed value disables spawning; it never falls back to a default.** An unreadable
@@ -669,11 +677,18 @@ Known gaps, stated because a gap nobody wrote down is the one that surprises som
 - **`bash` escapes governance.** Out of scope by decision (ADR-0012).
 - **`subagents:rpc:spawn` bypasses the tripwire.** Unfixable from here.
 - **The ledger is verified at session start** when one is configured: a damaged trail announces itself, an intact one stays quiet.
-- **Pane cleanup covers everything except being killed outright.** A run closes its pane in a `finally`,
-  and anything still open is closed on process `exit` — which does **not** cover SIGKILL, nor a SIGTERM
-  nothing else in the process is listening for, because Node runs no `exit` handlers there. `herdr tab
-  close <id>` is the remedy. No signal handler is installed, deliberately: one here would suppress Node's
-  default termination and turn pi's *"interrupt this turn"* into *"exit pi"* (R-62).
+- **A pane outlives its tool call only if its child settled.** A child that answered keeps its pane so you can
+  read it, and it is swept when you get your prompt back (`agent_settled`), with process `exit` as a backstop. A
+  child that did **not** settle — timeout, abort, failed start — loses its tab at once, because closing the tab is
+  the only way to stop a herdr agent (`herdr agent stop` does not exist). At most 8 panes are open at once, and
+  only *settled* ones are ever reclaimed: if they are all live the cap yields rather than killing a child.
+- **Pane cleanup does not cover being killed outright.** SIGKILL, and a SIGTERM nothing else is listening for,
+  run no `exit` handlers — by Node's design — so a pane can be orphaned; `herdr tab close <id>` is the remedy. No
+  signal handler is installed, deliberately: one here would suppress Node's default termination and turn pi's
+  *"interrupt this turn"* into *"exit pi"* (R-62, re-rated M×L now that panes are the default path).
+- **A running delegation is visible.** One status block per call — per child: its definition, its herdr agent, its
+  pane id, its state, elapsed time, and the last three lines it printed. Bounded in height and width, so a fan-out
+  cannot flood your screen. It is a **display, never the result**.
 - **A definition's *instructions* are governed only by identity.** `agent:<name>` says which file may be
   spawned and the digest says which version ran, but nothing reads a body and judges what it says — the
   operator authorises a file, and its contents are their responsibility.

package/dist/executor.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Which executor runs a governed child — ADR-0031.
+ *
+ * `PI_GRANTS_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 declare const ENV_HERDR = "PI_GRANTS_HERDR";
+export type ExecutorKind = "herdr" | "process";
+export interface ExecutorChoice {
+    kind: ExecutorKind;
+    /** The operator named it: `PI_GRANTS_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 declare function needsProbe(raw: string | undefined): boolean;
+export declare function chooseExecutor(raw: string | undefined, probe: HerdrProbe | null): ExecutorChoice;
+//# sourceMappingURL=executor.d.ts.map

package/dist/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,eAAO,MAAM,SAAS,oBAAoB,CAAC;AAE3C,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;AAE/C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,uEAAuE;IACvE,MAAM,EAAE,OAAO,CAAC;IAChB,8DAA8D;IAC9D,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,sGAAsG;AACtG,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE3D;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,cAAc,CA6EhG"}

package/dist/executor.js

@@ -0,0 +1,93 @@
+/**
+ * Which executor runs a governed child — ADR-0031.
+ *
+ * `PI_GRANTS_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).
+ */
+export const ENV_HERDR = "PI_GRANTS_HERDR";
+/** `0` is the one value that needs no probe: the operator ruled herdr out, so asking is pure cost. */
+export function needsProbe(raw) {
+    return raw === undefined || raw === "1";
+}
+export function chooseExecutor(raw, probe) {
+    if (raw === "0") {
+        return {
+            kind: "process",
+            forced: true,
+            probed: false,
+            disclosure: "captured subprocess (PI_GRANTS_HERDR=0) — children have no terminal",
+        };
+    }
+    if (raw === "1") {
+        if (probe?.ok) {
+            return { kind: "herdr", forced: true, probed: true, disclosure: "herdr panes (PI_GRANTS_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_GRANTS_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_GRANTS_HERDR to let this session probe, or set PI_GRANTS_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_GRANTS_GATED` does.
+        return {
+            kind: "process",
+            forced: false,
+            probed: probe !== null,
+            disclosure: `captured subprocess — PI_GRANTS_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_GRANTS_HERDR=1 to demand panes.`,
+    };
+}
+//# sourceMappingURL=executor.js.map

package/dist/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,CAAC,MAAM,SAAS,GAAG,iBAAiB,CAAC;AAqB3C,sGAAsG;AACtG,MAAM,UAAU,UAAU,CAAC,GAAuB;IAChD,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,GAAG,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,GAAuB,EAAE,KAAwB;IAC9E,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;QAChB,OAAO;YACL,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,IAAI;YACZ,MAAM,EAAE,KAAK;YACb,UAAU,EAAE,qEAAqE;SAClF,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;QAChB,IAAI,KAAK,EAAE,EAAE,EAAE,CAAC;YACd,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,iCAAiC,EAAE,CAAC;QACtG,CAAC;QACD,yGAAyG;QACzG,yGAAyG;QACzG,yGAAyG;QACzG,uEAAuE;QACvE,MAAM,GAAG,GAAG,KAAK,EAAE,KAAK,IAAI,iCAAiC,CAAC;QAC9D,OAAO;YACL,IAAI,EAAE,OAAO;YACb,MAAM,EAAE,IAAI;YACZ,MAAM,EAAE,IAAI;YACZ,OAAO,EACL,4EAA4E,GAAG,KAAK;gBACpF,kGAAkG;gBAClG,0FAA0F;gBAC1F,6FAA6F;YAC/F,UAAU,EAAE,yCAAyC,GAAG,kCAAkC;SAC3F,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,qGAAqG;QACrG,yGAAyG;QACzG,4FAA4F;QAC5F,qDAAqD;QACrD,OAAO;YACL,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,KAAK;YACb,MAAM,EAAE,KAAK,KAAK,IAAI;YACtB,UAAU,EACR,yFAAyF;gBACzF,4EAA4E;SAC/E,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,EAAE,EAAE,EAAE,CAAC;QACd,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,2CAA2C,EAAE,CAAC;IACjH,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,wGAAwG;QACxG,4GAA4G;QAC5G,wGAAwG;QACxG,0GAA0G;QAC1G,8BAA8B;QAC9B,EAAE;QACF,2GAA2G;QAC3G,sGAAsG;QACtG,+FAA+F;QAC/F,OAAO;YACL,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,KAAK;YACb,MAAM,EAAE,KAAK;YACb,UAAU,EAAE,4CAA4C;SACzD,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,KAAK;QACb,MAAM,EAAE,IAAI;QACZ,kGAAkG;QAClG,yGAAyG;QACzG,UAAU,EACR,mDAAmD,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK;YAC9F,wCAAwC;KAC3C,CAAC;AACJ,CAAC"}

package/dist/herdr-cli.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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`).
+ */
+/** 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 declare const defaultExec: HerdrExec;
+/**
+ * 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 declare function parseReply(reply: {
+    stdout: string;
+    stderr: string;
+}): {
+    result?: Record<string, unknown>;
+    error?: string;
+};
+/** Bound on the session-start probe. Short: it sits in front of the operator's first prompt. */
+export declare 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 declare function probeHerdr(options?: {
+    exec?: HerdrExec;
+    timeoutMs?: number;
+}): Promise<HerdrProbe>;
+/** herdr's own variable, set in every pane it creates. Measured 2026-08-17; documented nowhere. */
+export declare const ENV_PARENT_WORKSPACE = "HERDR_WORKSPACE_ID";
+/** The operator's explicit override. Defined here because this is the only module that reads it. */
+export declare 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 declare function resolveWorkspace(env: NodeJS.ProcessEnv): string | undefined;
+//# sourceMappingURL=herdr-cli.d.ts.map

package/dist/herdr-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-cli.d.ts","sourceRoot":"","sources":["../src/herdr-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,oGAAoG;AACpG,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE7G,eAAO,MAAM,WAAW,EAAE,SAatB,CAAC;AAEL;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAW1H;AAED,gGAAgG;AAChG,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,sGAAsG;IACtG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAAC,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,SAAS,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAsB5G;AAED,mGAAmG;AACnG,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AAEzD,oGAAoG;AACpG,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAE/D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,GAAG,SAAS,CAI3E"}

package/dist/herdr-cli.js

@@ -0,0 +1,113 @@
+/**
+ * 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";
+export const defaultExec = (args) => new Promise((settle) => {
+    execFile("herdr", args, { maxBuffer: 32 * 1024 * 1024 }, (error, stdout, stderr) => {
+        const raw = error?.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) {
+    try {
+        const parsed = JSON.parse(reply.stdout);
+        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;
+/**
+ * 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 = {}) {
+    const exec = options.exec ?? defaultExec;
+    const timeoutMs = options.timeoutMs ?? PROBE_TIMEOUT_MS;
+    let timer;
+    try {
+        return await Promise.race([
+            exec(["tab", "list"]).then((reply) => {
+                const parsed = parseReply(reply);
+                return parsed.error ? { ok: false, error: parsed.error } : { ok: true };
+            }),
+            new Promise((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) {
+    const explicit = env[ENV_HERDR_WORKSPACE]?.trim();
+    if (explicit)
+        return explicit;
+    return env[ENV_PARENT_WORKSPACE]?.trim() || undefined;
+}
+//# sourceMappingURL=herdr-cli.js.map

package/dist/herdr-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-cli.js","sourceRoot":"","sources":["../src/herdr-cli.ts"],"names":[],"mappings":"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"}

package/dist/herdr-name.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Naming a herdr agent: the grammar herdr enforces, and uniqueness it does not.
+ *
+ * Split out of `src/run-herdr.ts` at the 400-line ceiling, and a real seam: both rules below come from **herdr's
+ * own validation and lifecycle**, not from anything this package decides. Two shipping defects lived here, and
+ * both were invisible to every test because the unit fake accepts whatever name it is handed and the integration
+ * suite never reaches a real herdr spawn. They surfaced from two real spawns against the live daemon.
+ */
+/**
+ * Make a herdr agent name that is **valid** and cannot collide with a live one.
+ *
+ * **Validity is a separate, PRE-EXISTING defect, and it is the more serious half.** Callers build a name as
+ * `${definition}-${childId}`, and a ledger child id is hierarchical — `d0.1`, `d0.1.2` (ADR-0008/F8). Those dots
+ * are **not in herdr's grammar**, so `agent start review-d0.1 …` is rejected with `invalid_agent_name`. Every
+ * `delegate({agent})` on the herdr path has therefore failed at `agent start` since the executor was written.
+ *
+ * Nothing could see it. The unit fake accepts any name it is handed, and the integration suite never reaches a
+ * real herdr spawn — so both were green while the feature could not work. It surfaced only by running two real
+ * spawns against the live daemon, which is the argument for doing that at all.
+ *
+ * **Measured, and a shipping defect without it.** herdr binds an agent name to its **tab**, and only closing
+ * the tab frees the name: a second `agent start` with a name still held returns
+ * `agent_name_taken: agent <name> is already used; … tab_id=…`. `herdr agent stop` does not exist (see
+ * `cleanup`), so nothing else releases it.
+ *
+ * Callers build a name from the definition and the ledger child id — and for a plain blocking `delegate` that
+ * id is **constant** (`d0.1`, index 0 of the session), so every delegation in a session asked for the same
+ * name. That was harmless while the pane closed at the end of each call. Once ADR-0032 kept panes alive to
+ * `agent_settled`, the **first** delegation of a turn worked and every later one failed with
+ * `agent_name_taken`, on the executor ADR-0031 had just made the default.
+ *
+ * Uniquified HERE rather than at the call site, so no caller can forget: the constraint belongs to herdr, and
+ * this module is the only thing that talks to herdr. The suffix is a counter rather than a random token so a
+ * pane label stays readable and reproducible within a run.
+ */
+export declare function uniqueAgentName(base: string): string;
+//# sourceMappingURL=herdr-name.d.ts.map

package/dist/herdr-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-name.d.ts","sourceRoot":"","sources":["../src/herdr-name.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAapD"}

package/dist/herdr-name.js

@@ -0,0 +1,59 @@
+/**
+ * Naming a herdr agent: the grammar herdr enforces, and uniqueness it does not.
+ *
+ * Split out of `src/run-herdr.ts` at the 400-line ceiling, and a real seam: both rules below come from **herdr's
+ * own validation and lifecycle**, not from anything this package decides. Two shipping defects lived here, and
+ * both were invisible to every test because the unit fake accepts whatever name it is handed and the integration
+ * suite never reaches a real herdr spawn. They surfaced from two real spawns against the live daemon.
+ */
+/** Monotonic within this process. See `uniqueAgentName`. */
+let spawnSeq = 0;
+/**
+ * herdr's agent-name grammar, measured from its own rejection message.
+ *
+ * `agent name must start with a lowercase letter and contain only lowercase letters, digits, '-' or '_'
+ * (1-32 characters)`.
+ */
+const AGENT_NAME_MAX = 32;
+/**
+ * Make a herdr agent name that is **valid** and cannot collide with a live one.
+ *
+ * **Validity is a separate, PRE-EXISTING defect, and it is the more serious half.** Callers build a name as
+ * `${definition}-${childId}`, and a ledger child id is hierarchical — `d0.1`, `d0.1.2` (ADR-0008/F8). Those dots
+ * are **not in herdr's grammar**, so `agent start review-d0.1 …` is rejected with `invalid_agent_name`. Every
+ * `delegate({agent})` on the herdr path has therefore failed at `agent start` since the executor was written.
+ *
+ * Nothing could see it. The unit fake accepts any name it is handed, and the integration suite never reaches a
+ * real herdr spawn — so both were green while the feature could not work. It surfaced only by running two real
+ * spawns against the live daemon, which is the argument for doing that at all.
+ *
+ * **Measured, and a shipping defect without it.** herdr binds an agent name to its **tab**, and only closing
+ * the tab frees the name: a second `agent start` with a name still held returns
+ * `agent_name_taken: agent <name> is already used; … tab_id=…`. `herdr agent stop` does not exist (see
+ * `cleanup`), so nothing else releases it.
+ *
+ * Callers build a name from the definition and the ledger child id — and for a plain blocking `delegate` that
+ * id is **constant** (`d0.1`, index 0 of the session), so every delegation in a session asked for the same
+ * name. That was harmless while the pane closed at the end of each call. Once ADR-0032 kept panes alive to
+ * `agent_settled`, the **first** delegation of a turn worked and every later one failed with
+ * `agent_name_taken`, on the executor ADR-0031 had just made the default.
+ *
+ * Uniquified HERE rather than at the call site, so no caller can forget: the constraint belongs to herdr, and
+ * this module is the only thing that talks to herdr. The suffix is a counter rather than a random token so a
+ * pane label stays readable and reproducible within a run.
+ */
+export function uniqueAgentName(base) {
+    spawnSeq += 1;
+    const suffix = `-${spawnSeq}`;
+    const cleaned = base
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-") // dots from a child id, and anything else outside the grammar
+        .replace(/-{2,}/g, "-")
+        .replace(/^[^a-z]+/, ""); // must START with a lowercase letter, so a leading digit or dash goes
+    // Truncated so the whole name fits, and trimmed of a trailing separator so the join stays readable. The
+    // fallback covers a base that sanitises to nothing at all (a definition named entirely in non-Latin script).
+    const room = AGENT_NAME_MAX - suffix.length;
+    const head = cleaned.slice(0, room).replace(/[-_]+$/, "") || "agent";
+    return `${head}${suffix}`;
+}
+//# sourceMappingURL=herdr-name.js.map

package/dist/herdr-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-name.js","sourceRoot":"","sources":["../src/herdr-name.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,4DAA4D;AAC5D,IAAI,QAAQ,GAAG,CAAC,CAAC;AAEjB;;;;;GAKG;AACH,MAAM,cAAc,GAAG,EAAE,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,QAAQ,IAAI,CAAC,CAAC;IACd,MAAM,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;IAC9B,MAAM,OAAO,GAAG,IAAI;SACjB,WAAW,EAAE;SACb,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC,8DAA8D;SAC5F,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC,sEAAsE;IAClG,wGAAwG;IACxG,6GAA6G;IAC7G,MAAM,IAAI,GAAG,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC;IACrE,OAAO,GAAG,IAAI,GAAG,MAAM,EAAE,CAAC;AAC5B,CAAC"}