harnery 0.30.0 → 0.31.0

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

@@ -10,7 +10,7 @@ import {
   sameFilesystemIdentity,
   validateConfiguredRoot,
 } from "./paths.ts";
-import { appendWorkflowJournalEvent, stableDigest, writeWorkspaceRequest } from "./state.ts";
+import { appendWorkflowTranscriptEvent, stableDigest, writeWorkspaceRequest } from "./state.ts";
 import type {
   WorkspaceAttestation,
   WorkspaceBinding,
@@ -72,7 +72,7 @@ export async function resolveWorkspaceBinding(input: {
       unknowns: [],
       receipts: {},
     };
-    appendWorkflowJournalEvent(input.opts.coordRoot, input.runId, "workspace.compatibility", {
+    appendWorkflowTranscriptEvent(input.opts.coordRoot, input.runId, "workspace.compatibility", {
       requested_isolation: fallback.requested_isolation,
       effective_isolation: fallback.effective_isolation,
       selection_reason: fallback.selection_reason,
@@ -114,7 +114,7 @@ export async function resolveWorkspaceBinding(input: {
       }
       throw new Error(`workflow run ${input.runId} could not reattach its frozen workspace`);
     }
-    appendWorkflowJournalEvent(input.opts.coordRoot, input.runId, "workspace.reattach", {
+    appendWorkflowTranscriptEvent(input.opts.coordRoot, input.runId, "workspace.reattach", {
       binding_id: frozenBinding.binding_id,
       provider_id: frozenBinding.provider.id,
       attestation_sha256: stableDigest(reattached),
@@ -180,7 +180,7 @@ export async function resolveWorkspaceBinding(input: {
         unknowns: [...probe.unknowns],
         receipts: {},
       };
-      appendWorkflowJournalEvent(input.opts.coordRoot, input.runId, "workspace.fallback", {
+      appendWorkflowTranscriptEvent(input.opts.coordRoot, input.runId, "workspace.fallback", {
         requested_isolation: fallback.requested_isolation,
         effective_isolation: fallback.effective_isolation,
         selection_reason: fallback.selection_reason,
@@ -226,7 +226,7 @@ export async function resolveWorkspaceBinding(input: {
     idempotency_key: stableDigest(requestWithoutKey),
   };
   writeWorkspaceRequest(input.opts.coordRoot, request);
-  appendWorkflowJournalEvent(input.opts.coordRoot, input.runId, "execution.allocate.start", {
+  appendWorkflowTranscriptEvent(input.opts.coordRoot, input.runId, "execution.allocate.start", {
     provider_id: probe.capabilities.provider_id,
     request_sha256: stableDigest(request),
   });
@@ -261,7 +261,7 @@ export async function resolveWorkspaceBinding(input: {
     }
     throw new Error("workspace provider returned a binding that failed initial attestation");
   }
-  appendWorkflowJournalEvent(input.opts.coordRoot, input.runId, "execution.allocate.end", {
+  appendWorkflowTranscriptEvent(input.opts.coordRoot, input.runId, "execution.allocate.end", {
     binding_id: binding.binding_id,
     provider_id: binding.provider.id,
     active_root: binding.active_root,

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

@@ -97,7 +97,7 @@ export type WorkflowWorkspaceInspection =
   | { ok: true; value: WorkflowWorkspaceStatus }
   | { ok: false; run_id: string; error: string };
 
-interface WorkflowJournalProjectionEvent {
+interface WorkflowTranscriptProjectionEvent {
   event: string;
   ok?: boolean;
   status?: "blocked" | "lost" | "cancelled" | "unsupported" | "preserved_dirty";
@@ -119,7 +119,7 @@ export function readWorkflowWorkspaceStatus(
   const root = resolve(coordRoot);
   const runDir = workflowRunDir(root, runId);
   const manifest = readWorkflowRunManifest(root, runId);
-  const journal = readWorkspaceJournal(runDir, runId);
+  const transcript = readWorkspaceTranscript(runDir, runId);
   const proofPath = join(runDir, "proof.json");
   const proof = existsSync(proofPath) ? readWorkflowProof(root, runId) : undefined;
   const proofSha256 = proof ? fileSha256(proofPath) : undefined;
@@ -129,7 +129,7 @@ export function readWorkflowWorkspaceStatus(
   if (!binding) {
     const lifecycle = deriveWorkspaceLifecycle({
       manifest,
-      workflow_journal: journal,
+      workflow_transcript: transcript,
       proof,
       proof_sha256: proofSha256,
       allocation_unsupported: fallback !== undefined,
@@ -212,7 +212,7 @@ export function readWorkflowWorkspaceStatus(
     binding,
     provider_events: providerEvents,
     manifest,
-    workflow_journal: journal,
+    workflow_transcript: transcript,
     proof,
     proof_sha256: proofSha256,
     integration_plan: integrationPlan,
@@ -355,8 +355,11 @@ export function renderWorkflowWorkspaceStatus(status: WorkflowWorkspaceStatus):
 
 const MAX_LISTED_DIRTY_PATHS = 12;
 
-function readWorkspaceJournal(runDir: string, runId: string): WorkflowJournalProjectionEvent[] {
-  const path = join(runDir, "journal.jsonl");
+function readWorkspaceTranscript(
+  runDir: string,
+  runId: string,
+): WorkflowTranscriptProjectionEvent[] {
+  const path = join(runDir, "transcript.jsonl");
   if (!existsSync(path)) return [];
   return readFileSync(path, "utf8")
     .split("\n")
@@ -367,7 +370,7 @@ function readWorkspaceJournal(runDir: string, runId: string): WorkflowJournalPro
         record = JSON.parse(line) as Record<string, unknown>;
       } catch (error) {
         throw new Error(
-          `cannot parse workflow journal event ${index + 1}: ${
+          `cannot parse workflow transcript event ${index + 1}: ${
             error instanceof Error ? error.message : String(error)
           }`,
         );
@@ -376,12 +379,12 @@ function readWorkspaceJournal(runDir: string, runId: string): WorkflowJournalPro
         typeof record.event !== "string" ||
         (record.run_id !== undefined && record.run_id !== runId)
       ) {
-        throw new Error(`workflow journal event ${index + 1} is foreign or unsupported`);
+        throw new Error(`workflow transcript event ${index + 1} is foreign or unsupported`);
       }
       return {
         event: record.event,
         ok: typeof record.ok === "boolean" ? record.ok : undefined,
-        status: journalStatus(record.status),
+        status: transcriptStatus(record.status),
         work_event_seq:
           typeof record.work_event_seq === "number" ? record.work_event_seq : undefined,
         work_event_sha256:
@@ -424,10 +427,10 @@ function cleanupState(
   return intent || attemptStatus ? "pending" : "not_requested";
 }
 
-function journalStatus(value: unknown): WorkflowJournalProjectionEvent["status"] {
+function transcriptStatus(value: unknown): WorkflowTranscriptProjectionEvent["status"] {
   return typeof value === "string" &&
     ["blocked", "lost", "cancelled", "unsupported", "preserved_dirty"].includes(value)
-    ? (value as WorkflowJournalProjectionEvent["status"])
+    ? (value as WorkflowTranscriptProjectionEvent["status"])
     : undefined;
 }
 

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

@@ -16,7 +16,7 @@ import { readWorkflowRunManifest } from "../run-state.ts";
 import { acquireNoClobberLease } from "./leases.ts";
 import {
   appendIntegrationAttempt,
-  appendWorkflowJournalEvent,
+  appendWorkflowTranscriptEvent,
   fileSha256,
   readIntegrationAttempts,
   readWorkflowSupplement,
@@ -177,7 +177,7 @@ export async function prepareIntegration(input: PrepareIntegrationInput): Promis
     }
     if (!prior) {
       writeWorkflowSupplement(input.coordRoot, input.runId, "integration/plan.json", plan);
-      appendWorkflowJournalEvent(input.coordRoot, input.runId, "integration.plan", {
+      appendWorkflowTranscriptEvent(input.coordRoot, input.runId, "integration.plan", {
         plan_id: plan.plan_id,
         plan_sha256: stableDigest(plan),
       });
@@ -236,12 +236,12 @@ export async function applyIntegration(
     }
     if (
       authorization.decision_sha256 !== stableDigest(authorization.decision) ||
-      authorization.journal_anchor.event !== "integration.plan" ||
-      authorization.journal_anchor.plan_sha256 !== planSha256
+      authorization.transcript_anchor.event !== "integration.plan" ||
+      authorization.transcript_anchor.plan_sha256 !== planSha256
     ) {
-      throw new Error("integration authorization digest or journal anchor is corrupt");
+      throw new Error("integration authorization digest or transcript anchor is corrupt");
     }
-    assertIntegrationPlanJournal(input.coordRoot, input.runId, planSha256);
+    assertIntegrationPlanTranscript(input.coordRoot, input.runId, planSha256);
     if (authorization.approval_id) {
       const approval = readWorkflowApproval(input.coordRoot, authorization.approval_id);
       if (
@@ -397,7 +397,7 @@ export async function applyIntegration(
       applied_at: providerResult.applied_at,
     };
     writeWorkflowSupplement(input.coordRoot, input.runId, "integration/receipt.json", receipt);
-    appendWorkflowJournalEvent(input.coordRoot, input.runId, "integration.apply", {
+    appendWorkflowTranscriptEvent(input.coordRoot, input.runId, "integration.apply", {
       receipt_id: receipt.receipt_id,
       status: receipt.status,
       target_commit: receipt.target_commit,
@@ -721,7 +721,7 @@ function authorizePlan(input: PrepareIntegrationInput, plan: IntegrationPlan): v
     approval_id: approvalId,
     approval_actor: approvalActor,
     approval_sha256: approvalSha256,
-    journal_anchor: {
+    transcript_anchor: {
       event: "integration.plan",
       plan_sha256: stableDigest(plan),
     },
@@ -740,7 +740,7 @@ function authorizePlan(input: PrepareIntegrationInput, plan: IntegrationPlan): v
       prior.decision_sha256 !== stableDigest(prior.decision) ||
       prior.approval_id !== authorization.approval_id ||
       prior.approval_sha256 !== authorization.approval_sha256 ||
-      stableDigest(prior.journal_anchor) !== stableDigest(authorization.journal_anchor)
+      stableDigest(prior.transcript_anchor) !== stableDigest(authorization.transcript_anchor)
     ) {
       throw new Error("existing integration authorization does not match the exact plan");
     }
@@ -752,7 +752,7 @@ function authorizePlan(input: PrepareIntegrationInput, plan: IntegrationPlan): v
     "integration/authorization.json",
     authorization,
   );
-  appendWorkflowJournalEvent(input.coordRoot, input.runId, "integration.authorized", {
+  appendWorkflowTranscriptEvent(input.coordRoot, input.runId, "integration.authorized", {
     plan_id: plan.plan_id,
     authorization_sha256: stableDigest(authorization),
     policy_sha256: authorization.policy_sha256,
@@ -787,8 +787,12 @@ function requiredIntegrationRoot(binding: WorkspaceBinding): string {
   return binding.integration_root;
 }
 
-function assertIntegrationPlanJournal(coordRoot: string, runId: string, planSha256: string): void {
-  const path = join(workflowRunDir(coordRoot, runId), "journal.jsonl");
+function assertIntegrationPlanTranscript(
+  coordRoot: string,
+  runId: string,
+  planSha256: string,
+): void {
+  const path = join(workflowRunDir(coordRoot, runId), "transcript.jsonl");
   let records: Array<Record<string, unknown>>;
   try {
     records = readFileSync(path, "utf8")
@@ -796,7 +800,7 @@ function assertIntegrationPlanJournal(coordRoot: string, runId: string, planSha2
       .filter(Boolean)
       .map((line) => JSON.parse(line) as Record<string, unknown>);
   } catch (error) {
-    throw new Error(`workflow journal is corrupt: ${(error as Error).message}`);
+    throw new Error(`workflow transcript is corrupt: ${(error as Error).message}`);
   }
   if (
     records.some((record) => record.run_id !== runId || typeof record.event !== "string") ||
@@ -804,7 +808,7 @@ function assertIntegrationPlanJournal(coordRoot: string, runId: string, planSha2
       (record) => record.event === "integration.plan" && record.plan_sha256 === planSha256,
     )
   ) {
-    throw new Error("integration plan journal anchor is missing or mismatched");
+    throw new Error("integration plan transcript anchor is missing or mismatched");
   }
 }
 

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

@@ -135,7 +135,7 @@ export interface WorkspaceLifecycleProjectionInput {
   binding?: WorkspaceBinding;
   provider_events?: readonly WorkspaceProviderEvent[];
   manifest?: WorkflowRunManifest;
-  workflow_journal?: readonly {
+  workflow_transcript?: readonly {
     event: string;
     ok?: boolean;
     status?: "blocked" | "lost" | WorkspaceCancellationResult["status"];
@@ -207,22 +207,22 @@ export function deriveWorkspaceLifecycle(
     transition(next);
   }
 
-  const journal = input.workflow_journal ?? [];
-  for (const event of journal) {
+  const transcript = input.workflow_transcript ?? [];
+  for (const event of transcript) {
     if (input.binding && (event.event === "run.start" || event.event === "run.resume")) {
       transition("running");
     }
     if (event.event === "run.parked") transition("parked");
   }
-  const failedReattachment = [...journal]
+  const failedReattachment = [...transcript]
     .reverse()
     .find((event) => event.event === "workspace.reattach.failed");
   if (failedReattachment) transition(failedReattachment.status === "blocked" ? "blocked" : "lost");
   let workflowOutcome = proofOutcome(input.proof, input.binding);
-  const terminalJournal = [...journal].reverse().find((event) => event.event === "run.end");
+  const terminalTranscript = [...transcript].reverse().find((event) => event.event === "run.end");
   if (input.proof && !failedReattachment) transition(workflowOutcome!);
-  if (terminalJournal && !input.proof && !failedReattachment) {
-    workflowOutcome = terminalJournal.ok === false ? "failed_retained" : null;
+  if (terminalTranscript && !input.proof && !failedReattachment) {
+    workflowOutcome = terminalTranscript.ok === false ? "failed_retained" : null;
     transition("blocked");
   }
   if (projectedIntegrationState !== "none") transition("integration_requested");
@@ -269,7 +269,7 @@ export function deriveWorkspaceLifecycle(
     ((input.cancellation_receipt?.status === "cancelled" &&
       input.cancellation_receipt.work_event_seq === latestGovernance.seq &&
       input.cancellation_receipt.work_event_sha256 === workEventSha256) ||
-      journal.some(
+      transcript.some(
         (event) =>
           event.event === "workspace.cancel" &&
           event.status === "cancelled" &&
@@ -459,8 +459,8 @@ function validateIntegrationAuthorization(
     !digest(authorization.policy_sha256) ||
     authorization.decision?.verdict !== "allow" ||
     authorization.decision_sha256 !== stableDigest(authorization.decision) ||
-    authorization.journal_anchor?.event !== "integration.plan" ||
-    authorization.journal_anchor.plan_sha256 !== planSha256 ||
+    authorization.transcript_anchor?.event !== "integration.plan" ||
+    authorization.transcript_anchor.plan_sha256 !== planSha256 ||
     !validTimestamp(authorization.authorized_at) ||
     (authorization.approval_id !== undefined &&
       (typeof authorization.approval_actor !== "string" || !digest(authorization.approval_sha256)))

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

@@ -1,6 +1,13 @@
 import { randomBytes } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { WorkspaceAttestationError } from "./attestation-error.ts";
 import {
   git,
@@ -68,6 +75,8 @@ import { isWorkspaceAttestation } from "./validate.ts";
 
 const PROVIDER_ID = "local-git-worktree";
 const PROVIDER_VERSION = "1";
+const WORKSPACE_PARENT_SEGMENT = ".harnery-workspaces";
+const LEGACY_WORKSPACE_PARENT_SEGMENT = "harnery-workspaces";
 const LOCK_STALE_MS = 5 * 60 * 1_000;
 const OBJECT_FORMAT = /^[a-f0-9]{40,64}$/;
 const REF_FORMAT = /^refs\/heads\/[A-Za-z0-9][A-Za-z0-9._/-]{0,180}$/;
@@ -221,7 +230,11 @@ async function allocate(
   );
   const authorityOutside = describeAuthorityOutsideRoot(repo, root.realpath);
   if (authorityOutside) throw new Error(authorityOutside);
-  const workspaceRoot = candidateUnderRoot(root, ["harnery-workspaces", bindingId]);
+  // Claims are immutable, so a retry must reproduce the path the first attempt
+  // froze. Only a genuinely new allocation picks the current parent.
+  const priorClaim = readWorkspaceClaim(coordRoot, PROVIDER_ID, bindingId);
+  const parentSegment = priorClaim ? claimedParentSegment(priorClaim) : WORKSPACE_PARENT_SEGMENT;
+  const workspaceRoot = candidateUnderRoot(root, [parentSegment, bindingId]);
   const activeRoot = resolve(workspaceRoot, repo.requestedRelativePath);
   if (!containsPath(workspaceRoot, activeRoot)) {
     throw new Error("requested working directory escapes the isolated workspace");
@@ -287,6 +300,33 @@ async function allocate(
   }
 }
 
+/**
+ * A claim freezes its workspace path at allocation time, so reconciliation must
+ * follow the parent recorded there rather than the parent this version would
+ * choose. Only the names this provider has ever allocated under are accepted, so
+ * a tampered claim cannot redirect creation into an unrelated directory.
+ */
+function claimedParentSegment(claim: WorkspaceClaim): string {
+  const segment = basename(dirname(claim.workspace_root));
+  if (segment !== WORKSPACE_PARENT_SEGMENT && segment !== LEGACY_WORKSPACE_PARENT_SEGMENT) {
+    throw new Error("claimed workspace path is not under a provider-owned workspace parent");
+  }
+  return segment;
+}
+
+/**
+ * The parent holds real checkouts that would otherwise surface as untracked
+ * content in the surrounding repository. A directory whose every entry is
+ * ignored, including the ignore file itself, does not appear in `git status` at
+ * all, which keeps the guarantee with the provider instead of asking each
+ * consumer to maintain a rule.
+ */
+function hideWorkspaceParentFromGit(parent: string): void {
+  const ignoreFile = join(parent, ".gitignore");
+  if (existsSync(ignoreFile)) return;
+  writeFileSync(ignoreFile, "*\n", { mode: 0o600 });
+}
+
 function reconcileAllocation(
   coordRoot: string,
   claim: WorkspaceClaim,
@@ -328,7 +368,9 @@ function reconcileAllocation(
     throw new Error("provider-owned workspace branch no longer matches its frozen base");
   }
 
-  const workspaceParent = createContainedDirectories(root, ["harnery-workspaces"]);
+  const parentSegment = claimedParentSegment(claim);
+  const workspaceParent = createContainedDirectories(root, [parentSegment]);
+  hideWorkspaceParentFromGit(workspaceParent);
   const workspaceParentIdentity = filesystemIdentity(workspaceParent);
   const registered = worktreeInventory(claim.repository.source_root.realpath);
   const exact = registered.find((item) => resolve(item.path) === claim.workspace_root);
@@ -385,7 +427,7 @@ function reconcileAllocation(
         parent_identity: workspaceParentIdentity,
       });
     }
-    const openedWorkspace = openContainedDirectory(root, ["harnery-workspaces", claim.binding_id]);
+    const openedWorkspace = openContainedDirectory(root, [parentSegment, claim.binding_id]);
     if (openedWorkspace.path !== claim.workspace_root) {
       openedWorkspace.close();
       throw new Error("descriptor-backed workspace directory differs from the claim");

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

@@ -16,11 +16,11 @@ export function readWorkflowLiveness(coordRoot: string, runId: string): Workflow
     }
   }
 
-  const journalPath = join(root, ".harnery", "workflows", runId, "journal.jsonl");
-  if (!existsSync(journalPath)) return "unknown";
+  const transcriptPath = join(root, ".harnery", "workflows", runId, "transcript.jsonl");
+  if (!existsSync(transcriptPath)) return "unknown";
   let events: Array<{ event?: string; run_id?: string; ok?: unknown; status?: unknown }>;
   try {
-    events = readFileSync(journalPath, "utf8")
+    events = readFileSync(transcriptPath, "utf8")
       .split("\n")
       .filter(Boolean)
       .map(

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

@@ -18,7 +18,7 @@ import {
   writeImmutableJson,
 } from "../durable-record.ts";
 
-export { appendWorkflowJournalEvent } from "../journal.ts";
+export { appendWorkflowTranscriptEvent } from "../transcript.ts";
 
 import type {
   GitRepositoryBinding,
@@ -232,7 +232,8 @@ export function readWorkspaceEvents(
 ): WorkspaceProviderEvent[] {
   const path = workspaceEventsPath(coordRoot, providerId, bindingId);
   if (!existsSync(path)) return [];
-  if (statSync(path).size > JSON_LIMIT * 4) throw new Error("workspace event journal is too large");
+  if (statSync(path).size > JSON_LIMIT * 4)
+    throw new Error("workspace event transcript is too large");
   const claim = readWorkspaceClaim(coordRoot, providerId, bindingId);
   if (!claim) throw new Error("workspace event authority claim is missing");
   const records = readFileSync(path, "utf8")
@@ -391,7 +392,7 @@ function readChainedRecords<
 >(path: string, label: string): T[] {
   if (!existsSync(path)) return [];
   if (statSync(path).size > JSON_LIMIT * 4) {
-    throw new Error(`${label} journal is too large`);
+    throw new Error(`${label} transcript is too large`);
   }
   const records = readFileSync(path, "utf8")
     .split("\n")

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

@@ -353,7 +353,7 @@ export interface IntegrationAuthorization {
   approval_id?: string;
   approval_actor?: string;
   approval_sha256?: string;
-  journal_anchor: {
+  transcript_anchor: {
     event: "integration.plan";
     plan_sha256: string;
   };

package/src/lib/browser/asserts.ts

@@ -0,0 +1,177 @@
+// Value assertions for `harn browse --assert`.
+//
+// The layout + content checks answer "does the page look right"; asserts answer
+// "does the page SAY the right thing" — the h1 text, a price, how many cards
+// rendered, whether an error banner is absent. It lets an agent confirm the
+// values it expects without a human reading the page back.
+//
+// One repeatable flag with a small grammar:
+//   --assert 'text h1 => Welcome'          first match's trimmed text equals
+//   --assert 'contains .total => $49'      first match's text contains
+//   --assert 'matches .sku => ^BN-\d+$'    first match's text matches a regex
+//   --assert 'count .card => >=3'          match count vs a number or comparator
+//   --assert 'exists .cta'                 at least one match
+//   --assert 'absent .error'               zero matches
+//
+// `op selector => expected`; `exists`/`absent` take no `=> expected`.
+
+export type AssertOp = "text" | "contains" | "matches" | "count" | "exists" | "absent";
+
+export interface AssertSpec {
+  raw: string;
+  op: AssertOp;
+  selector: string;
+  expected: string;
+}
+
+export interface AssertResult {
+  raw: string;
+  op: AssertOp;
+  selector: string;
+  expected: string;
+  /** Observed value: the text, or the match count as a string. */
+  actual: string;
+  found: boolean;
+  outcome: "pass" | "fail";
+  /** Populated when the spec itself was malformed (e.g. bad regex, bad count). */
+  error?: string;
+}
+
+const OPS: readonly AssertOp[] = ["text", "contains", "matches", "count", "exists", "absent"];
+
+/** Parse one `--assert` expression. Throws with a clear message on malformed input. */
+export function parseAssertSpec(raw: string): AssertSpec {
+  const trimmed = raw.trim();
+  const spaceIdx = trimmed.indexOf(" ");
+  if (spaceIdx < 0) {
+    throw new Error(`--assert needs '<op> <selector> [=> expected]' (got: '${raw}')`);
+  }
+  const op = trimmed.slice(0, spaceIdx).toLowerCase() as AssertOp;
+  if (!OPS.includes(op)) {
+    throw new Error(`--assert op must be one of ${OPS.join(", ")} (got: '${op}')`);
+  }
+  const rest = trimmed.slice(spaceIdx + 1).trim();
+  const sep = rest.indexOf("=>");
+  if (op === "exists" || op === "absent") {
+    return { raw, op, selector: (sep < 0 ? rest : rest.slice(0, sep)).trim(), expected: "" };
+  }
+  if (sep < 0) {
+    throw new Error(`--assert '${op}' needs 'selector => expected' (got: '${raw}')`);
+  }
+  return {
+    raw,
+    op,
+    selector: rest.slice(0, sep).trim(),
+    expected: rest.slice(sep + 2).trim(),
+  };
+}
+
+/**
+ * Build the page evaluator. Serialized into the page by Playwright, so helpers
+ * are nested. Comparison logic that does not touch the DOM (count comparators,
+ * regex) also runs in-page to keep it one round trip.
+ */
+export function buildAssertCheck(): (specs: AssertSpec[]) => AssertResult[] {
+  return (specs) => {
+    const textOf = (el: Element): string => (el.textContent ?? "").replace(/\s+/g, " ").trim();
+
+    const compareCount = (count: number, expected: string): { ok: boolean; error?: string } => {
+      const m = /^(>=|<=|>|<|=)?\s*(\d+)$/.exec(expected.trim());
+      if (!m) return { ok: false, error: `bad count expected '${expected}'` };
+      const op = m[1] || "=";
+      const n = Number.parseInt(m[2]!, 10);
+      switch (op) {
+        case ">=":
+          return { ok: count >= n };
+        case "<=":
+          return { ok: count <= n };
+        case ">":
+          return { ok: count > n };
+        case "<":
+          return { ok: count < n };
+        default:
+          return { ok: count === n };
+      }
+    };
+
+    return specs.map((spec): AssertResult => {
+      const base = {
+        raw: spec.raw,
+        op: spec.op,
+        selector: spec.selector,
+        expected: spec.expected,
+      };
+      let nodes: Element[];
+      try {
+        nodes = Array.from(document.querySelectorAll(spec.selector));
+      } catch {
+        return { ...base, actual: "", found: false, outcome: "fail", error: "invalid selector" };
+      }
+      const first = nodes[0] ?? null;
+      const firstText = first ? textOf(first) : "";
+
+      switch (spec.op) {
+        case "exists":
+          return {
+            ...base,
+            actual: String(nodes.length),
+            found: nodes.length > 0,
+            outcome: nodes.length > 0 ? "pass" : "fail",
+          };
+        case "absent":
+          return {
+            ...base,
+            actual: String(nodes.length),
+            found: nodes.length > 0,
+            outcome: nodes.length === 0 ? "pass" : "fail",
+          };
+        case "count": {
+          const { ok, error } = compareCount(nodes.length, spec.expected);
+          return {
+            ...base,
+            actual: String(nodes.length),
+            found: true,
+            outcome: ok ? "pass" : "fail",
+            ...(error ? { error } : {}),
+          };
+        }
+        case "text":
+          return {
+            ...base,
+            actual: firstText,
+            found: !!first,
+            outcome: first && firstText === spec.expected ? "pass" : "fail",
+          };
+        case "contains":
+          return {
+            ...base,
+            actual: firstText,
+            found: !!first,
+            outcome: first && firstText.includes(spec.expected) ? "pass" : "fail",
+          };
+        case "matches": {
+          let re: RegExp;
+          try {
+            re = new RegExp(spec.expected);
+          } catch {
+            return {
+              ...base,
+              actual: firstText,
+              found: !!first,
+              outcome: "fail",
+              error: `invalid regex '${spec.expected}'`,
+            };
+          }
+          return {
+            ...base,
+            actual: firstText,
+            found: !!first,
+            outcome: first && re.test(firstText) ? "pass" : "fail",
+          };
+        }
+        default:
+          return { ...base, actual: "", found: false, outcome: "fail", error: "unknown op" };
+      }
+    });
+  };
+}