pi-daddy 0.28.0 → 0.32.0

package/src/executors/run-herdr.ts

@@ -0,0 +1,426 @@
+/**
+ * Run a governed child in a herdr pane — ADR-0016 point 6.
+ *
+ * The second executor for the same plan. `runChild` spawns `pi` directly and captures its stdout;
+ * `runHerdrPane` asks herdr to launch it in a visible, attachable terminal pane. `planSpawn` produces the
+ * argv either way, so the grant is identical and only the *place it runs* differs.
+ *
+ * **Why go through herdr's CLI rather than the third-party `pi-herdr` extension.** That extension exposes
+ * `agentArgs` and `env` as MODEL-facing tool parameters (R-30), which hands a model an argv array and the
+ * environment variable the grant travels on. Here the model chooses a definition and a task; this package
+ * builds the argv. Measured facts this relies on (`docs/probes/g16-herdr`):
+ *
+ *  - `herdr agent start … -- <args>` delivers argv **verbatim**, echoed back in the reply.
+ *  - `--tools` is enforced inside a pane exactly as it is for a direct spawn; `--no-tools` yields none.
+ *  - `herdr agent start` has **no `--env`**, but `tab create` / `pane split` do, and a pane's environment
+ *    reaches the shell that launches the agent — verified by reading `$PI_DADDY_GRANT` back out of a
+ *    pane created with it. That is how the grant, depth and ledger path propagate on this path.
+ *
+ * **What a pane is not: a boundary.** It is a terminal. `--tools` remains the enforcement point, ADR-0012's
+ * `bash` escape is unchanged, and a pane is *attachable by design*, so a human can type into a governed
+ * child. Humans are not this project's threat model, but nothing here should be read as containing one.
+ */
+
+import { rm } from "node:fs/promises";
+import { runWithFinalizers } from "../governance/finalization.ts";
+import type { ChildRunResult } from "../kernel/run-child.ts";
+import { DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_TIMEOUT_MS } from "../kernel/run-child.ts";
+import { MAX_OPEN_PANES, markPaneSettled, trackPane, trimOpenPanes, untrackPane } from "./pane-reaper.ts";
+import { defaultExec, parseReply, type HerdrExec } from "./herdr-cli.ts";
+import {
+  FRESH_LIFECYCLE_TIMEOUT_MS,
+  readPane,
+  waitForLifecycleBaseline,
+  waitForSettled,
+  observeHerdrSession,
+  type PollTarget,
+} from "./herdr-poll.ts";
+import { stageSystemPrompt } from "./herdr-stage.ts";
+import { uniqueAgentName } from "./herdr-name.ts";
+import { bundledHerdrPiLifecycleExtension } from "./herdr-pi-lifecycle.ts";
+import { startHerdrAgent } from "./herdr-start.ts";
+
+/**
+ * Re-exported so importers of the executor still reach the protocol at the name they always used.
+ *
+ * Deliberate rather than lazy: `test/run-herdr.test.ts` imports `HerdrExec` from here and must pass
+ * **unmodified** across this extraction — that is the only available proof the move changed no behaviour.
+ */
+export { type HerdrExec, parseReply } from "./herdr-cli.ts";
+/** Re-exported: `splitSystemPrompt` moved to `./herdr-stage.ts` under the ceiling, its tests import it here. */
+export { splitSystemPrompt, stageSystemPrompt } from "./herdr-stage.ts";
+/** Re-exported: the name rules moved to `./herdr-name.ts` under the ceiling; tests import them here. */
+export { uniqueAgentName } from "./herdr-name.ts";
+/** Re-exported after startup retry extraction; existing executor importers keep this public constant. */
+export { PANE_READY_POLL_MS } from "./herdr-start.ts";
+/**
+ * Re-exported so `test/run-herdr.test.ts` and any importer keep reaching these where they always were.
+ *
+ * `POLL_INTERVAL_MS` and `newSuffix` moved to `./herdr-poll.ts` under the 400-line ceiling; the names are part
+ * of this module's surface and moving a file should not move an export.
+ */
+export {
+  DEFAULT_SNAPSHOT_LINES,
+  POLL_INTERVAL_MS,
+  readPane,
+  tailLines,
+  waitForLifecycleBaseline,
+  waitForSettled,
+  type PollTarget,
+} from "./herdr-poll.ts";
+
+export interface HerdrRunRequest {
+  /** `planSpawn` args **without** the prompt — see `prompt`. */
+  args: string[];
+  /**
+   * The task, delivered with `herdr agent prompt` rather than as an argv element.
+   *
+   * This is strictly safer than the direct-spawn path, which has to defend a model-authored string from
+   * pi's argv parser by prefixing a space (`neutralisePrompt`, `docs/probes/g1-argv`). Here the task never
+   * reaches argv at all, so there is no parser in front of it.
+   */
+  prompt: string;
+  /** Grant/depth/ledger variables. Set on the PANE, which the agent's shell inherits. */
+  env: Record<string, string>;
+  cwd: string;
+  /** Unique pane and agent name. */
+  name: string;
+  /** herdr workspace to create the tab in. Omitted lets herdr choose. */
+  workspace?: string;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  /** Inactivity bound and its progress probe (PR 3e); see `PollTarget`. */
+  idleTimeoutMs?: number;
+  activityProbe?: PollTarget["activityProbe"];
+  maxOutputBytes?: number;
+  /**
+   * Leave the pane open after the run so a human can read or resume it.
+   *
+   * Default **false**: a fan-out that leaks a pane per child fills the operator's workspace, and
+   * `docs/probes/g16-herdr` records that panes are not trivially closable once orphaned.
+   */
+  keepPane?: boolean;
+  exec?: HerdrExec;
+  /**
+   * The pane's last few lines, re-reported every poll — a SNAPSHOT the consumer REPLACES, not appends.
+   *
+   * **Display only**, exactly as in `runChild`: the child's answer is still the returned `text`. Unlike
+   * `runChild`'s `onOutput`, this is not a stream: `agent read` returns a snapshot of a bounded terminal, and
+   * the previous append-shaped design produced an 89,000× amplification once a pane scrolled or passed the
+   * output cap. See `tailLines` in `./herdr-poll.ts`.
+   *
+   * Exceptions are swallowed; a renderer must not be able to break a governed run.
+   */
+  onSnapshot?: (lines: string[]) => void;
+  /** Available pane snapshots only, not a structured session transcript. Never awaited. */
+  onObservation?: (bytes: Uint8Array) => void;
+  /** How many pane lines to report per poll. Defaults to `DEFAULT_SNAPSHOT_LINES`. */
+  snapshotLines?: number;
+  /**
+   * The pane id, reported as soon as `tab create` returns it.
+   *
+   * Separate from `onOutput` because it arrives once and arrives *early*: it is what lets the parent print a
+   * name a human can switch to **while the child is alive**, which is the whole point of the pane surviving.
+   */
+  onPane?: (paneId: string, agentName: string) => void;
+  /** Called only after agent start and prompt both succeed; pane creation alone is still `starting`. */
+  onRunning?: (paneId: string, agentName: string) => void;
+  /** Security hook for attaching a writer lease to the tab. Unlike display callbacks, errors fail the run. */
+  onTab?: (tabId: string) => void;
+  /** Optional observation, unlike the required lease hook above. */
+  onNativeTab?: (tabId: string) => void;
+  onSessionReference?: PollTarget["onSessionReference"];
+  /** Close even a settled pane before releasing a writer lease; no post-lease prompt may remain live. */
+  closeOnSettle?: boolean;
+  /** Poll cadence override. Exists so tests do not wait `POLL_INTERVAL_MS` per state transition. */
+  pollIntervalMs?: number;
+}
+
+export class HerdrWriterCloseError extends Error {
+  constructor(tabId: string) {
+    super(`herdr writer tab ${tabId} could not be closed; retaining its workspace lease`);
+    this.name = "HerdrWriterCloseError";
+  }
+}
+
+/**
+ * Run one governed child in a pane and return its output.
+ *
+ * Deliberately returns `ChildRunResult` — the same shape as `runChild` — so the extension can choose an
+ * executor without knowing which one it got.
+ */
+export async function runHerdrPane(request: HerdrRunRequest): Promise<ChildRunResult> {
+  const exec = request.exec ?? defaultExec;
+  const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxOutputBytes = request.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const deadline = Date.now() + timeoutMs;
+  const empty: ChildRunResult = { code: null, text: "", truncated: false, timedOut: false, aborted: false };
+
+  // A-R3's rule, kept on this path too: checked BEFORE anything is created. An `AbortSignal` does not
+  // replay, so a check after the first `await` cannot see an abort that already happened — and we would
+  // have left a pane behind for a run that was never wanted.
+  if (request.signal?.aborted) return { ...empty, aborted: true };
+
+  // `--print` makes pi process the prompt and exit, so it never reaches the interactive readiness that
+  // `herdr agent start` waits for — the agent is simply never detected. Found by the first end-to-end run,
+  // which failed inside herdr with an empty reply. Caught here instead, naming the flag, because a
+  // mismatch between a plan and its executor is a caller bug and should read like one.
+  if (request.args.includes("--print") || request.args.includes("-p")) {
+    return {
+      ...empty,
+      spawnError:
+        "herdr needs an INTERACTIVE agent, but the plan contains --print, which makes pi exit immediately " +
+        "and never be detected. Build the plan with `print: false` for this executor.",
+    };
+  }
+
+  // A multi-line system prompt becomes a file; see `stageSystemPrompt`. Removed on every path that does not
+  // end up tracking a pane, because only a tracked pane's dir is reachable by a sweep.
+  const staged = await stageSystemPrompt(request.args);
+  if (staged.error) return { ...empty, spawnError: staged.error };
+  const promptDir = staged.promptDir;
+  let lifecycleExtension: string;
+  try {
+    lifecycleExtension = bundledHerdrPiLifecycleExtension();
+  } catch (error) {
+    if (promptDir) await rm(promptDir, { recursive: true, force: true }).catch(() => undefined);
+    return { ...empty, spawnError: String(error) };
+  }
+  // Pi's `--no-extensions` disables discovery, not this explicit, package-pinned lifecycle reporter. It
+  // registers no tools; pi's existing `--tools` allowlist remains the governed child surface.
+  const effectiveArgs = [...staged.args, "-e", lifecycleExtension];
+
+  const create = ["tab", "create", "--label", request.name, "--cwd", request.cwd];
+  if (request.workspace) create.push("--workspace", request.workspace);
+  for (const [key, value] of Object.entries(request.env)) create.push("--env", `${key}=${value}`);
+
+  // The name herdr will actually know this agent by. Every later command in this function uses `agentName`,
+  // never `request.name`, which is only a base.
+  const agentName = uniqueAgentName(request.name);
+  const created = parseReply(await exec(create));
+  if (created.error) {
+    // **The staged prompt is removed here too.** This path returned without touching it, and nothing tracked it,
+    // so neither sweep could ever reach it — a permanent `/tmp/grants-herdr-*` per failed `tab create`. Measured
+    // by a reviewer, who also found leftovers from earlier runs already sitting in `/tmp`. It is the most likely
+    // failure on a machine where herdr is not running, i.e. the common case.
+    if (promptDir) await rm(promptDir, { recursive: true, force: true }).catch(() => undefined);
+    return { ...empty, spawnError: `herdr tab create failed: ${created.error}` };
+  }
+
+  const rootPane = (created.result?.root_pane ?? {}) as { pane_id?: string; tab_id?: string };
+  const paneId = rootPane.pane_id;
+  const tabId = rootPane.tab_id;
+  if (tabId) {
+    try {
+      request.onNativeTab?.(tabId);
+    } catch {
+      /* observation only */
+    }
+  }
+  // **Tracked BEFORE the pane-id check, not after.** A tab can exist from the moment this reply is parsed,
+  // so registering later leaves a window — one herdr round-trip wide — in which a killed process orphans a
+  // tab nothing would reap. The normal path had no such window and the error path did, which is backwards:
+  // the error path is the one more likely to be taken while something is already going wrong.
+  if (tabId && request.keepPane && promptDir) {
+    // `keepPane` keeps the PANE, and the staged prompt with it — a human inspecting the pane may want to see
+    // what the child was told. Registered `settled` so the trim never touches it, but registered nonetheless so
+    // the `exit` sweep can remove the temp dir rather than leaving one per kept pane forever. Measured: this
+    // path leaked a `/tmp/grants-herdr-*` that neither sweep could reach.
+    trackPane({ tab: tabId, name: agentName, promptDir, settled: true, keepTab: true });
+  }
+  if (tabId && !request.keepPane) trackPane({ tab: tabId, name: agentName, promptDir });
+
+  // Attach before the first post-create await. If the parent dies after this point, the independent lock
+  // helper closes the tab before releasing the writer lease.
+  if (request.onTab) {
+    try {
+      if (!tabId) throw new Error("herdr returned no tab id for writer-lease attachment");
+      request.onTab(tabId);
+    } catch (error) {
+      if (tabId && !request.keepPane) {
+        const closed = await exec(["tab", "close", tabId]).catch(() => undefined);
+        if (closed === undefined || parseReply(closed).error) throw new HerdrWriterCloseError(tabId);
+      }
+      return { ...empty, spawnError: `workspace writer lease could not attach to herdr tab (${String(error)})` };
+    }
+  }
+
+  if (tabId && !request.keepPane) {
+    // ADR-0032: panes now live until `agent_settled`, so they accumulate across one agent run — and a plain
+    // blocking `delegate` spends nothing from the fan-out budget, so the count is otherwise unbounded. Trimmed
+    // here rather than at settle time so the bound holds DURING a long run, not only after it.
+    const dropped = await trimOpenPanes(exec);
+    if (dropped.length > 0 && request.onSnapshot) {
+      try {
+        request.onSnapshot([
+          `[grants] closed ${dropped.length} older pane(s) to stay within the ${MAX_OPEN_PANES}-pane limit: ` +
+            dropped.join(", "),
+        ]);
+      } catch {
+        /* display only */
+      }
+    }
+  }
+
+  if (!paneId) {
+    // The tab may exist even though the reply carried no pane id, and this return used to be BEFORE
+    // `cleanup` was defined — so the one path where herdr half-succeeded was the one that leaked a tab.
+    if (tabId && !request.keepPane) {
+      const reply = await exec(["tab", "close", tabId]).catch(() => undefined);
+      // Same rule as `cleanup`: untrack only what is provably gone, so a close herdr refused stays the
+      // reaper's problem rather than being dropped on the assumption that it worked.
+      if (reply === undefined || parseReply(reply).error) {
+        if (request.closeOnSettle) throw new HerdrWriterCloseError(tabId);
+      } else {
+        untrackPane(tabId);
+      }
+    }
+    // There is no agent in this pane to ask, so the staged prompt has no reader — remove it. Kept only under
+    // `keepPane`, where the operator asked to inspect whatever exists.
+    if (promptDir && !request.keepPane) await rm(promptDir, { recursive: true, force: true }).catch(() => undefined);
+    return { ...empty, spawnError: "herdr tab create returned no pane id" };
+  }
+
+  /**
+   * End this call. **A child that did not settle has its tab closed, because that is the only way to stop it.**
+   *
+   * ADR-0032 keeps a pane alive past its tool call so a human can read it. The original version of that also
+   * called `herdr agent stop` and claimed *"the agent is still stopped here… what survives is a terminal, not a
+   * running descendant."* **`herdr agent stop` does not exist.** Measured against herdr 0.7.5: the `agent`
+   * subcommands are `list get read send-keys prompt rename focus wait attach start explain`, and `agent stop`
+   * prints the usage banner and exits 0 — which `defaultExec` reports as a success, so nothing ever noticed.
+   * `docs/probes/g16-herdr/README.md` asserted it worked, in a *How to rerun* block that was never run.
+   *
+   * So there is exactly one kill available: closing the tab. That forces the distinction below.
+   *
+   *  - **Settled cleanly** (`idle`/`done`/`blocked` with an advanced counter): the child has answered and is
+   *    sitting idle. Its pane stays, which is the whole feature, and the `agent_settled` sweep reaps it.
+   *  - **Anything else** — a timeout, an abort, a failed start, a failed prompt, an unreadable pane: the child
+   *    may still be **working, with its grant**, after its tool call has already returned a result. Leaving
+   *    that running is a governance failure, not an untidy workspace, so the tab is closed here and now.
+   *
+   * `keepPane` is the operator overriding the whole question, and it is honoured either way: nothing is tracked
+   * and nothing is closed, which is what "keep this pane for me to inspect" has to mean.
+   */
+  const cleanup = async (settledCleanly: boolean) => {
+    if (request.keepPane) return;
+    if (settledCleanly && !request.closeOnSettle) return;
+    if (!tabId) return;
+    const reply = await exec(["tab", "close", tabId]).catch(() => undefined);
+    // Untracked only if provably closed — R-62's rule. A writer close failure must retain the lease;
+    // otherwise a still-promptable pane can overlap the successor admitted by a clean release.
+    if (reply === undefined || parseReply(reply).error) {
+      if (request.closeOnSettle) throw new HerdrWriterCloseError(tabId);
+      return;
+    }
+    untrackPane(tabId);
+    if (promptDir) await rm(promptDir, { recursive: true, force: true }).catch(() => undefined);
+  };
+
+  // ADR-0032: the pane exists and has a name, so tell the caller NOW. A pane id that arrives with the result is
+  // useless — the point is switching to a child while it is still working. Guarded because a renderer must not
+  // be able to strand a pane we have already created.
+  if (request.onPane) {
+    try {
+      request.onPane(paneId, agentName);
+    } catch {
+      /* display only */
+    }
+  }
+
+  // Set only on the one path where the child answered and stopped working. Everything else — including an
+  // early `return` from a failed start or prompt — leaves it false, so `cleanup` closes the tab.
+  let settledCleanly = false;
+
+  return runWithFinalizers(async () => {
+    const started = await startHerdrAgent(exec, agentName, paneId, effectiveArgs, deadline);
+    if (started.error) return { ...empty, spawnError: `herdr agent start failed: ${started.error}` };
+
+    // The bundled reporter queues its initial idle state asynchronously. Establish its native-authority
+    // baseline before prompting, otherwise that initial report could advance the counter after prompt and
+    // be mistaken for settlement.
+    const baseline = await waitForLifecycleBaseline(
+      exec,
+      { ...request, name: agentName, nativePaneId: paneId },
+      Math.min(deadline, Date.now() + FRESH_LIFECYCLE_TIMEOUT_MS),
+    );
+    if (baseline.aborted) return { ...empty, aborted: true };
+    if (baseline.spawnError || baseline.before === undefined)
+      return { ...empty, spawnError: baseline.spawnError ?? "Herdr lifecycle baseline is unavailable" };
+    observeHerdrSession(started.result?.agent, paneId, request.onSessionReference);
+
+    const prompted = parseReply(await exec(["agent", "prompt", agentName, request.prompt]));
+    if (prompted.error) return { ...empty, spawnError: `herdr agent prompt failed: ${prompted.error}` };
+    if (request.onRunning) {
+      try {
+        request.onRunning(paneId, agentName);
+      } catch {
+        /* display/observation only */
+      }
+    }
+
+    const settled = await waitForSettled(
+      exec,
+      { ...request, name: agentName, nativePaneId: paneId },
+      baseline.before,
+      deadline,
+      maxOutputBytes,
+    );
+    if (settled.aborted || settled.timedOut) {
+      // Still read: a timed-out child usually produced something, and a partial answer labelled partial is
+      // more useful than none. R-03's rule — a missing result must never look like an empty one.
+      const partial = await readPane(exec, agentName, maxOutputBytes);
+      if (!partial.readFailed) {
+        try {
+          request.onObservation?.(Buffer.from(partial.text));
+        } catch {
+          /* observation only */
+        }
+      }
+      return { ...empty, ...settled, text: partial.readFailed ? "" : partial.text, truncated: partial.truncated };
+    }
+    if (settled.spawnError) return { ...empty, spawnError: settled.spawnError };
+
+    const out = await readPane(exec, agentName, maxOutputBytes);
+    // **A failed read is a failed spawn, not an empty answer.** This branch used to return `readPane`'s own
+    // diagnostic as `text` with `code: 0`, so the orchestrator received
+    // `[grants] could not read the agent pane: …` **as the sub-agent's report** — R-03 exactly, and measured.
+    // The child may well have done its work; what we cannot do is claim to know what it said.
+    if (out.readFailed) {
+      return {
+        ...empty,
+        spawnError:
+          `the child settled but its pane could not be read (${out.readFailed}), so its answer is unknown. ` +
+          `The work may have been done — check pane ${paneId} if it is still open.`,
+      };
+    }
+    try {
+      request.onObservation?.(Buffer.from(out.text));
+    } catch {
+      /* observation only */
+    }
+    settledCleanly = true;
+    // The trim may now reclaim this pane if the cap is exceeded. Until this point it must not: closing the tab
+    // kills the child, and the child was still working.
+    if (tabId) markPaneSettled(tabId);
+    return {
+      code: settled.status === "blocked" ? 1 : 0,
+      // `truncated` is returned in the result too, but it was never SAID on this path, so a model received a
+      // tail with no indication that a head existed. The direct executor has always flagged it; a delegation
+      // that silently drops the first megabyte of an answer is the same defect wearing the other executor.
+      text: [
+        out.truncated ? `[grants] this pane exceeded the output cap; only its most recent output is below.\n` : "",
+        out.text,
+        settled.status === "blocked" ? `\n\n[grants] this agent is BLOCKED waiting for a human in pane ${paneId}.` : "",
+      ].join(""),
+      truncated: out.truncated,
+      timedOut: false,
+      aborted: false,
+    };
+  }, [
+    {
+      label: "herdr pane finalizer failed",
+      run: () => cleanup(settledCleanly),
+    },
+  ]);
+}

