pi-daddy 0.15.0 → 0.17.0

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/fanout.d.ts

@@ -28,6 +28,15 @@ export declare const DEFAULT_FANOUT_BUDGET = 8;
  * the total bound. Both are needed because they answer different questions.
  */
 export declare const MAX_CHILDREN_PER_CALL = 8;
+/**
+ * Steps a single `delegate_chain` may contain — ADR-0033.
+ *
+ * **Derived from `MAX_CHILDREN_PER_CALL` so the two cannot drift.** A chain is not concurrent, so the blast-radius
+ * argument for that constant does not apply directly; what does apply is that one tool call should not be able to
+ * create an unbounded number of descendants, and eight is already a long pipeline. Sharing the number also means an
+ * operator learns one bound rather than two.
+ */
+export declare const MAX_CHAIN_STEPS = 8;
 /** Read the budget from the environment, failing to the default on absent *or* malformed input. */
 export declare function budgetFromEnv(raw: string | undefined): number;
 export interface BudgetSplit {

package/dist/fanout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fanout.d.ts","sourceRoot":"","sources":["../src/fanout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,oGAAoG;AACpG,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,mGAAmG;AACnG,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM7D;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAmBtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpE"}
+{"version":3,"file":"fanout.d.ts","sourceRoot":"","sources":["../src/fanout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,oGAAoG;AACpG,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,IAAwB,CAAC;AAErD,mGAAmG;AACnG,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM7D;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAmBtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpE"}

package/dist/fanout.js

@@ -29,6 +29,15 @@ export const DEFAULT_FANOUT_BUDGET = 8;
  * the total bound. Both are needed because they answer different questions.
  */
 export const MAX_CHILDREN_PER_CALL = 8;
+/**
+ * Steps a single `delegate_chain` may contain — ADR-0033.
+ *
+ * **Derived from `MAX_CHILDREN_PER_CALL` so the two cannot drift.** A chain is not concurrent, so the blast-radius
+ * argument for that constant does not apply directly; what does apply is that one tool call should not be able to
+ * create an unbounded number of descendants, and eight is already a long pipeline. Sharing the number also means an
+ * operator learns one bound rather than two.
+ */
+export const MAX_CHAIN_STEPS = MAX_CHILDREN_PER_CALL;
 /** Read the budget from the environment, failing to the default on absent *or* malformed input. */
 export function budgetFromEnv(raw) {
     const parsed = parseBound(raw);

package/dist/fanout.js.map

@@ -1 +1 @@
-{"version":3,"file":"fanout.js","sourceRoot":"","sources":["../src/fanout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,oGAAoG;AACpG,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC,mGAAmG;AACnG,MAAM,UAAU,aAAa,CAAC,GAAuB;IACnD,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC/B,wGAAwG;IACxG,sGAAsG;IACtG,yDAAyD;IACzD,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,MAAM,CAAC;AAClG,CAAC;AASD;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,KAAa;IACvD,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oCAAoC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IAChG,IAAI,KAAK,GAAG,qBAAqB,EAAE,CAAC;QAClC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG,KAAK,2CAA2C,qBAAqB,EAAE;YAClF,QAAQ,EAAE,CAAC;SACZ,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,GAAG,KAAK,EAAE,CAAC;QACnB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,6BAA6B,KAAK,wBAAwB,MAAM,6BAA6B;gBAC7F,mEAAmE;YACrE,QAAQ,EAAE,CAAC;SACZ,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,KAAa;IAC1D,OAAO,GAAG,QAAQ,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;AACpC,CAAC"}
+{"version":3,"file":"fanout.js","sourceRoot":"","sources":["../src/fanout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,oGAAoG;AACpG,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,qBAAqB,CAAC;AAErD,mGAAmG;AACnG,MAAM,UAAU,aAAa,CAAC,GAAuB;IACnD,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC/B,wGAAwG;IACxG,sGAAsG;IACtG,yDAAyD;IACzD,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,MAAM,CAAC;AAClG,CAAC;AASD;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,KAAa;IACvD,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oCAAoC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IAChG,IAAI,KAAK,GAAG,qBAAqB,EAAE,CAAC;QAClC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG,KAAK,2CAA2C,qBAAqB,EAAE;YAClF,QAAQ,EAAE,CAAC;SACZ,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,GAAG,KAAK,EAAE,CAAC;QACnB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,6BAA6B,KAAK,wBAAwB,MAAM,6BAA6B;gBAC7F,mEAAmE;YACrE,QAAQ,EAAE,CAAC;SACZ,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,KAAa;IAC1D,OAAO,GAAG,QAAQ,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;AACpC,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"}

package/dist/herdr-poll.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 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 { type HerdrExec } from "./herdr-cli.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;
+    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;
+    /** 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;
+}
+/** How often to poll `agent get` while waiting for the child to settle. */
+export declare const POLL_INTERVAL_MS = 750;
+/** Lines of pane tail reported per poll. Matches the status block's own tail, so nothing is fetched unused. */
+export declare 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".
+ */
+export declare function waitForSettled(exec: HerdrExec, request: PollTarget, before: number, deadline: number, maxOutputBytes: number): Promise<{
+    status?: string;
+    timedOut?: boolean;
+    aborted?: boolean;
+    spawnError?: string;
+}>;
+/**
+ * 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 declare function tailLines(snapshot: string, keep: number): string[];
+/**
+ * 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 declare function readPane(exec: HerdrExec, name: string, maxOutputBytes: number): Promise<{
+    text: string;
+    truncated: boolean;
+    readFailed?: string;
+}>;
+//# sourceMappingURL=herdr-poll.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-poll.d.ts","sourceRoot":"","sources":["../src/herdr-poll.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACvC,oGAAoG;IACpG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kGAAkG;IAClG,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAKD,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,+GAA+G;AAC/G,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAoC1F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAalE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAuBpE"}