harnery 0.37.0 → 0.38.0

package/src/lib/admission.ts

@@ -0,0 +1,347 @@
+// Machine-wide admission control for heavy jobs (browser QA matrices,
+// production builds): a crash-safe FIFO slot queue with no daemon and no
+// distributed-lock pretensions. State is plain files on one machine.
+//
+// Layout, per resource under a caller-supplied base directory:
+//
+//   <dir>/<resource>/tickets/<epoch_ms-13pad>-<pid>-<rand>.json   waiters
+//   <dir>/<resource>/held/<same filename>.json                    holders
+//
+// Lexical filename order is enqueue order in BOTH directories. Admission is
+// an atomic rename tickets/ → held/. A waiter may rename only when the live
+// held count is under capacity AND its ticket is among the first
+// (capacity − heldCount) live tickets. After renaming it re-lists held/: if
+// live holders exceed capacity and its file is not among the capacity
+// lexically-oldest, it renames itself back and rejoins the queue — the
+// transient over-admission race self-corrects. Any participant prunes entries
+// whose PID is dead or whose age exceeds the TTL. Release unlinks the held
+// file; process death leaves a dead-PID file for the next participant to
+// prune.
+//
+// Toolkit tier: this module must not import src/core (layering check).
+
+import { randomUUID } from "node:crypto";
+import {
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { coordEnv } from "./env.ts";
+
+export interface AdmissionConfig {
+  /** Base directory holding one subdirectory per resource. */
+  dir: string;
+  /** Resource name, e.g. "browser-qa" or "build". */
+  resource: string;
+  /** Maximum concurrent holders. */
+  capacity: number;
+  /** Poll interval while waiting (default 500ms). */
+  pollMs?: number;
+  /** Entries older than this are pruned regardless of PID (default 6h). */
+  ttlMs?: number;
+}
+
+export interface AdmissionEntry {
+  pid: number;
+  label: string;
+  created_at: string;
+  /** Set on holders once admitted. */
+  acquired_at?: string;
+}
+
+export interface AdmissionWaitInfo {
+  /** 1-based position in the ticket queue. */
+  position: number;
+  holders: AdmissionEntry[];
+}
+
+export interface AdmissionAcquireOptions {
+  /** Human-readable holder description shown in status listings. */
+  label: string;
+  /** Maximum wait before AdmissionTimeoutError (default 20 minutes). */
+  timeoutMs?: number;
+  /** Progress callback, invoked at most once per poll while waiting. */
+  onWait?: (info: AdmissionWaitInfo) => void;
+}
+
+export interface AdmissionHandle {
+  /** The held entry's filename (diagnostics). */
+  entry: string;
+  /** Milliseconds spent waiting in the queue. */
+  waitedMs: number;
+  /** Give the slot back. Safe to call more than once. */
+  release: () => void;
+}
+
+export class AdmissionTimeoutError extends Error {
+  readonly holders: AdmissionEntry[];
+  constructor(resource: string, timeoutMs: number, holders: AdmissionEntry[]) {
+    const labels = holders.map((holder) => `${holder.label} (pid ${holder.pid})`).join(", ");
+    const seconds =
+      timeoutMs < 10_000 ? (timeoutMs / 1000).toFixed(1) : String(Math.round(timeoutMs / 1000));
+    super(
+      `no ${resource} slot became free within ${seconds}s; ` +
+        `current holder(s): ${labels || "none (queue contention)"}`,
+    );
+    this.name = "AdmissionTimeoutError";
+    this.holders = holders;
+  }
+}
+
+const DEFAULT_POLL_MS = 500;
+const DEFAULT_TTL_MS = 6 * 60 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 20 * 60 * 1000;
+/** An unparseable entry younger than this is left alone (it may be mid-write
+ * by a non-atomic writer); older, it is torn garbage and gets pruned. */
+const UNPARSEABLE_GRACE_MS = 60 * 1000;
+
+/** Is a PID alive on this machine? EPERM counts as alive; only ESRCH counts
+ * as dead (fail toward respecting holders rather than stealing slots). */
+export function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err: unknown) {
+    // EPERM = exists but not ours = alive. ESRCH (and anything else) = treat
+    // as dead only on ESRCH; unknown errors count as alive (fail toward
+    // respecting holders rather than stealing their slot).
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ESRCH") return false;
+    return true;
+  }
+}
+
+function ticketsDir(config: AdmissionConfig): string {
+  return join(config.dir, config.resource, "tickets");
+}
+
+function heldDir(config: AdmissionConfig): string {
+  return join(config.dir, config.resource, "held");
+}
+
+function ensureDirs(config: AdmissionConfig): void {
+  mkdirSync(ticketsDir(config), { recursive: true });
+  mkdirSync(heldDir(config), { recursive: true });
+}
+
+function writeEntry(dir: string, name: string, entry: AdmissionEntry): void {
+  const tmp = join(dir, `.${name}.${randomUUID().slice(0, 8)}.tmp`);
+  writeFileSync(tmp, `${JSON.stringify(entry, null, 2)}\n`);
+  renameSync(tmp, join(dir, name));
+}
+
+interface LiveEntry {
+  name: string;
+  entry: AdmissionEntry;
+}
+
+/** List live entries in lexical (= enqueue) order, pruning dead-PID, expired,
+ * and torn files as a side effect. Every participant prunes, so a crashed
+ * holder's slot frees as soon as anyone else looks. */
+function listLive(dir: string, ttlMs: number): LiveEntry[] {
+  let names: string[];
+  try {
+    names = readdirSync(dir)
+      .filter((name) => name.endsWith(".json"))
+      .sort();
+  } catch {
+    return [];
+  }
+  const now = Date.now();
+  const live: LiveEntry[] = [];
+  for (const name of names) {
+    const path = join(dir, name);
+    let entry: AdmissionEntry | undefined;
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        const record = parsed as Record<string, unknown>;
+        if (typeof record.pid === "number" && typeof record.created_at === "string") {
+          entry = {
+            pid: record.pid,
+            label: typeof record.label === "string" ? record.label : "",
+            created_at: record.created_at,
+            ...(typeof record.acquired_at === "string" ? { acquired_at: record.acquired_at } : {}),
+          };
+        }
+      }
+    } catch {
+      // fall through: unparseable
+    }
+    if (!entry) {
+      // Torn or foreign file: prune once it is clearly not mid-write. The
+      // enqueue timestamp is the filename prefix, so age is known without
+      // content.
+      const stamp = Number.parseInt(name.slice(0, 13), 10);
+      if (!Number.isFinite(stamp) || now - stamp > UNPARSEABLE_GRACE_MS) {
+        try {
+          unlinkSync(path);
+        } catch {
+          // a peer pruned it first
+        }
+      }
+      continue;
+    }
+    const age = now - Date.parse(entry.created_at);
+    if (!pidAlive(entry.pid) || Number.isNaN(age) || age > ttlMs) {
+      try {
+        unlinkSync(path);
+      } catch {
+        // a peer pruned it first
+      }
+      continue;
+    }
+    live.push({ name, entry });
+  }
+  return live;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+
+/**
+ * Join the FIFO queue for one resource and resolve once a slot is held.
+ * Throws AdmissionTimeoutError (with the holders snapshot) when no slot
+ * frees within the timeout — the caller decides whether that is fatal.
+ */
+export async function acquireAdmission(
+  config: AdmissionConfig,
+  options: AdmissionAcquireOptions,
+): Promise<AdmissionHandle> {
+  if (!Number.isInteger(config.capacity) || config.capacity < 1) {
+    throw new Error(`admission capacity must be a positive integer, got ${config.capacity}`);
+  }
+  ensureDirs(config);
+  const pollMs = config.pollMs ?? DEFAULT_POLL_MS;
+  const ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const tickets = ticketsDir(config);
+  const held = heldDir(config);
+
+  const myEntry: AdmissionEntry = {
+    pid: process.pid,
+    label: options.label,
+    created_at: new Date().toISOString(),
+  };
+  const myName = `${String(Date.now()).padStart(13, "0")}-${process.pid}-${randomUUID().slice(0, 8)}.json`;
+  writeEntry(tickets, myName, myEntry);
+
+  const startedWaiting = Date.now();
+  const deadline = startedWaiting + timeoutMs;
+  try {
+    while (true) {
+      const liveHeld = listLive(held, ttlMs);
+      const liveTickets = listLive(tickets, ttlMs);
+      const myIndex = liveTickets.findIndex((ticket) => ticket.name === myName);
+      if (myIndex === -1) {
+        // Pruned by a peer (should not happen while we are alive) or lost to
+        // a race; re-enqueue at the back rather than failing the caller.
+        writeEntry(tickets, myName, myEntry);
+        await sleep(pollMs);
+        continue;
+      }
+      const free = config.capacity - liveHeld.length;
+      if (free > 0 && myIndex < free) {
+        renameSync(join(tickets, myName), join(held, myName));
+        // Verify: the rename can transiently over-admit when a slot freed
+        // between two waiters' listings. Lexical order (= enqueue order)
+        // decides who stays; the loser rejoins the queue with its original
+        // priority because the filename keeps its enqueue timestamp.
+        const heldNow = listLive(held, ttlMs);
+        if (heldNow.length > config.capacity) {
+          const keepers = new Set(
+            heldNow.slice(0, config.capacity).map((holderEntry) => holderEntry.name),
+          );
+          if (!keepers.has(myName)) {
+            renameSync(join(held, myName), join(tickets, myName));
+            await sleep(pollMs);
+            continue;
+          }
+        }
+        writeEntry(held, myName, { ...myEntry, acquired_at: new Date().toISOString() });
+        let released = false;
+        return {
+          entry: myName,
+          waitedMs: Date.now() - startedWaiting,
+          release: () => {
+            if (released) return;
+            released = true;
+            try {
+              unlinkSync(join(held, myName));
+            } catch {
+              // already pruned
+            }
+          },
+        };
+      }
+      options.onWait?.({
+        position: myIndex + 1,
+        holders: liveHeld.map((holderEntry) => holderEntry.entry),
+      });
+      if (Date.now() >= deadline) {
+        throw new AdmissionTimeoutError(
+          config.resource,
+          timeoutMs,
+          liveHeld.map((holderEntry) => holderEntry.entry),
+        );
+      }
+      await sleep(pollMs);
+    }
+  } finally {
+    // On any non-admitted exit (timeout, caller abort via throw), leave no
+    // ticket behind. A successful acquire has already moved the file out.
+    try {
+      unlinkSync(join(tickets, myName));
+    } catch {
+      // admitted (file moved) or already pruned
+    }
+  }
+}
+
+export interface AdmissionStatus {
+  resource: string;
+  capacity?: number;
+  holders: AdmissionEntry[];
+  waiters: AdmissionEntry[];
+}
+
+/** Snapshot the queue for one resource, pruning dead entries on the way. */
+export function admissionStatus(
+  config: Pick<AdmissionConfig, "dir" | "resource" | "ttlMs">,
+): AdmissionStatus {
+  const ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
+  const full: AdmissionConfig = { ...config, capacity: 1 };
+  return {
+    resource: config.resource,
+    holders: listLive(heldDir(full), ttlMs).map((holderEntry) => holderEntry.entry),
+    waiters: listLive(ticketsDir(full), ttlMs).map((ticket) => ticket.entry),
+  };
+}
+
+/**
+ * Base directory for admission queue state. tmpdir clears on reboot, which
+ * is correct — stale queue state must not outlive the boot. Override with
+ * HARNERY_ADMISSION_DIR. Host CLIs and harn commands must share this helper
+ * so they join the same machine-wide queues.
+ */
+export function admissionBaseDir(): string {
+  return coordEnv("ADMISSION_DIR") ?? join(tmpdir(), "harnery-admission");
+}
+
+/** Resources present under an admission base directory. */
+export function listAdmissionResources(dir: string): string[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}

