pi-daddy 0.28.0 → 0.32.0

package/src/governance/lease-helper.ts

@@ -0,0 +1,124 @@
+/**
+ * **The lock helper: a separate program, and the parent's side of its pipes.**
+ *
+ * Split out of `workspace-lease.ts` because `test/file-size.test.ts` refused that file — at 405 lines on the
+ * ADR-0035 branch when PR #14 merged into it, and at 435 here once R-152's guards landed. Both branches take
+ * the same seam so they converge rather than diverge, and the cap has never been raised: `delegate.ts` was
+ * split at 413 the same way (rule: when a guard fails, obey it).
+ *
+ * The seam is not arbitrary. Everything here concerns the process that HOLDS the kernel lock — the source it
+ * runs, the readiness token it prints, and the parent-side handles that keep it referenced.
+ * `workspace-lease.ts` keeps the lease lifecycle that talks to it.
+ */
+
+export const LEASE_READY = "PI_DADDY_LEASE_READY";
+// The lock holder also owns crash cleanup for the governed child. If the parent dies, stdin closes;
+// the helper signals the attached process, or closes the herdr tab, before releasing flock. A raw
+// descendant deliberately detached by bash remains ADR-0012's OS-containment boundary, not a lease
+// guarantee. The process branch SIGTERMs, escalates to SIGKILL at +500ms, and releases at +750ms
+// WITHOUT confirming death (R-101). The herdr branch retries `tab close` a BOUNDED number of times
+// and then releases anyway, leaving a marker file: an unreleasable lock strands a worktree forever
+// with no in-product recovery, which is strictly worse than a recorded failure to close (R-102).
+//
+// **Each attempt is bounded in WALL CLOCK, not just in count (R-146).** `execFile` with no `timeout`
+// never calls back if `herdr` accepts the close and does not answer, so the retry counter never
+// decrements, `giveUp` never runs and no marker is written — the lock is held forever. That was masked
+// while the parent could not exit, because the operator saw a hung `pi` instead; measured with a `herdr`
+// that sleeps, the parent then exited in 82ms and left a silent strand, which is R-102's rejected outcome
+// reached quietly. A bound on retries is not a bound on time.
+export const HELPER_SOURCE = `
+import { execFile } from "node:child_process";
+import { writeFileSync } from "node:fs";
+let clean=false, target=null, buffered="";
+process.stdout.write(${JSON.stringify(`${LEASE_READY}:`)}+process.pid+"\\n");
+process.stdin.setEncoding("utf8");
+process.stdin.on("data",chunk=>{buffered+=chunk;
+for(;
+;
+){const i=buffered.indexOf("\\n");
+if(i<0)break;
+const line=buffered.slice(0,i);
+buffered=buffered.slice(i+1);
+try{const value=JSON.parse(line);
+if(value.release)clean=true;
+else if(value.process_pid)target={process_pid:value.process_pid};
+else if(value.herdr_tab)target={herdr_tab:value.herdr_tab};
+}catch{}}});
+process.stdin.on("end",()=>{if(clean||!target)return process.exit(0);
+if(target.process_pid){try{process.kill(target.process_pid,"SIGTERM")}catch{return process.exit(0)}setTimeout(()=>{try{process.kill(target.process_pid,"SIGKILL")}catch{}},500);
+return setTimeout(()=>process.exit(0),750);
+}let left=Number(process.env.PI_DADDY_LEASE_CLOSE_ATTEMPTS||10);
+const giveUp=last=>{
+try{
+if(process.env.PI_DADDY_LEASE_MARKER)writeFileSync(process.env.PI_DADDY_LEASE_MARKER,
+JSON.stringify({reason:last&&(last.killed||last.signal==="SIGKILL")?"herdr-close-timeout":"herdr-close-failed",herdr_tab:target.herdr_tab})+"\\n")
+}catch{}
+process.exit(0)};
+const close=()=>execFile("herdr",["tab","close",target.herdr_tab],
+{timeout:Number(process.env.PI_DADDY_LEASE_CLOSE_TIMEOUT_MS||15000),killSignal:"SIGKILL"},
+error=>{if(!error)return process.exit(0);
+if(--left<=0)return giveUp(error);
+setTimeout(close,1000)});
+close();
+});
+process.stdin.resume();`;
+
+/**
+ * `unref` the parent's end of one of the helper's pipes.
+ *
+ * A spawned pipe is a `net.Socket`, which has `unref`; `ChildProcess.stdin` is typed `Writable`, which does
+ * not. Hence the narrow cast. The optional call is **defensive, not load-bearing** — the holder is spawned at
+ * exactly one site with three pipes, so none of these is ever `null`, and an earlier version of this comment
+ * claimed otherwise by citing a `stdio: "ignore"` caller that does not exist.
+ *
+ * Only `stdout` and `stderr` are unref'ed. `stdin` was too, until a line-by-line reversion showed the suite
+ * stayed green without it — an unforced line inside the fix that exists to be forced, which is exactly the
+ * shape R-122 was about.
+ */
+export const unrefStream = (stream: unknown): void => {
+  (stream as { unref?: () => void } | null)?.unref?.();
+};
+
+/**
+ * The bounds on the helper's `herdr tab close` attempts live here, with the attempts they bound — moved out of
+ * `workspace-lease.ts` when the line ceiling refused it at 402 lines, once both this branch's ADR-0035 work and
+ * `main`'s R-152 guards had landed in it. Third time that guard has fired on this file and third time the
+ * answer was a seam rather than a bigger cap.
+ */
+/**
+ * **A bound that is not a bound throws, and it throws a `RangeError` (R-146, R-152).**
+ *
+ * Both ends fail, in opposite directions and both silently:
+ *
+ *  - `0` reads as "no limit" and Node agrees — `execFile` treats `timeout: 0` as *no* timeout (measured: the
+ *    callback for a 3s sleep arrives at 3004ms with no error), reinstating the unbounded hang the bound exists
+ *    to prevent. Negatives behave identically.
+ *  - anything above `2^31 - 1` truncates: `setTimeout` warns `TimeoutOverflowWarning … set to 1`, so
+ *    `Number.MAX_SAFE_INTEGER` — the plausible "effectively no limit" sentinel, given the argument about `0`
+ *    — SIGKILLs every `herdr tab close` after 1ms, before herdr can act. Measured: callback at 3ms.
+ *
+ * **Not a `GovernanceRefusal`.** It was one, carrying `WORKSPACE_LEASE_STALE`, which everywhere else in this
+ * package means *the lease went stale or was lost* — so an ADR-0034 controller switching on codes (the reason
+ * codes exist, R-103) would classify a permanent caller bug as transient and retry a call that can never
+ * succeed. A refusal is a governance outcome that gets ledgered; a bad argument is neither.
+ *
+ * Checked for read leases too, which the first version did not: it sat below the read-lease early return, so a
+ * controller smoke-testing its configuration against a read lease got a false all-clear.
+ */
+export const assertCloseBounds = (input: { herdrCloseTimeoutMs?: number; herdrCloseAttempts?: number }): void => {
+  const MAX_TIMER = 2_147_483_647;
+  for (const [name, value, ceiling] of [
+    ["herdrCloseTimeoutMs", input.herdrCloseTimeoutMs, MAX_TIMER],
+    ["herdrCloseAttempts", input.herdrCloseAttempts, Number.MAX_SAFE_INTEGER],
+  ] as const) {
+    if (value === undefined) continue;
+    if (!Number.isInteger(value) || value < 1 || value > ceiling) {
+      throw new RangeError(
+        `${name} must be a whole number between 1 and ${ceiling}, not ${String(value)}. Zero and negatives ` +
+          `are not "no limit" but no bound at all, a value past ${MAX_TIMER} truncates to 1ms, and a ` +
+          `fractional count is not a count — this bound exists so a hung herdr cannot hold the writer lock ` +
+          `forever (R-146).`,
+      );
+    }
+  }
+};

