@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/scripts/generate-forgeloop-skill.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+import { readFile, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { protocolInfo } from "../src/core/protocol-info.js";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const summaryPath = path.join(root, "docs", "AGENT_PROTOCOL_SUMMARY.md");
+const outputRoot = path.join(root, "skills", "forgeloop");
+const marker = "<!-- Generated by scripts/generate-forgeloop-skill.mjs. Do not edit manually. -->";
+
+function skillContent(info, summary) {
+  const phases = info.lifecycle.phases.join(", ");
+  return `---
+name: forgeloop
+description: >-
+  Operate a repository governed by the ForgeLoop protocol: discover or resume
+  tasks, follow canonical next actions, preserve claims and continuity, record
+  verification evidence, recover supported protocol state, and require
+  validator-backed completion.
+---
+
+${marker}
+
+# ForgeLoop
+
+## Purpose
+
+This skill is operational guidance generated from ForgeLoop's canonical protocol metadata. It is not protocol authority. Always follow the current repository runtime, \`protocol-info\`, \`next\`, schemas, validators, and canonical documentation when they differ from this skill.
+
+## When to Use
+
+Use when ForgeLoop is present in the repository or explicitly requested. Do not activate it for unrelated repositories merely because an agent supports skills.
+
+## Source of Truth
+
+Runtime registries and validators outrank canonical protocol docs; canonical docs outrank \`docs/AGENT_PROTOCOL_SUMMARY.md\`; this generated skill is the final non-normative projection. Protocol version is ${info.protocolVersion}. Mutable facts such as phases (${phases}) must be read from the runtime.
+
+## Command Resolution
+
+In ForgeLoop's own source repository, use \`node src/cli.js\`. In a consumer repository, use that repository's configured local invocation. Never silently install or upgrade ForgeLoop, and never use a stale global CLI when repository-local code exists. If compatibility is uncertain, inspect \`protocol-info --json\`.
+
+## Operating Workflow
+
+1. Discover existing work with \`node src/cli.js task-list --json\`.
+2. Select or resume the relevant task; a harness, session, model, or context change does not create a new task.
+3. Ask ForgeLoop for \`next --task <id> --json\` at every boundary and execute only the returned supported action.
+4. Require \`preflight\` to return \`READY\` before implementation.
+5. Preserve fresh, validator-owned evidence through verification, review, completion, and the terminal \`next\` check.
+
+## Task Discovery and Continuation
+
+Respect active write claims. Do not steal, override, manually release, or edit ownership artifacts. Reconcile continuity with canonical state rather than trusting stale narrative.
+
+## Verification Rules
+
+\`run-check\` executes the exact command and records ForgeLoop-owned provenance. \`record-check\` is serialization-only; its command text is metadata and is never executed. Claims, provider/advisory output, screenshots, and actor summaries are not evidence by themselves. Missing tools remain unavailable; do not auto-install a verifier.
+
+## Recovery Rules
+
+Use supported recovery only. Preserve failed evidence and follow \`next\` through diagnosis/correction. For state or ledger divergence, stop lifecycle mutation and inspect validation/classification. Never edit task state, receipts, recovery, continuity, claims, hashes, or \`events.ndjson\` manually. Reconcile \`COMMIT_UNKNOWN\` before any retry.
+
+## Completion Rule
+
+Never claim ForgeLoop-verified completion unless \`complete\` returns \`VALID\`. Green tests, CI, a merged PR, or provider output alone are insufficient. After \`VALID\`, run \`next --task <id> --json\` again and require the canonical terminal action.
+
+## Cross-Harness Continuity
+
+A harness or session change does not create a new task. Use supported continuity or handoff commands and reconcile persisted state before continuing.
+
+## Durable Action Safety
+
+For external actions use propose, authorize, execute, then verify or reconcile. Never blindly retry an uncertain external commit.
+
+## Never Do
+
+- Never manually assign COMPLETE.
+- Never invent lifecycle chronology or override \`next\`.
+- Never override active claims or rewrite the append-only ledger.
+- Never fabricate evidence or treat \`record-check\` as execution.
+- Never auto-install ForgeLoop or a verifier during normal operation.
+- Never duplicate a task because the harness changed.
+- Never treat provider/advisory output as protocol authority.
+
+## References
+
+- [Canonical Agent Protocol Summary](../../docs/AGENT_PROTOCOL_SUMMARY.md)
+- [Lifecycle](./references/lifecycle.md)
+- [Verification](./references/verification.md)
+- [Recovery](./references/recovery.md)
+`;
+}
+
+function referenceContent(title, body, summary) {
+  return `${marker}\n\n# ${title}\n\n${body}\n\n<!-- Canonical summary fingerprint source: docs/AGENT_PROTOCOL_SUMMARY.md -->\n${summary.includes("# ForgeLoop Agent Protocol Summary") ? "" : ""}`;
+}
+
+function files(info, summary) {
+  return {
+    "SKILL.md": skillContent(info, summary),
+    "README.md": `${marker}\n\n# ForgeLoop Agent Skill\n\nThis directory contains a generated, portable, harness-neutral Agent Skill. It is operational guidance, not protocol authority, and has no dependency on external Agent Skills tooling.\n\nCanonical hierarchy: runtime registries and validators -> canonical protocol docs -> \`docs/AGENT_PROTOCOL_SUMMARY.md\` -> this generated projection.\n\nRegenerate with \`npm run skill:generate\`; check exact freshness with \`npm run skill:check\`. The generator is deterministic, offline, and writes only the five known files in this directory.\n`,
+    "references/lifecycle.md": referenceContent("Lifecycle", `The canonical loop is task discovery, contract, route, preflight, execution, verification, review, validator-backed completion, and a terminal next check. Always query \`next\` rather than inferring a transition. The initial post-task-create shape may have no work state: \`next\` returns DISCOVER, then CREATE_CONTRACT, and only a real contract fingerprint permits the first work-state checkpoint.\n\nPhases are runtime-owned and currently include: ${info.lifecycle.phases.join(", ")}.`, summary),
+    "references/verification.md": referenceContent("Verification", "Use run-check for exact command execution and provenance. Use record-check only for supplied observations; it never launches command text. Evidence must be fresh, task-bound, requirement-bound, and validator-readable. Preserve failures, report unavailable tools, and require observed coverage before review and complete -> VALID.", summary),
+    "references/recovery.md": referenceContent("Recovery", "Fail closed on invalid ownership, state, ledger, receipt, or continuity. Use supported recovery commands only. Never edit .forgeloop/task-state, work-state.json, events.ndjson, recovery.json, claims, or hashes by hand. Claim release is not a lifecycle bypass. Reconcile COMMIT_UNKNOWN before retrying any external action.", summary),
+  };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length !== 1 || !["--write", "--check"].includes(args[0])) {
+    throw new Error("Usage: node scripts/generate-forgeloop-skill.mjs --write|--check");
+  }
+  const summary = await readFile(summaryPath, "utf8");
+  const generated = files(protocolInfo(), summary);
+  let failed = false;
+  for (const [relative, content] of Object.entries(generated)) {
+    const target = path.join(outputRoot, relative);
+    let current = null;
+    try { current = await readFile(target, "utf8"); } catch (error) { if (error.code !== "ENOENT") throw error; }
+    if (args[0] === "--check") {
+      if (current !== content) { console.error(`Generated Agent Skill is stale: skills/forgeloop/${relative}`); failed = true; }
+    } else {
+      await mkdir(path.dirname(target), { recursive: true });
+      await writeFile(target, content, "utf8");
+    }
+  }
+  if (failed) process.exitCode = 1;
+  else console.log(args[0] === "--check" ? "Generated Agent Skill is current." : "Generated Agent Skill.");
+}
+
+await main();

