harnery 0.38.0 → 0.40.0

package/src/core/workflow/admission.ts

@@ -1,5 +1,6 @@
-import { buildDiagnosticAdvice } from "../diagnostics/advice.ts";
+import { buildDiagnosticAdvice, unknownPressureAssessment } from "../diagnostics/advice.ts";
 import type { DiagnosticAdvice } from "../diagnostics/contract.ts";
+import { type PublishedPressure, readPublishedPressure } from "../resources/status.ts";
 import {
   type EnsureSupervisorResult,
   ensureSupervisorRunning,
@@ -25,6 +26,8 @@ export interface WorkflowDiagnosticAdmissionRuntime {
   ensureSupervisor: (coordRoot: string) => Promise<EnsureSupervisorResult>;
   readStatus: (coordRoot: string, nowMs?: number) => SupervisorStatus;
   readFindings: (coordRoot: string) => SupervisorFindings | undefined;
+  /** The observer's published assessment. Admission never computes one itself. */
+  readPressure: (coordRoot: string, nowMs?: number) => PublishedPressure;
 }
 
 export interface ObserveWorkflowDiagnosticAdmissionInput {
@@ -77,6 +80,7 @@ export async function observeWorkflowDiagnosticAdmission(
           );
         }
         const observedAt = runtime.now().toISOString();
+        const published = runtime.readPressure(input.coordRoot, runtime.now().getTime());
         return {
           requested_at: requestedAt,
           observed_at: observedAt,
@@ -85,8 +89,12 @@ export async function observeWorkflowDiagnosticAdmission(
           freshness: "fresh",
           sampled_at: sampledAt,
           advice: buildDiagnosticAdvice({
-            findings: mergeFindings(report),
-            sourceCapability: supportedCapability(),
+            assessment: published.assessment,
+            priorHysteresis: published.prior_hysteresis,
+            sourceCapability: published.capability,
+            activeFindingCount: mergeFindings(report).filter(
+              (finding) => finding.state === "opened",
+            ).length,
             evaluatedAt: observedAt,
           }),
         };
@@ -139,14 +147,29 @@ export function failedWorkflowDiagnosticAdmissionObservation(
     wait_ms: Math.max(0, observedAt.getTime() - requestedAt.getTime()),
     service_state: "unavailable",
     freshness: "unavailable",
-    advice: buildDiagnosticAdvice({
-      findings: [],
-      sourceCapability: capability,
-      evaluatedAt: observedAt.toISOString(),
-    }),
+    advice: unavailableAdvice(capability, observedAt.toISOString()),
   };
 }
 
+/**
+ * Shadow admission records what the observer published. When it published
+ * nothing, the record carries `unknown` with the gap stated, never a state the
+ * observer did not measure. Either way no value reaches a dispatch decision.
+ */
+function unavailableAdvice(capability: SupervisorCapability, observedAt: string): DiagnosticAdvice {
+  return buildDiagnosticAdvice({
+    assessment: unknownPressureAssessment({
+      observedAt,
+      reasonCode: "evidence_unavailable",
+      summary: `Local resource pressure cannot be determined because the assessment source is ${capability.state}${capability.reason_code ? ` (${capability.reason_code})` : ""}.`,
+    }),
+    priorHysteresis: null,
+    sourceCapability: capability,
+    activeFindingCount: 0,
+    evaluatedAt: observedAt,
+  });
+}
+
 function unavailableObservation(
   runtime: WorkflowDiagnosticAdmissionRuntime,
   requestedAt: string,
@@ -163,11 +186,7 @@ function unavailableObservation(
     reason_code: reasonCode,
     ...(detail ? { detail: detail.slice(0, 500) } : {}),
   };
-  const advice: DiagnosticAdvice = buildDiagnosticAdvice({
-    findings: [],
-    sourceCapability: capability,
-    evaluatedAt: observedAt,
-  });
+  const advice: DiagnosticAdvice = unavailableAdvice(capability, observedAt);
   return {
     requested_at: requestedAt,
     observed_at: observedAt,
@@ -185,10 +204,6 @@ function mergeFindings(report: SupervisorFindings): SupervisorFinding[] {
   return [...byId.values()];
 }
 
-function supportedCapability(): SupervisorCapability {
-  return { source_kind: "supervisor.findings", state: "supported" };
-}
-
 function normalizeWait(value: number | undefined): number {
   if (value === undefined) return DEFAULT_FRESH_CYCLE_WAIT_MS;
   if (!Number.isFinite(value) || value < 0) return DEFAULT_FRESH_CYCLE_WAIT_MS;
@@ -210,6 +225,7 @@ function admissionRuntime(
     ensureSupervisor: ensureSupervisorRunning,
     readStatus: readSupervisorStatus,
     readFindings: readSupervisorFindings,
+    readPressure: readPublishedPressure,
     ...overrides,
   };
 }

package/src/core/workflow/engine.ts

@@ -652,8 +652,8 @@ async function executeWorkflow(
         observation,
       });
       log(
-        `[admission] shadow pressure=${observation.advice.pressure} ` +
-          `recommendation=${observation.advice.fan_out_recommendation}; dispatch unchanged`,
+        `[admission] shadow pressure=${observation.advice.assessment.state} ` +
+          `action=${observation.advice.assessment.recommended_action}; dispatch unchanged`,
       );
     })();
     await diagnosticAdmissionPromise;

