pi-daddy 0.45.0 → 0.46.1

package/src/executors/herdr-launcher.ts

@@ -0,0 +1,124 @@
+/** Packaged pane entrypoint. Parent liveness is a private socket, native worker liveness is its control pipe. */
+import { stat } from "node:fs/promises";
+import { processTreeActivity } from "./process-activity.ts";
+import { createConnection } from "node:net";
+import { runOwnedChild, type OwnedChildRunRequest } from "./owned-worker.ts";
+import { wire } from "./herdr-wire.ts";
+export async function launchHerdrWorker(socketPath: string, token: string): Promise<void> {
+  const socket = createConnection(socketPath);
+  const abort = new AbortController();
+  let started = false,
+    authenticated = false,
+    acknowledge: (() => void) | undefined,
+    rejectGate: ((error: Error) => void) | undefined;
+  const lost = (error: Error) => {
+    abort.abort();
+    rejectGate?.(error);
+  };
+  socket.on("close", () => lost(Error("Herdr coordinator connection closed")));
+  const send = wire(
+    socket,
+    (message) => {
+      if (message?.type === "cancel") {
+        abort.abort();
+        rejectGate?.(Error("Herdr coordinator cancelled startup"));
+        return;
+      }
+      if (message?.type === "start" && authenticated) {
+        acknowledge?.();
+        acknowledge = undefined;
+        rejectGate = undefined;
+        return;
+      }
+      if (message?.type === "display" && authenticated && typeof message.text === "string") {
+        process.stdout.write(message.text);
+        return;
+      }
+      if (message?.type !== "request" || started) {
+        lost(Error("invalid Herdr coordinator request"));
+        socket.destroy();
+        return;
+      }
+      started = true;
+      authenticated = true;
+      const request = message.request as OwnedChildRunRequest & { sessionPath?: string };
+      let childPid: number | undefined;
+      void (async () => {
+        try {
+          const result = await runOwnedChild({
+            ...request,
+            signal: abort.signal,
+            activityProbe: async () => {
+              const file = request.sessionPath
+                ? await stat(request.sessionPath)
+                    .then((s) => String(s.size) + ":" + s.mtimeMs)
+                    .catch(() => undefined)
+                : undefined;
+              const tree = childPid === undefined ? undefined : await processTreeActivity(childPid);
+              return file === undefined && tree === undefined ? undefined : String(file) + "|" + tree;
+            },
+            onOwnership: (identity) =>
+              new Promise<void>((resolve, reject) => {
+                acknowledge = resolve;
+                rejectGate = reject;
+                if (abort.signal.aborted) {
+                  reject(Error("Herdr coordinator unavailable before ownership gate"));
+                  return;
+                }
+                send({ type: "ownership", identity });
+              }),
+            onObservation: (stream, bytes) => {
+              try {
+                const input = Buffer.from(bytes);
+                for (let offset = 0; offset < input.length; offset += 65536)
+                  send({ type: "bytes", stream, data: input.subarray(offset, offset + 65536).toString("base64") });
+              } catch (error) {
+                lost(error instanceof Error ? error : Error(String(error)));
+              }
+            },
+            onStreamEnd: (stream) => {
+              try {
+                send({ type: "stream-end", stream });
+              } catch {}
+            },
+            onSpawn: (pid) => {
+              childPid = pid;
+              send({ type: "spawned", pid });
+              process.stdout.write("pi-daddy: governed child running\n");
+            },
+          });
+          if (!socket.destroyed) {
+            send({ type: "result", result });
+            socket.end();
+          }
+          process.stdout.write("\npi-daddy: " + result.cleanup.state + "\n");
+        } catch (error) {
+          if (!socket.destroyed) {
+            try {
+              send({ type: "failure", reason: String(error) });
+            } finally {
+              socket.end();
+            }
+          }
+        }
+      })();
+    },
+    lost,
+  );
+  await new Promise<void>((resolve, reject) => {
+    socket.once("connect", () => {
+      try {
+        send({ type: "hello", token });
+      } catch (error) {
+        reject(error);
+      }
+    });
+    socket.once("close", resolve);
+    socket.once("error", reject);
+  });
+}
+if (/herdr-launcher\.(?:js|ts)$/.test(process.argv[1] ?? "")) {
+  const [, , path, token] = process.argv;
+  if (!path || !token) throw Error("Herdr launcher requires its private socket and nonce");
+  await launchHerdrWorker(path, token);
+}

package/src/executors/herdr-owned.ts

