@piagent/platform 1.3.1 → 1.4.1

package/packages/piagent-webui/ownership/session-lease-store.ts

@@ -0,0 +1,329 @@
+import { createHmac, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const FILE_LIMIT = 256 * 1024; // Shared single-writer authority for Gateway and terminal runtimes.
+const RECORD_LIMIT = 8 * 1024;
+const ENTRY_LIMIT = 512;
+const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+
+type LeaseEvent = "acquired" | "released" | "recovery-required";
+type MutationLock = { version: "piagent-session-lease-lock-v1"; pid: number; createdAt: string; nonce: string };
+type LeaseRecord = {
+  version: "piagent-session-lease-v1";
+  sequence: number;
+  recordedAt: string;
+  sessionRef: string;
+  event: LeaseEvent;
+  ownerEpoch: string;
+  gatewayInstanceRef: string;
+  runtimeInstanceRef: string;
+  previousDigest: string | null;
+  reasonCode: string | null;
+  recordDigest: string;
+};
+
+export type SessionLeaseSnapshot = {
+  state: "released" | "gateway-owned" | "terminal-owned" | "recovery-required" | "unavailable";
+  ownerEpoch: string | null;
+  gatewayInstanceRef: string | null;
+  runtimeInstanceRef: string | null;
+  continuity: "exact" | "released" | "unknown";
+  revision: string | null;
+  reasonCode: string | null;
+};
+
+const TERMINAL_OWNER_PREFIX = "terminal_";
+
+function terminalOwnerPid(value: string | null): number | null {
+  const match = value?.match(/^terminal_(\d+)_/), pid = Number(match?.[1]);
+  return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+
+function gatewayOwnerPid(value: string | null): number | null {
+  const match = value?.match(/^gateway_(\d+)_/), pid = Number(match?.[1]);
+  return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+
+function processAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return !(error && typeof error === "object" && "code" in error && error.code === "ESRCH"); }
+}
+
+function exactTimestamp(value: unknown): value is string {
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)
+    && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+}
+
+function validRef(value: unknown): value is string { return typeof value === "string" && REF.test(value); }
+
+function unsigned(record: LeaseRecord): Omit<LeaseRecord, "recordDigest"> {
+  const { recordDigest: _ignored, ...value } = record;
+  return value;
+}
+
+export class SessionLeaseStore {
+  readonly directory: string;
+  readonly #key: Buffer;
+
+  constructor(root: string, key: Buffer) {
+    this.directory = path.join(root, "leases");
+    this.#key = key;
+    fs.mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+    const stat = fs.lstatSync(this.directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()
+      || (typeof process.getuid === "function" && stat.uid !== process.getuid())) throw new Error("session-lease-root-invalid");
+    fs.chmodSync(this.directory, 0o700);
+  }
+
+  #digest(namespace: string, value: unknown): string {
+    return `${namespace}_${createHmac("sha256", this.#key).update(JSON.stringify(value)).digest("hex")}`;
+  }
+
+  #file(sessionRef: string): string {
+    if (!validRef(sessionRef)) throw new Error("session-lease-ref-invalid");
+    return path.join(this.directory, `${this.#digest("lease-file", sessionRef).slice("lease-file_".length)}.jsonl`);
+  }
+
+  #lockFile(sessionRef: string): string {
+    return `${this.#file(sessionRef)}.lock`;
+  }
+
+  #reclaimDeadMutationLock(file: string): boolean {
+    let stat: fs.Stats;
+    try { stat = fs.lstatSync(file); } catch { return false; }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1_024
+      || (typeof process.getuid === "function" && stat.uid !== process.getuid())) return false;
+    const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    let value: unknown;
+    try {
+      const opened = fs.fstatSync(descriptor);
+      if (opened.dev !== stat.dev || opened.ino !== stat.ino || opened.size !== stat.size) return false;
+      value = JSON.parse(fs.readFileSync(descriptor, "utf8"));
+    } catch { return false; }
+    finally { fs.closeSync(descriptor); }
+    if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+    const lock = value as Partial<MutationLock>;
+    if (Object.keys(lock).length !== 4 || lock.version !== "piagent-session-lease-lock-v1"
+      || !Number.isSafeInteger(lock.pid) || Number(lock.pid) < 1 || !exactTimestamp(lock.createdAt)
+      || !validRef(lock.nonce) || processAlive(Number(lock.pid))) return false;
+    let current: fs.Stats;
+    try { current = fs.lstatSync(file); } catch { return false; }
+    if (current.dev !== stat.dev || current.ino !== stat.ino || !current.isFile() || current.isSymbolicLink()) return false;
+    try { fs.unlinkSync(file); return true; } catch { return false; }
+  }
+
+  #withMutationLock<T>(sessionRef: string, action: () => T): T {
+    const file = this.#lockFile(sessionRef);
+    let descriptor: number;
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        descriptor = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL
+          | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+        break;
+      } catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "EEXIST") {
+          if (attempt === 0 && this.#reclaimDeadMutationLock(file)) continue;
+          throw new Error("session-lease-busy");
+        }
+        throw error;
+      }
+    }
+    try {
+      const lock: MutationLock = { version: "piagent-session-lease-lock-v1", pid: process.pid,
+        createdAt: new Date().toISOString(), nonce: `lock_${randomBytes(24).toString("base64url")}` };
+      fs.writeFileSync(descriptor, JSON.stringify(lock)); fs.fsyncSync(descriptor); fs.fchmodSync(descriptor, 0o600);
+      return action();
+    } finally {
+      fs.closeSync(descriptor);
+      try { fs.unlinkSync(file); } catch { /* a missing lock fails the next mutation closed through continuity checks */ }
+    }
+  }
+
+  #valid(record: unknown, sessionRef: string, index: number, previousDigest: string | null): record is LeaseRecord {
+    if (!record || typeof record !== "object" || Array.isArray(record)) return false;
+    const value = record as Partial<LeaseRecord>;
+    if (Object.keys(value).length !== 11 || !Object.keys(value).every((key) => ["version", "sequence", "recordedAt",
+      "sessionRef", "event", "ownerEpoch", "gatewayInstanceRef", "runtimeInstanceRef", "previousDigest", "reasonCode",
+      "recordDigest"].includes(key))) return false;
+    if (value.version !== "piagent-session-lease-v1" || value.sequence !== index + 1 || !exactTimestamp(value.recordedAt)
+      || value.sessionRef !== sessionRef || !["acquired", "released", "recovery-required"].includes(String(value.event))
+      || !validRef(value.ownerEpoch) || !validRef(value.gatewayInstanceRef) || !validRef(value.runtimeInstanceRef)
+      || value.previousDigest !== previousDigest || !validRef(value.recordDigest)
+      || !(value.reasonCode === null || validRef(value.reasonCode))) return false;
+    if (value.event === "recovery-required" ? value.reasonCode === null : value.reasonCode !== null) return false;
+    return value.recordDigest === this.#digest("lease-record", unsigned(value as LeaseRecord));
+  }
+
+  #read(sessionRef: string): LeaseRecord[] {
+    const file = this.#file(sessionRef);
+    let stat: fs.Stats;
+    try { stat = fs.lstatSync(file); } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return [];
+      throw error;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > FILE_LIMIT) throw new Error("session-lease-file-invalid");
+    const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+      const opened = fs.fstatSync(descriptor);
+      if (opened.dev !== stat.dev || opened.ino !== stat.ino || opened.size !== stat.size) throw new Error("session-lease-file-race");
+      const lines = fs.readFileSync(descriptor, "utf8").split("\n");
+      if (lines.at(-1) === "") lines.pop();
+      if (lines.length > ENTRY_LIMIT) throw new Error("session-lease-entry-limit");
+      const records: LeaseRecord[] = [];
+      for (const [index, line] of lines.entries()) {
+        if (!line || Buffer.byteLength(line) > RECORD_LIMIT) throw new Error("session-lease-record-limit");
+        let value: unknown;
+        try { value = JSON.parse(line); } catch { throw new Error("session-lease-record-invalid"); }
+        if (!this.#valid(value, sessionRef, index, records.at(-1)?.recordDigest ?? null)) throw new Error("session-lease-record-invalid");
+        records.push(value);
+      }
+      return records;
+    } finally { fs.closeSync(descriptor); }
+  }
+
+  #append(sessionRef: string, value: Omit<LeaseRecord, "version" | "sequence" | "previousDigest" | "recordDigest">): LeaseRecord {
+    const records = this.#read(sessionRef);
+    if (records.length >= ENTRY_LIMIT) throw new Error("session-lease-entry-limit");
+    const partial = {
+      version: "piagent-session-lease-v1" as const,
+      sequence: records.length + 1,
+      previousDigest: records.at(-1)?.recordDigest ?? null,
+      ...value
+    };
+    const record: LeaseRecord = { ...partial, recordDigest: this.#digest("lease-record", partial) };
+    const body = Buffer.from(`${JSON.stringify(record)}\n`);
+    if (body.length > RECORD_LIMIT) throw new Error("session-lease-record-limit");
+    const file = this.#file(sessionRef);
+    let stat: fs.Stats | null = null;
+    try { stat = fs.lstatSync(file); } catch { /* first record */ }
+    if (stat && (!stat.isFile() || stat.isSymbolicLink() || stat.size + body.length > FILE_LIMIT)) throw new Error("session-lease-file-invalid");
+    const descriptor = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT
+      | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+    try { fs.writeFileSync(descriptor, body); fs.fsyncSync(descriptor); }
+    finally { fs.closeSync(descriptor); }
+    fs.chmodSync(file, 0o600);
+    return record;
+  }
+
+  inspect(sessionRef: string): SessionLeaseSnapshot {
+    try {
+      const last = this.#read(sessionRef).at(-1);
+      if (!last || last.event === "released") return {
+        state: "released", ownerEpoch: null, gatewayInstanceRef: null, runtimeInstanceRef: null,
+        continuity: "released", revision: last?.recordDigest ?? this.#digest("lease-empty", sessionRef), reasonCode: null
+      };
+      return {
+        state: last.event === "acquired"
+          ? last.gatewayInstanceRef.startsWith(TERMINAL_OWNER_PREFIX) ? "terminal-owned" : "gateway-owned"
+          : "recovery-required",
+        ownerEpoch: last.ownerEpoch, gatewayInstanceRef: last.gatewayInstanceRef, runtimeInstanceRef: last.runtimeInstanceRef,
+        continuity: last.event === "acquired" ? "exact" : "unknown", revision: last.recordDigest,
+        reasonCode: last.reasonCode
+      };
+    } catch {
+      return { state: "unavailable", ownerEpoch: null, gatewayInstanceRef: null, runtimeInstanceRef: null,
+        continuity: "unknown", revision: null, reasonCode: "session-lease-unavailable" };
+    }
+  }
+
+  acquire(sessionRef: string, gatewayInstanceRef: string, runtimeInstanceRef: string, now = new Date()): SessionLeaseSnapshot {
+    if (!validRef(gatewayInstanceRef) || !validRef(runtimeInstanceRef) || !Number.isFinite(now.getTime())) throw new Error("session-lease-input-invalid");
+    if (gatewayInstanceRef.startsWith(TERMINAL_OWNER_PREFIX)) throw new Error("session-lease-input-invalid");
+    return this.#acquireOwner(sessionRef, gatewayInstanceRef, runtimeInstanceRef, now);
+  }
+
+  releaseDeadOwnerForExplicitRecovery(sessionRef: string, now = new Date()): SessionLeaseSnapshot {
+    if (!Number.isFinite(now.getTime())) throw new Error("session-lease-input-invalid");
+    return this.#withMutationLock(sessionRef, () => {
+      const current = this.inspect(sessionRef);
+      const pid = current.state === "terminal-owned" ? terminalOwnerPid(current.gatewayInstanceRef)
+        : current.state === "gateway-owned" ? gatewayOwnerPid(current.gatewayInstanceRef) : null;
+      if (!pid || processAlive(pid)) throw new Error("session-owner-not-proven-dead");
+      this.#append(sessionRef, { recordedAt: now.toISOString(), sessionRef, event: "recovery-required", ownerEpoch: current.ownerEpoch!,
+        gatewayInstanceRef: current.gatewayInstanceRef!, runtimeInstanceRef: current.runtimeInstanceRef!, reasonCode: "owner-process-exited" });
+      this.#append(sessionRef, { recordedAt: now.toISOString(), sessionRef, event: "released", ownerEpoch: current.ownerEpoch!,
+        gatewayInstanceRef: current.gatewayInstanceRef!, runtimeInstanceRef: current.runtimeInstanceRef!, reasonCode: null });
+      return this.inspect(sessionRef);
+    });
+  }
+
+  acquireTerminal(sessionRef: string, terminalInstanceRef: string, runtimeInstanceRef: string, now = new Date()): SessionLeaseSnapshot {
+    if (!terminalInstanceRef.startsWith(TERMINAL_OWNER_PREFIX)) throw new Error("session-lease-input-invalid");
+    if (!validRef(terminalInstanceRef) || !validRef(runtimeInstanceRef) || !Number.isFinite(now.getTime())) {
+      throw new Error("session-lease-input-invalid");
+    }
+    return this.#withMutationLock(sessionRef, () => {
+      const current = this.inspect(sessionRef), previousPid = terminalOwnerPid(current.gatewayInstanceRef);
+      if (current.state === "terminal-owned" && previousPid && !processAlive(previousPid)) {
+        this.#append(sessionRef, { recordedAt: now.toISOString(), sessionRef, event: "recovery-required",
+          ownerEpoch: current.ownerEpoch!, gatewayInstanceRef: current.gatewayInstanceRef!, runtimeInstanceRef: current.runtimeInstanceRef!,
+          reasonCode: "terminal-owner-process-exited" });
+        this.#append(sessionRef, { recordedAt: now.toISOString(), sessionRef, event: "released", ownerEpoch: current.ownerEpoch!,
+          gatewayInstanceRef: current.gatewayInstanceRef!, runtimeInstanceRef: current.runtimeInstanceRef!, reasonCode: null });
+      } else if (current.state !== "released") {
+        throw new Error(current.state === "recovery-required" ? "session-recovery-required" : "session-owner-conflict");
+      }
+      const ownerEpoch = `owner_${randomBytes(24).toString("base64url")}`;
+      this.#append(sessionRef, { recordedAt: now.toISOString(), sessionRef, event: "acquired", ownerEpoch,
+        gatewayInstanceRef: terminalInstanceRef, runtimeInstanceRef, reasonCode: null });
+      return this.inspect(sessionRef);
+    });
+  }
+
+  #acquireOwner(sessionRef: string, ownerInstanceRef: string, runtimeInstanceRef: string, now: Date): SessionLeaseSnapshot {
+    if (!validRef(ownerInstanceRef) || !validRef(runtimeInstanceRef) || !Number.isFinite(now.getTime())) throw new Error("session-lease-input-invalid");
+    return this.#withMutationLock(sessionRef, () => {
+      const current = this.inspect(sessionRef);
+      if (current.state === "unavailable") throw new Error(current.reasonCode ?? "session-lease-unavailable");
+      if (current.state !== "released") throw new Error(current.state === "recovery-required" ? "session-recovery-required" : "session-owner-conflict");
+      const ownerEpoch = `owner_${randomBytes(24).toString("base64url")}`;
+      this.#append(sessionRef, { recordedAt: now.toISOString(), sessionRef, event: "acquired", ownerEpoch,
+        gatewayInstanceRef: ownerInstanceRef, runtimeInstanceRef, reasonCode: null });
+      return this.inspect(sessionRef);
+    });
+  }
+
+  release(sessionRef: string, ownerEpoch: string, gatewayInstanceRef: string, runtimeInstanceRef: string, now = new Date()): SessionLeaseSnapshot {
+    if (gatewayInstanceRef.startsWith(TERMINAL_OWNER_PREFIX)) throw new Error("session-lease-input-invalid");
+    return this.#releaseOwner(sessionRef, ownerEpoch, gatewayInstanceRef, runtimeInstanceRef, "gateway-owned", now);
+  }
+
+  releaseTerminal(sessionRef: string, ownerEpoch: string, terminalInstanceRef: string, runtimeInstanceRef: string,
+    now = new Date()): SessionLeaseSnapshot {
+    if (!terminalInstanceRef.startsWith(TERMINAL_OWNER_PREFIX)) throw new Error("session-lease-input-invalid");
+    return this.#releaseOwner(sessionRef, ownerEpoch, terminalInstanceRef, runtimeInstanceRef, "terminal-owned", now);
+  }
+
+  #releaseOwner(sessionRef: string, ownerEpoch: string, ownerInstanceRef: string, runtimeInstanceRef: string,
+    expectedState: "gateway-owned" | "terminal-owned", now: Date): SessionLeaseSnapshot {
+    return this.#withMutationLock(sessionRef, () => {
+      const current = this.#matchingOwner(sessionRef, ownerEpoch, ownerInstanceRef, runtimeInstanceRef, expectedState, now);
+      this.#append(sessionRef, { recordedAt: now.toISOString(), sessionRef, event: "released", ownerEpoch: current.ownerEpoch!,
+        gatewayInstanceRef: current.gatewayInstanceRef!, runtimeInstanceRef: current.runtimeInstanceRef!, reasonCode: null });
+      return this.inspect(sessionRef);
+    });
+  }
+
+  requireRecovery(sessionRef: string, ownerEpoch: string, gatewayInstanceRef: string, runtimeInstanceRef: string,
+    reasonCode: string, now = new Date()): SessionLeaseSnapshot {
+    if (!validRef(reasonCode)) throw new Error("session-lease-reason-invalid");
+    return this.#withMutationLock(sessionRef, () => {
+      const current = this.#matchingOwner(sessionRef, ownerEpoch, gatewayInstanceRef, runtimeInstanceRef, "gateway-owned", now);
+      this.#append(sessionRef, { recordedAt: now.toISOString(), sessionRef, event: "recovery-required", ownerEpoch: current.ownerEpoch!,
+        gatewayInstanceRef: current.gatewayInstanceRef!, runtimeInstanceRef: current.runtimeInstanceRef!, reasonCode });
+      return this.inspect(sessionRef);
+    });
+  }
+
+  #matchingOwner(sessionRef: string, ownerEpoch: string, gatewayInstanceRef: string, runtimeInstanceRef: string,
+    expectedState: "gateway-owned" | "terminal-owned", now: Date): SessionLeaseSnapshot {
+    if (!validRef(ownerEpoch) || !validRef(gatewayInstanceRef) || !validRef(runtimeInstanceRef) || !Number.isFinite(now.getTime())) {
+      throw new Error("session-lease-input-invalid");
+    }
+    const current = this.inspect(sessionRef);
+    if (current.state !== expectedState || current.ownerEpoch !== ownerEpoch || current.gatewayInstanceRef !== gatewayInstanceRef
+      || current.runtimeInstanceRef !== runtimeInstanceRef) throw new Error("session-owner-conflict");
+    return current;
+  }
+}