package/src/governance/lease-record.ts

@@ -0,0 +1,131 @@
+/**
+ * The lease's RECORD: what a workspace lease writes down about who holds it and how they let it go.
+ *
+ * Split from `./workspace-lease.ts` to stay under the 400-line module ceiling, along the seam this
+ * review round kept finding defects on — absent vs unreadable metadata, a swallowed handover write, a
+ * 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 type { ValidatedWorkspace, WorkspaceAccess } from "../kernel/workspace.ts";
+
+export interface LeaseMetadata {
+  version: 1;
+  state: "active" | "released";
+  token: string;
+  owner_id: string;
+  workspace_id: string;
+  root: string;
+  pid: number;
+  acquired_at: string;
+  released_at?: string;
+  release_reason?: string;
+}
+
+export interface WorkspaceLease {
+  workspace: ValidatedWorkspace;
+  access: WorkspaceAccess;
+  ownerId: string;
+  /**
+   * `true` only when the kernel lock was free but metadata said the prior owner never released.
+   * `"unknown"` when the prior owner's record could not be read at all — that is not evidence of a
+   * clean handover and must not be recorded as one (R-100).
+   */
+  recovered: boolean | "unknown";
+  /** Attach the governed resource so parent death cleans it before the kernel lock is released. */
+  attachProcess(pid: number): void;
+  attachHerdrTab(tabId: string): void;
+  /** Resolves only when the kernel-lock helper exits before explicit release. */
+  lost: Promise<Error>;
+  /**
+   * NEVER throws. A cleanup function that can throw destroys its caller's return value — a completed
+   * child's entire output was discarded this way (R-99) — so the outcome is a VALUE the caller records:
+   *   `"released"`            the kernel lock was handed back and the handover recorded;
+   *   `"released-unrecorded"` the lock was handed back but the record failed, so the NEXT owner will
+   *                           report a recovery that did not happen unless this is ledgered;
+   *   `"lost"`                the helper was already gone, so this owner never released anything.
+   */
+  release(reason?: string): Promise<LeaseReleaseOutcome>;
+  /**
+   * Record that this lease is being kept deliberately, WITHOUT releasing the kernel lock.
+   *
+   * Needed because a retained lease never calls `release()`, so the metadata stays `state: "active"` and
+   * whoever acquires next reports `recovered: true` — blaming a crash on a known-good path.
+   */
+  /**
+   * Record that the lease is being KEPT rather than handed back, and answer what actually happened — the
+   * caller ledgers this word (R-152). It is not always `retained`: a helper that has already died makes the
+   * fact `lost`, and a lease already settled by `release()` keeps the outcome it had.
+   */
+  markRetained(reason?: string): Promise<LeaseReleaseOutcome>;
+  /** Reads the give-up marker the helper leaves when it could not close a herdr writer tab. */
+  readCloseFailure(): Promise<{ reason: string; herdr_tab?: string } | null>;
+}
+
+/**
+ * What a release actually did. Six members rather than three, because the first version conflated facts
+ * that call for different responses — and one of them is an alarm:
+ *   `released`             the lock went back and THIS owner wrote its own handover;
+ *   `released-unrecorded`  the lock went back and the record does not say so, so the next owner will report
+ *                          a recovery that never happened unless the caller ledgers this. **The alarm.**
+ *   `released-superseded`  the lock went back and a successor already owns the metadata, so we correctly
+ *                          declined to overwrite it. Healthy, and previously indistinguishable from the
+ *                          alarm above;
+ *   `not-held`             a read lease, which never took a kernel lock — recording it as `released`
+ *                          overstated how many handovers the kernel performed, which is R-105 on the
+ *                          release side of the same defect;
+ *   `lost`                 the helper was already gone; this owner released nothing.
+ */
+export type LeaseReleaseOutcome =
+  | "released"
+  | "released-unrecorded"
+  | "released-superseded"
+  | "not-held"
+  | "lost"
+  /**
+   * The lease was RETAINED and is therefore already settled — `release()` after `markRetained()` answers
+   * this instead of running the clean handshake (R-146). It was previously expressible only as the
+   * `| "retained"` bolted onto two signatures, which is why `release()` could not say it and claimed
+   * `released` instead: a clean handover for a lease kept precisely because a pane would not close.
+   */
+  | "retained";
+
+export function leasePaths(leaseDir: string, root: string) {
+  // Canonical root, never caller-chosen workspace ID: aliases for one worktree must contend.
+  const key = createHash("sha256").update(root, "utf8").digest("hex");
+  return {
+    lock: join(leaseDir, `${key}.lock`),
+    metadata: join(leaseDir, `${key}.json`),
+    marker: join(leaseDir, `${key}.close-failed.json`),
+  };
+}
+
+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 });
+  await rename(temp, path);
+}
+
+/**
+ * `null` means no prior owner was recorded. `"malformed"` means a record exists and cannot be read,
+ * which is strictly LESS evidence than a readable "active" one and must never read as a clean handover
+ * (R-100). Absent and unreadable are different facts; conflating them silently erases a real recovery.
+ */
+export async function readMetadata(path: string): Promise<LeaseMetadata | null | "malformed"> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    return (error as NodeJS.ErrnoException)?.code === "ENOENT" ? null : "malformed";
+  }
+  try {
+    const value = JSON.parse(raw) as Partial<LeaseMetadata>;
+    if (value?.version !== 1) return "malformed";
+    if (value.state !== "active" && value.state !== "released") return "malformed";
+    if (typeof value.token !== "string" || !value.token) return "malformed";
+    return value as LeaseMetadata;
+  } catch {
+    return "malformed";
+  }
+}

