pi-daddy 0.43.0 → 0.44.0

package/src/governance/captured-worker-record.ts

@@ -0,0 +1,138 @@
+/** Independent ownership evidence; unreadable/mismatched receipts never establish settlement. */
+import { constants } from "node:fs";
+import { open, realpath, stat, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { CapturedWorkerIdentity, CapturedWorkerReceipt } from "../kernel/captured-worker-contract.ts";
+
+const identityKeys = [
+  "revision",
+  "executionId",
+  "nonce",
+  "root",
+  "rootDevice",
+  "rootInode",
+  "bootId",
+  "pidNamespace",
+  "helperPid",
+  "helperStartTicks",
+  "helperSha256",
+  "workerPid",
+  "ownershipPath",
+  "receiptPath",
+] as const;
+export function isCapturedWorkerIdentity(value: unknown): value is CapturedWorkerIdentity {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  if (
+    v.revision !== 1 ||
+    !Number.isSafeInteger(v.helperPid) ||
+    Number(v.helperPid) < 1 ||
+    !Number.isSafeInteger(v.workerPid) ||
+    Number(v.workerPid) < 1
+  )
+    return false;
+  if (
+    identityKeys.some(
+      (key) => !["revision", "helperPid", "workerPid"].includes(key) && (typeof v[key] !== "string" || !v[key]),
+    )
+  )
+    return false;
+  if (!/^[a-f0-9]{64}$/.test(String(v.helperSha256)) || !/^\d+$/.test(String(v.helperStartTicks))) return false;
+  return (
+    v.ownershipPath === join(dirname(String(v.receiptPath)), "ownership.json") &&
+    v.receiptPath === join(dirname(String(v.ownershipPath)), "receipt.json")
+  );
+}
+export async function readWorkerRecord(path: string): Promise<unknown> {
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const info = await file.stat();
+    if (!info.isFile() || info.size > 16384) throw new Error("worker record must be a bounded ordinary file");
+    const buffer = Buffer.alloc(16385);
+    const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+    if (bytesRead > 16384) throw new Error("worker record grew beyond its bound");
+    return JSON.parse(buffer.subarray(0, bytesRead).toString("utf8"));
+  } finally {
+    await file.close();
+  }
+}
+export function sameWorkerIdentity(a: CapturedWorkerIdentity, b: CapturedWorkerIdentity): boolean {
+  return identityKeys.every((key) => a[key] === b[key]);
+}
+export async function readCapturedWorkerReceipt(
+  identity: CapturedWorkerIdentity,
+): Promise<CapturedWorkerReceipt | null> {
+  try {
+    if (!isCapturedWorkerIdentity(identity)) return null;
+    const ownership = (await readWorkerRecord(identity.ownershipPath)) as { state?: unknown; identity?: unknown };
+    const value = (await readWorkerRecord(identity.receiptPath)) as CapturedWorkerReceipt;
+    if (
+      ownership.state !== "ready" ||
+      !isCapturedWorkerIdentity(ownership.identity) ||
+      !sameWorkerIdentity(identity, ownership.identity)
+    )
+      return null;
+    if (
+      value.state !== "settled" ||
+      value.reapedAll !== true ||
+      !isCapturedWorkerIdentity(value.identity) ||
+      !sameWorkerIdentity(identity, value.identity)
+    )
+      return null;
+    if (
+      value.workerCode !== null &&
+      (!Number.isInteger(value.workerCode) || value.workerCode < 0 || value.workerCode > 255)
+    )
+      return null;
+    if (!Number.isInteger(value.workerSignal) || value.workerSignal < 0 || value.workerSignal > 64) return null;
+    if (
+      !["worker-exit", "owner-loss", "cancelled", "helper-signal", "ownership-write-failed", "start-failed"].includes(
+        value.reason,
+      )
+    )
+      return null;
+    if (value.workerSignal !== 0 && value.workerCode !== null) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+/** Before release of the execution gate, validate namespace, workspace and the still-live actual helper. */
+export async function validateLiveWorker(identity: CapturedWorkerIdentity, helperPath: string): Promise<void> {
+  if (!isCapturedWorkerIdentity(identity)) throw new Error("malformed captured worker identity");
+  const [root, rootInfo, boot, namespace, processStat, executable, packaged] = await Promise.all([
+    realpath(identity.root),
+    stat(identity.root, { bigint: true }),
+    readFile("/proc/sys/kernel/random/boot_id", "utf8"),
+    import("node:fs/promises").then((fs) => fs.readlink("/proc/self/ns/pid")),
+    readFile(`/proc/${identity.helperPid}/stat`, "utf8"),
+    stat(`/proc/${identity.helperPid}/exe`),
+    stat(helperPath),
+  ]);
+  const fields = processStat.slice(processStat.lastIndexOf(")") + 2).split(" ");
+  if (
+    root !== identity.root ||
+    String(rootInfo.dev) !== identity.rootDevice ||
+    String(rootInfo.ino) !== identity.rootInode ||
+    boot.trim() !== identity.bootId ||
+    namespace !== identity.pidNamespace ||
+    fields[19] !== identity.helperStartTicks ||
+    executable.dev !== packaged.dev ||
+    executable.ino !== packaged.ino
+  )
+    throw new Error("captured worker identity differs from actual live ownership");
+}
+
+export async function matchesWorkerWorkspace(identity: CapturedWorkerIdentity, root: string): Promise<boolean> {
+  try {
+    const info = await stat(root, { bigint: true });
+    return (
+      identity.root === root &&
+      (await realpath(root)) === root &&
+      String(info.dev) === identity.rootDevice &&
+      String(info.ino) === identity.rootInode
+    );
+  } catch {
+    return false;
+  }
+}

package/src/governance/lease-record.ts

@@ -6,10 +6,13 @@
  * successor's token — all of which are about what the record SAYS rather than about the kernel lock.
  */
 import { createHash, randomUUID } from "node:crypto";
-import { readFile, rename, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { open, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import type { ValidatedWorkspace, WorkspaceAccess } from "../kernel/workspace.ts";
 
+import type { CapturedWorkerIdentity } from "../kernel/captured-worker-contract.ts";
+import { isCapturedWorkerIdentity } from "./captured-worker-record.ts";
+
 export interface LeaseMetadata {
   version: 1;
   state: "active" | "released";
@@ -19,6 +22,7 @@ export interface LeaseMetadata {
   root: string;
   pid: number;
   acquired_at: string;
+  captured_worker?: CapturedWorkerIdentity;
   released_at?: string;
   release_reason?: string;
 }
@@ -35,6 +39,8 @@ export interface WorkspaceLease {
   recovered: boolean | "unknown";
   /** Attach the governed resource so parent death cleans it before the kernel lock is released. */
   attachProcess(pid: number): void;
+  /** Persist exact gated-worker ownership before its command may execute. */
+  attachCapturedWorker(identity: CapturedWorkerIdentity): Promise<void>;
   attachHerdrTab(tabId: string): void;
   /** Resolves only when the kernel-lock helper exits before explicit release. */
   lost: Promise<Error>;
@@ -104,7 +110,19 @@ export function leasePaths(leaseDir: string, root: string) {
 export async function atomicMetadata(path: string, value: LeaseMetadata): Promise<void> {
   const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
   await writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+  const file = await open(temp, "r+");
+  try {
+    await file.sync();
+  } finally {
+    await file.close();
+  }
   await rename(temp, path);
+  const directory = await open(dirname(path), "r");
+  try {
+    await directory.sync();
+  } finally {
+    await directory.close();
+  }
 }
 
 /**
@@ -124,6 +142,7 @@ export async function readMetadata(path: string): Promise<LeaseMetadata | null |
     if (value?.version !== 1) return "malformed";
     if (value.state !== "active" && value.state !== "released") return "malformed";
     if (typeof value.token !== "string" || !value.token) return "malformed";
+    if (value.captured_worker !== undefined && !isCapturedWorkerIdentity(value.captured_worker)) return "malformed";
     return value as LeaseMetadata;
   } catch {
     return "malformed";

package/src/governance/ledger-events.ts

@@ -150,13 +150,13 @@ export interface ChildLifecycleEvent extends LedgerEventBase {
   idleTimeoutMs?: number;
   /** The provider/model selected for the child, confirmed from its persisted assistant message when available. */
   resolvedModel?: { provider: string; modelId: string } | null;
-  modelSource?: "explicit" | "session" | "definition" | "global" | "pi";
+  modelSource?: "explicit" | "session" | "definition" | "authored" | "global" | "pi";
   /** The persisted effective level and its selection source, when pi reports one. */
   thinkingLevel?: {
     level: string;
-    source: "explicit" | "session" | "advisor" | "definition" | "global" | "pi";
+    source: "explicit" | "session" | "advisor" | "definition" | "authored" | "global" | "pi";
   } | null;
-  thinkingSource?: "explicit" | "session" | "advisor" | "definition" | "global" | "pi";
+  thinkingSource?: "explicit" | "session" | "advisor" | "definition" | "authored" | "global" | "pi";
   /** Provider-reported token dimensions; zero is normalised to null rather than invented as reported usage. */
   tokenDetail?: ChildTokenDetail;
   /** Aggregate model usage read from the child's pi session file after it stopped. */
@@ -353,9 +353,9 @@ export function buildChildLifecycleEvent(args: {
   truncated?: boolean;
   reason?: string;
   resolvedModel?: { provider: string; modelId: string };
-  modelSource?: "explicit" | "session" | "definition" | "global" | "pi";
+  modelSource?: "explicit" | "session" | "definition" | "authored" | "global" | "pi";
   effectiveThinkingLevel?: string;
-  thinkingSource?: "explicit" | "session" | "advisor" | "definition" | "global" | "pi";
+  thinkingSource?: "explicit" | "session" | "advisor" | "definition" | "authored" | "global" | "pi";
   tokenDetail?: ChildTokenDetail;
   usage?: ChildUsageTotals;
   compactionCount?: number;

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

@@ -406,7 +406,7 @@ function validResolvedModel(value: unknown): boolean {
   );
 }
 
-const MODEL_SOURCES = ["explicit", "session", "definition", "global", "pi"];
+const MODEL_SOURCES = ["explicit", "session", "definition", "authored", "global", "pi"];
 const THINKING_SOURCES = [...MODEL_SOURCES, "advisor"];
 function validThinkingLevel(value: unknown): boolean {
   return (

package/src/governance/workspace-acceptance.ts

@@ -40,8 +40,9 @@
  *
  * Keyed by registry path, not by project: accepting an id is a statement about the operator's registry.
  */
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { readAuthorityText } from "../kernel/authority-text.ts";
 import { acceptedWorkspacesPath } from "../kernel/project-paths.ts";
 
 export interface AcceptedWorkspaces {
@@ -84,12 +85,23 @@ export async function reconcileAcceptedWorkspaces(
   registryPath: string,
   registryIds: readonly string[],
   env: NodeJS.ProcessEnv = process.env,
+  /** Trusted physical-read dependency; never supplied by a registry or requester. */
+  read: (path: string) => Promise<string> = readAuthorityText,
+  assertHealthy?: () => void,
 ): Promise<AcceptedWorkspaces> {
+  assertHealthy?.();
   const path = acceptedWorkspacesPath(registryPath, env);
-  const text = await readFile(path, "utf8").catch(() => undefined);
+  const text = await read(path).catch((error: unknown) => {
+    // Unknown decisions are not first use; preserve physical failures and their recovery capabilities.
+    if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") throw error;
+    assertHealthy?.();
+    return undefined;
+  });
+  assertHealthy?.();
   if (text === undefined) {
     const accepted = [...registryIds].sort();
-    await write(path, { version: 1, registry: registryPath, accepted });
+    await write(path, { version: 1, registry: registryPath, accepted }, assertHealthy);
+    assertHealthy?.();
     return { accepted, firstUse: true, unaccepted: [] };
   }
   const stored = parse(text);
@@ -116,9 +128,13 @@ export async function acceptWorkspaces(
 }
 
 /** Atomic, for the reason every other store here is: a half-written record reads as a narrower decision. */
-async function write(path: string, body: StoredAcceptance): Promise<void> {
+async function write(path: string, body: StoredAcceptance, assertHealthy?: () => void): Promise<void> {
+  assertHealthy?.();
   await mkdir(dirname(path), { recursive: true });
+  assertHealthy?.();
   const temp = join(dirname(path), `.${Math.random().toString(36).slice(2)}.tmp`);
   await writeFile(temp, `${JSON.stringify(body, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  assertHealthy?.();
   await rename(temp, path);
+  assertHealthy?.();
 }

package/src/governance/workspace-lease.ts

@@ -1,3 +1,10 @@
+import {
+  readCapturedWorkerReceipt,
+  matchesWorkerWorkspace,
+  readWorkerRecord,
+  sameWorkerIdentity,
+  isCapturedWorkerIdentity,
+} from "./captured-worker-record.ts";
 import { createHash, randomUUID } from "node:crypto";
 import {
   atomicMetadata,
@@ -84,6 +91,7 @@ export async function acquireWorkspaceLease(input: {
       ownerId: input.ownerId,
       recovered: false,
       attachProcess: () => {},
+      attachCapturedWorker: async () => {},
       attachHerdrTab: () => {},
       // A read lease took no kernel lock, so there is nothing to keep: `not-held` is the same answer
       // `release()` gives, and it is the truth rather than a retention that never happened (R-152).
@@ -238,8 +246,25 @@ export async function acquireWorkspaceLease(input: {
   }
 
   const previous = await readMetadata(paths.metadata);
+  // A free kernel lock cannot establish settlement of an earlier captured subtree.
+  if (
+    previous === "malformed" ||
+    (previous?.captured_worker &&
+      (!(await matchesWorkerWorkspace(previous.captured_worker, input.workspace.root)) ||
+        !(await readCapturedWorkerReceipt(previous.captured_worker)))) ||
+    (previous?.state === "active" && !previous.captured_worker)
+  ) {
+    holder.stdin?.end();
+    throw new GovernanceRefusal(
+      refusal(
+        "WORKSPACE_LEASE_STALE",
+        "predecessor workspace ownership is unresolved; original matching worker settlement evidence is required",
+        { workspace_id: input.workspace.workspaceId, root: input.workspace.root },
+      ),
+    );
+  }
   // "malformed" is not "no prior owner": an unreadable record cannot prove a clean handover (R-100).
-  const recovered: boolean | "unknown" = previous === "malformed" ? "unknown" : previous?.state === "active";
+  const recovered = previous?.state === "active";
   const token = randomUUID();
   const metadata: LeaseMetadata = {
     version: 1,
@@ -295,6 +320,28 @@ export async function acquireWorkspaceLease(input: {
     access: "write",
     ownerId: input.ownerId,
     recovered,
+    async attachCapturedWorker(identity) {
+      if (releasing || holder.exitCode !== null || holder.signalCode !== null)
+        throw new Error("writer lease lost before captured ownership persistence");
+      if (!isCapturedWorkerIdentity(identity) || !(await matchesWorkerWorkspace(identity, input.workspace.root)))
+        throw new Error("captured identity does not match leased workspace");
+      const current = await readMetadata(paths.metadata);
+      if (current === "malformed" || current?.token !== token)
+        throw new Error("writer ownership record changed before captured attachment");
+      if (metadata.captured_worker && !sameWorkerIdentity(metadata.captured_worker, identity))
+        throw new Error("writer lease already owns another captured execution");
+      const record = (await readWorkerRecord(identity.ownershipPath)) as { state?: unknown; identity?: unknown };
+      if (
+        record.state !== "ready" ||
+        !isCapturedWorkerIdentity(record.identity) ||
+        !sameWorkerIdentity(identity, record.identity)
+      )
+        throw new Error("captured readiness record mismatch");
+      metadata.captured_worker = identity;
+      await atomicMetadata(paths.metadata, metadata);
+      if (holder.exitCode !== null || holder.signalCode !== null)
+        throw new Error("writer lease lost during captured ownership persistence");
+    },
     attachProcess(pid) {
       attach({ process_pid: pid });
     },
@@ -383,6 +430,17 @@ export async function acquireWorkspaceLease(input: {
     async release(reason = "completed"): Promise<LeaseReleaseOutcome> {
       // Memoized, not a boolean. A second call used to answer "released" whatever the first returned, so a
       // retry — or a `finally` after an explicit release — read a clean handover that never happened.
+      if (metadata.captured_worker) {
+        const receipt = await readCapturedWorkerReceipt(metadata.captured_worker);
+        if (!receipt) {
+          holder.unref();
+          unrefStream(holder.stdout);
+          unrefStream(holder.stderr);
+          return (settled = "retained");
+        }
+        // Only original matching receipt can reconcile a previously uncertain captured worker.
+        if (settled === "retained") settled = undefined;
+      }
       if (settled) return settled;
       releasing = true;
       // Already gone: this owner never released anything, and saying so is the caller's business to

package/src/kernel/authority-text.ts

@@ -0,0 +1,17 @@
+/** Authority metadata: only ENOENT is absence; damage and unresolved cleanup preserve failure. */
+import { readBoundedFile } from "./bounded-read.ts";
+export async function readAuthorityText(path: string): Promise<string> {
+  const read = await readBoundedFile(path, { maxBytes: 1024 * 1024, timeoutMs: 2_000 });
+  if (read.ok) return read.text;
+  const error = new Error(`Cannot read ${path}: ${read.why} (${read.detail})`);
+  if ("code" in read && read.code) Object.assign(error, { code: read.code });
+  throw error;
+}
+export async function readOptionalAuthorityText(path: string): Promise<string | undefined> {
+  try {
+    return await readAuthorityText(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}

package/src/kernel/bounded-read-failures.ts

@@ -0,0 +1,42 @@
+import { BoundedReadCleanupError } from "./bounded-read.ts";
+
+/** Independent failed readers remain typed, with every original recovery capability intact. */
+export class CollectedBoundedReadCleanupError extends BoundedReadCleanupError {
+  readonly errors: readonly BoundedReadCleanupError[];
+  constructor(errors: readonly BoundedReadCleanupError[]) {
+    const members = Object.freeze([...errors]);
+    super(members, async () => {
+      const outcomes = await Promise.allSettled(members.map((error) => error.cleanup()));
+      const failed = members.filter((_error, index) => outcomes[index].status === "rejected");
+      if (failed.length) throw collectBoundedReadFailures(failed);
+    });
+    this.name = "CollectedBoundedReadCleanupError";
+    this.message = `${members.length} bounded reader descriptor cleanups unresolved; retain and explicitly retry`;
+    this.errors = members;
+  }
+}
+
+/** Preserve singleton identity; flatten only our typed collection, never arbitrary caller errors. */
+export function collectBoundedReadFailures(errors: readonly unknown[]): BoundedReadCleanupError | undefined {
+  const members = [
+    ...new Set(
+      errors.flatMap((error) =>
+        error instanceof CollectedBoundedReadCleanupError
+          ? error.errors
+          : error instanceof BoundedReadCleanupError
+            ? [error]
+            : [],
+      ),
+    ),
+  ];
+  const existing = errors.find(
+    (error) =>
+      error instanceof CollectedBoundedReadCleanupError &&
+      error.errors.length === members.length &&
+      error.errors.every((member, index) => member === members[index]),
+  );
+  return (
+    (existing as CollectedBoundedReadCleanupError | undefined) ??
+    (members.length > 1 ? new CollectedBoundedReadCleanupError(members) : members[0])
+  );
+}

package/src/kernel/bounded-read-sync.ts

@@ -0,0 +1,87 @@
+/** Bounded synchronous reads for the synchronous planner/settings seams. */
+import { constants, openSync, closeSync, fstatSync, readSync, realpathSync } from "node:fs";
+import { isAbsolute, relative } from "node:path";
+import { BoundedReadCleanupError } from "./bounded-read.ts";
+
+export interface SyncReadPorts {
+  open: typeof openSync;
+  close: typeof closeSync;
+  stat: typeof fstatSync;
+  read: typeof readSync;
+  realpath: (path: string) => string;
+}
+const ports: SyncReadPorts = {
+  open: openSync,
+  close: closeSync,
+  stat: fstatSync,
+  read: readSync,
+  realpath: realpathSync,
+};
+const unresolved = new Set<BoundedReadCleanupError>();
+/** Diagnostic owners only: a numeric fd cannot safely be retried after close failed and may have been reused. */
+export function unresolvedSyncReadCleanups(): readonly BoundedReadCleanupError[] {
+  return [...unresolved];
+}
+export function readBoundedTextSync(
+  path: string,
+  options: {
+    maxBytes: number;
+    timeoutMs?: number;
+    prefix?: boolean;
+    confinedRoot?: string;
+    now?: () => number;
+  },
+  io: SyncReadPorts = ports,
+): { text: string; truncated: boolean; size: number } {
+  const now = options.now ?? Date.now;
+  const deadline = now() + (options.timeoutMs ?? 2_000);
+  const fd = io.open(path, constants.O_RDONLY | constants.O_NONBLOCK | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const stat = io.stat(fd);
+    if (!stat.isFile()) throw new Error("not a regular file");
+    // Linux /proc resolves the held object, including ancestor substitutions between realpath and open.
+    // If this proof is unavailable, named context files are refused rather than trusting the earlier path.
+    if (options.confinedRoot) {
+      const held = io.realpath(`/proc/self/fd/${fd}`);
+      const within = relative(options.confinedRoot, held);
+      if (!within || within === ".." || within.startsWith("../") || isAbsolute(within))
+        throw new Error("held file is outside this session's working directory");
+    }
+    if (!options.prefix && stat.size > options.maxBytes) throw new Error("file exceeds byte limit");
+    const bytes = Buffer.alloc(options.maxBytes + 1);
+    let offset = 0;
+    while (offset < bytes.length) {
+      if (now() > deadline) throw new Error("bounded read timed out");
+      const count = io.read(fd, bytes, offset, Math.min(64 * 1024, bytes.length - offset), offset);
+      if (!count) break;
+      offset += count;
+    }
+    const truncated = offset > options.maxBytes;
+    if (truncated && !options.prefix) throw new Error("file grew beyond byte limit");
+    // stream:true accepts only an incomplete final codepoint at a deliberately truncated boundary.
+    // Malformed bytes in the retained prefix still throw; valid replacement characters remain intact.
+    let text: string;
+    try {
+      text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
+        bytes.subarray(0, Math.min(offset, options.maxBytes)),
+        { stream: truncated },
+      );
+    } catch (cause) {
+      throw new Error("invalid UTF-8", { cause });
+    }
+    return { text, truncated, size: stat.size };
+  } finally {
+    try {
+      io.close(fd);
+    } catch (cause) {
+      let failure: BoundedReadCleanupError;
+      failure = new BoundedReadCleanupError(cause, async () => {
+        throw failure;
+      });
+      failure.message =
+        "synchronous reader close failed; descriptor ownership is unresolved; automatic retry is unsafe";
+      unresolved.add(failure);
+      throw failure;
+    }
+  }
+}