package/scripts/jev-smoke.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { DECISION_DEFAULT_POLICY } from "../src/core/decision/constants.js";
+import { createTypesafeEngine } from "../src/adapters/typesafe/engine.js";
+
+const engine = createTypesafeEngine({ policy: DECISION_DEFAULT_POLICY });
+const result = await engine.health();
+const status = result.status === "missing" ? "NOT_RUN" : result.status;
+console.log(JSON.stringify({
+  status,
+  provider: result.engine,
+  model: result.model,
+  ...(result.latencyMs !== undefined ? { latencyMs: result.latencyMs } : {}),
+  ...(result.usage ? { usage: result.usage } : {}),
+  ...(result.errorCode ? { errorCode: result.errorCode } : {}),
+  ...(result.providerErrorType ? { providerErrorType: result.providerErrorType } : {}),
+  ...(result.httpStatus ? { httpStatus: result.httpStatus } : {}),
+  ...(result.requestId ? { requestId: result.requestId } : {}),
+}, null, 2));
+if (status !== "healthy" && status !== "NOT_RUN") process.exitCode = 1;

package/skills/forgeloop/README.md

@@ -0,0 +1,9 @@
+<!-- Generated by scripts/generate-forgeloop-skill.mjs. Do not edit manually. -->
+
+# ForgeLoop Agent Skill
+
+This directory contains a generated, portable, harness-neutral Agent Skill. It is operational guidance, not protocol authority, and has no dependency on external Agent Skills tooling.
+
+Canonical hierarchy: runtime registries and validators -> canonical protocol docs -> `docs/AGENT_PROTOCOL_SUMMARY.md` -> this generated projection.
+
+Regenerate with `npm run skill:generate`; check exact freshness with `npm run skill:check`. The generator is deterministic, offline, and writes only the five known files in this directory.