package/src/governance/ledger-events.ts

@@ -0,0 +1,222 @@
+/**
+ * The v3 runtime-event half of the ledger: workspace leases and child lifecycle, with
+ * their builders. Split out of `./ledger.ts` only to stay under the 400-line module ceiling this
+ * project enforces mechanically; `./ledger.ts` re-exports everything here, so "the ledger module"
+ * remains one import.
+ */
+import { LEDGER_VERSION, type LedgerEventBase, type GrantRecord } from "./ledger.ts";
+import type { ExecutorKind } from "../kernel/delegate-types.ts";
+import type { CorrelationMetadata } from "../kernel/correlation.ts";
+import type { StructuredRefusal } from "../kernel/refusals.ts";
+import { assertExecutionId } from "../kernel/execution-id.ts";
+import { assertLedgerV3Wire } from "./ledger-v3-validation.ts";
+
+export const WORKSPACE_ACCESSES = ["read", "write"] as const;
+export type WorkspaceAccess = (typeof WORKSPACE_ACCESSES)[number];
+
+export const WORKSPACE_RECOVERY_VALUES = [false, true, "unknown"] as const;
+export type WorkspaceRecovery = (typeof WORKSPACE_RECOVERY_VALUES)[number];
+
+export const CHILD_LIFECYCLE_STATES = ["starting", "running", "completed", "failed"] as const;
+export type ChildLifecycleState = (typeof CHILD_LIFECYCLE_STATES)[number];
+
+/** The complete Node signal vocabulary accepted by a v3 child-lifecycle event. */
+export const CHILD_PROCESS_SIGNALS = [
+  "SIGABRT",
+  "SIGALRM",
+  "SIGBUS",
+  "SIGCHLD",
+  "SIGCONT",
+  "SIGFPE",
+  "SIGHUP",
+  "SIGILL",
+  "SIGINT",
+  "SIGIO",
+  "SIGIOT",
+  "SIGKILL",
+  "SIGPIPE",
+  "SIGPOLL",
+  "SIGPROF",
+  "SIGPWR",
+  "SIGQUIT",
+  "SIGSEGV",
+  "SIGSTKFLT",
+  "SIGSTOP",
+  "SIGSYS",
+  "SIGTERM",
+  "SIGTRAP",
+  "SIGTSTP",
+  "SIGTTIN",
+  "SIGTTOU",
+  "SIGUNUSED",
+  "SIGURG",
+  "SIGUSR1",
+  "SIGUSR2",
+  "SIGVTALRM",
+  "SIGWINCH",
+  "SIGXCPU",
+  "SIGXFSZ",
+  "SIGBREAK",
+  "SIGLOST",
+  "SIGINFO",
+] as const satisfies readonly NodeJS.Signals[];
+export type ChildProcessSignal = (typeof CHILD_PROCESS_SIGNALS)[number];
+
+/**
+ * `released` is a handover this owner performed. FOUR members were added by the 0.18.0 review pass, and
+ * they were not all previously recorded the same way — `uncontended` was recorded as an *acquisition*, and
+ * `lost` was recorded as nothing at all, because the old `release()` threw before the append ran:
+ *   `lost`     the kernel lock went away under a live governed writer — NOT the same fact as a user
+ *              cancelling, which is what it used to be indistinguishable from (R-103);
+ *   `retained` the lease was deliberately kept because a herdr writer tab would not close, so the
+ *              successor's `recovered: true` would otherwise blame a healthy path (R-104);
+ *   `uncontended` a read lease took no kernel lock at all, so counting it as an acquisition
+ *              overstated how many exclusions the kernel actually performed (R-105).
+ */
+export const WORKSPACE_LEASE_OUTCOMES = [
+  "acquired",
+  "uncontended",
+  "refused",
+  "released",
+  "released-unrecorded",
+  "lost",
+  "retained",
+  "timeout",
+  "recovered",
+] as const;
+export type WorkspaceLeaseOutcome = (typeof WORKSPACE_LEASE_OUTCOMES)[number];
+
+export interface WorkspaceLeaseEvent extends LedgerEventBase {
+  ledgerVersion: typeof LEDGER_VERSION;
+  event: "workspace_lease";
+  executionId: string;
+  parentExecutionId: string | null;
+  childId: string;
+  workspaceId: string;
+  root: string;
+  access: WorkspaceAccess;
+  outcome: WorkspaceLeaseOutcome;
+  /** `"unknown"` when the prior owner's record was unreadable — not evidence of a clean handover. */
+  recovered?: WorkspaceRecovery;
+  releaseReason?: string;
+  refusal?: StructuredRefusal;
+}
+
+export interface ChildLifecycleEvent extends LedgerEventBase {
+  ledgerVersion: typeof LEDGER_VERSION;
+  event: "child_lifecycle";
+  executionId: string;
+  parentExecutionId: string | null;
+  childId: string;
+  state: ChildLifecycleState;
+  executor: ExecutorKind;
+  /** Bound after which a non-terminal start is known to be incomplete. */
+  deadlineAt?: string;
+  /** Herdr runtime identity is observational and never an enforcement boundary. */
+  herdrPaneId?: string;
+  herdrAgentName?: string;
+  exitCode?: number | null;
+  signal?: ChildProcessSignal | null;
+  timedOut?: true;
+  aborted?: true;
+  truncated?: true;
+  reason?: string;
+  /** The inactivity bound (ms) that governed this child beside the `deadlineAt` ceiling (PR 3e). */
+  idleTimeoutMs?: number;
+}
+
+export type CapabilityDecisionEvent = GrantRecord & {
+  ledgerVersion: typeof LEDGER_VERSION;
+  event: "capability_decision";
+  executionId: string;
+  parentExecutionId: string | null;
+  taskDigest: string;
+};
+
+export type RuntimeLedgerEvent = CapabilityDecisionEvent | WorkspaceLeaseEvent | ChildLifecycleEvent;
+
+export function buildWorkspaceLeaseEvent(args: {
+  executionId: string;
+  parentExecutionId: string | null;
+  childId: string;
+  workspaceId: string;
+  root: string;
+  access: WorkspaceAccess;
+  outcome: WorkspaceLeaseOutcome;
+  recovered?: WorkspaceRecovery;
+  releaseReason?: string;
+  refusal?: StructuredRefusal;
+  correlation?: CorrelationMetadata;
+  now: Date;
+}): WorkspaceLeaseEvent {
+  assertEventIdentity(args);
+  return assertLedgerV3Wire({
+    ledgerVersion: LEDGER_VERSION,
+    event: "workspace_lease",
+    ts: args.now.toISOString(),
+    executionId: args.executionId,
+    parentExecutionId: args.parentExecutionId,
+    childId: args.childId,
+    workspaceId: args.workspaceId,
+    root: args.root,
+    access: args.access,
+    outcome: args.outcome,
+    // `!== undefined`, not truthiness. `recovered: false` — a POSITIVE assertion that the predecessor
+    // handed over cleanly — was dropped while the truthy `"unknown"` survived, so absence meant both
+    // "clean" and "never supplied". R-100's whole argument is that absence of evidence is not evidence,
+    // and this was the one line discarding the evidence.
+    ...(args.recovered !== undefined ? { recovered: args.recovered } : {}),
+    ...(args.releaseReason ? { releaseReason: args.releaseReason } : {}),
+    ...(args.refusal ? { refusal: structuredClone(args.refusal) } : {}),
+    ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
+  });
+}
+
+export function buildChildLifecycleEvent(args: {
+  executionId: string;
+  parentExecutionId: string | null;
+  childId: string;
+  state: ChildLifecycleState;
+  executor: ExecutorKind;
+  deadlineAt?: string;
+  idleTimeoutMs?: number;
+  herdrPaneId?: string;
+  herdrAgentName?: string;
+  exitCode?: number | null;
+  signal?: ChildProcessSignal | null;
+  timedOut?: boolean;
+  aborted?: boolean;
+  truncated?: boolean;
+  reason?: string;
+  correlation?: CorrelationMetadata;
+  now: Date;
+}): ChildLifecycleEvent {
+  assertEventIdentity(args);
+  return assertLedgerV3Wire({
+    ledgerVersion: LEDGER_VERSION,
+    event: "child_lifecycle",
+    ts: args.now.toISOString(),
+    executionId: args.executionId,
+    parentExecutionId: args.parentExecutionId,
+    childId: args.childId,
+    state: args.state,
+    executor: args.executor,
+    ...(args.deadlineAt ? { deadlineAt: args.deadlineAt } : {}),
+    ...(args.idleTimeoutMs !== undefined ? { idleTimeoutMs: args.idleTimeoutMs } : {}),
+    ...(args.herdrPaneId ? { herdrPaneId: args.herdrPaneId } : {}),
+    ...(args.herdrAgentName ? { herdrAgentName: args.herdrAgentName } : {}),
+    ...(args.exitCode !== undefined ? { exitCode: args.exitCode } : {}),
+    ...(args.signal !== undefined ? { signal: args.signal } : {}),
+    ...(args.timedOut ? { timedOut: true } : {}),
+    ...(args.aborted ? { aborted: true } : {}),
+    ...(args.truncated ? { truncated: true } : {}),
+    ...(args.reason ? { reason: args.reason } : {}),
+    ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
+  });
+}
+
+function assertEventIdentity(args: { executionId: string; parentExecutionId: string | null }): void {
+  assertExecutionId(args.executionId);
+  if (args.parentExecutionId !== null) assertExecutionId(args.parentExecutionId, "parentExecutionId");
+  if (args.parentExecutionId === args.executionId) throw new TypeError("an execution cannot be its own parent");
+}