pi-daddy 0.44.4 → 0.46.0

package/extensions/execution-evidence.ts

@@ -83,7 +83,7 @@ export function executionEvidenceContent(
   outcomes: readonly DelegationOutcome[],
   requested: number,
 ) {
-  const evidence = { version: 1, tool, requested, outcomes: outcomes.map(outcomeEvidence) };
+  const evidence = executionEvidence(tool, outcomes, requested);
   return {
     type: "text" as const,
     text:
@@ -92,3 +92,12 @@ export function executionEvidenceContent(
       "\n```",
   };
 }
+
+/** Shared allowlisted projection for the model-visible text and exact local capture. */
+export function executionEvidence(
+  tool: "delegate" | "delegate_all" | "delegate_chain",
+  outcomes: readonly DelegationOutcome[],
+  requested: number,
+) {
+  return { version: 1, tool, requested, outcomes: outcomes.map(outcomeEvidence) };
+}

package/extensions/executor-session.ts

@@ -1,9 +1,10 @@
 import { chooseExecutor, needsProbe, ENV_HERDR } from "../src/executors/executor.ts";
+import { qualifyHerdr } from "../src/executors/herdr-qualification.ts";
 import { probeHerdr } from "../src/executors/herdr-cli.ts";
 import type { GrantsSession } from "./session.ts";
 
 /** Settle one executor at session start; a later daemon change never relocates siblings. */
 export async function resolveExecutor(session: GrantsSession): Promise<void> {
   const raw = process.env[ENV_HERDR];
-  session.executor = chooseExecutor(raw, needsProbe(raw) ? await probeHerdr() : null);
+  session.executor = chooseExecutor(raw, needsProbe(raw) ? await qualifyHerdr(await probeHerdr()) : null);
 }

package/extensions/grants.ts

@@ -20,6 +20,7 @@
  * spawn triggered the human prompt, and `childEnv` clamps it to the grant again on the way out. Each
  * child derives its own grant from the tool array of its first provider request.
  */
+import { registerRuntimeSnapshot } from "./runtime-snapshot.ts";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
@@ -80,6 +81,7 @@ export default function (pi: ExtensionAPI, trustedSession?: GrantsSession) {
   const session = trustedSession ?? createGrantsSession(extensionPath, undefined, observerExtensionPath);
   session.currentThinking = typeof pi.getThinkingLevel === "function" ? () => pi.getThinkingLevel() : undefined;
   registerActivityTimeline(pi, session);
+  const runtimeSnapshot = registerRuntimeSnapshot(pi, session);
   const dashboardPluginRoot = fileURLToPath(new URL("../herdr-plugin/", import.meta.url));
   const dashboardPaths = defaultDashboardPaths(agentDir());
   // Definitions are registered only after owner-bound session_start. Until then there is no delegation
@@ -215,6 +217,7 @@ export default function (pi: ExtensionAPI, trustedSession?: GrantsSession) {
       // (R-60), and `probeHerdr` is documented as never throwing precisely so this is belt-and-braces.
       try {
         await resolveExecutor(session);
+        if (session.reloadLifecycle === reload.lifecycle) await runtimeSnapshot.bind(ctx);
       } catch (error) {
         if (session.reloadLifecycle !== reload.lifecycle) return undefined;
         // Says what is actually true of the state left behind, which depends on the variable: with

package/extensions/public-evidence.ts

@@ -0,0 +1,90 @@
+/** Composition-only bridge. Snapshot definitions when dispatch actually selects them, never reread paths. */
+import {
+  capturePublicEvidence,
+  type PublicEvidenceOwner,
+  type PublicEvidenceRequest,
+  type PublicDefinitionEvidence,
+} from "../src/products/public-evidence.ts";
+import { digestDefinition, type SkillDefinition } from "../src/kernel/definitions.ts";
+import { executionEvidence } from "./execution-evidence.ts";
+import type { DelegationOutcome } from "./execute-child.ts";
+type Tool = "delegate_describe" | "delegate" | "delegate_all" | "delegate_chain";
+interface Result {
+  isError?: boolean;
+  content: { type: "text"; text: string }[];
+  details?: unknown;
+}
+export function publicEvidenceCall(
+  owner: PublicEvidenceOwner | undefined,
+  toolCallId: string,
+  tool: Tool,
+  specs: readonly { agent?: string; definitionId?: string }[],
+  executionIds: readonly string[] = [],
+) {
+  const requested: PublicEvidenceRequest[] = specs.map((spec, index) => ({
+    ordinal: index + 1,
+    agent: spec.agent ?? null,
+    requestedDefinitionId: spec.definitionId ?? null,
+    definitionId: null,
+    executionId: executionIds[index] ?? null,
+  }));
+  const definitions = new Map<number, PublicDefinitionEvidence>();
+  return {
+    selected(index: number, definition: SkillDefinition | undefined) {
+      if (!owner) return;
+      definitions.delete(index);
+      if (requested[index]) requested[index].definitionId = null;
+      if (!definition) return;
+      const request = requested[index];
+      if (!request || !definition.definitionId) return;
+      request.definitionId = definition.definitionId;
+      definitions.set(index, {
+        agent: definition.name,
+        definitionId: definition.definitionId,
+        sourceHash: definition.sourceHash ?? null,
+        bodySha256: digestDefinition(definition).sha256,
+        binding: definition.binding ?? null,
+        snapshot: definition.sourceSnapshot,
+      });
+    },
+    finish<T extends Result>(result: T, outcomes: readonly DelegationOutcome[] = []): T {
+      if (!owner) return result;
+      let status: unknown;
+      try {
+        const ref = capturePublicEvidence(owner, {
+          toolCallId,
+          tool,
+          response: { isError: result.isError ?? false, content: result.content },
+          requested,
+          runtimeEvidence: tool === "delegate_describe" ? null : executionEvidence(tool, outcomes, specs.length),
+          definitions: [...definitions.values()],
+          finals: outcomes.map((outcome, index) => ({
+            ordinal: index + 1,
+            executionId: requested[index]?.executionId ?? null,
+            final:
+              outcome.final?.state === "complete"
+                ? {
+                    state: "complete",
+                    text: outcome.final.text,
+                    sessionId: outcome.final.sessionId,
+                    messageId: outcome.final.messageId,
+                    leafId: outcome.final.leafId,
+                    sha256: outcome.final.sha256,
+                  }
+                : null,
+          })),
+        });
+        status = { status: "captured", ref: { path: ref.path, sha256: ref.sha256 } };
+      } catch (error) {
+        status = {
+          status: "failed",
+          reason: error instanceof Error ? error.message : "public evidence capture failed",
+        };
+      }
+      return {
+        ...result,
+        content: [...result.content, { type: "text", text: "Public evidence capture: " + JSON.stringify(status) }],
+      };
+    },
+  };
+}

package/extensions/reload-environment.ts

@@ -4,6 +4,10 @@ import type { BoundedReadCleanupError } from "../src/kernel/bounded-read.ts";
 
 /** The root baseline and latest child publication for one real Pi session owner. */
 export interface ReloadLifecycle {
+  runtimeSnapshotUnsubscribe?: () => void;
+  runtimeSnapshotGeneration?: object;
+  runtimeSettlements?: Map<string, import("../src/governance/runtime-settlement.ts").RuntimeSettlement>;
+  runtimeSettlement?: import("../src/governance/runtime-settlement.ts").RuntimeSettlement;
   root: Record<string, string | undefined>;
   /** Never replaced for the same owner, even when an explicit root environment changes. */
   capacity?: OwnerCapacity;
@@ -99,6 +103,10 @@ export function bindReloadLifecycle(
         activityRootId: existing.activityRootId,
         episodeId: existing.episodeId,
         capacity: existing.capacity,
+        runtimeSettlement: existing.runtimeSettlement,
+        runtimeSettlements: existing.runtimeSettlements,
+        runtimeSnapshotUnsubscribe: existing.runtimeSnapshotUnsubscribe,
+        runtimeSnapshotGeneration: existing.runtimeSnapshotGeneration,
       };
       holder.owners.set(owner, existing);
     }

package/extensions/run-delegation.ts

@@ -73,6 +73,8 @@ interface DelegationToolContext extends ApprovalUIContext {
 /** A planned delegation, plus whatever approvals contributed to it. */
 export interface GatedPlan {
   plan: ReturnType<typeof planDelegation>;
+  /** Opt-in observation of the exact context used by the final planner invocation. */
+  definition?: import("../src/kernel/definitions.ts").SkillDefinition;
   /** Absent when the gate was never reached — i.e. the plan succeeded or failed for another reason. */
   approval?: ApprovalOutcome;
 }
@@ -112,8 +114,17 @@ export async function planWithApprovals(
   // the re-plan — and two spellings of one argument is the defect R-28 was.
   const approvalSubject = request.agent ?? DELEGATE_SUBJECT;
 
-  let plan = planDelegation(request, { ...(await session.delegationContext(preApproved)), ...extra });
-  if (plan.ok || !shouldSeekApproval(plan.result)) return { plan };
+  let definition: GatedPlan["definition"];
+  const observedPlan = (context: Parameters<typeof planDelegation>[1]) => {
+    const next = planDelegation(request, context);
+    definition =
+      session.publicEvidence && next.definitionDigest && request.agent
+        ? context.definitions?.get(request.agent)
+        : undefined;
+    return next;
+  };
+  let plan = observedPlan({ ...(await session.delegationContext(preApproved)), ...extra });
+  if (plan.ok || !shouldSeekApproval(plan.result)) return { plan, ...(definition ? { definition } : {}) };
 
   let approval: ApprovalOutcome | undefined;
   try {
@@ -133,7 +144,7 @@ export async function planWithApprovals(
     );
     const outcome = approval;
     if (outcome.approved.length > 0) {
-      plan = planDelegation(request, {
+      plan = observedPlan({
         // The scope is the REAL one: a `once` approval still authorises this spawn, and
         // `inheritApprovals` then keeps it from reaching the child. See ADR-0014. R-29 is what makes
         // this safe under fan-out: a `once` is consumed by exactly one concurrent caller.
@@ -170,7 +181,7 @@ export async function planWithApprovals(
     plan = { ...plan, reason: message, refusal: structuredRefusal("APPROVAL_FLOW_FAILED", message) };
   }
 
-  return { plan, approval };
+  return { plan, approval, ...(definition ? { definition } : {}) };
 }
 
 /**
@@ -211,6 +222,7 @@ export async function runOneDelegation(
     /** Trusted reservation made before a chain's upfront gate. */
     capacityReservation?: CapacityReservation;
     /** Exact pair selected during the chain preflight; never reselect after its approval. */
+    onDefinition?: (definition: import("../src/kernel/definitions.ts").SkillDefinition | undefined) => void;
     resolvedRuntime?: import("./definition-runtime.ts").ResolvedDefinitionRuntime;
     /** Actual public execute argument, never read from model-authored correlation or output. */
     toolCallId?: string;
@@ -266,6 +278,7 @@ export async function runOneDelegation(
   try {
     await session.ensureDefinitions?.();
     assertDefinitionIdentity(session, spec);
+
     const { toolCallId, onProgress, preApproved, taskFrom, taskFromExecutionId, approvalFacts } = options;
     // pi resolves a BARE model id to an unauthenticated provider and the child dies at startup — the id
     // alone is not enough, it must be qualified with its provider (`Model<Api>` carries both).
@@ -347,6 +360,7 @@ export async function runOneDelegation(
       // no child process.
       const preview = await planWithApprovals(session, request, planContext, null, signal, preApproved);
       plan = preview.plan;
+      options.onDefinition?.(preview.definition);
       if (plan.ok || shouldSeekApproval(plan.result)) {
         try {
           preparedWorkspace = await prepareDelegationWorkspace({
@@ -363,6 +377,7 @@ export async function runOneDelegation(
           request.correlation = preparedWorkspace.correlation;
           const gated = await planWithApprovals(session, request, planContext, ctx, signal, preApproved);
           plan = gated.plan;
+          options.onDefinition?.(gated.definition);
           approvalOutcome = gated.approval;
         } catch (error) {
           const value =
@@ -382,6 +397,7 @@ export async function runOneDelegation(
         preApproved,
       );
       plan = gated.plan;
+      options.onDefinition?.(gated.definition);
       approvalOutcome = gated.approval;
     }
 

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

@@ -13,6 +13,8 @@
  * module reads them **through this object**, live, rather than capturing a copy at load time; capturing a
  * copy of `ownGrant` before observation is exactly how a stale upper bound would become an enforced one.
  */
+import { createPublicEvidenceOwner, type PublicEvidenceOwner } from "../src/products/public-evidence.ts";
+import { ENV_PUBLIC_EVIDENCE_DIR } from "../src/kernel/env-names.ts";
 import { randomUUID } from "node:crypto";
 import { BoundedReadCleanupError } from "../src/kernel/bounded-read.ts";
 import type { discoverSkillPackages } from "../src/kernel/skill-packages.ts";
@@ -139,6 +141,8 @@ export function activityChildEnv(activity: { rootId: string; path: string; taskI
 }
 /** Keep each child's pane after it finishes, for inspection. Off by default: fan-out would flood it. */
 export interface GrantsSession extends NativeSessionHost {
+  /** Reconciled from the actual owner root on reload; captured call owners stay immutable. */
+  publicEvidence?: PublicEvidenceOwner;
   /** Legacy PI_GRANTS_* names adopted at construction (ADR-0076 PR 3b); the session-start warning names them. */
   readonly adoptedLegacyEnv: readonly string[];
   /** False only for the explicit PI_DADDY_GOVERNANCE opt-out; otherwise roots are observed-bound. */
@@ -519,7 +523,8 @@ async function loadProjectDiscovery(
   await establishRootPin(session, lifecycle);
   const skips: string[] = [];
   assertDiscoveryHealthy(session, lifecycle);
-  const snapshot = selected === undefined ? undefined : await selectedDefinitions(selected);
+  const snapshot =
+    selected === undefined ? undefined : await selectedDefinitions(selected, session.publicEvidence !== undefined);
   const definitions =
     snapshot?.definitions ??
     (await (session.discovery.definitions ?? loadDefinitions)(cwd, (_path, reason) => skips.push(reason)));
@@ -632,6 +637,7 @@ export function createGrantsSession(
      */
     mayDelegate: !governed || inherited.includes(DELEGATE_CAPABILITY) || inherited.includes(WILDCARD),
     ownerBound: false,
+    publicEvidence: createPublicEvidenceOwner(environment[ENV_PUBLIC_EVIDENCE_DIR]),
     allowUnresolvedModels: environment[ENV_ALLOW_UNRESOLVED_MODELS] === "1",
     nativeSessionRoot: nativeSessionRootFromEnv(process.env),
     modelResolutionCache: new Map<string, boolean>(),
@@ -687,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,
@@ -707,6 +713,9 @@ export function createGrantsSession(
       session.publishChildEnv();
     },
     reconcileEnvironment: (environment, lifecycle) => {
+      const evidenceDirectory = environment[ENV_PUBLIC_EVIDENCE_DIR];
+      if (session.reloadLifecycle !== lifecycle || session.publicEvidence?.directory !== evidenceDirectory)
+        session.publicEvidence = createPublicEvidenceOwner(evidenceDirectory);
       if (session.reloadLifecycle !== lifecycle) {
         session.pinSettled = false;
         session.workspacePin = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.44.4",
+  "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);
+}