package/src/core/workflow/live-session-v3.ts

@@ -8,6 +8,8 @@ import {
 } from "../agents/state/heartbeat-writer.ts";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
 import { ensureLiveCoordinationHeartbeat } from "../agents/state/live-coordination-writer.ts";
+import { assignName } from "../agents/state/names.ts";
+import { coordFreshnessSeconds } from "../config.ts";
 import { ensureEventLedgerV3 } from "../events/v3/bootstrap.ts";
 import {
   recordLiveHookSignalV3,
@@ -58,6 +60,9 @@ export function startWorkflowChildSessionV3(input: WorkflowChildSessionV3Input):
     input.model,
   );
   if (!cache) throw new Error("workflow_child_v3_cache_missing");
+  const name = assignName(input.coordRoot, input.instanceId, "workflow-child", {
+    freshnessSecs: coordFreshnessSeconds(input.coordRoot),
+  });
   if (input.label) {
     recordLiveTaskChangeV3({
       coordRoot: input.coordRoot,
@@ -67,14 +72,7 @@ export function startWorkflowChildSessionV3(input: WorkflowChildSessionV3Input):
       task: input.label,
     });
   }
-  if (
-    !setIdentityCache(
-      input.coordRoot,
-      input.instanceId,
-      input.label ?? input.agentId,
-      input.agentId,
-    )
-  ) {
+  if (!setIdentityCache(input.coordRoot, input.instanceId, name, input.agentId)) {
     throw new Error("workflow_child_v3_identity_cache_failed");
   }
   const projected = readLiveCoordinationRow(input.coordRoot, input.instanceId);

package/src/core/workflow/proof.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import type { RepoSnapshot } from "../context/index.ts";
+import { DIAGNOSTIC_ADVICE_SCHEMA_VERSION } from "../diagnostics/contract.ts";
 import type {
   NormalizedPolicy,
   PolicyDecision,
@@ -445,7 +446,7 @@ function validDiagnosticAdmissionProof(
     ["running", "started", "unavailable"].includes(observation.service_state) &&
     ["fresh", "unavailable"].includes(observation.freshness) &&
     (observation.sampled_at === undefined || validTimestamp(observation.sampled_at)) &&
-    observation.advice?.schema_version === 1 &&
+    observation.advice?.schema_version === DIAGNOSTIC_ADVICE_SCHEMA_VERSION &&
     observation.advice.observer_only === true
   );
 }
@@ -506,8 +507,8 @@ export function renderWorkflowProof(proof: WorkflowProof): string {
     const observation = proof.diagnostic_admission.observation;
     lines.push(
       observation
-        ? `admission: shadow ${observation.advice.pressure}; ` +
-            `${observation.advice.fan_out_recommendation}; action none`
+        ? `admission: shadow ${observation.advice.assessment.state}; ` +
+            `${observation.advice.assessment.recommended_action}; action none`
         : "admission: shadow not needed; no real child dispatch",
     );
   }

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

@@ -96,3 +96,26 @@ export function stitchPngRows(pieces: readonly Buffer[]): Buffer {
 export function pngDimensions(buffer: Buffer): { width: number; height: number } {
   return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
 }
+
+/** Crop already decoded native pixels; callers reuse one decode across all selected rectangles. */
+export function cropNativePng(
+  png: PNG,
+  rect: { x: number; y: number; width: number; height: number },
+): Buffer {
+  if (
+    ![rect.x, rect.y, rect.width, rect.height].every(Number.isSafeInteger) ||
+    rect.x < 0 ||
+    rect.y < 0 ||
+    rect.width <= 0 ||
+    rect.height <= 0 ||
+    rect.x + rect.width > png.width ||
+    rect.y + rect.height > png.height
+  )
+    throw new Error("Native capture rectangle lies outside the image.");
+  const out = new PNG({ width: rect.width, height: rect.height });
+  for (let y = 0; y < rect.height; y++) {
+    const start = ((rect.y + y) * png.width + rect.x) * 4;
+    png.data.copy(out.data, y * rect.width * 4, start, start + rect.width * 4);
+  }
+  return PNG.sync.write(out);
+}

package/src/lib/browser/client.ts

@@ -625,6 +625,31 @@ export class Browser {
     return await this.currentPage.screenshot({ type: "png", fullPage: true });
   }
 
+  /** Wait for font-driven DOM/layout initialization, with a bounded convergence check. */
+  async waitForReviewReady(timeoutMs = 15_000): Promise<void> {
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000)
+      throw new RangeError("waitForReviewReady timeoutMs must be an integer from 1 to 60000");
+    const settled = await this.currentPage.evaluate(async (timeoutMs) => {
+      await document.fonts.ready;
+      const deadline = performance.now() + timeoutMs;
+      let previous = "";
+      let consecutive = 0;
+      while (performance.now() < deadline) {
+        await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+        const geometry = `${document.documentElement.scrollWidth},${document.documentElement.scrollHeight},${document.body?.scrollWidth},${document.body?.scrollHeight}`;
+        const current = geometry + document.documentElement.outerHTML;
+        consecutive = current === previous ? consecutive + 1 : 0;
+        if (consecutive >= 8) return true;
+        previous = current;
+      }
+      return false;
+    }, timeoutMs);
+    if (!settled)
+      throw new Error(
+        "Page review source or layout did not settle; rerun when page initialization completes.",
+      );
+  }
+
   /** Base64 PNG of a document-space clip rect. Used to capture one critique tile. */
   async screenshotClipBase64(rect: {
     x: number;
@@ -670,12 +695,22 @@ export class Browser {
     width: number;
     height: number;
   }): Promise<Buffer> {
+    const [image] = await this.captureRegionsByScroll([rect]);
+    return image;
+  }
+
+  /** Capture a document-ordered group with one pinned-element inventory and restore. */
+  async captureRegionsByScroll(
+    rects: Array<{ x: number; y: number; width: number; height: number }>,
+  ): Promise<Buffer[]> {
+    if (!rects.length) return [];
     const page = this.currentPage;
-    if (!(rect.width > 0) || !(rect.height > 0)) {
-      throw new Error(
-        `captureRegionByScroll: rect must have a positive size (got ${rect.width}×${rect.height})`,
-      );
-    }
+    for (const rect of rects)
+      if (!(rect.width > 0) || !(rect.height > 0)) {
+        throw new Error(
+          `captureRegionByScroll: rect must have a positive size (got ${rect.width}×${rect.height})`,
+        );
+      }
     const settle = (top: number) =>
       page.evaluate(async (target: number) => {
         window.scrollTo({ left: window.scrollX, top: target, behavior: "instant" });
@@ -695,7 +730,7 @@ export class Browser {
         };
       }, top);
     const original = await page.evaluate(() => ({ x: window.scrollX, y: window.scrollY }));
-    const pieces: Buffer[] = [];
+    const captures: Buffer[] = [];
     // Viewport-pinned candidates, measured at scroll 0 so each later capture
     // can tell "still where the full page shows it" from "riding along".
     await settle(0);
@@ -713,10 +748,19 @@ export class Browser {
         priorTransition: string;
         priorTransitionPriority: string;
       }> = [];
-      const all = document.querySelectorAll<HTMLElement>("body *");
-      const limit = Math.min(all.length, 20_000);
-      for (let i = 0; i < limit; i++) {
-        const el = all[i] as HTMLElement;
+      // Fixed controls can live inside a static shadow host. Walk open roots
+      // without hiding their ordinary content or exceeding the total node cap.
+      const walkers = [document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT)];
+      let visited = 0;
+      while (walkers.length && visited < 20_000) {
+        const el = walkers[walkers.length - 1].nextNode() as HTMLElement | null;
+        if (!el) {
+          walkers.pop();
+          continue;
+        }
+        visited++;
+        if (el.shadowRoot)
+          walkers.push(document.createTreeWalker(el.shadowRoot, NodeFilter.SHOW_ELEMENT));
         const position = getComputedStyle(el).position;
         if (position !== "fixed" && position !== "sticky") continue;
         out.push({
@@ -735,7 +779,11 @@ export class Browser {
         async ([entries, action]) => {
           for (const entry of entries) {
             const restore = () => {
+              // Restore opacity while transitions are still disabled. Restoring both
+              // declarations in one style flush starts a new fade from zero.
+              entry.el.style.setProperty("transition", "none", "important");
               entry.el.style.setProperty("opacity", entry.priorOpacity, entry.priorOpacityPriority);
+              void getComputedStyle(entry.el).opacity;
               entry.el.style.setProperty(
                 "transition",
                 entry.priorTransition,
@@ -760,41 +808,45 @@ export class Browser {
         [pinned, mode] as const,
       );
     try {
-      const bottom = rect.y + rect.height;
-      let cursor = rect.y;
-      let first = true;
-      while (cursor < bottom) {
-        const remaining = bottom - cursor;
-        // Top-align the piece; a final partial piece is then re-anchored to
-        // the viewport bottom once the viewport height is known.
-        let view = await settle(cursor);
-        if (!first && remaining < view.innerHeight) {
-          view = await settle(Math.max(0, bottom - view.innerHeight));
-        }
-        await syncPinned("hide-moved");
-        const offset = cursor - view.scrollY;
-        if (offset < 0 || offset >= view.innerHeight) {
-          throw new Error(
-            `captureRegionByScroll: document y ${cursor} is not reachable in the viewport ` +
-              `(scrollY ${view.scrollY}, innerHeight ${view.innerHeight})`,
-          );
-        }
-        const pieceHeight = Math.min(remaining, view.innerHeight - offset);
-        const clipX = Math.max(0, rect.x - view.scrollX);
-        const clipWidth = Math.min(rect.width, view.innerWidth - clipX);
-        if (!(clipWidth > 0)) {
-          throw new Error(
-            `captureRegionByScroll: document x ${rect.x} is outside the viewport (innerWidth ${view.innerWidth})`,
+      for (const rect of rects) {
+        const pieces: Buffer[] = [];
+        const bottom = rect.y + rect.height;
+        let cursor = rect.y;
+        let first = true;
+        while (cursor < bottom) {
+          const remaining = bottom - cursor;
+          // Top-align the piece; a final partial piece is then re-anchored to
+          // the viewport bottom once the viewport height is known.
+          let view = await settle(cursor);
+          if (!first && remaining < view.innerHeight) {
+            view = await settle(Math.max(0, bottom - view.innerHeight));
+          }
+          await syncPinned("hide-moved");
+          const offset = cursor - view.scrollY;
+          if (offset < 0 || offset >= view.innerHeight) {
+            throw new Error(
+              `captureRegionByScroll: document y ${cursor} is not reachable in the viewport ` +
+                `(scrollY ${view.scrollY}, innerHeight ${view.innerHeight})`,
+            );
+          }
+          const pieceHeight = Math.min(remaining, view.innerHeight - offset);
+          const clipX = Math.max(0, rect.x - view.scrollX);
+          const clipWidth = Math.min(rect.width, view.innerWidth - clipX);
+          if (!(clipWidth > 0)) {
+            throw new Error(
+              `captureRegionByScroll: document x ${rect.x} is outside the viewport (innerWidth ${view.innerWidth})`,
+            );
+          }
+          pieces.push(
+            await page.screenshot({
+              type: "png",
+              clip: { x: clipX, y: offset, width: clipWidth, height: pieceHeight },
+            }),
           );
+          cursor += pieceHeight;
+          first = false;
         }
-        pieces.push(
-          await page.screenshot({
-            type: "png",
-            clip: { x: clipX, y: offset, width: clipWidth, height: pieceHeight },
-          }),
-        );
-        cursor += pieceHeight;
-        first = false;
+        captures.push(stitchPngRows(pieces));
       }
     } finally {
       try {
@@ -808,7 +860,7 @@ export class Browser {
         );
       }
     }
-    return stitchPngRows(pieces);
+    return captures;
   }
 
   /** Document-space rects + labels for each element matching `selector` (semantic tiling). */

package/src/lib/browser/index.ts

@@ -86,6 +86,20 @@ export {
   serializeNetscapeCookies,
   writeNetscapeCookieFile,
 } from "./netscape-cookies.js";
+export type {
+  PageReviewBudgetCoverage,
+  PageReviewCandidate,
+  PageReviewCapturePlan,
+  PageReviewContextAllocation,
+  PageReviewDecisionSlot,
+  PageReviewDurableDecision,
+  PageReviewEvidenceContext,
+  PageReviewNativeEvidence,
+  PageReviewNativeTile,
+  PageReviewRect,
+  PageReviewTileBudgetAllocation,
+} from "./page-review-contracts.js";
+export { nativePixelDigest } from "./page-review-evidence.js";
 export {
   type JudgedContext,
   type JudgePageReviewPackOptions,
@@ -112,8 +126,8 @@ export {
   packPaths,
   readPackContext,
   readPackDom,
-  readPackFullPage,
   readPackManifest,
+  readPackOverview,
   readPackSignature,
   readPackTiles,
   renderReviewMarkdown,