harnery 0.32.0 → 0.34.0

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

@@ -0,0 +1,126 @@
+import type { Adapter } from "../adapter.ts";
+import { recordLiveTaskChangeV3 } from "../agents/live-authority-v3.ts";
+import { endSessionExplicitV3 } from "../agents/session-finalizer-v3.ts";
+import {
+  clearCoordinationCache,
+  type Heartbeat,
+  setIdentityCache,
+} from "../agents/state/heartbeat-writer.ts";
+import {
+  ensureLiveCoordinationHeartbeat,
+  readLiveCoordinationRow,
+} from "../agents/state/live-coordination-view.ts";
+import { ensureEventLedgerV3 } from "../events/v3/bootstrap.ts";
+import {
+  recordLiveHookSignalV3,
+  resolveLiveEventLedgerRouteV3,
+} from "../events/v3/live-routing.ts";
+import { stableScopeId } from "./scope-id.ts";
+
+export interface WorkflowChildSessionV3Input {
+  coordRoot: string;
+  instanceId: string;
+  runId: string;
+  agentId: string;
+  sessionId?: string;
+  adapter?: string;
+  label?: string;
+  model?: string;
+}
+
+/** Start a headless workflow child through the same canonical V3 producer as native hooks. */
+export function startWorkflowChildSessionV3(input: WorkflowChildSessionV3Input): Heartbeat {
+  const adapter = workflowAdapter(input.adapter);
+  const sessionId = input.sessionId ?? input.instanceId;
+  const route = requireV3Route(input.coordRoot);
+  const result = recordLiveHookSignalV3({
+    coordRoot: input.coordRoot,
+    route,
+    eventName: "session-start",
+    adapter,
+    instanceId: input.instanceId,
+    run_id: stableScopeId("run", input.runId),
+    workflow_id: stableScopeId("wf", input.runId),
+    workflow_agent_id: input.agentId,
+    payload: {
+      session_id: sessionId,
+      model: input.model,
+      source: "workflow-engine",
+      raw: {},
+    },
+  });
+  if (result.state !== "recorded" && result.state !== "already_started") {
+    throw new Error(`workflow_child_v3_start_failed:${result.state}`);
+  }
+  const cache = ensureLiveCoordinationHeartbeat(
+    input.coordRoot,
+    input.instanceId,
+    sessionId,
+    adapter,
+    input.model,
+  );
+  if (!cache) throw new Error("workflow_child_v3_cache_missing");
+  if (input.label) {
+    recordLiveTaskChangeV3({
+      coordRoot: input.coordRoot,
+      owner: input.instanceId,
+      nativeSessionId: sessionId,
+      adapter,
+      task: input.label,
+    });
+  }
+  if (
+    !setIdentityCache(
+      input.coordRoot,
+      input.instanceId,
+      input.label ?? input.agentId,
+      input.agentId,
+    )
+  ) {
+    throw new Error("workflow_child_v3_identity_cache_failed");
+  }
+  const projected = readLiveCoordinationRow(input.coordRoot, input.instanceId);
+  if (!projected) throw new Error("workflow_child_v3_projection_missing");
+  return projected;
+}
+
+/** Record the authoritative terminal before removing the disposable coordination cache. */
+export function endWorkflowChildSessionV3(
+  input: WorkflowChildSessionV3Input & { cleanExit: boolean },
+): void {
+  requireV3Route(input.coordRoot);
+  const row = readLiveCoordinationRow(input.coordRoot, input.instanceId);
+  if (!row?.v3_instance_id || !row.v3_generation_id) {
+    throw new Error("workflow_child_v3_generation_missing");
+  }
+  const result = endSessionExplicitV3({
+    coordRoot: input.coordRoot,
+    instance_id: row.v3_instance_id,
+    generation_id: row.v3_generation_id,
+    coordination_finalized: true,
+    outcome: input.cleanExit ? "succeeded" : "failed",
+  });
+  if (result.state !== "recorded" && result.state !== "already_ended") {
+    throw new Error(
+      `workflow_child_v3_end_failed:${result.state}${"reason" in result ? `:${result.reason}` : ""}`,
+    );
+  }
+  clearCoordinationCache(input.coordRoot, input.instanceId);
+}
+
+function requireV3Route(coordRoot: string) {
+  let route = resolveLiveEventLedgerRouteV3(coordRoot);
+  if (route.state === "blocked" && route.reason === "v3_not_initialized") {
+    ensureEventLedgerV3(coordRoot, "harnery-workflow-v3-universal");
+    route = resolveLiveEventLedgerRouteV3(coordRoot);
+  }
+  if (route.state === "blocked") throw new Error(`workflow_child_v3_gate:${route.reason}`);
+  return route;
+}
+
+function workflowAdapter(adapter: string | undefined): Adapter {
+  if (adapter === "codex" || adapter === "cursor" || adapter === "claude-code") return adapter;
+  return "claude-code";
+}
+
+export { stableScopeId } from "./scope-id.ts";