package/src/lib/agent-browser/client.ts

@@ -1,11 +1,6 @@
 import { type SpawnSyncOptions, spawnSync } from "node:child_process";
 import { writeFileSync } from "node:fs";
-import {
-  type CookieJar,
-  type CookieStore,
-  type Cookie as JarCookie,
-  mergeCookies,
-} from "../cookies/index.ts";
+import type { CookieJar, Cookie as JarCookie } from "../cookies/index.ts";
 
 /**
  * Thin wrapper over Vercel Labs' `agent-browser` Rust CLI.
@@ -216,10 +211,7 @@ export class AgentBrowser {
       const parsed = JSON.parse(result.stdout);
       const cookies: JarCookie[] = parsed.data?.cookies ?? parsed.cookies ?? [];
       if (!Array.isArray(cookies) || cookies.length === 0) return { saved: 0 };
-      const jar = this.opts.jar;
-      const store: CookieStore = jar.load();
-      const merged = mergeCookies(store, cookies);
-      jar.save(merged);
+      this.opts.jar.merge(cookies);
       return { saved: cookies.length };
     } catch {
       return { saved: 0 };

package/src/lib/browser/capture-fidelity.ts

@@ -0,0 +1,98 @@
+// Capture-fidelity probe for page review packs (pure: no browser, no src/core).
+//
+// A full-page screenshot of a very tall page can carry raster artifacts (a
+// blank block, a callout clipped mid-sentence) that a viewport render of the
+// same region does not show. While the capture browser is still open, the
+// capture branch re-shoots every band by scroll-and-clip and pixel compares
+// each with the crop the tiler took from the full-page image. When any band
+// disagrees, the tiles are re-cut from those scrolled captures and the
+// context records `capture_fidelity.source = "scrolled-bands"`.
+//
+// This module owns the parts that need no browser: the comparison, the
+// decision, and the row stitch that joins viewport-height pieces into one
+// band capture. `client.ts` owns the scroll-and-clip itself.
+
+import { PNG } from "pngjs";
+import type { PageReviewCaptureFidelity } from "./page-review-pack.js";
+import { DEFAULT_REUSE_MISMATCH_RATIO, rectMismatch } from "./qa-reuse.js";
+
+/** The band-diff reuse threshold doubles as the fidelity threshold: a probe
+ * that would count as "unchanged" for reuse counts as "agrees" here. */
+export const CAPTURE_FIDELITY_MISMATCH_THRESHOLD = DEFAULT_REUSE_MISMATCH_RATIO;
+
+export type FidelityProbe = PageReviewCaptureFidelity["probed"][number];
+
+/**
+ * Pixel-compare a band cropped from the full-page screenshot with the same
+ * band captured by scrolling. `mismatch_ratio` is measured over the area the
+ * two images share (pixelmatch, anti-aliasing tolerant, the same math as
+ * band-diff reuse). `size_mismatch` is set when the two differ by more than a
+ * rounding pixel in either dimension; the caller treats that probe as
+ * inconclusive rather than as proof the full page is wrong, because a page
+ * wider than the viewport cannot be rendered whole by scrolling.
+ */
+export function compareBand(
+  fullPageCrop: PNG,
+  scrolledCapture: PNG,
+  threshold: number = CAPTURE_FIDELITY_MISMATCH_THRESHOLD,
+): { mismatch_ratio: number; exceeds: boolean; size_mismatch: boolean } {
+  const width = Math.min(fullPageCrop.width, scrolledCapture.width);
+  const height = Math.min(fullPageCrop.height, scrolledCapture.height);
+  const size_mismatch =
+    Math.abs(fullPageCrop.width - scrolledCapture.width) > 1 ||
+    Math.abs(fullPageCrop.height - scrolledCapture.height) > 1;
+  if (width <= 0 || height <= 0) return { mismatch_ratio: 1, exceeds: true, size_mismatch: true };
+  const cmp = rectMismatch(fullPageCrop, scrolledCapture, { x: 0, y: 0, width, height });
+  return { mismatch_ratio: cmp.ratio, exceeds: cmp.ratio > threshold, size_mismatch };
+}
+
+/**
+ * Turn the probe results into the record the context carries. Any probe over
+ * the threshold means the full-page screenshot is not trustworthy for this
+ * context and the tiles must come from scrolled captures.
+ */
+export function decideFidelity(
+  probes: readonly FidelityProbe[],
+  threshold: number = CAPTURE_FIDELITY_MISMATCH_THRESHOLD,
+): PageReviewCaptureFidelity {
+  const mismatched = probes
+    .filter((probe) => probe.mismatch_ratio > threshold)
+    .map((probe) => probe.tile_id);
+  return {
+    source: mismatched.length > 0 ? "scrolled-bands" : "full-page",
+    probed: probes.map((probe) => ({ ...probe })),
+    mismatched,
+    mismatch_threshold: threshold,
+  };
+}
+
+/**
+ * Join PNG pieces top to bottom into one image. The output takes the first
+ * piece's width; a narrower piece leaves transparent pixels on its right, a
+ * wider one is cropped. Used to assemble a band taller than the viewport from
+ * viewport-height captures (see `Browser.captureRegionByScroll`).
+ */
+export function stitchPngRows(pieces: readonly Buffer[]): Buffer {
+  const first = pieces[0];
+  if (!first) throw new Error("stitchPngRows: at least one piece is required");
+  if (pieces.length === 1) return first;
+  const decoded = pieces.map((piece) => PNG.sync.read(piece));
+  const width = (decoded[0] as PNG).width;
+  const height = decoded.reduce((sum, piece) => sum + piece.height, 0);
+  const out = new PNG({ width, height });
+  let row = 0;
+  for (const piece of decoded) {
+    const copyWidth = Math.min(width, piece.width);
+    for (let y = 0; y < piece.height; y++) {
+      const srcStart = y * piece.width * 4;
+      piece.data.copy(out.data, (row + y) * width * 4, srcStart, srcStart + copyWidth * 4);
+    }
+    row += piece.height;
+  }
+  return PNG.sync.write(out);
+}
+
+/** Width and height from a PNG header, without decoding the image. */
+export function pngDimensions(buffer: Buffer): { width: number; height: number } {
+  return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+}