pi-daddy 0.45.0 → 0.46.0

package/extensions/runtime-snapshot.ts

@@ -0,0 +1,123 @@
+/** Trusted extension event bridge. Tool calls and model-produced text cannot supply runtime facts. */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { realpath } from "node:fs/promises";
+import { openRuntimeSettlement, settlementHash } from "../src/governance/runtime-settlement.ts";
+import { reconcileDelegationCapacity } from "./session-capacity.ts";
+import { agentDir } from "../src/kernel/project-paths.ts";
+import type { GrantsSession } from "./session.ts";
+export const RUNTIME_SNAPSHOT_EVENT = "pi-daddy:runtime-snapshot:v1";
+export function registerRuntimeSnapshot(
+  pi: ExtensionAPI,
+  session: GrantsSession,
+): {
+  bind(ctx: ExtensionContext): Promise<void>;
+} {
+  let bound: { sessionId: string; cwd: string; lifecycle: object } | undefined, problem: string | undefined;
+  const generation = {};
+  let bindSequence = 0;
+  const unsubscribe = pi.events?.on?.(RUNTIME_SNAPSHOT_EVENT, (input: unknown) => {
+    const request = input as {
+      version?: number;
+      requestId?: string;
+      sessionId?: string;
+      cwd?: string;
+      reply?: (value: unknown) => void;
+    };
+    if (
+      request?.version !== 1 ||
+      typeof request.requestId !== "string" ||
+      request.requestId.length > 512 ||
+      typeof request.reply !== "function"
+    )
+      return;
+    if (bound && session.reloadLifecycle.runtimeSnapshotGeneration !== generation) return;
+    void (async () => {
+      const current = bound,
+        lifecycle = session.reloadLifecycle;
+      const unavailable = (reason: string) => ({
+        version: 1,
+        requestId: request.requestId,
+        sessionId: current?.sessionId ?? "",
+        cwd: current?.cwd ?? "",
+        ownerScope: "",
+        ownerId: "",
+        backend: session.executor.kind,
+        qualified: false,
+        state: "unknown",
+        evidenceDigest: settlementHash({ reason }),
+        settledExecutionIds: [],
+        outstandingExecutionIds: [],
+        reason,
+      });
+      if (
+        !current ||
+        current.lifecycle !== lifecycle ||
+        request.sessionId !== current.sessionId ||
+        request.cwd !== current.cwd ||
+        !lifecycle.runtimeSettlement
+      ) {
+        request.reply!(unavailable(problem ?? "runtime owner is not ready"));
+        return;
+      }
+      try {
+        if (Array.isArray(session.capacity.retainedReservations)) await reconcileDelegationCapacity(session);
+        const snapshot = await lifecycle.runtimeSettlement.snapshot();
+        if (
+          bound !== current ||
+          session.reloadLifecycle !== lifecycle ||
+          lifecycle.runtimeSnapshotGeneration !== generation
+        ) {
+          request.reply!(unavailable("runtime owner changed during snapshot"));
+          return;
+        }
+        const qualified = !session.executor.refusal && !session.discoveryCleanupFailure && !session.capacityRefusal;
+        request.reply!({
+          version: 1,
+          requestId: request.requestId,
+          sessionId: current.sessionId,
+          cwd: current.cwd,
+          ...snapshot,
+          backend: session.executor.kind,
+          qualified,
+          state: !qualified
+            ? "unknown"
+            : session.capacity.reserved > 0 && snapshot.state === "idle"
+              ? "busy"
+              : snapshot.state,
+          ...(problem ? { reason: problem } : {}),
+        });
+      } catch (error) {
+        request.reply!(unavailable(String(error)));
+      }
+    })().catch(() => undefined);
+  });
+  return {
+    async bind(ctx) {
+      const sequence = ++bindSequence,
+        lifecycle = session.reloadLifecycle;
+      lifecycle.runtimeSettlement = undefined;
+      bound = undefined;
+      problem = undefined;
+      try {
+        const sessionId = ctx.sessionManager.getSessionId(),
+          cwd = await realpath(ctx.cwd);
+        if (sequence !== bindSequence || session.reloadLifecycle !== lifecycle) return;
+        if (lifecycle.runtimeSnapshotUnsubscribe !== unsubscribe) lifecycle.runtimeSnapshotUnsubscribe?.();
+        lifecycle.runtimeSnapshotUnsubscribe = unsubscribe;
+        lifecycle.runtimeSnapshotGeneration = generation;
+        lifecycle.runtimeSettlements ??= new Map();
+        const key = JSON.stringify([sessionId, cwd]);
+        let runtime = lifecycle.runtimeSettlements.get(key);
+        if (!runtime) {
+          runtime = await openRuntimeSettlement(agentDir(), sessionId, cwd);
+          lifecycle.runtimeSettlements.set(key, runtime);
+        }
+        if (sequence !== bindSequence || session.reloadLifecycle !== lifecycle) return;
+        lifecycle.runtimeSettlement = runtime;
+        bound = { sessionId, cwd, lifecycle: session.reloadLifecycle };
+      } catch (error) {
+        if (sequence === bindSequence && session.reloadLifecycle === lifecycle) problem = String(error);
+      }
+    },
+  };
+}

package/extensions/session.ts