package/src/core/workflow/scope-id.ts

@@ -0,0 +1,6 @@
+import { createHash } from "node:crypto";
+
+/** Stable opaque scope identity for a workflow run. Pure and safe for read-only consumers. */
+export function stableScopeId<P extends "run" | "wf">(prefix: P, value: string): `${P}_${string}` {
+  return `${prefix}_${createHash("sha256").update(value.normalize("NFC")).digest("hex")}`;
+}

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

@@ -18,6 +18,7 @@ import { hostname } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 
 const MAX_LEASE_BYTES = 8 * 1024;
+const MAX_CONTENTION_OBSERVATION_ATTEMPTS = 8;
 const SAFE_COMPONENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
 
 export interface NoClobberLeaseOwner {
@@ -49,6 +50,10 @@ export interface AcquireNoClobberLeaseInput {
   now?: () => number;
   pid?: number;
   host?: string;
+  /** Fault-injection hook immediately before the lease directory is created. */
+  onLeaseDirectoryCreate?: () => void;
+  /** Fault-injection hook after contention is observed and before owner inspection. */
+  onContention?: () => void;
   onRecoveryStep?: (step: LeaseRecoveryStep) => void;
 }
 
@@ -74,7 +79,7 @@ interface RecoveryClaim {
 export function acquireNoClobberLease(input: AcquireNoClobberLeaseInput): NoClobberLease {
   validateInput(input);
   const leaseDir = resolve(input.path);
-  ensureLeaseDirectory(leaseDir);
+  ensureLeaseDirectory(leaseDir, input.onLeaseDirectoryCreate);
 
   const now = input.now ?? Date.now;
   const created = now();
@@ -105,20 +110,32 @@ export function acquireNoClobberLease(input: AcquireNoClobberLeaseInput): NoClob
       reclaimAbandonedRecovery(leaseDir, recoveryPath, input, now());
     }
 
-    try {
-      linkSync(ownerPath, currentPath);
-      fsyncDirectory(leaseDir);
-      assertExactOwner(currentPath, ownerPath, ownerBytes, owner);
-      if (existsSync(recoveryPath)) {
-        unlinkExactCurrent(currentPath, ownerPath);
-        throw new Error(`lease ${input.scope} recovery is already in progress`);
+    let observed: ReturnType<typeof readOwner> | undefined;
+    for (let attempt = 0; attempt < MAX_CONTENTION_OBSERVATION_ATTEMPTS; attempt += 1) {
+      try {
+        linkSync(ownerPath, currentPath);
+        fsyncDirectory(leaseDir);
+        assertExactOwner(currentPath, ownerPath, ownerBytes, owner);
+        if (existsSync(recoveryPath)) {
+          unlinkExactCurrent(currentPath, ownerPath);
+          throw new Error(`lease ${input.scope} recovery is already in progress`);
+        }
+        return leaseHandle(leaseDir, ownerPath, ownerBytes, owner);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
       }
-      return leaseHandle(leaseDir, ownerPath, ownerBytes, owner);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-    }
 
-    const observed = readOwner(currentPath);
+      input.onContention?.();
+      try {
+        observed = readOwner(currentPath);
+        break;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      }
+    }
+    if (observed === undefined) {
+      throw new Error(`lease ${input.scope} changed repeatedly during contention`);
+    }
     if (leaseIsLive(observed.owner, now(), input.staleAfterMs)) {
       throw new Error(`lease ${input.scope} is held by a live or unexpired owner`);
     }
@@ -184,13 +201,20 @@ function validateInput(input: AcquireNoClobberLeaseInput): void {
   }
 }
 
-function ensureLeaseDirectory(leaseDir: string): void {
+function ensureLeaseDirectory(leaseDir: string, onCreate?: () => void): void {
   mkdirSync(dirname(leaseDir), { recursive: true, mode: 0o700 });
-  if (existsSync(leaseDir) && !lstatSync(leaseDir).isDirectory()) {
+  let created = false;
+  onCreate?.();
+  try {
+    mkdirSync(leaseDir, { mode: 0o700 });
+    created = true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+  if (!lstatSync(leaseDir).isDirectory()) {
     throw new Error(`lease path is not a directory: ${leaseDir}`);
   }
-  if (!existsSync(leaseDir)) {
-    mkdirSync(leaseDir, { mode: 0o700 });
+  if (created) {
     fsyncDirectory(dirname(leaseDir));
   }
 }
@@ -377,10 +401,23 @@ function readOwner(path: string): { owner: NoClobberLeaseOwner; bytes: string }
     if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("lease owner is not a plain file");
     size = stat.size;
   } catch (error) {
-    throw new Error(`lease owner cannot be inspected: ${(error as Error).message}`);
+    const inspectionError = new Error(
+      `lease owner cannot be inspected: ${(error as Error).message}`,
+    ) as NodeJS.ErrnoException;
+    inspectionError.code = (error as NodeJS.ErrnoException).code;
+    throw inspectionError;
   }
   if (size <= 0 || size > MAX_LEASE_BYTES) throw new Error("lease owner bytes are invalid");
-  const bytes = readFileSync(path, "utf8");
+  let bytes: string;
+  try {
+    bytes = readFileSync(path, "utf8");
+  } catch (error) {
+    const inspectionError = new Error(
+      `lease owner cannot be read: ${(error as Error).message}`,
+    ) as NodeJS.ErrnoException;
+    inspectionError.code = (error as NodeJS.ErrnoException).code;
+    throw inspectionError;
+  }
   let value: unknown;
   try {
     value = JSON.parse(bytes);

package/src/index.ts

@@ -5,7 +5,7 @@
  * Examples of intended consumption:
  *   import { createHarneryProgram } from 'harnery';     // CLI composition
  *   import { evaluateClaim } from 'harnery/core/agents'; // verdict rule directly
- *   import type { Heartbeat } from 'harnery/core/agents'; // schema types
+ *   import type { EventV3 } from 'harnery/core/events/v3'; // canonical schema types
  *
  * Heavy modules (web UI, hook scripts) are not re-exported from here; they're
  * reachable via their own subpath entries in package.json#exports.

package/src/lib/browser/client.ts

@@ -626,6 +626,236 @@ export class Browser {
     }, selector);
   }
 
+  /**
+   * Extract the page's visual atoms for content-aware tiling (tiling.ts):
+   * text line boxes (one per rendered line, so a cut between the lines of a
+   * paragraph is legal), replaced/intrinsically-visual elements, and small
+   * bordered boxes (cards, callouts — height-capped so section wrappers
+   * don't count). Coordinates are document-space CSS px.
+   */
+  async visualAtoms(): Promise<
+    Array<{ kind: "text-line" | "replaced" | "box"; top: number; bottom: number }>
+  > {
+    return await this.currentPage.evaluate(() => {
+      const atoms: Array<{ kind: "text-line" | "replaced" | "box"; top: number; bottom: number }> =
+        [];
+      const sy = window.scrollY;
+
+      const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+      let node: Node | null = walker.nextNode();
+      while (node) {
+        if (node.textContent && node.textContent.trim().length > 0) {
+          const range = document.createRange();
+          range.selectNodeContents(node);
+          for (const r of Array.from(range.getClientRects())) {
+            if (r.height > 0 && r.width > 0) {
+              atoms.push({ kind: "text-line", top: r.top + sy, bottom: r.bottom + sy });
+            }
+          }
+        }
+        node = walker.nextNode();
+      }
+
+      for (const el of Array.from(
+        document.querySelectorAll("img, svg, canvas, video, input, button, select, textarea, hr"),
+      )) {
+        // Children of an inline <svg> are covered by the root svg's rect.
+        if (el instanceof SVGElement && el.ownerSVGElement) continue;
+        const r = el.getBoundingClientRect();
+        if (r.height > 0 && r.width > 0) {
+          atoms.push({ kind: "replaced", top: r.top + sy, bottom: r.bottom + sy });
+        }
+      }
+
+      for (const el of Array.from(document.body.querySelectorAll("*"))) {
+        if (el instanceof SVGElement) continue;
+        const cs = getComputedStyle(el);
+        const hasEdge =
+          (Number.parseFloat(cs.borderTopWidth) > 0 && cs.borderTopStyle !== "none") ||
+          Number.parseFloat(cs.borderRadius) > 0;
+        if (!hasEdge) continue;
+        const r = el.getBoundingClientRect();
+        if (r.height > 0 && r.height <= 600 && r.width > 0) {
+          atoms.push({ kind: "box", top: r.top + sy, bottom: r.bottom + sy });
+        }
+      }
+
+      return atoms;
+    });
+  }
+
+  /**
+   * Capture the page's QA signature for diff-aware classification
+   * (qa-plan.ts): a structural fingerprint per element (path, tag, canonical
+   * attributes, direct-text digest, nearest stable-ancestor anchor) plus
+   * applied-stylesheet digests. DOM equality alone never proves a change is
+   * text-only — a one-line edit to a linked stylesheet changes zero DOM bytes
+   * and every pixel — so external sheet text is fetched and digested too; an
+   * unreadable sheet records digest "unavailable" and the classifier widens.
+   */
+  async qaSignature(): Promise<{
+    nodes: Array<{
+      path: string;
+      tag: string;
+      attrs: string;
+      text?: string;
+      visual?: string;
+      anchor?: { selector: string; path: string };
+    }>;
+    stylesheets: Array<{ key: string; kind: "external" | "inline"; digest: string }>;
+    domHtml: string;
+    truncated: boolean;
+  }> {
+    return await this.currentPage.evaluate(async () => {
+      const MAX_NODES = 20_000;
+      const fnv = (text: string): string => {
+        let hash = 0x811c9dc5;
+        for (let i = 0; i < text.length; i++) {
+          hash ^= text.charCodeAt(i);
+          hash = Math.imul(hash, 0x01000193);
+        }
+        return `${(hash >>> 0).toString(16).padStart(8, "0")}-${text.length}`;
+      };
+
+      // Anchor uniqueness prepass: an id or data-qa-scope value that appears
+      // more than once is not a stable anchor.
+      const idCount = new Map<string, number>();
+      for (const el of Array.from(document.querySelectorAll("[id]"))) {
+        idCount.set(el.id, (idCount.get(el.id) ?? 0) + 1);
+      }
+      const scopeCount = new Map<string, number>();
+      for (const el of Array.from(document.querySelectorAll("[data-qa-scope]"))) {
+        const v = el.getAttribute("data-qa-scope") ?? "";
+        scopeCount.set(v, (scopeCount.get(v) ?? 0) + 1);
+      }
+      const anchorFor = (el: Element): string | null => {
+        if (el.id && idCount.get(el.id) === 1) return `#${CSS.escape(el.id)}`;
+        const scope = el.getAttribute("data-qa-scope");
+        if (scope && scopeCount.get(scope) === 1) {
+          return `[data-qa-scope="${CSS.escape(scope)}"]`;
+        }
+        return null;
+      };
+
+      const SKIP = new Set(["SCRIPT", "NOSCRIPT", "TEMPLATE", "STYLE", "LINK", "META"]);
+      // Leaves whose subtree is fingerprinted as one opaque unit (mirrors the
+      // replaced-element treatment in visual atoms).
+      const LEAF = new Set(["SVG", "CANVAS", "VIDEO", "IFRAME", "OBJECT"]);
+      const nodes: Array<{
+        path: string;
+        tag: string;
+        attrs: string;
+        text?: string;
+        visual?: string;
+        anchor?: { selector: string; path: string };
+      }> = [];
+      let truncated = false;
+
+      const visit = (
+        el: Element,
+        path: string,
+        anchor: { selector: string; path: string } | undefined,
+      ): void => {
+        if (nodes.length >= MAX_NODES) {
+          truncated = true;
+          return;
+        }
+        const tag = el.tagName.toLowerCase();
+        const attrs = el
+          .getAttributeNames()
+          .sort()
+          .map((name) => `${name}=${el.getAttribute(name) ?? ""}`)
+          .join("\x1f");
+        const isLeaf = LEAF.has(el.tagName.toUpperCase());
+        let text: string | undefined;
+        let visual: string | undefined;
+        if (isLeaf) {
+          if (el instanceof HTMLCanvasElement) {
+            try {
+              visual = fnv(el.toDataURL("image/png"));
+            } catch {
+              visual = "unavailable";
+            }
+          } else {
+            visual = fnv(el.innerHTML);
+          }
+        } else {
+          let direct = "";
+          for (const child of Array.from(el.childNodes)) {
+            if (child.nodeType === Node.TEXT_NODE) direct += child.textContent ?? "";
+          }
+          const normalized = direct.replace(/\s+/g, " ").trim();
+          if (normalized) text = fnv(normalized);
+        }
+        nodes.push({
+          path,
+          tag,
+          attrs,
+          ...(text !== undefined ? { text } : {}),
+          ...(visual !== undefined ? { visual } : {}),
+          ...(anchor ? { anchor } : {}),
+        });
+        if (isLeaf) return;
+        const own = anchorFor(el);
+        const childAnchor = own ? { selector: own, path } : anchor;
+        let index = 0;
+        for (const child of Array.from(el.children)) {
+          if (SKIP.has(child.tagName.toUpperCase())) continue;
+          visit(child, `${path}>${child.tagName.toLowerCase()}:${index}`, childAnchor);
+          index++;
+        }
+      };
+      if (document.body) visit(document.body, "body", undefined);
+
+      const stylesheets: Array<{ key: string; kind: "external" | "inline"; digest: string }> = [];
+      let inlineIdx = 0;
+      for (const sheet of Array.from(document.styleSheets)) {
+        const href = sheet.href;
+        const key = href ?? `inline:${inlineIdx}`;
+        if (!href) inlineIdx++;
+        let digest = "unavailable";
+        try {
+          digest = fnv(
+            Array.from(sheet.cssRules)
+              .map((rule) => rule.cssText)
+              .join("\n"),
+          );
+        } catch {
+          // Cross-origin: cssRules throws. Fetch the sheet text instead; a
+          // CORS-blocked fetch leaves the digest "unavailable" on purpose.
+          if (href) {
+            try {
+              const res = await fetch(href);
+              if (res.ok) digest = fnv(await res.text());
+            } catch {
+              /* stays unavailable */
+            }
+          }
+        }
+        stylesheets.push({ key, kind: href ? "external" : "inline", digest });
+      }
+      let adoptedIdx = 0;
+      for (const sheet of document.adoptedStyleSheets ?? []) {
+        try {
+          stylesheets.push({
+            key: `adopted:${adoptedIdx}`,
+            kind: "inline",
+            digest: fnv(
+              Array.from(sheet.cssRules)
+                .map((rule) => rule.cssText)
+                .join("\n"),
+            ),
+          });
+        } catch {
+          stylesheets.push({ key: `adopted:${adoptedIdx}`, kind: "inline", digest: "unavailable" });
+        }
+        adoptedIdx++;
+      }
+
+      return { nodes, stylesheets, domHtml: document.documentElement.outerHTML, truncated };
+    });
+  }
+
   /**
    * Capture a full-page screenshot from an explicit capture viewport and
    * evaluate the caller's final evidence expression immediately before the