@@ -0,0 +1,260 @@
+/** Governed work runs in its own Herdr pane, under the same independently settling native owner as captured work. */
+import { createServer, type Socket } from "node:net";
+import { randomUUID } from "node:crypto";
+import { chmod, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { OwnedChildRunRequest, OwnedChildRunResult } from "./owned-worker.ts";
+import type { CapturedWorkerIdentity } from "../kernel/captured-worker-contract.ts";
+import {
+  isCapturedWorkerIdentity,
+  readCapturedWorkerReceipt,
+  validateLiveWorker,
+} from "../governance/captured-worker-record.ts";
+import { defaultExec, parseReply, type HerdrExec } from "./herdr-cli.ts";
+import { WORKER_SHA256 } from "./worker-artifact.ts";
+import { wire } from "./herdr-wire.ts";
+const quote = (value: string) => "'" + value.replaceAll("'", "'\\''") + "'";
+export interface HerdrOwnedOptions {
+  exec?: HerdrExec;
+  workspace?: string;
+  keepPane?: boolean;
+  onPane?: (paneId: string, tabId: string) => void;
+  onDisplay?: (display: (text: string) => void) => void;
+  /** Tests may select a freshly built launcher. Production always uses the packaged build. */
+  launcherPath?: string;
+}
+export async function runHerdrOwned(
+  request: OwnedChildRunRequest,
+  options: HerdrOwnedOptions = {},
+): Promise<OwnedChildRunResult> {
+  const exec = options.exec ?? defaultExec;
+  const directory = await mkdtemp(join(tmpdir(), "pd-herdr-"));
+  const path = join(directory, "owner.sock"),
+    token = randomUUID();
+  const launcher =
+    options.launcherPath ?? fileURLToPath(new URL("../../dist/executors/herdr-launcher.js", import.meta.url));
+  const helper = fileURLToPath(new URL("../../native/linux-x64/worker", import.meta.url));
+  let socket: Socket | undefined, send: ((value: unknown) => void) | undefined;
+  let identity: CapturedWorkerIdentity | undefined, outcome: OwnedChildRunResult | undefined, error: string | undefined;
+  let tabId: string | undefined,
+    entered = false,
+    done = false,
+    authenticated = false;
+  let finish!: () => void;
+  const startupTimer = setTimeout(
+    () => {
+      fail("Herdr launcher did not connect before startup deadline");
+      socket?.destroy();
+      finish();
+    },
+    Math.min(request.timeoutMs ?? 10000, 10000),
+  );
+  const completed = new Promise<void>((resolve) => {
+    finish = resolve;
+  });
+  const abort = () => {
+    try {
+      send?.({ type: "cancel" });
+    } catch {}
+  };
+  const fail = (cause: unknown) => {
+    error ??= String(cause);
+    abort();
+  };
+  const server = createServer((candidate) => {
+    if (socket) {
+      candidate.destroy();
+      return;
+    }
+    socket = candidate;
+    send = wire(
+      candidate,
+      (message) => {
+        if (!authenticated) {
+          if (message?.type !== "hello" || message.token !== token) throw Error("Herdr launcher nonce mismatch");
+          authenticated = true;
+          clearTimeout(startupTimer);
+          const {
+            signal: _signal,
+            onOwnership: _owner,
+            onSpawn: _spawn,
+            onOutput: _out,
+            onObservation: _observation,
+            onStreamEnd: _end,
+            activityProbe: _probe,
+            ...serializable
+          } = request;
+          send!({ type: "request", request: serializable });
+          return;
+        }
+        if (message?.type === "ownership") {
+          if (identity || !isCapturedWorkerIdentity(message.identity)) throw Error("ambiguous Herdr worker ownership");
+          const actual = message.identity as CapturedWorkerIdentity;
+          if (
+            actual.executionId !== request.executionId ||
+            actual.root !== request.cwd ||
+            actual.helperSha256 !== WORKER_SHA256 ||
+            actual.ownershipPath !== join(request.ownershipDir, "ownership.json")
+          )
+            throw Error("Herdr worker identity differs from requested execution");
+          identity = actual;
+          void (async () => {
+            try {
+              await validateLiveWorker(actual, helper);
+              await request.onOwnership?.(actual);
+              if (!done && !request.signal?.aborted && !error) {
+                request.onSpawn?.(actual.workerPid);
+                send!({ type: "start" });
+              } else abort();
+            } catch (cause) {
+              fail(cause);
+              abort();
+            }
+          })();
+          return;
+        }
+        if (
+          message?.type === "bytes" &&
+          ["stdout", "stderr"].includes(message.stream) &&
+          typeof message.data === "string"
+        ) {
+          if (
+            !identity ||
+            message.data.length > 90000 ||
+            !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(message.data)
+          )
+            throw Error("invalid Herdr output frame");
+          try {
+            request.onObservation?.(message.stream, Buffer.from(message.data, "base64"));
+          } catch {}
+          return;
+        }
+        if (message?.type === "stream-end" && ["stdout", "stderr"].includes(message.stream)) {
+          try {
+            request.onStreamEnd?.(message.stream);
+          } catch {}
+          return;
+        }
+        if (message?.type === "spawned" && identity && message.pid === identity.workerPid) {
+          return;
+        }
+        if (message?.type === "result" && !outcome) {
+          outcome = message.result;
+          return;
+        }
+        if (message?.type === "failure") {
+          fail(message.reason);
+          return;
+        }
+        throw Error("invalid Herdr worker transport message");
+      },
+      fail,
+    );
+    options.onDisplay?.((text) => {
+      if (authenticated && send) {
+        for (let at = 0; at < text.length; at += 16000) send({ type: "display", text: text.slice(at, at + 16000) });
+      }
+    });
+    candidate.on("close", finish);
+  });
+  const timeout = setTimeout(
+    () => {
+      fail("Herdr execution exceeded its transport deadline");
+      socket?.destroy();
+      finish();
+    },
+    (request.timeoutMs ?? 3600000) + Math.min(request.killGraceMs ?? 1500, 60000) + 7000,
+  );
+  request.signal?.addEventListener("abort", abort, { once: true });
+  try {
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(path, resolve);
+    });
+    await chmod(path, 0o600);
+    if (request.signal?.aborted || (request.hardDeadlineAt !== undefined && request.hardDeadlineAt <= Date.now()))
+      return {
+        code: null,
+        text: "",
+        truncated: false,
+        timedOut: false,
+        aborted: true,
+        cleanup: { state: "not-started", reason: "cancelled before Herdr pane launch" },
+      };
+    const created = parseReply(
+      await exec([
+        "tab",
+        "create",
+        "--cwd",
+        request.cwd,
+        "--label",
+        "pi-daddy governed child",
+        "--no-focus",
+        ...(options.workspace ? ["--workspace", options.workspace] : []),
+      ]),
+    );
+    if (created.error) throw Error(created.error);
+    const pane = created.result?.root_pane as { pane_id?: string; tab_id?: string } | undefined;
+    tabId = pane?.tab_id;
+    if (!pane?.pane_id || !tabId) throw Error("Herdr creation returned no exact pane/tab identity");
+    options.onPane?.(pane.pane_id, tabId);
+    if (error || request.signal?.aborted) throw Error(error ?? "cancelled before Herdr command launch");
+    entered = true;
+    const launchReply = await exec([
+      "pane",
+      "run",
+      pane.pane_id,
+      (options.keepPane ? "" : "exec ") + [process.execPath, launcher, path, token].map(quote).join(" "),
+    ]);
+    if (launchReply.code !== 0) throw Error(parseReply(launchReply).error ?? "Herdr pane launch failed");
+    if (launchReply.stdout.trim()) {
+      const launched = parseReply(launchReply);
+      if (launched.error) throw Error(launched.error);
+    }
+    await completed;
+    if (outcome?.cleanup?.state === "not-started" && !identity) return outcome;
+    if (!outcome || !identity) throw Error(error ?? "Herdr launcher closed without a complete result/ownership");
+    const receipt = await readCapturedWorkerReceipt(identity);
+    if (!receipt) throw Error("Herdr worker supplied no independently verified cleanup receipt");
+    return { ...outcome, cleanup: { state: "settled", identity, receipt }, ...(error ? { spawnError: error } : {}) };
+  } catch (cause) {
+    fail(cause);
+    socket?.destroy();
+    // Lost transport is never evidence of cleanup. Reconcile only the original bound receipt.
+    let receipt = identity ? await readCapturedWorkerReceipt(identity) : null;
+    const deadline = Date.now() + Math.min(request.killGraceMs ?? 1500, 60000) + 5500;
+    while (identity && !receipt && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      receipt = await readCapturedWorkerReceipt(identity);
+    }
+    return {
+      code: receipt?.workerCode ?? null,
+      text: "",
+      truncated: false,
+      timedOut: false,
+      aborted: Boolean(request.signal?.aborted),
+      spawnError: error ?? String(cause),
+      cleanup:
+        identity && receipt
+          ? { state: "settled", identity, receipt }
+          : entered
+            ? { state: "unknown", ...(identity ? { identity } : {}), reason: error ?? String(cause) }
+            : { state: "not-started", reason: error ?? String(cause) },
+    };
+  } finally {
+    done = true;
+    clearTimeout(timeout);
+    clearTimeout(startupTimer);
+    request.signal?.removeEventListener("abort", abort);
+    socket?.destroy();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    if (tabId && !options.keepPane) {
+      const closed = parseReply(await exec(["tab", "close", tabId]));
+      if (closed.error && !/tab .* not found|tab_not_found/.test(closed.error))
+        console.error("pi-daddy: settled worker pane could not close:", closed.error);
+    }
+    await rm(directory, { recursive: true, force: true });
+  }
+}