package/src/governance/approval-prompt.ts

@@ -0,0 +1,225 @@
+/**
+ * The approval dialog — the only place a human enters the capability-governance path.
+ *
+ * Kept out of `extensions/grants.ts` deliberately: that file is wiring only, and this holds decisions
+ * (what to offer, what a dismissal means, what happens with nobody watching) that must be testable
+ * without pi. `ApprovalUI` is the minimal slice of pi's `ExtensionUIContext` needed here, so a test can
+ * supply a plain object.
+ *
+ * Everything here denies on uncertainty. pi already agrees: in non-interactive modes it installs a
+ * no-op UI context whose `select` resolves undefined, so even a missed `hasUI` check would deny.
+ */
+
+import { approvalKey, offeredScopes, type ApprovalPath, type ApprovalScope } from "../kernel/approval.ts";
+import type { Capability } from "../kernel/resolve.ts";
+
+/** The slice of pi's `ExtensionUIContext` this module needs. */
+export interface ApprovalUI {
+  select(
+    title: string,
+    options: string[],
+    opts?: { timeout?: number; signal?: AbortSignal },
+  ): Promise<string | undefined>;
+  notify(message: string, type?: "info" | "warning" | "error"): void;
+}
+
+export const DENY_LABEL = "Deny";
+
+export const SCOPE_LABELS: Record<ApprovalScope, string> = {
+  once: "Allow once",
+  session: "Allow for this session",
+  always: "Always allow in this project (30 days)",
+};
+
+export interface PromptRequest {
+  capability: Capability;
+  /** Agent type name, or `DELEGATE_SUBJECT` on the delegate path. */
+  subject: string;
+  path: ApprovalPath;
+  /** Shown to the human for context. Never itself part of a key. */
+  task?: string;
+  /** Trusted exact-scope identity; bound requests single-flight only with an identical binding. */
+  bindingKey?: string;
+  signal?: AbortSignal;
+}
+
+/**
+ * Which of the five outcomes a request produced.
+ *
+ * `scope: null` alone conflates four different kinds of no — a caller that needs to know whether a
+ * PERSON actually declined (as opposed to nobody being there to ask, a dismissal, or the dialog itself
+ * breaking) cannot recover that from `scope` or from parsing `reason`. Only "declined" means a human said
+ * no; the other three are absence-of-signal, not a signal.
+ */
+export const PROMPT_OUTCOME_KINDS = ["granted", "declined", "dismissed", "no-ui", "error"] as const;
+export type PromptOutcomeKind = (typeof PROMPT_OUTCOME_KINDS)[number];
+
+export interface PromptOutcome {
+  /** The scope the human chose, or null for any form of no. */
+  scope: ApprovalScope | null;
+  /** Which of the five outcomes this was. Set on every return path. */
+  kind: PromptOutcomeKind;
+  /** Why, when the answer was no. */
+  reason?: string;
+  /**
+   * True when this caller RODE another caller's answer rather than being asked (R-66).
+   *
+   * The single-flight queue shares any non-`once` outcome, which is right — a human approving
+   * `tool:bash` *for this session* authorised the capability, not one child. What is not right is
+   * recording the riders as though each had faced a dialog: the ledger's whole job is answering "did a
+   * human authorise this?", and a fan-out of eight wrote eight lines claiming a prompt where there was
+   * one. The rider's honest source is `session`, and this flag is how the caller can tell.
+   */
+  joined?: boolean;
+}
+
+export interface ApprovalGateOptions {
+  ui: ApprovalUI;
+  /** pi's `ctx.hasUI` — false in print/json mode, and therefore in every governed child. */
+  hasUI: boolean;
+  /** pi's `ctx.mode`, quoted back in the refusal so an operator can see why. */
+  mode: string;
+  timeoutMs?: number;
+}
+
+export interface ApprovalGate {
+  request(request: PromptRequest): Promise<PromptOutcome>;
+}
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+/**
+ * Read `PI_DADDY_APPROVAL_TIMEOUT`, in SECONDS, into the milliseconds pi expects.
+ *
+ * `0` or an unparseable value means no timeout: waiting forever denies nothing, so it is the safe
+ * interpretation of a value we do not understand.
+ */
+export function timeoutMsFromEnv(raw: string | undefined): number | undefined {
+  if (raw === undefined) return DEFAULT_TIMEOUT_MS;
+  const seconds = Number.parseInt(raw, 10);
+  if (!Number.isFinite(seconds) || seconds <= 0) return undefined;
+  return seconds * 1000;
+}
+
+function labelToScope(label: string, scopes: ApprovalScope[]): ApprovalScope | null {
+  return scopes.find((s) => SCOPE_LABELS[s] === label) ?? null;
+}
+
+/**
+ * The single-flight queue: one dialog per approval key at a time.
+ *
+ * `delegate` sets no `executionMode`, so an orchestrator can fan out several children at once and two can
+ * hit the same gate simultaneously — otherwise two stacked dialogs asking the identical question.
+ *
+ * **R-29 — the key does two jobs, and only one of them may be shared.** `approvalKey` is
+ * `capability@subject`, and on the delegate path the subject is the constant `DELEGATE_SUBJECT`, which is
+ * deliberate: the only things naming a delegated child are the task and the tool list, both model-chosen,
+ * and a key the model controls is not a key (`approval.ts:24-32`). That reasoning governs *approval
+ * identity* — what a human said yes to, and what may be persisted — and it is right.
+ *
+ * It does **not** govern de-duplication. Sharing one dialog's outcome is correct for `session` and
+ * `always`, which are genuinely answers about the session or the project, and for a decline or an error,
+ * which answer everyone. It is **wrong for `once`**, which means *this spawn*. Measured before the fix:
+ * four concurrent delegations gating `tool:bash`, one dialog, one click of *Allow once* → four `granted`
+ * outcomes, with the human having seen only the first caller's task. That is a confused deputy, and it
+ * falsified ADR-0014's decided property that "`once` stops at the boundary".
+ */
+export type InFlightApprovals = Map<string, Promise<PromptOutcome>>;
+
+/**
+ * Build gates that SHARE one single-flight queue.
+ *
+ * This exists because of how the wiring actually calls in. The gate's options depend on the per-call
+ * `ExtensionContext` (`ui`, `hasUI`, `mode`), so the extension necessarily builds a gate per invocation —
+ * and a gate that owns its queue privately therefore de-duplicates nothing across invocations, which is
+ * exactly the case §6.1 exists for (two concurrent `delegate` calls are two separate invocations).
+ *
+ * The provider separates the two lifetimes: options stay per-call and fresh, the queue is created once and
+ * lives as long as the provider. Preferred over a module-level map because that would be shared by every
+ * gate in the process — including across tests — for no benefit.
+ */
+export function createApprovalGateProvider(): (options: ApprovalGateOptions) => ApprovalGate {
+  const inFlight: InFlightApprovals = new Map();
+  return (options) => createApprovalGate(options, inFlight);
+}
+
+/**
+ * @param inFlight optional shared single-flight queue — see `createApprovalGateProvider`. Defaults to one
+ * private to this gate, which only de-duplicates requests made through this same gate object.
+ */
+export function createApprovalGate(
+  options: ApprovalGateOptions,
+  inFlight: InFlightApprovals = new Map(),
+): ApprovalGate {
+  const ask = async (request: PromptRequest): Promise<PromptOutcome> => {
+    const scopes = offeredScopes(request.path);
+    const title =
+      `grants: approve ${request.capability} for ${request.subject}?` +
+      (request.task ? `\n  task: ${request.task}` : "");
+
+    let chosen: string | undefined;
+    try {
+      chosen = await options.ui.select(title, [DENY_LABEL, ...scopes.map((s) => SCOPE_LABELS[s])], {
+        timeout: options.timeoutMs,
+        signal: request.signal,
+      });
+    } catch (error) {
+      // A governance layer that errors must deny, not permit. This is a dialog malfunction, not a
+      // person's answer — `kind: "error"` keeps it out of "declined".
+      return { scope: null, kind: "error", reason: `approval dialog failed, denying (${String(error)})` };
+    }
+
+    // undefined covers dismissal, timeout, and abort. All are a no, but none is a person saying no.
+    if (chosen === undefined) {
+      return { scope: null, kind: "dismissed", reason: `approval for ${request.capability} was dismissed` };
+    }
+    if (chosen === DENY_LABEL) {
+      return { scope: null, kind: "declined", reason: `${request.capability} was denied by a human` };
+    }
+
+    const scope = labelToScope(chosen, scopes);
+    return scope === null
+      ? { scope: null, kind: "error", reason: `unrecognised approval choice ${JSON.stringify(chosen)}, denying` }
+      : { scope, kind: "granted" };
+  };
+
+  return {
+    async request(request: PromptRequest): Promise<PromptOutcome> {
+      if (!options.hasUI) {
+        // Nobody was there to ask — distinct from a person declining, which is why this is its own kind
+        // rather than being folded into "declined" (see PromptOutcomeKind).
+        return {
+          scope: null,
+          kind: "no-ui",
+          reason:
+            `${request.capability} requires approval and this session has no interactive user ` +
+            `(mode: ${options.mode}). Pre-approve it in an interactive session, or drop it from the request.`,
+        };
+      }
+
+      const key = `${approvalKey(request.capability, request.subject)}${request.bindingKey ? `#${request.bindingKey}` : ""}`;
+
+      // R-29. Join an in-flight dialog, but only *keep* its answer if that answer was about more than one
+      // spawn. A `once` belongs to whichever caller the human was actually looking at — the title shows
+      // that caller's task — so anyone else who joined must ask their own question rather than ride a yes
+      // given for somebody else's work. The loop (rather than a single retry) covers the case where a
+      // fellow waiter started its own dialog first: we join that one instead of opening a third.
+      for (;;) {
+        const existing = inFlight.get(key);
+        if (!existing) break;
+        const outcome = await existing;
+        // **`joined` marks the rider, and the ledger depends on it (R-66).** Sharing a non-`once` outcome
+        // is correct — the human authorised the capability for the session, not for one child — but the
+        // caller then stamped `approvalSource: "prompt"` on every one of them, so a fan-out of eight wrote
+        // eight lines each asserting a human was prompted when exactly one was. That is R-46's defect at
+        // the concurrency level, and `ledger.ts` calls over-claiming in this direction "the worst available
+        // failure". Confirmed by execution: one dialog, eight `granted/session` outcomes.
+        if (outcome.scope !== "once") return { ...outcome, joined: true };
+      }
+
+      const pending = ask(request).finally(() => inFlight.delete(key));
+      inFlight.set(key, pending);
+      return pending;
+    },
+  };
+}