package/skills/forgeloop/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: forgeloop
+description: >-
+  Operate a repository governed by the ForgeLoop protocol: discover or resume
+  tasks, follow canonical next actions, preserve claims and continuity, record
+  verification evidence, recover supported protocol state, and require
+  validator-backed completion.
+---
+
+<!-- Generated by scripts/generate-forgeloop-skill.mjs. Do not edit manually. -->
+
+# ForgeLoop
+
+## Purpose
+
+This skill is operational guidance generated from ForgeLoop's canonical protocol metadata. It is not protocol authority. Always follow the current repository runtime, `protocol-info`, `next`, schemas, validators, and canonical documentation when they differ from this skill.
+
+## When to Use
+
+Use when ForgeLoop is present in the repository or explicitly requested. Do not activate it for unrelated repositories merely because an agent supports skills.
+
+## Source of Truth
+
+Runtime registries and validators outrank canonical protocol docs; canonical docs outrank `docs/AGENT_PROTOCOL_SUMMARY.md`; this generated skill is the final non-normative projection. Protocol version is 1. Mutable facts such as phases (RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECUTING, VERIFYING, DIAGNOSING, CORRECTING, REVIEWING, COMPLETE, BLOCKED) must be read from the runtime.
+
+## Command Resolution
+
+In ForgeLoop's own source repository, use `node src/cli.js`. In a consumer repository, use that repository's configured local invocation. Never silently install or upgrade ForgeLoop, and never use a stale global CLI when repository-local code exists. If compatibility is uncertain, inspect `protocol-info --json`.
+
+## Operating Workflow
+
+1. Discover existing work with `node src/cli.js task-list --json`.
+2. Select or resume the relevant task; a harness, session, model, or context change does not create a new task.
+3. Ask ForgeLoop for `next --task <id> --json` at every boundary and execute only the returned supported action.
+4. Require `preflight` to return `READY` before implementation.
+5. Preserve fresh, validator-owned evidence through verification, review, completion, and the terminal `next` check.
+
+## Task Discovery and Continuation
+
+Respect active write claims. Do not steal, override, manually release, or edit ownership artifacts. Reconcile continuity with canonical state rather than trusting stale narrative.
+
+## Verification Rules
+
+`run-check` executes the exact command and records ForgeLoop-owned provenance. `record-check` is serialization-only; its command text is metadata and is never executed. Claims, provider/advisory output, screenshots, and actor summaries are not evidence by themselves. Missing tools remain unavailable; do not auto-install a verifier.
+
+## Recovery Rules
+
+Use supported recovery only. Preserve failed evidence and follow `next` through diagnosis/correction. For state or ledger divergence, stop lifecycle mutation and inspect validation/classification. Never edit task state, receipts, recovery, continuity, claims, hashes, or `events.ndjson` manually. Reconcile `COMMIT_UNKNOWN` before any retry.
+
+## Completion Rule
+
+Never claim ForgeLoop-verified completion unless `complete` returns `VALID`. Green tests, CI, a merged PR, or provider output alone are insufficient. After `VALID`, run `next --task <id> --json` again and require the canonical terminal action.
+
+## Cross-Harness Continuity
+
+A harness or session change does not create a new task. Use supported continuity or handoff commands and reconcile persisted state before continuing.
+
+## Durable Action Safety
+
+For external actions use propose, authorize, execute, then verify or reconcile. Never blindly retry an uncertain external commit.
+
+## Never Do
+
+- Never manually assign COMPLETE.
+- Never invent lifecycle chronology or override `next`.
+- Never override active claims or rewrite the append-only ledger.
+- Never fabricate evidence or treat `record-check` as execution.
+- Never auto-install ForgeLoop or a verifier during normal operation.
+- Never duplicate a task because the harness changed.
+- Never treat provider/advisory output as protocol authority.
+
+## References
+
+- [Canonical Agent Protocol Summary](../../docs/AGENT_PROTOCOL_SUMMARY.md)
+- [Lifecycle](./references/lifecycle.md)
+- [Verification](./references/verification.md)
+- [Recovery](./references/recovery.md)

