harnery 0.27.0 → 0.29.0

package/src/core/workflow/journal.ts

@@ -0,0 +1,90 @@
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fsyncParentDirectory, stableDigest } from "./durable-record.ts";
+
+// Limit for the JSON record body. The trailing newline delimiter is outside the
+// record and is not counted by readers after splitting journal lines.
+export const WORKFLOW_JOURNAL_EVENT_BYTES = 16 * 1024;
+
+/** Key under which a shrunk record names the fields it had to drop. */
+export const WORKFLOW_JOURNAL_OMITTED = "omitted_fields";
+
+const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+
+export interface WorkflowJournalOmission {
+  field: string;
+  bytes: number;
+  sha256: string;
+}
+
+export function workflowJournalPath(coordRoot: string, runId: string): string {
+  if (!RUN_ID.test(runId)) throw new Error(`invalid workflow run id ${JSON.stringify(runId)}`);
+  return join(resolve(coordRoot), ".harnery", "workflows", runId, "journal.jsonl");
+}
+
+/**
+ * Append one journal record, always.
+ *
+ * A record that would exceed what a reader accepts has its largest fields
+ * replaced by a digest and a byte count until it fits, and it names what it
+ * dropped. Size never raises.
+ *
+ * Refusing an oversized record would let a valid run fail on its own opening
+ * line: `run.start` carries the workflow's declared metadata plus the frozen
+ * work and attempt context, and Harnery's own validators permit those to exceed
+ * this limit by construction. Losing detail from a record is recoverable.
+ * Losing the run that was writing it is not.
+ */
+export function appendWorkflowJournalEvent(
+  coordRoot: string,
+  runId: string,
+  event: string,
+  data: Record<string, unknown>,
+): void {
+  const path = workflowJournalPath(coordRoot, runId);
+  const record = fitWorkflowJournalRecord(
+    { schema_version: 1, run_id: runId, ts: new Date().toISOString(), event },
+    data,
+  );
+  const line = `${JSON.stringify(record)}\n`;
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const existed = existsSync(path);
+  const fd = openSync(path, "a", 0o600);
+  try {
+    writeFileSync(fd, line, "utf8");
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  if (!existed) fsyncParentDirectory(path);
+}
+
+/**
+ * Shrink a record to the reader's limit by dropping its largest fields first.
+ * The envelope is never dropped, so a record keeps its run id, timestamp, and
+ * event name however much detail it loses. Exported for tests.
+ */
+export function fitWorkflowJournalRecord(
+  envelope: Record<string, unknown>,
+  data: Record<string, unknown>,
+): Record<string, unknown> {
+  const candidate = { ...envelope, ...data };
+  if (Buffer.byteLength(JSON.stringify(candidate)) <= WORKFLOW_JOURNAL_EVENT_BYTES) {
+    return candidate;
+  }
+  const kept: Record<string, unknown> = { ...data };
+  const omitted: WorkflowJournalOmission[] = [];
+  const bySize = Object.keys(data)
+    .map((field) => ({ field, bytes: Buffer.byteLength(JSON.stringify(data[field]) ?? "") }))
+    .sort((a, b) => b.bytes - a.bytes);
+
+  for (const { field, bytes } of bySize) {
+    omitted.push({ field, bytes, sha256: stableDigest(data[field]) });
+    delete kept[field];
+    const next = { ...envelope, ...kept, [WORKFLOW_JOURNAL_OMITTED]: omitted };
+    if (Buffer.byteLength(JSON.stringify(next)) <= WORKFLOW_JOURNAL_EVENT_BYTES) return next;
+  }
+  // Every field dropped and still over: the omission list is itself the excess.
+  // Keep the envelope and a count so the record stays parseable and honest.
+  return { ...envelope, [WORKFLOW_JOURNAL_OMITTED]: omitted.length };
+}

package/src/core/workflow/spawn-claude.ts

@@ -62,6 +62,14 @@ export function buildClaudeInvocation(req: SpawnRequest): HarnessInvocation {
 }
 
 export function normalizeClaudeResult(raw: HarnessRawResult): SpawnResult {
+  if (raw.timedOut) {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: `claude timed out after ${raw.durationMs}ms and was killed`,
+    };
+  }
   if (raw.exitCode === 127) {
     return {
       ok: false,

package/src/core/workflow/spawn-codex.ts

@@ -61,6 +61,14 @@ export function buildCodexInvocation(req: SpawnRequest, resultFile?: string): Ha
 }
 
 export function normalizeCodexResult(raw: HarnessRawResult): SpawnResult {
+  if (raw.timedOut) {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: `codex timed out after ${raw.durationMs}ms and was killed`,
+    };
+  }
   if (raw.exitCode === 127) {
     return { ok: false, text: "", durationMs: raw.durationMs, error: notFoundError("codex") };
   }

package/src/core/workflow/spawn-cursor.ts

@@ -74,6 +74,14 @@ export function buildCursorInvocation(req: SpawnRequest): HarnessInvocation {
 }
 
 export function normalizeCursorResult(raw: HarnessRawResult): SpawnResult {
+  if (raw.timedOut) {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: `cursor timed out after ${raw.durationMs}ms and was killed`,
+    };
+  }
   if (raw.exitCode === 127) {
     return { ok: false, text: "", durationMs: raw.durationMs, error: notFoundError("cursor") };
   }

package/src/core/workflow/types.ts

@@ -427,6 +427,18 @@ export interface WorkflowAttemptContext {
   readonly number: number;
   readonly trigger: "initial" | "retry";
   readonly prior?: Readonly<WorkflowAttemptPriorContext>;
+  /** Open findings an operator raised against a prior attempt. Present on any
+   * trigger, because a reopen with findings starts a fresh initial attempt.
+   * Distinct from `prior`, which is evidence the run itself produced. */
+  readonly findings?: readonly Readonly<WorkflowOperatorFinding>[];
+}
+
+/** One correction an operator raised against work they judged wrong. Authored
+ * by a human, not derived from proof, and carried until explicitly disposed. */
+export interface WorkflowOperatorFinding {
+  readonly id: string;
+  readonly actor: string;
+  readonly statement: string;
 }
 
 export interface EngineOpts {

package/src/core/workflow/workspaces/local-git.ts

@@ -123,16 +123,26 @@ export async function probe(
   if (input.writable_roots.length === 0) {
     unsupported.push(reason("writable_roots_required", "explicit writable roots are required"));
   }
-  for (const root of input.writable_roots) {
+  // Allocation always selects writable_roots[0] (validateRequest pins the selected root
+  // to it), so probe's authority-coverage verdict must be judged against that same root.
+  let selectedRoot: ValidatedRoot | undefined;
+  input.writable_roots.forEach((root, index) => {
     try {
-      validateConfiguredRoot(root);
+      const validated = validateConfiguredRoot(root);
+      if (index === 0) selectedRoot = validated;
     } catch (error) {
       unsupported.push(reason("writable_root_invalid", (error as Error).message));
     }
-  }
+  });
   if (version.ok) {
     try {
-      inspectSourceRepository(input.requested_cwd);
+      const repo = inspectSourceRepository(input.requested_cwd);
+      if (selectedRoot) {
+        const outside = describeAuthorityOutsideRoot(repo, selectedRoot.realpath);
+        if (outside) {
+          unsupported.push(reason("repository_authority_outside_writable_root", outside));
+        }
+      }
     } catch (error) {
       unsupported.push(reason("repository_unsupported", (error as Error).message));
     }
@@ -209,12 +219,8 @@ async function allocate(
     repo.commonDir.realpath,
     "Git common directory",
   );
-  if (
-    !containsPath(root.realpath, repo.sourceRoot.realpath) ||
-    !containsPath(root.realpath, repo.commonDir.realpath)
-  ) {
-    throw new Error("source repository and Git common dir must be inside the writable root");
-  }
+  const authorityOutside = describeAuthorityOutsideRoot(repo, root.realpath);
+  if (authorityOutside) throw new Error(authorityOutside);
   const workspaceRoot = candidateUnderRoot(root, ["harnery-workspaces", bindingId]);
   const activeRoot = resolve(workspaceRoot, repo.requestedRelativePath);
   if (!containsPath(workspaceRoot, activeRoot)) {
@@ -1192,6 +1198,25 @@ async function applyIntegrationUnderLease(
   }
   revalidateClaimResources(claim, validateConfiguredRoot(plan.binding.writable_root.configured));
   inspectIntegrationTarget(current.target_root, plan.binding);
+  // The fast-forward moves the target branch ref, which for a submodule or linked
+  // worktree lives in the common directory outside the checkout tree. allowed_paths is
+  // the real write authority (allocate and cleanup already gate the common directory on
+  // it), so re-authorize both the target checkout and its common directory here rather
+  // than trusting containment alone.
+  const applyCommonDir = plan.binding.repository?.common_dir.realpath;
+  if (!applyCommonDir) {
+    throw new Error("integration binding is missing Git common-dir authority");
+  }
+  assertAllowedPathAuthority(
+    claim.request.allowed_paths,
+    current.target_root,
+    "integration target path",
+  );
+  assertAllowedPathAuthority(
+    claim.request.allowed_paths,
+    applyCommonDir,
+    "integration Git common directory",
+  );
   git(current.target_root, ["merge", "--ff-only", expected.source_commit]);
   const finalCommit = git(current.target_root, ["rev-parse", "HEAD"]);
   const finalTree = git(current.target_root, ["rev-parse", "HEAD^{tree}"]);
@@ -1287,20 +1312,17 @@ function inspectSourceRepository(cwd: string): {
   if (!containsPath(sourceRoot, requestedCwd.realpath)) {
     throw new Error("requested working directory is outside the resolved Git worktree");
   }
-  if (lstatSync(join(sourceRoot, ".git")).isSymbolicLink()) {
-    throw new Error("symlink Git directories are unsupported");
-  }
-  if (!lstatSync(join(sourceRoot, ".git")).isDirectory()) {
-    throw new Error("linked worktree and submodule source repositories are unsupported");
-  }
-  const requestedGitDir = realpathSync(join(sourceRoot, ".git"));
+  const pointedGitDir = resolveGitDirPointer(sourceRoot);
   const gitDir = realpathSync(resolve(sourceRoot, git(sourceRoot, ["rev-parse", "--git-dir"])));
   const commonDir = realpathSync(
     resolve(sourceRoot, git(sourceRoot, ["rev-parse", "--git-common-dir"])),
   );
-  if (gitDir !== requestedGitDir || commonDir !== requestedGitDir) {
+  if (pointedGitDir !== gitDir) {
     throw new Error("resolved Git authority does not match the requested checkout");
   }
+  if (!containsPath(commonDir, gitDir)) {
+    throw new Error("resolved Git directory is not inside its common directory");
+  }
   const branch = gitMaybe(sourceRoot, ["symbolic-ref", "-q", "--short", "HEAD"]);
   if (!branch.ok || !branch.out) throw new Error("detached integration targets are unsupported");
   const targetRef = `refs/heads/${branch.out}`;
@@ -1321,6 +1343,47 @@ function inspectSourceRepository(cwd: string): {
   };
 }
 
+// Resolve the `.git` entry at a checkout root to the real Git directory it names,
+// without trusting the ambient environment. `.git` is a real directory in a plain
+// checkout, and a `gitdir:` pointer file in a linked worktree, submodule, or
+// worktree-of-a-submodule. A symlink is refused: the identity model pins a path to a
+// device and inode, and a symlink lets the target move under a pinned pointer.
+//
+// The caller cross-checks the result against `rev-parse --git-dir`. That is a
+// consistency assertion, not spoof detection: Git honours a `gitdir:` pointer, so a
+// pointer aimed at an unrelated repository agrees with `rev-parse` and is accepted.
+// It cannot be otherwise, because a doctored pointer and a submodule's pointer are
+// the same construct. What the equality buys is that this resolution and Git's own
+// never silently diverge, which is defence in depth over the `GIT_*` stripping in
+// `isolatedGitEnvironment`. The real authority check is containment plus
+// `allowed_paths` on the resolved common directory.
+function resolveGitDirPointer(sourceRoot: string): string {
+  const dotGit = join(sourceRoot, ".git");
+  let stats: ReturnType<typeof lstatSync>;
+  try {
+    stats = lstatSync(dotGit);
+  } catch {
+    throw new Error("requested checkout has no .git entry");
+  }
+  if (stats.isSymbolicLink()) {
+    throw new Error("symlink Git directories are unsupported");
+  }
+  if (stats.isDirectory()) {
+    return realpathSync(dotGit);
+  }
+  if (!stats.isFile()) {
+    throw new Error(".git must be a directory or a gitdir pointer file");
+  }
+  const pointer = readFileSync(dotGit, "utf8").split(/\r?\n/, 1)[0]?.trim() ?? "";
+  const prefix = "gitdir:";
+  if (!pointer.startsWith(prefix)) {
+    throw new Error(".git file is not a gitdir pointer");
+  }
+  const target = pointer.slice(prefix.length).trim();
+  if (!target) throw new Error(".git gitdir pointer is empty");
+  return realpathSync(resolve(sourceRoot, target));
+}
+
 function inspectFrozenSourceAuthority(
   sourceRoot: GitRepositoryBinding["source_root"],
   commonDir: GitRepositoryBinding["common_dir"],
@@ -1680,6 +1743,28 @@ function validFrozenFilesystemPath(
   );
 }
 
+// Explain, in the caller's terms, why a checkout's Git authority falls outside a
+// writable root — naming the offending path so a submodule or linked-worktree user
+// who declared only the inner checkout knows exactly what to widen. Returns undefined
+// when both the source checkout and its common directory are inside the root.
+function describeAuthorityOutsideRoot(
+  repo: ReturnType<typeof inspectSourceRepository>,
+  rootRealpath: string,
+): string | undefined {
+  if (!containsPath(rootRealpath, repo.commonDir.realpath)) {
+    return (
+      `Git keeps this checkout's administrative files in ${repo.commonDir.realpath}, ` +
+      `which is outside the writable root ${rootRealpath}. Linked-worktree and submodule ` +
+      `checkouts keep their Git authority in the enclosing repository, and allocating a ` +
+      `worktree writes there; declare that repository (or a parent of it) as the writable root.`
+    );
+  }
+  if (!containsPath(rootRealpath, repo.sourceRoot.realpath)) {
+    return `the source checkout ${repo.sourceRoot.realpath} is outside the writable root ${rootRealpath}`;
+  }
+  return undefined;
+}
+
 function assertAllowedPathAuthority(
   allowedPaths: WorkspaceAllocationRequest["allowed_paths"],
   candidate: string,
@@ -1783,10 +1868,15 @@ function capabilityDigestForClaim(claim: WorkspaceClaim): string {
 function acquireRepositoryLease(coordRoot: string, claim: WorkspaceClaim): () => void {
   const leaseDir = join(resolve(coordRoot), ".harnery", "workspaces", PROVIDER_ID, ".leases");
   mkdirSync(leaseDir, { recursive: true, mode: 0o700 });
-  const key = stableDigest({
-    common: claim.repository.common_dir.identity,
-    root: claim.writable_root.identity,
-  });
+  // Mutual exclusion keys on the Git common directory alone. `git worktree add`,
+  // `prune`, and the shared-`config` migration all write to the common directory's
+  // administrative area, and once worktrees and submodules are allowed, several
+  // distinct source checkouts (a superproject and its linked worktrees; a submodule
+  // and a worktree of it) share one common directory under different — possibly
+  // nested — writable roots. Including the writable root in the key would hand those
+  // agents different locks and let their admin-area writes race. The writable root
+  // stays in the lease metadata for diagnostics, not in the exclusion key.
+  const key = stableDigest({ common: claim.repository.common_dir.identity });
   return acquireLease(coordRoot, join(leaseDir, `repository-${key}.lock`), claim, "repository");
 }
 

package/src/core/workflow/workspaces/state.ts

@@ -17,6 +17,9 @@ import {
   stableDigest,
   writeImmutableJson,
 } from "../durable-record.ts";
+
+export { appendWorkflowJournalEvent } from "../journal.ts";
+
 import type {
   GitRepositoryBinding,
   IntegrationApplyAttempt,
@@ -34,7 +37,7 @@ import type {
 } from "./types.ts";
 
 const JSON_LIMIT = 512 * 1024;
-const EVENT_LIMIT = 32 * 1024;
+const WORKSPACE_EVENT_BYTES = 32 * 1024;
 const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
 
 export interface WorkspaceClaim {
@@ -181,7 +184,11 @@ export function appendWorkspaceEvent(
   event: string,
   data: Record<string, unknown> = {},
 ): WorkspaceProviderEvent {
-  if (!event || event.length > 100 || Buffer.byteLength(JSON.stringify(data)) > EVENT_LIMIT / 2) {
+  if (
+    !event ||
+    event.length > 100 ||
+    Buffer.byteLength(JSON.stringify(data)) > WORKSPACE_EVENT_BYTES / 2
+  ) {
     throw new Error("workspace provider event is invalid or too large");
   }
   const path = workspaceEventsPath(coordRoot, claim.provider_id, claim.binding_id);
@@ -204,7 +211,7 @@ export function appendWorkspaceEvent(
     record_sha256: stableDigest(basis),
   };
   const line = `${canonicalJson(record)}\n`;
-  if (Buffer.byteLength(line) > EVENT_LIMIT)
+  if (Buffer.byteLength(line) > WORKSPACE_EVENT_BYTES)
     throw new Error("workspace provider event is too large");
   const fd = openSync(path, "a", 0o600);
   try {
@@ -232,7 +239,7 @@ export function readWorkspaceEvents(
     .split("\n")
     .filter(Boolean)
     .map((line, index) => {
-      if (Buffer.byteLength(line) > EVENT_LIMIT) {
+      if (Buffer.byteLength(line) > WORKSPACE_EVENT_BYTES) {
         throw new Error(`workspace event ${index + 1} is too large`);
       }
       let record: WorkspaceProviderEvent;
@@ -270,33 +277,6 @@ function recordsDigestPlaceholder(): null {
   return null;
 }
 
-export function appendWorkflowJournalEvent(
-  coordRoot: string,
-  runId: string,
-  event: string,
-  data: Record<string, unknown>,
-): void {
-  const path = join(workflowRunDir(coordRoot, runId), "journal.jsonl");
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  const existed = existsSync(path);
-  const line = `${JSON.stringify({
-    schema_version: 1,
-    run_id: runId,
-    ts: new Date().toISOString(),
-    event,
-    ...data,
-  })}\n`;
-  if (Buffer.byteLength(line) > EVENT_LIMIT) throw new Error("workflow journal event is too large");
-  const fd = openSync(path, "a", 0o600);
-  try {
-    writeFileSync(fd, line, "utf8");
-    fsyncSync(fd);
-  } finally {
-    closeSync(fd);
-  }
-  if (!existed) fsyncParentDirectory(path);
-}
-
 export type WorkflowSupplement =
   | WorkspaceBinding
   | IntegrationReviewRecord
@@ -327,7 +307,7 @@ export function appendCleanupAttempt(
     record_sha256: stableDigest(basis),
   };
   const line = `${canonicalJson(attempt)}\n`;
-  if (Buffer.byteLength(line) > EVENT_LIMIT) {
+  if (Buffer.byteLength(line) > WORKSPACE_EVENT_BYTES) {
     throw new Error("workspace cleanup attempt is too large");
   }
   const fd = openSync(path, "a", 0o600);
@@ -388,7 +368,7 @@ function appendChainedRecord(
   label: string,
 ): void {
   const line = `${canonicalJson(record)}\n`;
-  if (Buffer.byteLength(line) > EVENT_LIMIT) {
+  if (Buffer.byteLength(line) > WORKSPACE_EVENT_BYTES) {
     throw new Error(`${label} is too large`);
   }
   const fd = openSync(path, "a", 0o600);

package/src/lib/browser/client.ts

@@ -295,6 +295,135 @@ export class Browser {
     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<T = unknown>(
+    path: string,
+    evaluation: string,
+    opts: { fullPage?: boolean } = {},
+  ): Promise<{
+    bytes: number;
+    evaluation: T;
+    viewport: { width: number; height: number };
+    evidence: {
+      converged: boolean;
+      reason: string;
+      passes: number;
+      max_passes: number;
+      max_dimension: number;
+      max_pixels: number;
+      original_viewport: { width: number; height: number };
+      evaluated_viewport: { width: number; height: number };
+      document_extent_before_evaluation: { width: number; height: number };
+      document_extent_after_evaluation: { width: number; height: number };
+      document_extent_after_screenshot: { width: number; height: number };
+      screenshot: { width: number; height: number; bytes: number };
+    };
+  }> {
+    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<T>(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/src/lib/exec.ts

@@ -13,6 +13,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 {
@@ -46,7 +50,11 @@ export function exec(cmd: string[], opts: ExecOpts = {}): Promise<ExecResult> {
     proc.stderr?.on("data", (d: Buffer) => 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: number, errOverride?: string): void => {
       clearTimeout(timer);
@@ -57,6 +65,7 @@ export function exec(cmd: string[], opts: ExecOpts = {}): Promise<ExecResult> {
         stdout: shouldTrim ? stdout.trim() : stdout.replace(/\n$/, ""),
         stderr: shouldTrim ? stderr.trim() : stderr.replace(/\n$/, ""),
         exitCode,
+        ...(timedOut ? { timedOut: true } : {}),
       });
     };