pi-daddy 0.44.4 → 0.46.0

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/runtime-settlement-lock.ts

@@ -0,0 +1,76 @@
+/** An OS-held single-writer lock; parent pipe loss releases it without stale-age guesses. */
+import { spawn } from "node:child_process";
+import { constants, openSync, closeSync, fstatSync } from "node:fs";
+export async function lockRuntimeSettlement(path: string): Promise<{ healthy(): boolean; release(): Promise<void> }> {
+  const fd = openSync(path, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+  const info = fstatSync(fd);
+  if (!info.isFile() || info.uid !== process.getuid!() || info.mode & 0o077) {
+    closeSync(fd);
+    throw Error("runtime lock is not a private ordinary file");
+  }
+  const child = spawn(
+    "/usr/bin/flock",
+    [
+      "--no-fork",
+      "--wait",
+      "1",
+      "/proc/self/fd/3",
+      process.execPath,
+      "-e",
+      'process.stdout.write("locked\\n");process.stdin.resume();process.stdin.on("end",()=>process.exit(0));',
+    ],
+    { stdio: ["pipe", "pipe", "ignore", fd] },
+  );
+  closeSync(fd);
+  let healthy = false,
+    line = "";
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      child.stdin?.destroy();
+      child.kill();
+      reject(Error("runtime ownership lock timed out"));
+    }, 3000);
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on("exit", () => {
+      healthy = false;
+      clearTimeout(timer);
+      reject(Error("another live runtime owns this Pi session"));
+    });
+    child.stdout?.on("data", (bytes) => {
+      line += bytes.toString();
+      if (line === "locked\n") {
+        healthy = true;
+        clearTimeout(timer);
+        resolve();
+      } else if (line.length > 16) {
+        clearTimeout(timer);
+        child.stdin?.destroy();
+        reject(Error("runtime lock returned malformed readiness"));
+      }
+    });
+  });
+  child.unref();
+  (child.stdin as import("node:net").Socket).unref();
+  (child.stdout as import("node:net").Socket).unref();
+  let releasing: Promise<void> | undefined;
+  return {
+    healthy: () => healthy && child.exitCode === null && child.signalCode === null,
+    release: () =>
+      (releasing ??= new Promise<void>((resolve) => {
+        healthy = false;
+        if (child.exitCode !== null || child.signalCode !== null) {
+          resolve();
+          return;
+        }
+        const timer = setTimeout(() => child.kill("SIGKILL"), 1000);
+        child.once("close", () => {
+          clearTimeout(timer);
+          resolve();
+        });
+        child.stdin?.end();
+      })),
+  };
+}

package/src/governance/runtime-settlement.ts

@@ -0,0 +1,271 @@
+/** Local runtime facts for explicitly armed resume; no task text, grants, approval or model verdicts. */
+import { lockRuntimeSettlement } from "./runtime-settlement-lock.ts";
+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.ts";
+import type { CapturedWorkerCleanup, CapturedWorkerIdentity } from "../kernel/captured-worker-contract.ts";
+import { isCapturedWorkerIdentity, readCapturedWorkerReceipt, sameWorkerIdentity } from "./captured-worker-record.ts";
+const MAX_RECORD = 4 * 1024 * 1024;
+interface Execution {
+  id: string;
+  state: "pending" | "settled" | "not-started" | "unknown";
+  identity?: CapturedWorkerIdentity;
+  receiptSha256?: string;
+  problem?: string;
+}
+interface Journal {
+  version: 1;
+  sessionId: string;
+  cwd: string;
+  ownerScope: string;
+  ownerId: string;
+  executions: Execution[];
+}
+export const settlementHash = (value: unknown): string =>
+  createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const ownerId = (): string => {
+  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: string): boolean {
+  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 as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+function validate(value: unknown, sessionId: string, cwd: string): Journal {
+  const j = value as Journal;
+  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<string>();
+  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 interface RuntimeSettlement {
+  readonly ownerScope: string;
+  readonly ownerId: string;
+  readonly sessionId: string;
+  readonly cwd: string;
+  begin(id: string): void;
+  bind(identity: CapturedWorkerIdentity): void;
+  finish(id: string, cleanup: CapturedWorkerCleanup, problem?: string): Promise<void>;
+  snapshot(): Promise<{
+    ownerScope: string;
+    ownerId: string;
+    evidenceDigest: string;
+    state: "idle" | "busy" | "unknown";
+    settledExecutionIds: string[];
+    outstandingExecutionIds: string[];
+    reason?: string;
+  }>;
+}
+export async function openRuntimeSettlement(
+  directory: string,
+  sessionId: string,
+  cwd: string,
+): Promise<RuntimeSettlement> {
+  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: 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 as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      journal = { version: 1, sessionId, cwd, ownerScope: randomUUID(), ownerId: ownerId(), executions: [] };
+    }
+    let failed: string | undefined,
+      active = new Set<string>();
+    const save = () => {
+      let temporary: string | undefined, fd: number | undefined;
+      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: string) => {
+      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;
+  }
+}