package/src/executors/herdr-qualification.ts

@@ -0,0 +1,33 @@
+/** Measured transport matrix. Reachability alone never qualifies a backend or changes execution location. */
+import { defaultExec, type HerdrExec, type HerdrProbe } from "./herdr-cli.ts";
+export const QUALIFIED_HERDR_VERSION = "0.8.2";
+export const QUALIFIED_HERDR_PROTOCOL = 20;
+export async function qualifyHerdr(probe: HerdrProbe, exec: HerdrExec = defaultExec): Promise<HerdrProbe> {
+  if (!probe.ok) return probe;
+  try {
+    if (process.platform !== "linux" || process.arch !== "x64") throw Error("Herdr owned execution requires Linux x64");
+    const [client, server] = await Promise.all([exec(["--version"]), exec(["status", "server"])]);
+    if (client.code !== 0 || client.stdout.trim() !== "herdr " + QUALIFIED_HERDR_VERSION)
+      throw Error("Herdr client version is not qualified");
+    const fields = Object.fromEntries(
+      server.stdout
+        .trim()
+        .split("\n")
+        .map((line) => {
+          const at = line.indexOf(":");
+          return [line.slice(0, at).trim(), line.slice(at + 1).trim()];
+        }),
+    );
+    if (
+      server.code !== 0 ||
+      fields.status !== "running" ||
+      fields.version !== QUALIFIED_HERDR_VERSION ||
+      fields.protocol !== String(QUALIFIED_HERDR_PROTOCOL) ||
+      fields.compatible !== "yes"
+    )
+      throw Error("Herdr server version/protocol is not qualified");
+    return { ...probe, qualified: true };
+  } catch (error) {
+    return { ...probe, qualified: false, qualificationReason: String(error) };
+  }
+}