package/skills/forgeloop/references/lifecycle.md

@@ -0,0 +1,9 @@
+<!-- Generated by scripts/generate-forgeloop-skill.mjs. Do not edit manually. -->
+
+# Lifecycle
+
+The canonical loop is task discovery, contract, route, preflight, execution, verification, review, validator-backed completion, and a terminal next check. Always query `next` rather than inferring a transition. The initial post-task-create shape may have no work state: `next` returns DISCOVER, then CREATE_CONTRACT, and only a real contract fingerprint permits the first work-state checkpoint.
+
+Phases are runtime-owned and currently include: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECUTING, VERIFYING, DIAGNOSING, CORRECTING, REVIEWING, COMPLETE, BLOCKED.
+
+<!-- Canonical summary fingerprint source: docs/AGENT_PROTOCOL_SUMMARY.md -->

package/skills/forgeloop/references/recovery.md

@@ -0,0 +1,7 @@
+<!-- Generated by scripts/generate-forgeloop-skill.mjs. Do not edit manually. -->
+
+# Recovery
+
+Fail closed on invalid ownership, state, ledger, receipt, or continuity. Use supported recovery commands only. Never edit .forgeloop/task-state, work-state.json, events.ndjson, recovery.json, claims, or hashes by hand. Claim release is not a lifecycle bypass. Reconcile COMMIT_UNKNOWN before retrying any external action.
+
+<!-- Canonical summary fingerprint source: docs/AGENT_PROTOCOL_SUMMARY.md -->

package/skills/forgeloop/references/verification.md

@@ -0,0 +1,7 @@
+<!-- Generated by scripts/generate-forgeloop-skill.mjs. Do not edit manually. -->
+
+# Verification
+
+Use run-check for exact command execution and provenance. Use record-check only for supplied observations; it never launches command text. Evidence must be fresh, task-bound, requirement-bound, and validator-readable. Preserve failures, report unavailable tools, and require observed coverage before review and complete -> VALID.
+
+<!-- Canonical summary fingerprint source: docs/AGENT_PROTOCOL_SUMMARY.md -->

package/src/adapters/agent-browser/assertions.js

