pi-daddy 0.45.0 → 0.46.0

package/dist/governance/runtime-settlement.js

@@ -0,0 +1,236 @@
+/** Local runtime facts for explicitly armed resume; no task text, grants, approval or model verdicts. */
+import { lockRuntimeSettlement } from "./runtime-settlement-lock.js";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, realpathSync, lstatSync, openSync, writeFileSync, fsyncSync, closeSync, renameSync, unlinkSync, constants, readFileSync, } from "node:fs";
+import { join } from "node:path";
+import { readBoundedTextSync } from "../kernel/bounded-read-sync.js";
+import { isCapturedWorkerIdentity, readCapturedWorkerReceipt, sameWorkerIdentity } from "./captured-worker-record.js";
+const MAX_RECORD = 4 * 1024 * 1024;
+export const settlementHash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const ownerId = () => {
+    const stat = readFileSync("/proc/self/stat", "utf8");
+    return [
+        readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim(),
+        process.pid,
+        stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19],
+    ].join(":");
+};
+function ownerAlive(id) {
+    const [boot, pid, ticks] = id.split(":");
+    if (!/^\d+$/.test(pid ?? "") || !/^\d+$/.test(ticks ?? ""))
+        throw Error("invalid runtime journal owner");
+    if (readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim() !== boot)
+        return false;
+    try {
+        const text = readFileSync("/proc/" + pid + "/stat", "utf8");
+        return text.slice(text.lastIndexOf(")") + 2).split(" ")[19] === ticks;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function validate(value, sessionId, cwd) {
+    const j = value;
+    if (!j ||
+        j.version !== 1 ||
+        j.sessionId !== sessionId ||
+        j.cwd !== cwd ||
+        !/^[a-f0-9-]{36}$/.test(j.ownerScope) ||
+        typeof j.ownerId !== "string" ||
+        !Array.isArray(j.executions) ||
+        j.executions.length > 10000)
+        throw Error("invalid runtime journal identity");
+    const ids = new Set();
+    for (const e of j.executions) {
+        if (!e ||
+            typeof e.id !== "string" ||
+            !e.id ||
+            e.id.length > 512 ||
+            ids.has(e.id) ||
+            !["pending", "settled", "not-started", "unknown"].includes(e.state) ||
+            (e.identity !== undefined && (!isCapturedWorkerIdentity(e.identity) || e.identity.executionId !== e.id)) ||
+            (e.receiptSha256 !== undefined && !/^[a-f0-9]{64}$/.test(e.receiptSha256)) ||
+            (e.state === "settled" && (!e.identity || !e.receiptSha256)) ||
+            (e.state === "not-started" && e.identity) ||
+            (e.problem !== undefined && typeof e.problem !== "string"))
+            throw Error("invalid runtime journal execution");
+        ids.add(e.id);
+    }
+    return j;
+}
+export async function openRuntimeSettlement(directory, sessionId, cwd) {
+    if (process.platform !== "linux" || process.arch !== "x64")
+        throw Error("runtime settlement requires Linux x64");
+    if (!sessionId || sessionId.length > 512 || cwd !== realpathSync(cwd))
+        throw Error("runtime session/cwd identity is unavailable");
+    const root = join(realpathSync(directory), "pi-daddy", "runtime-settlement");
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    if (realpathSync(root) !== root)
+        throw Error("runtime settlement root must not contain symlinks");
+    const info = lstatSync(root);
+    if (!info.isDirectory() || info.uid !== process.getuid() || info.mode & 0o077)
+        throw Error("runtime settlement root must be private");
+    const path = join(root, settlementHash([sessionId, cwd]) + ".json");
+    const lock = await lockRuntimeSettlement(path + ".lock");
+    try {
+        let journal;
+        try {
+            journal = validate(JSON.parse(readBoundedTextSync(path, { maxBytes: MAX_RECORD }).text), sessionId, cwd);
+            if (ownerAlive(journal.ownerId))
+                throw Error("prior runtime owner is still alive");
+            journal.ownerId = ownerId();
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            journal = { version: 1, sessionId, cwd, ownerScope: randomUUID(), ownerId: ownerId(), executions: [] };
+        }
+        let failed, active = new Set();
+        const save = () => {
+            let temporary, fd;
+            try {
+                if (!lock.healthy())
+                    throw Error("runtime ownership lock was lost");
+                const text = JSON.stringify(journal) + "\n";
+                if (Buffer.byteLength(text) > MAX_RECORD)
+                    throw Error("runtime settlement journal exceeds its bound");
+                temporary = path + "." + randomUUID();
+                fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+                writeFileSync(fd, text);
+                fsyncSync(fd);
+                closeSync(fd);
+                fd = undefined;
+                renameSync(temporary, path);
+                const parent = openSync(root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+                try {
+                    fsyncSync(parent);
+                }
+                finally {
+                    closeSync(parent);
+                }
+            }
+            catch (error) {
+                failed = String(error);
+                throw error;
+            }
+            finally {
+                if (fd !== undefined)
+                    closeSync(fd);
+                if (temporary)
+                    try {
+                        unlinkSync(temporary);
+                    }
+                    catch { }
+            }
+        };
+        const entry = (id) => {
+            const e = journal.executions.find((e) => e.id === id);
+            if (!e)
+                throw Error("runtime execution was not registered");
+            return e;
+        };
+        save();
+        return {
+            ownerScope: journal.ownerScope,
+            ownerId: journal.ownerId,
+            sessionId,
+            cwd,
+            begin(id) {
+                if (failed)
+                    throw Error(failed);
+                if (typeof id !== "string" ||
+                    !id ||
+                    id.length > 512 ||
+                    journal.executions.some((e) => e.id === id) ||
+                    journal.executions.length >= 10000)
+                    throw Error("runtime execution id must be fresh and bounded");
+                journal.executions.push({ id, state: "pending" });
+                active.add(id);
+                save();
+            },
+            bind(identity) {
+                const e = entry(identity.executionId);
+                if (e.state !== "pending" || (e.identity && !sameWorkerIdentity(e.identity, identity)))
+                    throw Error("runtime ownership changed");
+                e.identity = { ...identity };
+                save();
+            },
+            async finish(id, cleanup, problem) {
+                const e = entry(id);
+                if (problem)
+                    e.problem = problem.slice(0, 2000);
+                try {
+                    if (cleanup.state === "not-started" && !e.identity)
+                        e.state = "not-started";
+                    else if (cleanup.state === "settled" && e.identity && sameWorkerIdentity(e.identity, cleanup.identity)) {
+                        const receipt = await readCapturedWorkerReceipt(e.identity);
+                        if (receipt) {
+                            e.state = "settled";
+                            e.receiptSha256 = settlementHash(receipt);
+                        }
+                        else
+                            e.state = "unknown";
+                    }
+                    else
+                        e.state = "unknown";
+                    save();
+                }
+                finally {
+                    active.delete(id);
+                }
+            },
+            async snapshot() {
+                if (!lock.healthy())
+                    failed = "runtime ownership lock was lost";
+                let changed = false;
+                for (const e of journal.executions) {
+                    if (active.has(e.id) || !e.identity)
+                        continue;
+                    const receipt = await readCapturedWorkerReceipt(e.identity);
+                    if (!receipt || (e.receiptSha256 && e.receiptSha256 !== settlementHash(receipt))) {
+                        if (e.state === "settled") {
+                            e.state = "unknown";
+                            changed = true;
+                        }
+                        continue;
+                    }
+                    if (e.state !== "settled") {
+                        e.state = "settled";
+                        e.receiptSha256 = settlementHash(receipt);
+                        changed = true;
+                    }
+                }
+                if (changed) {
+                    try {
+                        save();
+                    }
+                    catch { }
+                }
+                const outstanding = journal.executions.filter((e) => !["settled", "not-started"].includes(e.state) || e.problem);
+                const state = failed || outstanding.some((e) => !active.has(e.id))
+                    ? "unknown"
+                    : active.size
+                        ? "busy"
+                        : outstanding.length
+                            ? "unknown"
+                            : "idle";
+                return {
+                    ownerScope: journal.ownerScope,
+                    ownerId: journal.ownerId,
+                    evidenceDigest: settlementHash({ ownerScope: journal.ownerScope, executions: journal.executions }),
+                    state,
+                    settledExecutionIds: journal.executions.filter((e) => e.state === "settled").map((e) => e.id),
+                    outstandingExecutionIds: outstanding.map((e) => e.id),
+                    ...(failed ? { reason: failed } : {}),
+                };
+            },
+        };
+    }
+    catch (error) {
+        await lock.release();
+        throw error;
+    }
+}
+//# sourceMappingURL=runtime-settlement.js.map

package/dist/governance/runtime-settlement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-settlement.js","sourceRoot":"","sources":["../../src/governance/runtime-settlement.ts"],"names":[],"mappings":"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"}

package/extensions/execute-child.ts

@@ -1,7 +1,7 @@
 import { BoundedReadCleanupError } from "../src/kernel/bounded-read.ts";
 import { retainDiscoveryCleanupFailure } from "./session.ts";
 import type { CapacityReservation } from "../src/kernel/capacity.ts";
-import { HERDR_UNQUALIFIED_REASON } from "../src/executors/executor.ts";
+import { runHerdrOwned } from "../src/executors/herdr-owned.ts";
 import { runCapturedExecution } from "../src/executors/captured-execution.ts";
 import type { ChildFinal } from "../src/executors/child-final.ts";
 import type { CapturedWorkerCleanup } from "../src/kernel/captured-worker-contract.ts";
@@ -20,13 +20,12 @@ import {
   ENV_CHILD_IDLE_TIMEOUT,
   ENV_CHILD_TIMEOUT,
   idleTimeoutFromEnv,
-  runChild,
   timeoutFromEnv,
 } from "../src/kernel/run-child.ts";
 import { activitySessionFor } from "../src/executors/activity-session.ts";
 import { processTreeActivity } from "../src/executors/process-activity.ts";
 import { resolveWorkspace } from "../src/executors/herdr-cli.ts";
-import { HerdrWriterCloseError, runHerdrPane } from "../src/executors/run-herdr.ts";
+import { HerdrWriterCloseError } from "../src/executors/run-herdr.ts";
 import { GovernanceRefusal, refusal, type StructuredRefusal } from "../src/kernel/refusals.ts";
 import { ENV_HERDR_KEEP_PANE, type GrantsSession } from "./session.ts";
 import { CHILD_ATTRIBUTION_ENV_KEYS, ENV_EPISODE_ID } from "../src/kernel/env-names.ts";
@@ -138,15 +137,49 @@ export interface ChildExecutionInput {
 }
 export async function executePlannedChild(input: ChildExecutionInput): Promise<DelegationOutcome> {
   let executorEntered = false;
+  const runtime = input.session.reloadLifecycle?.runtimeSettlement;
+  let registered = false;
   try {
-    return await executePreparedChild(input, () => {
-      executorEntered = true;
-    });
+    runtime?.begin(input.executionId);
+    registered = Boolean(runtime);
+    const result = await executePreparedChild(
+      input,
+      () => {
+        executorEntered = true;
+      },
+      runtime,
+    );
+    try {
+      await runtime?.finish(
+        input.executionId,
+        result.cleanup ?? { state: "unknown", reason: "executor omitted cleanup" },
+        result.control === "failed" ? (result.reason ?? "runtime control failed") : undefined,
+      );
+    } catch (error) {
+      return {
+        ...result,
+        control: "failed",
+        reason: [result.reason, `runtime settlement record failed: ${String(error)}`].filter(Boolean).join("; "),
+      };
+    }
+    return result;
   } catch (error) {
-    if (executorEntered) throw error;
-    // Every operation above the executor-entry marker is local setup: no helper or worker exists yet.
-    input.capacityReservation?.finalize({ state: "not-started", reason: "child setup failed before executor entry" });
     const failures: unknown[] = [error];
+    if (registered)
+      try {
+        await runtime?.finish(input.executionId, {
+          state: executorEntered ? "unknown" : "not-started",
+          reason: String(error),
+        });
+      } catch (recordError) {
+        failures.push(recordError);
+      }
+    if (executorEntered) {
+      if (failures.length > 1) throw new AggregateError(failures, failures.map(String).join("; "));
+      throw error;
+    }
+    // Setup failures prove no worker started, even if recording that fact also failed.
+    input.capacityReservation?.finalize({ state: "not-started", reason: "child setup failed before executor entry" });
     try {
       const released = await releaseDelegationWorkspace({
         prepared: input.preparedWorkspace,
@@ -174,6 +207,7 @@ export async function executePlannedChild(input: ChildExecutionInput): Promise<D
 async function executePreparedChild(
   input: ChildExecutionInput,
   onExecutorEntry: () => void,
+  runtime?: import("../src/governance/runtime-settlement.ts").RuntimeSettlement,
 ): Promise<DelegationOutcome> {
   const { session, plan, childId, executionId, parentExecutionId, preparedWorkspace, signal, onProgress } = input;
   const ledgerPath = session.ledgerPath;
@@ -229,7 +263,7 @@ async function executePreparedChild(
   const activitySession = await activitySessionFor(plan.args, executionId);
   // Disposed on every path (review finding: it leaked on every throw), except when the operator keeps a Herdr pane,
   // where the interactive pi in that pane is still alive and still appending to this file.
-  const keepPaneRequested = session.executor.kind === "herdr" && process.env[ENV_HERDR_KEEP_PANE] === "1";
+  const keepPaneRequested = false; // The qualified pane launcher exits; retained panes contain no live Pi writer.
   try {
     return await executeWithActivitySession();
   } finally {
@@ -368,73 +402,63 @@ async function executePreparedChild(
       }
     };
     try {
-      if (String(session.executor.kind) === "herdr")
-        throw new GovernanceRefusal(refusal("EXECUTOR_UNAVAILABLE", HERDR_UNQUALIFIED_REASON));
+      if (session.executor.refusal)
+        throw new GovernanceRefusal(refusal("EXECUTOR_UNAVAILABLE", session.executor.refusal));
       executorEntered = true;
       onExecutorEntry();
-      const output =
-        session.executor.kind === "herdr"
-          ? await runHerdrPane({
-              args: args.slice(0, -1),
-              prompt: args[args.length - 1].trimStart(),
-              env: plan.env,
-              cwd,
-              name: `${input.agent ?? "delegate"}-${childId}`,
-              workspace: resolveWorkspace(process.env),
-              signal: executionSignal,
-              timeoutMs: remainingTimeoutMs,
-              idleTimeoutMs: configuredIdleMs,
-              activityProbe: activitySession.probe, // Herdr: session file plus pane text when a display is attached
-              keepPane: writerLease ? false : process.env[ENV_HERDR_KEEP_PANE] === "1",
-              closeOnSettle: Boolean(writerLease),
-              onPane: (paneId, agentName) => {
-                retention.native({ paneId, agentName });
-                onProgress?.({ paneId, agentName, state: "starting" });
-              },
-              onObservation: (bytes) => retention.capture("paneSnapshot", bytes, true),
-              onSessionReference: (reference) => retention.observeSession(reference),
-              onRunning: (paneId, agentName) => {
-                // Record first: runHerdrPane isolates this display callback, so a renderer exception after the
-                // observation cannot suppress the authoritative running event.
-                recordRunning("herdr", { id: paneId, agentName });
-                onProgress?.({ paneId, agentName, state: "running" });
-              },
-              onTab: preparedWorkspace ? (tabId) => preparedWorkspace.lease.attachHerdrTab(tabId) : undefined,
-              onNativeTab: (tabId) => retention.native({ tabId }),
-              onSnapshot: onProgress ? (snapshot) => onProgress({ snapshot }) : undefined,
-            })
-          : await runCapturedExecution({
-              executionId,
-              sessionPath: activitySession.path,
-              onReadCleanup,
-              onOwnership: async (identity) => {
-                input.capacityReservation?.bindOwnership(identity);
-                await preparedWorkspace?.lease.attachCapturedWorker(identity);
-              },
-              command: "pi",
-              args,
-              env: mergeChildEnv(process.env, plan.env),
-              cwd,
-              signal: executionSignal,
-              // SIGTERM gets only grace that fits INSIDE the recorded deadline. The independent hard timer
-              // prevents a delayed soft-timeout callback from starting a fresh grace period beyond that bound.
-              timeoutMs: Math.max(1, remainingTimeoutMs - terminationGraceMs),
-              hardDeadlineAt: Date.parse(deadlineAt),
-              idleTimeoutMs: configuredIdleMs,
-              activityProbe: probe,
-              onOutput: onProgress ? (chunk) => onProgress({ chunk }) : undefined,
-              onObservation: (stream, bytes) => retention.capture(stream, bytes),
-              onSpawn: (pid) => {
-                childPid = pid;
-                // Lease attachment is a security hook and may fail the spawn. The shared reporters isolate
-                // display exceptions before they reach this callback; runChild deliberately kills on any error
-                // here, so presentation must never be added directly without that reporter boundary.
+      let displayHerdr: ((text: string) => void) | undefined;
+      const output = await runCapturedExecution(
+        {
+          executionId,
+          sessionPath: activitySession.path,
+          onReadCleanup,
+          onOwnership: async (identity) => {
+            runtime?.bind(identity);
+            input.capacityReservation?.bindOwnership(identity);
+            await preparedWorkspace?.lease.attachCapturedWorker(identity);
+          },
+          command: "pi",
+          args,
+          env: mergeChildEnv(process.env, plan.env),
+          cwd,
+          signal: executionSignal,
+          // SIGTERM gets only grace that fits INSIDE the recorded deadline. The independent hard timer
+          // prevents a delayed soft-timeout callback from starting a fresh grace period beyond that bound.
+          timeoutMs: Math.max(1, remainingTimeoutMs - terminationGraceMs),
+          hardDeadlineAt: Date.parse(deadlineAt),
+          idleTimeoutMs: configuredIdleMs,
+          activityProbe: probe,
+          onOutput: (chunk) => {
+            displayHerdr?.(chunk);
+            onProgress?.({ chunk });
+          },
+          onObservation: (stream, bytes) => retention.capture(stream, bytes),
+          onSpawn: (pid) => {
+            childPid = pid;
+            // Lease attachment is a security hook and may fail the spawn. The shared reporters isolate
+            // display exceptions before they reach this callback; runChild deliberately kills on any error
+            // here, so presentation must never be added directly without that reporter boundary.
 
-                retention.native({ pid });
-                recordRunning("process");
-                onProgress?.({ state: "running" });
-              },
-            });
+            retention.native({ pid });
+            recordRunning(session.executor.kind);
+            onProgress?.({ state: "running" });
+          },
+        },
+        session.executor.kind === "herdr"
+          ? (request) =>
+              runHerdrOwned(request, {
+                onDisplay: (display) => {
+                  displayHerdr = display;
+                },
+                workspace: resolveWorkspace(process.env),
+                keepPane: process.env[ENV_HERDR_KEEP_PANE] === "1",
+                onPane: (paneId, tabId) => {
+                  retention.native({ paneId, tabId });
+                  onProgress?.({ paneId, state: "starting" });
+                },
+              })
+          : undefined,
+      );
 
       if (sessionFlag >= 0) retention.observeSession({ source: "pi-session-file", value: plan.args[sessionFlag + 1] });
       retention.capture("result", Buffer.from(output.text), true);

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