package/src/executors/herdr-wire.ts

@@ -0,0 +1,43 @@
+/** Bounded local framing; this channel carries private execution input only between its two owners. */
+import type { Socket } from "node:net";
+export const HERDR_WIRE_LIMIT = 8 * 1024 * 1024;
+export function wire(socket: Socket, receive: (value: any) => void, failed: (error: Error) => void) {
+  let pending = "";
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const fail = (error: unknown) => {
+    failed(error instanceof Error ? error : new Error(String(error)));
+    socket.destroy();
+  };
+  socket.on("data", (bytes) => {
+    try {
+      pending += decoder.decode(bytes, { stream: true });
+      let end: number;
+      while ((end = pending.indexOf("\n")) >= 0) {
+        if (Buffer.byteLength(pending.slice(0, end)) > HERDR_WIRE_LIMIT)
+          throw Error("Herdr transport record exceeds bound");
+        const line = pending.slice(0, end);
+        pending = pending.slice(end + 1);
+        receive(JSON.parse(line));
+      }
+      if (Buffer.byteLength(pending) > HERDR_WIRE_LIMIT) throw Error("Herdr transport record exceeds bound");
+    } catch (error) {
+      fail(error);
+    }
+  });
+  socket.on("end", () => {
+    try {
+      pending += decoder.decode();
+      if (pending) throw Error("Herdr transport record is incomplete");
+    } catch (error) {
+      fail(error);
+    }
+  });
+  socket.on("error", (error) => failed(error));
+  return (value: unknown) => {
+    const text = JSON.stringify(value) + "\n";
+    if (Buffer.byteLength(text) > HERDR_WIRE_LIMIT || socket.writableLength > HERDR_WIRE_LIMIT * 2)
+      throw Error("Herdr transport buffering exceeds bound");
+    if (socket.destroyed || !socket.writable) throw Error("Herdr transport is closed");
+    socket.write(text);
+  };
+}