@@ -0,0 +1,47 @@
+import { E_BROWSER_VERIFICATION_RESULT_INVALID } from "../../core/error-codes.js";
+
+export function actualValue(data) {
+  if (typeof data === "string" || typeof data === "number" || typeof data === "boolean") return String(data);
+  if (!data || typeof data !== "object" || Array.isArray(data)) return "";
+  for (const key of ["text", "value", "attribute", "url", "title", "visible"]) {
+    if (data[key] !== undefined && data[key] !== null) return String(data[key]);
+  }
+  return "";
+}
+
+export function observedScalar(data, label = "Agent Browser observation") {
+  if (typeof data === "string" || typeof data === "number" || typeof data === "boolean") {
+    return String(data);
+  }
+  if (data && typeof data === "object" && !Array.isArray(data)) {
+    for (const key of ["text", "value", "attribute", "url", "title", "visible"]) {
+      if (Object.prototype.hasOwnProperty.call(data, key) && data[key] !== undefined && data[key] !== null) {
+        const value = data[key];
+        if (["string", "number", "boolean"].includes(typeof value)) return String(value);
+      }
+    }
+  }
+  const error = new Error(`${label} was malformed`);
+  error.code = E_BROWSER_VERIFICATION_RESULT_INVALID;
+  throw error;
+}
+
+export function matchesAssertion(kind, actual, expected) {
+  if (kind === "VISIBLE") return actual === "true";
+  if (kind === "HIDDEN") return actual !== "true";
+  if (kind === "TEXT_CONTAINS") return actual.includes(expected);
+  if (kind === "TEXT_EQUALS" || kind === "VALUE_EQUALS" || kind === "ATTRIBUTE_EQUALS" || kind === "TITLE_EQUALS") return actual === expected;
+  if (kind === "URL_IS") return actual === expected;
+  if (kind === "URL_PREFIX") return actual.startsWith(expected);
+  return false;
+}
+
+export function assertionResult(assertion, status, actual, message) {
+  return {
+    id: assertion.id,
+    kind: assertion.kind,
+    status,
+    ...(actual !== undefined ? { actual: String(actual) } : {}),
+    ...(message ? { message } : {}),
+  };
+}

package/src/adapters/agent-browser/commands.js

@@ -0,0 +1,54 @@
+const SAFE_GLOBAL_FLAGS = Object.freeze(["--content-boundaries", "--no-webmcp"]);
+
+function globalArgs({ sessionId, allowedOrigins, maxOutputChars = 50_000 } = {}) {
+  const domains = [...new Set((allowedOrigins ?? []).map((origin) => new URL(origin).hostname.toLowerCase()))].join(",");
+  return [
+    "--session", sessionId,
+    "--allowed-domains", domains,
+    "--max-output", String(maxOutputChars),
+    ...SAFE_GLOBAL_FLAGS,
+  ];
+}
+
+function command({ sessionId, allowedOrigins, maxOutputChars, name, args = [], json = true }) {
+  return [
+    ...globalArgs({ sessionId, allowedOrigins, maxOutputChars }),
+    name,
+    ...args,
+    ...(json ? ["--json"] : []),
+  ];
+}
+
+export function versionCommand() { return ["--version"]; }
+export function openCommand(input) { return command({ ...input, name: "open", args: [input.url] }); }
+export function clickCommand(input) { return command({ ...input, name: "click", args: [input.selector] }); }
+export function focusCommand(input) { return command({ ...input, name: "focus", args: [input.selector] }); }
+export function fillCommand(input) { return command({ ...input, name: "fill", args: [input.selector, input.text] }); }
+export function pressCommand(input) { return command({ ...input, name: "press", args: [input.key] }); }
+export function snapshotCommand(input) { return command({ ...input, name: "snapshot", args: ["-i"] }); }
+export function visibleCommand(input) { return command({ ...input, name: "is", args: ["visible", input.selector] }); }
+export function textCommand(input) { return command({ ...input, name: "get", args: ["text", input.selector] }); }
+export function valueCommand(input) { return command({ ...input, name: "get", args: ["value", input.selector] }); }
+export function attributeCommand(input) { return command({ ...input, name: "get", args: ["attr", input.selector, input.attribute] }); }
+export function urlCommand(input) { return command({ ...input, name: "get", args: ["url"] }); }
+export function titleCommand(input) { return command({ ...input, name: "get", args: ["title"] }); }
+export function screenshotCommand(input) { return command({ ...input, name: "screenshot", args: [input.outputPath], json: true }); }
+export function closeCommand(input) { return command({ ...input, name: "close", args: [] }); }
+
+export const AGENT_BROWSER_COMMANDS = Object.freeze({
+  version: versionCommand,
+  open: openCommand,
+  click: clickCommand,
+  focus: focusCommand,
+  fill: fillCommand,
+  press: pressCommand,
+  snapshot: snapshotCommand,
+  visible: visibleCommand,
+  text: textCommand,
+  value: valueCommand,
+  attribute: attributeCommand,
+  url: urlCommand,
+  title: titleCommand,
+  screenshot: screenshotCommand,
+  close: closeCommand,
+});

