harnery 0.27.0 → 0.28.0

package/dist/lib/browser/client.js

@@ -155,6 +155,109 @@ export class Browser {
         const buf = await page.screenshot({ path, fullPage: opts.fullPage ?? true, type: "png" });
         return buf.length;
     }
+    /**
+     * Capture a full-page screenshot from an explicit capture viewport and
+     * evaluate the caller's final evidence expression immediately before the
+     * pixels are written. Playwright normally manages the full-page viewport
+     * internally, which leaves callers unable to inspect fixed/sticky geometry
+     * in the state the PNG actually renders.
+     */
+    async screenshotWithEvaluation(path, evaluation, opts = {}) {
+        const page = this.currentPage;
+        const fullPage = opts.fullPage ?? true;
+        const maxPasses = 4;
+        const maxDimension = 32_000;
+        const maxPixels = 128_000_000;
+        const documentExtent = () => page.evaluate(() => ({
+            width: Math.max(document.documentElement.scrollWidth, document.body?.scrollWidth ?? 0),
+            height: Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight ?? 0),
+        }));
+        const originalViewport = page.viewportSize();
+        if (!originalViewport) {
+            throw new Error("Capture-state evaluation requires a page with an explicit viewport.");
+        }
+        let captureViewport = originalViewport;
+        let passes = fullPage ? 0 : 1;
+        let extentBeforeEvaluation = await documentExtent();
+        let bounded = true;
+        if (fullPage) {
+            for (let pass = 0; pass < maxPasses; pass += 1) {
+                passes = pass + 1;
+                const nextViewport = {
+                    width: originalViewport.width,
+                    height: Math.max(originalViewport.height, Math.ceil(extentBeforeEvaluation.height)),
+                };
+                bounded =
+                    nextViewport.width <= maxDimension &&
+                        nextViewport.height <= maxDimension &&
+                        nextViewport.width * nextViewport.height <= maxPixels;
+                if (!bounded)
+                    break;
+                if (nextViewport.width === captureViewport.width &&
+                    nextViewport.height === captureViewport.height &&
+                    extentBeforeEvaluation.width <= captureViewport.width &&
+                    extentBeforeEvaluation.height === captureViewport.height) {
+                    break;
+                }
+                captureViewport = nextViewport;
+                await page.setViewportSize(captureViewport);
+                extentBeforeEvaluation = await documentExtent();
+            }
+        }
+        try {
+            const evaluationResult = await page.evaluate(evaluation);
+            const extentAfterEvaluation = await documentExtent();
+            const buf = await page.screenshot({ path, fullPage: fullPage && bounded, type: "png" });
+            const extentAfterScreenshot = await documentExtent();
+            const screenshot = {
+                width: buf.readUInt32BE(16),
+                height: buf.readUInt32BE(20),
+                bytes: buf.length,
+            };
+            const exact = fullPage
+                ? bounded &&
+                    captureViewport.width === extentBeforeEvaluation.width &&
+                    captureViewport.height === extentBeforeEvaluation.height &&
+                    captureViewport.width === extentAfterEvaluation.width &&
+                    captureViewport.height === extentAfterEvaluation.height &&
+                    captureViewport.width === extentAfterScreenshot.width &&
+                    captureViewport.height === extentAfterScreenshot.height &&
+                    captureViewport.width === screenshot.width &&
+                    captureViewport.height === screenshot.height
+                : captureViewport.width === screenshot.width &&
+                    captureViewport.height === screenshot.height;
+            const reason = !bounded
+                ? "capture_bounds_exceeded"
+                : exact
+                    ? "capture_viewport_converged"
+                    : "capture_viewport_non_convergent";
+            return {
+                bytes: buf.length,
+                evaluation: evaluationResult,
+                viewport: captureViewport,
+                evidence: {
+                    converged: exact,
+                    reason,
+                    passes,
+                    max_passes: maxPasses,
+                    max_dimension: maxDimension,
+                    max_pixels: maxPixels,
+                    original_viewport: originalViewport,
+                    evaluated_viewport: captureViewport,
+                    document_extent_before_evaluation: extentBeforeEvaluation,
+                    document_extent_after_evaluation: extentAfterEvaluation,
+                    document_extent_after_screenshot: extentAfterScreenshot,
+                    screenshot,
+                },
+            };
+        }
+        finally {
+            if (captureViewport.width !== originalViewport.width ||
+                captureViewport.height !== originalViewport.height) {
+                await page.setViewportSize(originalViewport);
+            }
+        }
+    }
     /**
      * Plain-text snapshot of the document body. Suitable as a coarse "what's
      * on screen" signal for LLM iteration loops. For richer extraction, use

package/dist/lib/exec.d.ts

@@ -10,6 +10,10 @@ export interface ExecResult {
     stdout: string;
     stderr: string;
     exitCode: number;
+    /** True when this process killed the child for exceeding `opts.timeout`. A
+     * child that handles the signal cleanly still exits 0, so the exit code alone
+     * cannot distinguish a kill from an ordinary finish. */
+    timedOut?: boolean;
 }
 export interface ExecOpts {
     cwd?: string;

package/dist/lib/exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/lib/exec.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,QAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAmC5E;AAED,sEAAsE;AACtE,wBAAsB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAEhG"}
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/lib/exec.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB;;4DAEwD;IACxD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,QAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAwC5E;AAED,sEAAsE;AACtE,wBAAsB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAEhG"}

package/dist/lib/exec.js

@@ -29,7 +29,11 @@ export function exec(cmd, opts = {}) {
         proc.stdout?.on("data", (d) => out.push(d));
         proc.stderr?.on("data", (d) => err.push(d));
         const timeout = opts.timeout ?? 30_000;
-        const timer = setTimeout(() => proc.kill(), timeout);
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            proc.kill();
+        }, timeout);
         const finish = (exitCode, errOverride) => {
             clearTimeout(timer);
             const stdout = Buffer.concat(out).toString("utf-8");
@@ -39,6 +43,7 @@ export function exec(cmd, opts = {}) {
                 stdout: shouldTrim ? stdout.trim() : stdout.replace(/\n$/, ""),
                 stderr: shouldTrim ? stderr.trim() : stderr.replace(/\n$/, ""),
                 exitCode,
+                ...(timedOut ? { timedOut: true } : {}),
             });
         };
         // ENOENT (binary not found) and similar spawn failures surface here rather

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",