package/src/governance/approval-prompt.ts

@@ -43,21 +43,22 @@ export interface PromptRequest {
   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;
+/** Only declined means a human chose Deny. Expiry, cancellation and dismissal grant nothing. */
+export const PROMPT_OUTCOME_KINDS = [
+  "granted",
+  "declined",
+  "dismissed",
+  "expired",
+  "aborted",
+  "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. */
+  /** Which outcome this was. Set on every return path. */
   kind: PromptOutcomeKind;
   /** Why, when the answer was no. */
   reason?: string;
@@ -87,17 +88,14 @@ 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.
  *
- * Only literal `0` disables the deadline. Other values must be canonical whole seconds
+ * Absent or literal `0` waits for the human without a deadline. Other values must be canonical whole seconds
  * within Node's signed 32-bit millisecond timer limit; malformed settings refuse a needed prompt.
  */
 export function timeoutMsFromEnv(raw: string | undefined): number | undefined {
-  if (raw === undefined) return DEFAULT_TIMEOUT_MS;
-  if (raw === "0") return undefined;
+  if (raw === undefined || raw === "0") return undefined;
   if (!/^[1-9][0-9]*$/.test(raw) || Number(raw) > 2_147_483)
     throw new Error(
       "PI_DADDY_APPROVAL_TIMEOUT must be literal 0 or whole seconds 1..2147483 without signs, padding or units",
@@ -108,6 +106,64 @@ function labelToScope(label: string, scopes: ApprovalScope[]): ApprovalScope | n
   return scopes.find((s) => SCOPE_LABELS[s] === label) ?? null;
 }
 
+const interrupted = (request: PromptRequest, kind: "expired" | "aborted"): PromptOutcome => ({
+  scope: null,
+  kind,
+  reason:
+    `approval for ${request.capability} ${kind === "expired" ? "expired before an answer" : "was canceled"}. ` +
+    "No permission was granted. Retry the delegation to open a new approval prompt.",
+});
+
+/** Own the deadline so Pi's undefined dismissal cannot erase whether our timer or cancellation fired. */
+async function selectApproval(
+  options: ApprovalGateOptions,
+  request: PromptRequest,
+  title: string,
+  labels: string[],
+): Promise<string | undefined | PromptOutcome> {
+  const timeout = typeof options.timeoutMs === "function" ? options.timeoutMs() : options.timeoutMs;
+  const controller = new AbortController();
+  let outcome: PromptOutcome | undefined;
+  let wake!: (value: PromptOutcome) => void;
+  const stopped = new Promise<PromptOutcome>((resolve) => {
+    wake = resolve;
+  });
+  const stop = (kind: "expired" | "aborted") => {
+    if (outcome) return;
+    outcome = interrupted(request, kind);
+    // Resolve our tagged outcome before a UI reacts to abort by returning undefined.
+    wake(outcome);
+    controller.abort();
+  };
+  const abort = () => stop("aborted");
+  request.signal?.addEventListener("abort", abort, { once: true });
+  const timer = timeout === undefined ? undefined : setTimeout(() => stop("expired"), timeout);
+  try {
+    if (request.signal?.aborted) stop("aborted");
+    if (outcome) return outcome;
+    const chosen = await Promise.race([options.ui.select(title, labels, { signal: controller.signal }), stopped]);
+    return outcome ?? chosen;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    request.signal?.removeEventListener("abort", abort);
+  }
+}
+
+async function joinApproval(pending: Promise<PromptOutcome>, request: PromptRequest): Promise<PromptOutcome> {
+  if (!request.signal) return pending;
+  let abort!: () => void;
+  const stopped = new Promise<PromptOutcome>((resolve) => {
+    abort = () => resolve(interrupted(request, "aborted"));
+    request.signal!.addEventListener("abort", abort, { once: true });
+    if (request.signal!.aborted) abort();
+  });
+  try {
+    return await Promise.race([pending, stopped]);
+  } finally {
+    request.signal.removeEventListener("abort", abort);
+  }
+}
+
 /**
  * The single-flight queue: one dialog per approval key at a time.
  *
@@ -160,24 +216,27 @@ export function createApprovalGate(
       `grants: approve ${request.capability} for ${request.subject}?` +
       (request.task ? `\n  task: ${request.task}` : "");
 
-    let chosen: string | undefined;
+    let chosen: string | undefined | PromptOutcome;
     try {
-      chosen = await options.ui.select(title, [DENY_LABEL, ...scopes.map((s) => SCOPE_LABELS[s])], {
-        timeout: typeof options.timeoutMs === "function" ? options.timeoutMs() : options.timeoutMs,
-        signal: request.signal,
-      });
+      chosen = await selectApproval(options, request, title, [DENY_LABEL, ...scopes.map((s) => SCOPE_LABELS[s])]);
     } 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)})` };
     }
 
-    if (request.signal?.aborted)
-      return { scope: null, kind: "dismissed", reason: `approval for ${request.capability} was canceled` };
+    if (request.signal?.aborted) return interrupted(request, "aborted");
 
-    // undefined covers dismissal, timeout, and abort. All are a no, but none is a person saying no.
+    if (typeof chosen === "object") return chosen;
+    // Only an ordinary UI dismissal reaches undefined; our deadline and abort carry explicit outcomes.
     if (chosen === undefined) {
-      return { scope: null, kind: "dismissed", reason: `approval for ${request.capability} was dismissed` };
+      return {
+        scope: null,
+        kind: "dismissed",
+        reason:
+          `approval for ${request.capability} was dismissed. No permission was granted. ` +
+          "Retry the delegation to open a new approval prompt.",
+      };
     }
     if (chosen === DENY_LABEL) {
       return { scope: null, kind: "declined", reason: `${request.capability} was denied by a human` };
@@ -191,8 +250,7 @@ export function createApprovalGate(
 
   return {
     async request(request: PromptRequest): Promise<PromptOutcome> {
-      if (request.signal?.aborted)
-        return { scope: null, kind: "dismissed", reason: `approval for ${request.capability} was canceled` };
+      if (request.signal?.aborted) return interrupted(request, "aborted");
       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).
@@ -215,9 +273,8 @@ export function createApprovalGate(
       for (;;) {
         const existing = inFlight.get(key);
         if (!existing) break;
-        const outcome = await existing;
-        if (request.signal?.aborted)
-          return { scope: null, kind: "dismissed", reason: `approval for ${request.capability} was canceled` };
+        const outcome = await joinApproval(existing, request);
+        if (request.signal?.aborted) return interrupted(request, "aborted");
         // **`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

package/src/governance/ledger-v3-validation.ts

@@ -23,7 +23,7 @@ const SHA256_RE = /^[a-f0-9]{64}$/i;
 const EXECUTORS = new Set(["process", "herdr"]);
 const APPROVAL_SOURCES = new Set(["prompt", "session", "persisted", "inherited"]);
 const APPROVAL_SCOPES = new Set(["once", "session", "always"]);
-const GATE_OUTCOMES = new Set(["declined", "dismissed", "no-ui", "error"]);
+const GATE_OUTCOMES = new Set(["declined", "dismissed", "expired", "aborted", "no-ui", "error"]);
 const LEASE_OUTCOMES = new Set([
   "acquired",
   "uncontended",

package/src/governance/ledger.ts

@@ -44,7 +44,7 @@ export const LEDGER_EVENT_KINDS = [
   "episode_outcome",
 ] as const;
 export type LedgerEventKind = (typeof LEDGER_EVENT_KINDS)[number];
-export const LEDGER_GATE_OUTCOMES = ["declined", "dismissed", "no-ui", "error"] as const;
+export const LEDGER_GATE_OUTCOMES = ["declined", "dismissed", "expired", "aborted", "no-ui", "error"] as const;
 export type LedgerGateOutcome = (typeof LEDGER_GATE_OUTCOMES)[number];
 
 export interface LedgerEventBase {
@@ -137,9 +137,8 @@ export interface GrantRecord extends LedgerEventBase {
    * The discriminant was already computed and thrown away. ADR-0026 leans on this vocabulary being able to
    * say *"nobody was there to ask"* and be believed, so it is recorded rather than inferred.
    *
-   * **Privacy is unchanged**: this is a fixed five-member enum, not text — nothing model-authored, nothing
-   * a task could carry. The prompt has five outcomes, but `granted` is deliberately omitted from the
-   * four-member ledger enum because the approval source/scope fields already record a yes.
+   * **Privacy is unchanged**: this is a fixed enum, not task-authored text. Explicit expiry and caller
+   * cancellation have their own outcomes; `granted` is omitted because approval source/scope records a yes.
    */
   gateOutcome?: LedgerGateOutcome;
   /**