package/src/adapters/agent-browser/index.js

@@ -0,0 +1,3 @@
+export { createAgentBrowserVerificationProvider } from "./provider.js";
+export { AGENT_BROWSER_PROCESS_LIMITS, parseAgentBrowserJson, runAgentBrowserCommand } from "./process.js";
+export * from "./commands.js";

package/src/adapters/agent-browser/locator.js

@@ -0,0 +1,40 @@
+import { E_BROWSER_VERIFICATION_RESULT_INVALID } from "../../core/error-codes.js";
+
+function locatorError(message) {
+  const error = new Error(message);
+  error.code = E_BROWSER_VERIFICATION_RESULT_INVALID;
+  error.kind = "BLOCKED";
+  return error;
+}
+
+function refsFromSnapshot(snapshot) {
+  if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)) return [];
+  const refs = snapshot.refs;
+  if (!refs || typeof refs !== "object" || Array.isArray(refs)) return [];
+  return Object.entries(refs).map(([ref, value]) => ({ ref, ...(value && typeof value === "object" ? value : { name: value }) }));
+}
+
+function candidateText(value) {
+  return [value?.name, value?.text, value?.label, value?.value].filter((item) => typeof item === "string");
+}
+
+export function resolveSnapshotLocator(locator, snapshot) {
+  if (!locator || typeof locator !== "object") throw locatorError("Browser locator is invalid");
+  if (locator.kind === "CSS") return locator.value;
+  const refs = refsFromSnapshot(snapshot);
+  const needle = locator.value;
+  const matches = refs.filter((entry) => {
+    const values = candidateText(entry);
+    if (locator.kind === "TEXT" || locator.kind === "LABEL") return values.some((value) => value === needle);
+    if (locator.kind === "ROLE") {
+      return entry.role === needle || values.some((value) => `${entry.role ?? ""} ${value}`.trim() === needle);
+    }
+    return false;
+  });
+  if (matches.length !== 1) {
+    throw locatorError(matches.length === 0 ? "Browser locator was not found" : "Browser locator was ambiguous");
+  }
+  return matches[0].ref;
+}
+
+export function snapshotRefs(snapshot) { return refsFromSnapshot(snapshot); }

package/src/adapters/agent-browser/process.js