package/src/commands/browse.ts

@@ -67,6 +67,7 @@ interface BrowseOpts {
   press?: string;
   waitFor?: string;
   evaluate?: string;
+  captureEvaluate?: string;
   batch?: string;
   networkHar?: string;
   login?: boolean;
@@ -179,6 +180,10 @@ export function registerBrowseCommand(
       "--evaluate <js>",
       "Run JS in the page context after navigation; result printed to stdout",
     )
+    .option(
+      "--capture-evaluate <js>",
+      "In trio mode, evaluate JS inside the exact screenshot viewport immediately before capture; result is written as captureEval",
+    )
     .option(
       "--batch <steps>",
       "Run multiple steps in one session, semicolon-separated. Each step is one of: " +
@@ -601,6 +606,11 @@ async function runBrowse(
     }
 
     if (printMode) {
+      if (opts.captureEvaluate) {
+        throw new Error(
+          "--capture-evaluate requires trio mode so its result can be bound to a screenshot.",
+        );
+      }
       if (opts.baseline || opts.diff) {
         throw new Error(
           "--baseline / --diff require trio mode (screenshot file). Remove --snapshot/--html/--json or capture the screenshot first.",
@@ -911,10 +921,27 @@ async function runTrioMode(
   const skipScreenshot = opts.screenshot === false || opts.domOnly === true;
   let pngPath: string | undefined;
   let pngBytes: number | undefined;
+  let captureEvalResult: unknown;
+  let captureViewport: { width: number; height: number } | undefined;
+  let captureEvidence: unknown;
   if (!skipScreenshot) {
     pngPath = `${prefix}.png`;
-    pngBytes = await browser.screenshot(pngPath, { fullPage: opts.fullPage !== false });
+    if (opts.captureEvaluate) {
+      const captured = await browser.screenshotWithEvaluation(pngPath, opts.captureEvaluate, {
+        fullPage: opts.fullPage !== false,
+      });
+      pngBytes = captured.bytes;
+      captureEvalResult = captured.evaluation;
+      captureViewport = captured.viewport;
+      captureEvidence = captured.evidence;
+    } else {
+      pngBytes = await browser.screenshot(pngPath, { fullPage: opts.fullPage !== false });
+    }
     written.push(pngPath);
+  } else if (opts.captureEvaluate) {
+    throw new Error(
+      "--capture-evaluate requires a screenshot; remove --no-screenshot / --dom-only.",
+    );
   }
 
   const htmlPath = `${prefix}.html`;
@@ -937,6 +964,11 @@ async function runTrioMode(
   };
   if (pngBytes !== undefined) envelope.screenshotBytes = pngBytes;
   if (opts.evaluate) envelope.eval = evalResult;
+  if (opts.captureEvaluate) {
+    envelope.captureEval = captureEvalResult;
+    envelope.captureViewport = captureViewport;
+    envelope.captureEvidence = captureEvidence;
+  }
   if (opts.networkHar) envelope.har = resolve(opts.networkHar);
   if (visibility) envelope.visibility = visibility;
   if (widths) envelope.width = widths;

package/src/commands/work.ts

@@ -19,6 +19,7 @@ import {
   reconcileWorkItem,
   reopenWorkItem,
   runWorkItem,
+  type WorkAttempt,
   type WorkRecord,
 } from "../core/work/index.ts";
 import { WorkflowParkedError } from "../core/workflow/index.ts";
@@ -52,8 +53,12 @@ interface GovernanceOpts {
   actor?: string;
   reason?: string;
   json?: boolean;
+  finding?: string[];
+  dispose?: string[];
 }
 
+const MAX_ATTEMPT_JOURNAL_ERROR_RENDER = 240;
+
 export function registerWorkCommand(program: Command, emit: EmitContext): void {
   const registry = createBuiltinHarnessRegistry();
   const harnesses = registry.ids();
@@ -257,14 +262,66 @@ function registerGovernanceCommand(
     )
     .option("--actor <name>", "Actor recorded in the governance receipt")
     .option("--reason <text>", "Bounded decision reason")
-    .option("--json", "Emit the complete work record as JSON")
-    .action((workId: string, opts: GovernanceOpts) => {
-      withWorkRoot(emit, (coordRoot) => {
-        const fn =
-          name === "accept" ? acceptWorkItem : name === "cancel" ? cancelWorkItem : reopenWorkItem;
-        emitWork(fn(coordRoot, workId, opts), opts.json, emit, true);
-      });
+    .option("--json", "Emit the complete work record as JSON");
+  const command = work.commands.at(-1) as Command;
+  if (name === "reopen") {
+    command.option(
+      "--finding <text>",
+      "Correction the next attempt must address (repeatable)",
+      collectValue,
+      [] as string[],
+    );
+  }
+  if (name === "accept") {
+    command.option(
+      "--dispose <id=outcome[:reason]>",
+      "Dispose of an open finding: fixed, or deferred:<reason> (repeatable)",
+      collectValue,
+      [] as string[],
+    );
+  }
+  command.action((workId: string, opts: GovernanceOpts) => {
+    withWorkRoot(emit, (coordRoot) => {
+      const fn =
+        name === "accept" ? acceptWorkItem : name === "cancel" ? cancelWorkItem : reopenWorkItem;
+      emitWork(
+        fn(coordRoot, workId, {
+          ...opts,
+          ...(opts.finding?.length ? { findings: opts.finding } : {}),
+          ...(opts.dispose?.length ? { dispositions: opts.dispose.map(parseDisposition) } : {}),
+        }),
+        opts.json,
+        emit,
+        true,
+      );
     });
+  });
+}
+
+function collectValue(value: string, previous: string[]): string[] {
+  return [...previous, value];
+}
+
+/** `<id>=fixed` or `<id>=deferred:<reason>`. Deferring without a reason is
+ * rejected downstream, so a lapsed finding cannot look like a decision. */
+function parseDisposition(input: string): {
+  id: string;
+  outcome: "fixed" | "deferred";
+  reason?: string;
+} {
+  const split = input.indexOf("=");
+  if (split <= 0)
+    throw new Error(`invalid --dispose ${JSON.stringify(input)}; expected <id>=<outcome>`);
+  const id = input.slice(0, split).trim();
+  const rest = input.slice(split + 1).trim();
+  const [outcome, ...reasonParts] = rest.split(":");
+  if (outcome !== "fixed" && outcome !== "deferred") {
+    throw new Error(
+      `invalid --dispose outcome ${JSON.stringify(outcome)}; expected fixed or deferred`,
+    );
+  }
+  const reason = reasonParts.join(":").trim();
+  return { id, outcome, ...(reason ? { reason } : {}) };
 }
 
 function emitWork(
@@ -297,18 +354,28 @@ function emitWork(
     lines.push("acceptance:", ...record.intent.acceptance.map((item) => `  - ${item}`));
   }
   if (projection.attempts.length) {
-    lines.push(
-      "attempts:",
-      ...projection.attempts.map(
-        (attempt) => `  ${attempt.number}. ${attempt.run_id}  ${attempt.status}`,
-      ),
-    );
+    lines.push("attempts:", ...projection.attempts.map(renderAttemptRow));
   }
   if (projection.approval_id) lines.push(`approval: ${projection.approval_id}`);
   if (projection.proof_path) lines.push(`proof: ${projection.proof_path}`);
   emit.text(`${lines.join("\n")}\n`);
 }
 
+export function renderAttemptRow(attempt: WorkAttempt): string {
+  const statusDetail =
+    attempt.status === "journal_unreadable"
+      ? `: ${renderAttemptJournalError(attempt.journal_error)}`
+      : "";
+  return `  ${attempt.number}. ${attempt.run_id}  ${attempt.status}${statusDetail}`;
+}
+
+function renderAttemptJournalError(error: string | undefined): string {
+  const normalized = (error ?? "").replace(/\s+/g, " ").trim();
+  const value = normalized || "unknown journal read error";
+  if (value.length <= MAX_ATTEMPT_JOURNAL_ERROR_RENDER) return value;
+  return `${value.slice(0, MAX_ATTEMPT_JOURNAL_ERROR_RENDER - 3).trimEnd()}...`;
+}
+
 function renderWorkRow(record: WorkRecord): string {
   const projection = record.projection;
   return `${record.intent.id}  ${projection.state.padEnd(17)}  ${projection.attempts_used}/${record.intent.max_attempts}  ${projection.next_action.padEnd(21)}  ${record.intent.title}`;

package/src/core/harnesses/types.ts

@@ -83,6 +83,11 @@ export interface HarnessRawResult {
   exitCode: number;
   durationMs: number;
   resultFileText?: string;
+  /** The host killed this child for exceeding its timeout. A vendor CLI that
+   * handles the signal cleanly still exits 0, so exit code alone cannot tell a
+   * kill from a finish; without this a timed-out child reads as a success with
+   * an empty answer. */
+  timedOut?: boolean;
 }
 
 export interface HarnessBenchFixture {

package/src/core/work/index.ts

@@ -7,6 +7,7 @@ export {
   createWorkItem,
   listWorkItems,
   newWorkId,
+  openOperatorFindings,
   readWorkItem,
   reconcileAllWorkItems,
   reconcileWorkItem,

package/src/core/work/runner.ts

@@ -18,6 +18,7 @@ import {
   assertWorkflowUnchanged,
   boundedActor,
   newWorkflowRunId,
+  openOperatorFindings,
   readWorkItemIgnoringLease,
   type WorkAttempt,
 } from "./state.ts";
@@ -81,11 +82,18 @@ export async function runWorkItem(input: RunWorkItemInput): Promise<RunReport> {
       }
       prior = priorContext(coordRoot, latest);
     }
+    const open = openOperatorFindings(coordRoot, input.workId);
+    const findings = open.findings.map((finding) => ({
+      id: finding.id,
+      actor: open.actor,
+      statement: finding.statement,
+    }));
     const attemptContext: WorkflowAttemptContext = {
       schema_version: WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION,
       number: attempt,
       trigger,
       ...(prior ? { prior } : {}),
+      ...(findings.length === 0 ? {} : { findings }),
     };
     const runId = newWorkflowRunId();
     appendWorkEvent(coordRoot, input.workId, {