package/packages/piagent-webui/ownership/session-refs.ts

@@ -0,0 +1,8 @@
+import { createHmac } from "node:crypto";
+
+function ref(key: Buffer, namespace: string, value: string): string {
+  return `${namespace}_${createHmac("sha256", key).update(value).digest("base64url").slice(0, 43)}`;
+}
+
+export function sessionRefForPath(key: Buffer, sessionPath: string): string { return ref(key, "session", sessionPath); }
+export function projectRefForCwd(key: Buffer, cwd: string): string { return ref(key, "project", cwd || "unknown"); }

package/packages/piagent-webui/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@piagent/webui",
+  "version": "0.0.0-private",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "generate:contracts": "node scripts/generate-contracts.mjs --write",
+    "check:contracts": "node scripts/generate-contracts.mjs --check",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "npm run check:contracts && vite build",
+    "benchmark": "node benchmark/benchmark.mjs"
+  },
+  "dependencies": {
+    "@emotion/cache": "^11.14.0",
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "@mui/icons-material": "^9.3.1",
+    "@mui/material": "^9.3.1",
+    "react": "19.2.8",
+    "react-dom": "19.2.8"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
+    "@vitejs/plugin-react": "6.0.5",
+    "json-schema-to-typescript": "15.0.4",
+    "typescript": "7.0.2",
+    "vite": "8.2.1"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/packages/piagent-webui/server/README.md

@@ -0,0 +1,4 @@
+# Server boundary
+
+The loopback server, bootstrap authentication and read-only routes begin in
+WUI1-02. WUI1-01 intentionally contains no listener or route implementation.

package/packages/piagent-webui/server/benchmark-release-monitor.ts

@@ -0,0 +1,230 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { validBenchmarkCandidateProvenance } from "../../piagent-core/benchmark/benchmark-candidate.js";
+import { benchmarkCandidateProvenance } from "../../piagent-core/benchmark/benchmark-forensics.js";
+import { assertBenchmarkLedgerBinding, inspectBenchmarkLedger, validateBenchmarkLedgerPrefix } from "../../piagent-core/benchmark/benchmark-ledger.js";
+import { completedBenchmarkRecord } from "../../piagent-core/benchmark/benchmark-record-validation.js";
+import { benchmarkGitEnvironment } from "../../piagent-core/benchmark/benchmark-runtime.js";
+import { redactSensitiveText } from "../../piagent-core/extensions/redaction-core.js";
+
+const MAX_RUNS = 20, MAX_DIRECTORIES = 100, MAX_DIRECTORY_ENTRIES = 5_000, MAX_JSON_BYTES = 32 * 1024 * 1024;
+type Identity = { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string | null; taskRunId: string | null;
+  agentOperationId: null; toolCallId: null };
+
+function opaque(prefix: string, value: string): string {
+  return `${prefix}.${createHash("sha256").update(`piagent-webui-release-monitor-v1\0${value}`).digest("hex").slice(0, 48)}`;
+}
+function timestamp(value: unknown): value is string {
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)
+    && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+}
+function text(value: unknown, maximum = 160): string | null {
+  const result = redactSensitiveText(String(value ?? "")).text.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+  return result ? result.slice(0, maximum) : null;
+}
+function number(value: unknown): number | null { return Number.isFinite(value) ? Number(value) : null; }
+function stableBytes(file: string, maximum = MAX_JSON_BYTES): Buffer {
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  try {
+    const before = fs.fstatSync(fd, { bigint: true });
+    if (!before.isFile() || before.size > BigInt(maximum)) throw new Error("monitor-file-invalid");
+    const bytes = fs.readFileSync(fd), after = fs.fstatSync(fd, { bigint: true });
+    const stableFields = ["dev", "ino", "mode", "size", "mtimeNs", "ctimeNs"] as const;
+    if (stableFields.some((field) => before[field] !== after[field])) throw new Error("monitor-file-changed");
+    return bytes;
+  } finally { fs.closeSync(fd); }
+}
+function json(file: string, maximum = MAX_JSON_BYTES): any { return JSON.parse(stableBytes(file, maximum).toString("utf8")); }
+function safeDirectory(file: string): boolean { try { const stat = fs.lstatSync(file); return stat.isDirectory() && !stat.isSymbolicLink(); } catch { return false; } }
+function boundedDirectories(root: string) {
+  const handle = fs.opendirSync(root), values: string[] = []; let truncated = false;
+  try {
+    while (values.length <= MAX_DIRECTORY_ENTRIES) {
+      const entry = handle.readSync(); if (!entry) break;
+      if (entry.isDirectory() && !entry.isSymbolicLink()) values.push(path.join(root, entry.name));
+    }
+    truncated = values.length > MAX_DIRECTORY_ENTRIES;
+  } finally { handle.closeSync(); }
+  return { values: values.slice(0, MAX_DIRECTORY_ENTRIES), truncated };
+}
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", ["-C", cwd, ...args], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024,
+    env: benchmarkGitEnvironment(), stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+function repository(cwd: string) {
+  const head = git(cwd, ["rev-parse", "HEAD"]), membership = new Map<string, boolean>();
+  const hasCommit = (commit: unknown) => {
+    if (typeof commit !== "string" || !/^[a-f0-9]{40,64}$/.test(commit)) return false;
+    const cached = membership.get(commit); if (cached !== undefined) return cached;
+    try { git(cwd, ["cat-file", "-e", `${commit}^{commit}`]); membership.set(commit, true); return true; }
+    catch { membership.set(commit, false); return false; }
+  };
+  return { head, hasCommit };
+}
+function rcCandidateDigest(cwd: string): string {
+  const raw = execFileSync("git", ["-C", cwd, "ls-files", "--cached", "--others", "--exclude-standard", "-z"], {
+    encoding: "buffer", maxBuffer: 64 * 1024 * 1024, env: benchmarkGitEnvironment(), stdio: ["ignore", "pipe", "pipe"]
+  });
+  const files = raw.toString("utf8").split("\0").filter(Boolean).sort();
+  if (files.length > 50_000) throw new Error("release-candidate-too-large");
+  const digest = createHash("sha256"); let total = 0;
+  for (const relative of files) {
+    if (!relative || relative.startsWith("/") || relative.split("/").includes("..")) throw new Error("release-candidate-path-invalid");
+    const absolute = path.join(cwd, relative), stat = fs.lstatSync(absolute);
+    const bytes = stat.isSymbolicLink() ? Buffer.from(fs.readlinkSync(absolute)) : stableBytes(absolute, 16 * 1024 * 1024);
+    total += bytes.length; if (total > 512 * 1024 * 1024) throw new Error("release-candidate-too-large");
+    digest.update(relative).update("\0").update(bytes).update("\0");
+  }
+  return digest.digest("hex");
+}
+
+function sourceBinding(cwd: string, provenance: any, commit: unknown, repo: ReturnType<typeof repository>, cache: { benchmark?: any }) {
+  if (validBenchmarkCandidateProvenance(provenance)) {
+    cache.benchmark ??= benchmarkCandidateProvenance(cwd);
+    if (cache.benchmark.contentDigest === provenance.contentDigest) return "current";
+  }
+  return repo.hasCommit(commit) ? "stale" : "unbound";
+}
+function ledger(runRoot: string, expected: any, records?: any[]): { records: any[]; binding: any } {
+  const inspected = inspectBenchmarkLedger(path.join(runRoot, "runs.jsonl"));
+  assertBenchmarkLedgerBinding(expected, inspected.binding, "WebUI benchmark ledger");
+  if (records && JSON.stringify(records) !== JSON.stringify(inspected.records)) throw new Error("benchmark-report-ledger-mismatch");
+  return inspected;
+}
+function scores(report: any) {
+  const value = report.surfaces?.piagent?.scores ?? {};
+  return { quality: number(value.quality), safety: number(value.safety), reliability: number(value.reliability),
+    workflow: number(value.workflow), efficiency: number(value.efficiency), overall: number(value.overall) };
+}
+function completeRun(cwd: string, runRoot: string, report: any, repo: ReturnType<typeof repository>, cache: { benchmark?: any }) {
+  if (report?.schemaVersion !== 2 || typeof report.runId !== "string" || report.runId.length > 160 || !timestamp(report.startedAt)
+    || !timestamp(report.completedAt) || typeof report.suite?.id !== "string" || !Array.isArray(report.runs)
+    || report.runs.length > 1_000 || report.runCount !== report.runs.length) throw new Error("benchmark-report-invalid");
+  const binding = sourceBinding(cwd, report.environment?.candidateProvenance, report.environment?.source?.commit, repo, cache);
+  if (binding === "unbound") return null;
+  if (report.runs.some((item: any) => !completedBenchmarkRecord(item) || item.runId !== report.runId)) throw new Error("benchmark-report-invalid");
+  ledger(runRoot, report.ledger, report.runs);
+  const gate = report.comparison?.productionGate ?? report.comparison?.suiteGate;
+  return { runRef: opaque("benchmark", report.runId), suiteId: text(report.suite.id, 80) ?? "unknown", lifecycle: "completed",
+    evidenceState: "complete", sourceState: binding, startedAt: report.startedAt, updatedAt: report.completedAt,
+    completedRuns: report.runCount, expectedRuns: report.runCount, verdict: text(report.verdict?.status, 100),
+    releaseGate: gate?.passed === true ? "passed" : gate?.passed === false ? "failed" : "not-applicable",
+    tokenClaimAllowed: typeof report.comparison?.tokenClaimAllowed === "boolean" ? report.comparison.tokenClaimAllowed : null,
+    claimTier: ["smoke", "public-regression", "capability", "private-holdout", "production-shadow"].includes(report.comparison?.claimEligibility?.achievedTier)
+      ? report.comparison.claimEligibility.achievedTier : "unknown", scores: scores(report) };
+}
+const MARKERS = [
+  ["paused.json", "paused", "pausedAt"], ["interrupted.json", "interrupted", "interruptedAt"],
+  ["stopped.json", "stopped", "stoppedAt"], ["aborted.json", "aborted", "abortedAt"]
+] as const;
+function partialRun(cwd: string, runRoot: string, manifest: any, repo: ReturnType<typeof repository>, cache: { benchmark?: any }) {
+  if (manifest?.schemaVersion !== 1 || typeof manifest.runId !== "string" || !timestamp(manifest.startedAt)
+    || !Array.isArray(manifest.order) || manifest.order.length > 1_000) throw new Error("benchmark-manifest-invalid");
+  const binding = sourceBinding(cwd, manifest.candidateProvenance, manifest.sourceIdentity?.commit, repo, cache);
+  if (binding === "unbound") return null;
+  for (const [name, lifecycle, timeField] of MARKERS) {
+    const file = path.join(runRoot, name); if (!fs.existsSync(file)) continue;
+    const marker = json(file, 2 * 1024 * 1024);
+    if (marker?.schemaVersion !== 1 || marker.runId !== manifest.runId || !timestamp(marker[timeField])
+      || !Number.isInteger(marker.completedRuns) || !Number.isInteger(marker.expectedRuns) || marker.completedRuns < 0
+      || marker.expectedRuns < marker.completedRuns) throw new Error("benchmark-marker-invalid");
+    const inspected = ledger(runRoot, marker.ledger);
+    validateBenchmarkLedgerPrefix(inspected.records, manifest.order, completedBenchmarkRecord);
+    if (inspected.records.length !== marker.completedRuns || manifest.order.length !== marker.expectedRuns) throw new Error("benchmark-marker-count-mismatch");
+    return { runRef: opaque("benchmark", manifest.runId), suiteId: text(manifest.suite?.id, 80) ?? "unknown", lifecycle,
+      evidenceState: "partial", sourceState: binding, startedAt: manifest.startedAt, updatedAt: marker[timeField],
+      completedRuns: marker.completedRuns, expectedRuns: marker.expectedRuns, verdict: null, releaseGate: "unknown",
+      tokenClaimAllowed: null, claimTier: "unknown", scores: { quality: null, safety: null, reliability: null, workflow: null, efficiency: null, overall: null } };
+  }
+  const inspected = ledger(runRoot, manifest.ledger);
+  validateBenchmarkLedgerPrefix(inspected.records, manifest.order, completedBenchmarkRecord);
+  const lockPath = path.join(runRoot, ".benchmark-run.lock"); let live = false, updatedAt = manifest.startedAt;
+  if (fs.existsSync(lockPath)) {
+    const lock = json(lockPath, 16 * 1024);
+    if (lock?.schemaVersion !== 1 || lock.runId !== manifest.runId || !Number.isInteger(lock.pid) || lock.pid < 1
+      || lock.hostname !== os.hostname() || !timestamp(lock.acquiredAt)) throw new Error("benchmark-lock-invalid");
+    try { process.kill(lock.pid, 0); live = true; } catch { live = false; }
+    updatedAt = lock.acquiredAt;
+  }
+  return { runRef: opaque("benchmark", manifest.runId), suiteId: text(manifest.suite?.id, 80) ?? "unknown",
+    lifecycle: live ? "in-progress" : "incomplete", evidenceState: "partial", sourceState: binding,
+    startedAt: manifest.startedAt, updatedAt, completedRuns: inspected.records.length, expectedRuns: manifest.order.length,
+    verdict: null, releaseGate: "unknown", tokenClaimAllowed: null, claimTier: "unknown",
+    scores: { quality: null, safety: null, reliability: null, workflow: null, efficiency: null, overall: null } };
+}
+function benchmarkRuns(cwd: string, root: string, repo: ReturnType<typeof repository>) {
+  const warnings: Array<{ code: string; count: number; message: string }> = [], cache: { benchmark?: any } = {};
+  if (!safeDirectory(root)) return { state: "missing", runs: [], warnings, page: { total: 0, returned: 0, truncated: false } };
+  const bounded = boundedDirectories(root);
+  const allDirectories = bounded.values.filter(safeDirectory)
+    .map((directory) => ({ directory, modifiedAt: fs.statSync(directory).mtimeMs }))
+    .sort((a, b) => b.modifiedAt - a.modifiedAt);
+  const directories = allDirectories.slice(0, MAX_DIRECTORIES).map((item) => item.directory);
+  const runs: any[] = [], seenRuns = new Set<string>(); let corrupt = 0;
+  for (const runRoot of directories) {
+    if (runs.length >= MAX_RUNS) break;
+    try {
+      const reportPath = path.join(runRoot, "report.json"), manifestPath = path.join(runRoot, "run-manifest.json");
+      const value = fs.existsSync(reportPath) ? completeRun(cwd, runRoot, json(reportPath), repo, cache)
+        : fs.existsSync(manifestPath) ? partialRun(cwd, runRoot, json(manifestPath, 4 * 1024 * 1024), repo, cache) : null;
+      if (value) {
+        if (seenRuns.has(value.runRef)) corrupt += 1;
+        else { seenRuns.add(value.runRef); runs.push(value); }
+      }
+    } catch { corrupt += 1; }
+  }
+  if (corrupt) warnings.push({ code: "benchmark-evidence-corrupt", count: corrupt, message: `${corrupt} benchmark run(s) could not be validated.` });
+  if (allDirectories.length > MAX_DIRECTORIES || bounded.truncated) warnings.push({ code: "benchmark-directory-truncated",
+    count: Math.max(1, allDirectories.length - MAX_DIRECTORIES), message: "Older benchmark directories are outside the bounded inspection window." });
+  return { state: runs.length ? "ready" : corrupt ? "unavailable" : "missing", runs, warnings,
+    page: { total: allDirectories.length, returned: runs.length,
+      truncated: bounded.truncated || allDirectories.length > MAX_DIRECTORIES || runs.length >= MAX_RUNS } };
+}
+
+function releaseReadiness(cwd: string, file: string, repo: ReturnType<typeof repository>) {
+  if (!fs.existsSync(file)) return { state: "missing", reportRef: null, generatedAt: null, sourceState: "unknown", localSafeGate: "unknown",
+    rcAssembly: "unknown", beta: "unknown", gaRelease: "unknown", blockerCount: 0, blockers: [], authorization: { releaseCommit: false, tag: false, publish: false, push: false } };
+  try {
+    const report = json(file, 4 * 1024 * 1024), repository = report?.matrix?.repository, readiness = report?.readiness, authorization = report?.authorization;
+    if (report?.schemaVersion !== 1 || report.reportVersion !== "rc-local-readiness-v1" || !timestamp(report.generatedAt)
+      || !/^[a-f0-9]{40,64}$/.test(String(repository?.head ?? "")) || !/^[a-f0-9]{64}$/.test(String(repository?.candidateContentDigest ?? ""))
+      || !Array.isArray(readiness?.blockers) || readiness.blockers.length > 100
+      || ["releaseCommit", "tag", "publish", "push"].some((key) => authorization?.[key] !== false)) throw new Error("release-readiness-invalid");
+    const sourceState = repo.head === repository.head && rcCandidateDigest(cwd) === repository.candidateContentDigest ? "current" : "stale";
+    const blockers = readiness.blockers.slice(0, 8).map((item: unknown) => text(item, 240)).filter(Boolean);
+    return { state: sourceState === "current" ? "ready" : "stale", reportRef: opaque("release", `${report.generatedAt}\0${repository.candidateContentDigest}`),
+      generatedAt: report.generatedAt, sourceState, localSafeGate: ["passed", "failed"].includes(readiness.localSafeGate) ? readiness.localSafeGate : "unknown",
+      rcAssembly: text(readiness.rcAssembly, 100) ?? "unknown", beta: text(readiness.beta, 100) ?? "unknown", gaRelease: text(readiness.gaRelease, 100) ?? "unknown",
+      blockerCount: readiness.blockers.length, blockers,
+      authorization: { releaseCommit: false, tag: false, publish: false, push: false } };
+  } catch {
+    return { state: "unavailable", reportRef: null, generatedAt: null, sourceState: "unknown", localSafeGate: "unknown",
+      rcAssembly: "unknown", beta: "unknown", gaRelease: "unknown", blockerCount: 0, blockers: [], authorization: { releaseCommit: false, tag: false, publish: false, push: false } };
+  }
+}
+
+export function projectBenchmarkReleaseMonitor(input: { cwd: string; identity: Identity; generatedAt?: string; benchmarkRoot?: string; releaseReportPath?: string }) {
+  const generatedAt = input.generatedAt ?? new Date().toISOString();
+  try {
+    const repo = repository(input.cwd), root = input.benchmarkRoot ?? path.join(process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent"), "benchmarks", "piagent");
+    const releasePath = input.releaseReportPath ?? path.join(input.cwd, "plans", "codex-first-product", "evidence", "p7-local-readiness", "report.json");
+    const benchmark = benchmarkRuns(input.cwd, root, repo), release = releaseReadiness(input.cwd, releasePath, repo);
+    const revision = `release-monitor.${createHash("sha256").update(JSON.stringify({ benchmark, release })).digest("hex")}`;
+    const degraded = benchmark.state === "unavailable" || ["unavailable", "stale"].includes(release.state) || benchmark.warnings.length > 0;
+    return { schemaVersion: 1, version: "piagent-webui-release-monitor-v1", generatedAt, identity: structuredClone(input.identity),
+      state: "ready", monitorRevision: revision, benchmark, release,
+      actions: { runBenchmark: false, resumeBenchmark: false, releaseCommit: false, tag: false, publish: false, push: false },
+      health: degraded ? { state: "degraded", reasonCode: "monitor-evidence-incomplete", message: "Some local benchmark or release evidence is unavailable." }
+        : { state: "ok", reasonCode: null, message: null } };
+  } catch {
+    return { schemaVersion: 1, version: "piagent-webui-release-monitor-v1", generatedAt, identity: structuredClone(input.identity),
+      state: "unavailable", monitorRevision: null, benchmark: { state: "unavailable", runs: [], warnings: [], page: { total: 0, returned: 0, truncated: false } },
+      release: { state: "unavailable", reportRef: null, generatedAt: null, sourceState: "unknown", localSafeGate: "unknown", rcAssembly: "unknown", beta: "unknown", gaRelease: "unknown", blockerCount: 0, blockers: [], authorization: { releaseCommit: false, tag: false, publish: false, push: false } },
+      actions: { runBenchmark: false, resumeBenchmark: false, releaseCommit: false, tag: false, publish: false, push: false },
+      health: { state: "error", reasonCode: "release-monitor-unavailable", message: "Local benchmark and release evidence is unavailable." } };
+  }
+}