@@ -0,0 +1,215 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  E_BROWSER_VERIFICATION_OUTPUT_LIMIT,
+  E_BROWSER_VERIFICATION_CANCELLED,
+  E_BROWSER_VERIFICATION_EXECUTION_FAILED,
+  E_BROWSER_VERIFICATION_PROVIDER_INVALID,
+  E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE,
+  E_BROWSER_VERIFICATION_RESULT_INVALID,
+  E_BROWSER_VERIFICATION_TIMEOUT,
+} from "../../core/error-codes.js";
+
+export const AGENT_BROWSER_PROCESS_LIMITS = Object.freeze({
+  maxStdoutBytes: 1024 * 1024,
+  maxStderrBytes: 64 * 1024,
+  terminationGraceMs: 150,
+  maxVersionBytes: 64 * 1024,
+  maxOutputChars: 50_000,
+});
+
+function processError(code, message) {
+  const error = new Error(message);
+  error.name = "AgentBrowserProcessError";
+  error.code = code;
+  return error;
+}
+
+function portableString(value, label) {
+  if (typeof value !== "string" || value.length === 0 || /\p{Cc}/u.test(value)) {
+    throw processError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, `${label} must be a non-empty portable string`);
+  }
+  return value;
+}
+
+export function assertAbsoluteRegularFile(value, label, fsImpl = fs) {
+  portableString(value, label);
+  if (!path.isAbsolute(value)) {
+    throw processError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, `${label} must be an absolute path`);
+  }
+  let link;
+  let stat;
+  try {
+    link = fsImpl.lstatSync(value);
+    stat = fsImpl.statSync(value);
+  } catch {
+    throw processError(E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE, `${label} is unavailable`);
+  }
+  if (link.isSymbolicLink?.() || !stat.isFile?.()) {
+    throw processError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, `${label} must be a regular file without symlink indirection`);
+  }
+  return value;
+}
+
+function bytes(chunk) {
+  return Buffer.isBuffer(chunk) ? chunk.byteLength : Buffer.byteLength(String(chunk));
+}
+
+function terminate(child) {
+  if (!child || typeof child.kill !== "function") return;
+  try { child.kill("SIGTERM"); } catch { /* exited between checks */ }
+  const timer = setTimeout(() => {
+    try { child.kill("SIGKILL"); } catch { /* preserve original failure */ }
+  }, AGENT_BROWSER_PROCESS_LIMITS.terminationGraceMs);
+  timer.unref?.();
+}
+
+function waitForClose(child) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve();
+    };
+    child?.once?.("close", finish);
+    const timer = setTimeout(finish, AGENT_BROWSER_PROCESS_LIMITS.terminationGraceMs + 500);
+    timer.unref?.();
+  });
+}
+
+function filteredEnvironment(overrides = {}, trustedEnvKeys = new Set()) {
+  const forbidden = new Set([
+    "AGENT_BROWSER_PROVIDER", "AGENT_BROWSER_PROFILE", "AGENT_BROWSER_RESTORE", "AGENT_BROWSER_STATE",
+    "AGENT_BROWSER_CDP", "AGENT_BROWSER_AUTO_CONNECT", "AGENT_BROWSER_PLUGINS", "AGENT_BROWSER_INIT_SCRIPTS",
+    "AGENT_BROWSER_EXTENSIONS", "AGENT_BROWSER_ALLOWED_DOMAINS", "AGENT_BROWSER_MAX_OUTPUT",
+    "AGENT_BROWSER_CONTENT_BOUNDARIES", "AGENT_BROWSER_NO_WEBMCP", "AGENT_BROWSER_EXECUTABLE_PATH",
+    "AGENT_BROWSER_SESSION", "AGENT_BROWSER_SCREENSHOT_DIR", "AGENT_BROWSER_DOWNLOAD_PATH",
+    "AGENT_BROWSER_ACTION_POLICY", "AGENT_BROWSER_CONFIRM_ACTIONS", "AGENT_BROWSER_ENGINE",
+    "AI_GATEWAY_API_KEY", "AI_GATEWAY_MODEL", "AI_GATEWAY_URL", "BROWSERBASE_API_KEY",
+    "BROWSERLESS_API_KEY", "BROWSER_USE_API_KEY", "KERNEL_API_KEY", "AGENT_BROWSER_CONFIG",
+  ]);
+  const env = {};
+  for (const [key, value] of Object.entries({ ...process.env, ...overrides })) {
+    if ((!forbidden.has(key) || trustedEnvKeys.has(key)) && typeof value === "string") env[key] = value;
+  }
+  return env;
+}
+
+export async function runAgentBrowserCommand(executablePath, args, {
+  cwd,
+  timeoutMs,
+  signal,
+  spawnImpl = nodeSpawn,
+  env,
+  maxStdoutBytes = AGENT_BROWSER_PROCESS_LIMITS.maxStdoutBytes,
+  maxStderrBytes = AGENT_BROWSER_PROCESS_LIMITS.maxStderrBytes,
+  fsImpl = fs,
+  trustedEnvKeys = [],
+} = {}) {
+  assertAbsoluteRegularFile(executablePath, "Agent Browser executable", fsImpl);
+  portableString(cwd, "Agent Browser cwd");
+  if (!path.isAbsolute(cwd)) throw processError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, "Agent Browser cwd must be absolute");
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string" || /\p{Cc}/u.test(arg))) {
+    throw processError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, "Agent Browser argv must be a portable string array");
+  }
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+    throw processError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, "Agent Browser timeout must be a positive integer");
+  }
+  if (signal?.aborted) throw processError(E_BROWSER_VERIFICATION_CANCELLED, "Agent Browser verification was cancelled");
+
+  let child;
+  try {
+    child = spawnImpl(executablePath, [...args], {
+      cwd,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: filteredEnvironment(env, new Set(trustedEnvKeys)),
+    });
+  } catch (error) {
+    throw processError(
+      error?.code === "ENOENT" ? E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE : E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE,
+      "Agent Browser executable could not be started",
+    );
+  }
+  if (!child?.stdout || !child?.stderr || typeof child.on !== "function") {
+    terminate(child);
+    throw processError(E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE, "Agent Browser process did not expose safe output streams");
+  }
+
+  return new Promise((resolve, reject) => {
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    const stdout = [];
+    let settled = false;
+    const timerRef = { value: null };
+    const cleanup = () => {
+      if (timerRef.value) clearTimeout(timerRef.value);
+      signal?.removeEventListener?.("abort", abortListener);
+      child.stdout.removeAllListeners?.("data");
+      child.stderr.removeAllListeners?.("data");
+    };
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      terminate(child);
+      child.stdout.resume?.();
+      child.stderr.resume?.();
+      waitForClose(child).then(() => reject(error));
+    };
+    const finish = (code, signalName) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (code !== 0) {
+        reject(processError(E_BROWSER_VERIFICATION_EXECUTION_FAILED, `Agent Browser command failed (${code ?? "null"}/${signalName ?? "none"})`));
+        return;
+      }
+      resolve({
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stdoutBytes,
+        stderrBytes,
+      });
+    };
+    const abortListener = () => fail(processError(E_BROWSER_VERIFICATION_CANCELLED, "Agent Browser verification was cancelled"));
+    child.stdout.on("data", (chunk) => {
+      stdoutBytes += bytes(chunk);
+      if (stdoutBytes > maxStdoutBytes) {
+        fail(processError(E_BROWSER_VERIFICATION_OUTPUT_LIMIT, "Agent Browser stdout exceeded its bound"));
+        return;
+      }
+      stdout.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    });
+    child.stderr.on("data", (chunk) => {
+      stderrBytes += bytes(chunk);
+      if (stderrBytes > maxStderrBytes) fail(processError(E_BROWSER_VERIFICATION_OUTPUT_LIMIT, "Agent Browser stderr exceeded its bound"));
+    });
+    child.once?.("error", () => fail(processError(E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE, "Agent Browser process failed")));
+    child.once?.("close", finish);
+    signal?.addEventListener?.("abort", abortListener, { once: true });
+    timerRef.value = setTimeout(() => fail(processError(E_BROWSER_VERIFICATION_TIMEOUT, "Agent Browser command timed out")), timeoutMs);
+    timerRef.value.unref?.();
+  });
+}
+
+export function parseAgentBrowserJson(stdout, label = "Agent Browser response") {
+  if (typeof stdout !== "string" || stdout.length > AGENT_BROWSER_PROCESS_LIMITS.maxStdoutBytes) {
+    throw processError(E_BROWSER_VERIFICATION_OUTPUT_LIMIT, `${label} exceeded its bound`);
+  }
+  let value;
+  try { value = JSON.parse(stdout); } catch { throw processError(E_BROWSER_VERIFICATION_RESULT_INVALID, `${label} was not valid JSON`); }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw processError(E_BROWSER_VERIFICATION_RESULT_INVALID, `${label} must be a JSON object`);
+  }
+  if (value.success !== true || !Object.prototype.hasOwnProperty.call(value, "data")
+    || Object.keys(value).some((key) => !["success", "data"].includes(key))) {
+    throw processError(E_BROWSER_VERIFICATION_RESULT_INVALID, `${label} had an unsupported response envelope`);
+  }
+  return value.data === undefined ? value : value.data;
+}
+
+export { filteredEnvironment, processError as agentBrowserProcessError };