@@ -693,7 +693,7 @@ export function createGrantsSession(
       // Read live off `session.executor` (ADR-0031) rather than a boolean captured in the factory: the probe
       // has not run when this session object is built, so a captured value would plan `--print` for a session
       // that turns out to use panes — and `runHerdrPane` refuses a plan containing `--print` by design.
-      interactive: session.executor.kind === "herdr",
+      interactive: false, // Both qualified backends use the same one-shot Pi JSON protocol.
       ...(approved ? { approved } : {}),
     }),
     storeCwd,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "Capability governance for pi sub-agents: spawn Agent Skills (SKILL.md) definitions whose allowed-tools becomes a grant that can only narrow going down a delegation tree, enforced by pi's own --tools allowlist, with an append-only ledger.",
   "keywords": [
     "pi-package",

package/src/executors/captured-execution.ts

@@ -15,6 +15,7 @@ export async function runCapturedExecution(
     sessionPath: string;
     onReadCleanup?: (error: BoundedReadCleanupError) => void;
   },
+  runOwned: typeof runOwnedChild = runOwnedChild,
 ): Promise<CapturedExecutionResult> {
   let directory: string;
   try {
@@ -36,7 +37,7 @@ export async function runCapturedExecution(
   }
   const capture = new ChildFinalCapture(request.onOutput, request.onReadCleanup);
   const args = [...request.args.slice(0, -1), "--mode", "json", request.args.at(-1)!];
-  const output = await runOwnedChild({
+  const output = await runOwned({
     ...request,
     args,
     ownershipDir: join(directory, "ownership"),

package/src/executors/executor.ts

@@ -44,15 +44,17 @@ export function needsProbe(raw: string | undefined): boolean {
 }
 
 export const HERDR_UNQUALIFIED_REASON =
-  "Herdr governed execution is not qualified for complete current finals and subtree cleanup in this release. " +
+  "Herdr governed execution is not qualified for complete current finals and subtree cleanup on the detected transport. " +
   "Delegation is refused; set PI_DADDY_HERDR=0 explicitly to select captured execution. No backend fallback occurs.";
 
 export function chooseExecutor(raw: string | undefined, probe: HerdrProbe | null): ExecutorChoice {
   const choice = selectExecutor(raw, probe);
   if (choice.kind !== "herdr") return choice;
+  if (!choice.refusal && probe?.qualified === true)
+    return { ...choice, disclosure: `${choice.disclosure} — qualified native ownership` };
   return {
     ...choice,
-    refusal: [choice.refusal, HERDR_UNQUALIFIED_REASON].filter(Boolean).join(" "),
+    refusal: [choice.refusal, HERDR_UNQUALIFIED_REASON, probe?.qualificationReason].filter(Boolean).join(" "),
     disclosure: `${choice.disclosure} — unqualified; governed delegation will refuse`,
   };
 }

package/src/executors/herdr-cli.ts

@@ -19,17 +19,22 @@ export type HerdrExec = (args: string[]) => Promise<{ code: number | null; stdou
 
 export const defaultExec: HerdrExec = (args) =>
   new Promise((settle) => {
-    execFile("herdr", args, { maxBuffer: 32 * 1024 * 1024 }, (error, stdout, stderr) => {
-      const raw = (error as { code?: unknown } | null)?.code;
-      const code = typeof raw === "number" ? raw : error ? 1 : 0;
-      // **A string `code` is a spawn failure, and it used to be thrown away.** `ENOENT` — herdr not installed —
-      // arrives as `code: "ENOENT"`, so the numeric test failed, the message was dropped, and an operator with
-      // `PI_DADDY_HERDR=1` on a machine without herdr was told *"herdr is not answering (unparseable herdr
-      // reply: (no output))"* rather than that the binary is missing. Rule 8 wants the loud version, and this is
-      // the first diagnostic such an operator meets.
-      const spawnFailure = typeof raw === "string" ? `herdr could not be run (${raw}): ${error?.message ?? ""}` : "";
-      settle({ code, stdout: String(stdout), stderr: spawnFailure || String(stderr) });
-    });
+    execFile(
+      "herdr",
+      args,
+      { maxBuffer: 32 * 1024 * 1024, timeout: 10000, killSignal: "SIGKILL" },
+      (error, stdout, stderr) => {
+        const raw = (error as { code?: unknown } | null)?.code;
+        const code = typeof raw === "number" ? raw : error ? 1 : 0;
+        // **A string `code` is a spawn failure, and it used to be thrown away.** `ENOENT` — herdr not installed —
+        // arrives as `code: "ENOENT"`, so the numeric test failed, the message was dropped, and an operator with
+        // `PI_DADDY_HERDR=1` on a machine without herdr was told *"herdr is not answering (unparseable herdr
+        // reply: (no output))"* rather than that the binary is missing. Rule 8 wants the loud version, and this is
+        // the first diagnostic such an operator meets.
+        const spawnFailure = typeof raw === "string" ? `herdr could not be run (${raw}): ${error?.message ?? ""}` : "";
+        settle({ code, stdout: String(stdout), stderr: spawnFailure || String(stderr) });
+      },
+    );
   });
 
 /**
@@ -44,7 +49,7 @@ export function parseReply(reply: { stdout: string; stderr: string }): {
   error?: string;
 } {
   try {
-    const parsed = JSON.parse(reply.stdout) as {
+    const parsed = JSON.parse(reply.stdout.trim() || reply.stderr.trim()) as {
       result?: Record<string, unknown>;
       error?: { message?: string; code?: string };
     };
@@ -63,6 +68,8 @@ export const PROBE_TIMEOUT_MS = 2000;
 
 export interface HerdrProbe {
   ok: boolean;
+  qualified?: boolean;
+  qualificationReason?: string;
   /** herdr's own words when it is not reachable. Carried so the disclosure line can name the reason. */
   error?: string;
 }

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) };
+  }
+}