ci: require real-browser integration and saved QA on Linux and macOS

Adds a browser job (ubuntu/macos x Node 22/24) that installs pinned
agent-browser 0.33.2, installs Chromium, and runs doctor, test:integration
and test:qa, so skipped browser coverage can no longer pass CI. The unit
job runs npm run validate on Node 20/22/24.

makeBrowser now passes the renderer's env to agent-browser, and the e2e
test uses a short AGENT_BROWSER_SOCKET_DIR so long checkout paths stay
under the macOS Unix socket path limit.

Recovered from jig run 6806b9fd, which passed its gates but was held
locally by the UI's keep-local delivery.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: Steel-tech

.github/workflows/ci.yml

@@ -14,9 +14,8 @@ jobs:
     timeout-minutes: 10
     strategy:
       matrix:
-        # 20 is the supported floor; 22 exercises live streaming and CDP
-        # attach mode (global WebSocket client).
-        node-version: [20, 22]
+        # 20 is the supported floor; 22/24 support the global WebSocket client.
+        node-version: [20, 22, 24]
     steps:
       - name: Check out repository
         # v4.2.2
@@ -30,11 +29,66 @@ jobs:
         uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b
         with:
           node-version: ${{ matrix.node-version }}
-      - name: Run tests
-        run: npm test
-      - name: Validate shell syntax
-        run: bash -n scripts/*.sh
+      - name: Validate source, manifest, shell scripts, and tests
+        run: npm run validate
       - name: Run ShellCheck
         run: shellcheck scripts/*.sh
-      - name: Validate plugin manifest
-        run: node scripts/check-manifest.mjs
+
+  browser:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        node-version: [22, 24]
+    steps:
+      - name: Check out repository
+        # v4.2.2
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          persist-credentials: false
+      - name: Set up Node.js for agent-browser installation
+        # agent-browser 0.33.2 requires Node 24 to install its native CLI.
+        # v4.0.3
+        uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b
+        with:
+          node-version: 24
+      - name: Install pinned agent-browser
+        run: |
+          npm install --global --prefix "$RUNNER_TEMP/agent-browser" agent-browser@0.33.2
+          echo "$RUNNER_TEMP/agent-browser/bin" >> "$GITHUB_PATH"
+      - name: Install Chromium and platform prerequisites
+        shell: bash
+        run: |
+          if [[ "$RUNNER_OS" == "Linux" ]]; then
+            agent-browser install --with-deps
+          else
+            agent-browser install
+          fi
+      - name: Export installed Chromium executable
+        shell: bash
+        run: |
+          python3 - <<'PY' >> "$GITHUB_ENV"
+          import os
+          from pathlib import Path
+
+          cache = Path.home() / ".agent-browser" / "browsers"
+          binaries = [p for p in cache.rglob("*")
+                      if p.name in ("chrome", "Google Chrome for Testing")
+                      and p.is_file() and os.access(p, os.X_OK)]
+          if len(binaries) != 1:
+              raise SystemExit(f"Expected one installed Chromium executable, found {binaries}")
+          print(f"HERDR_BROWSER_CHROMIUM={binaries[0]}")
+          PY
+      - name: Set up Node.js under test
+        # v4.0.3
+        uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Check browser prerequisites
+        run: npm run doctor
+      - name: Require real-browser integration coverage
+        run: npm run test:integration
+      - name: Require saved QA browser coverage
+        run: npm run test:qa

README.md

@@ -499,6 +499,7 @@ npm run doctor
 npm run build
 npm run validate
 npm run test:integration
+npm run test:qa
 herdr plugin link .
 ```
 
@@ -514,7 +515,15 @@ browser coverage; optional browser tests skip when their prerequisites are
 unavailable. `npm run test:integration` requires both an installed Chrome or
 Chromium and agent-browser with its engine installed, on Node 22+. It fails
 instead of silently skipping either real-browser path. Tests use a local HTTP
-fixture and isolated browser sessions.
+fixture and isolated browser sessions. `npm run test:qa` requires agent-browser
+with its engine installed and runs saved desktop/mobile scenarios, including
+assertion failures and browser error evidence. CI installs pinned agent-browser
+0.33.2 using Node 24, then tests the plugin on Node 22/24 on Linux and macOS.
+
+Before release, require local validation, both strict browser commands, and the
+hosted CI matrix to pass for the reviewed commit. A passing suite with browser
+coverage skipped is insufficient. Manually verify Kitty graphics and symbol
+rendering in Herdr on macOS and Linux.
 
 For backend choices and the remaining readiness work, see the
 [readiness assessment](docs/readiness.md).

bin/renderer.mjs

@@ -423,7 +423,7 @@ export function formatNetworkFailure({ method, url, status }) {
 
 // --- agent-browser access ---
 
-export function makeBrowser(session, bin = "agent-browser") {
+export function makeBrowser(session, bin = "agent-browser", env = process.env) {
 	// Console rings on noisy pages reach several MB — Node's 1 MiB default
 	// maxBuffer would throw on every tick and freeze the pane for good.
 	const maxBuffer = 16 * 1024 * 1024;
@@ -446,7 +446,7 @@ export function makeBrowser(session, bin = "agent-browser") {
 		const { stdout } = await pExecFile(
 			bin,
 			["--session", session, "batch", "--bail", "--json", ...cmds],
-			{ timeout, maxBuffer },
+			{ timeout, maxBuffer, env },
 		);
 		const arr = parse(stdout, "batch output");
 		for (const r of arr) {
@@ -464,6 +464,7 @@ export function makeBrowser(session, bin = "agent-browser") {
 			{
 				timeout: 10_000,
 				maxBuffer,
+				env,
 			},
 		);
 		const parsed = parse(stdout, "output");
@@ -541,6 +542,7 @@ export function makeBrowser(session, bin = "agent-browser") {
 				const { stdout } = await pExecFile(bin, ["session", "list", "--json"], {
 					timeout: 10_000,
 					maxBuffer,
+					env,
 				});
 				// Exact match only: a substring hit (herdr-ws-w2 vs herdr-ws-w22)
 				// would make the pane attach and auto-create a session it must not.
@@ -592,7 +594,7 @@ export class Renderer {
 		this.browser =
 			this.backend === "attach"
 				? makeCdpBrowser(this.cdpEndpoint)
-				: makeBrowser(this.session, this.bin);
+				: makeBrowser(this.session, this.bin, this.env);
 		// Attach mode observes a browser someone else owns: ownership is never
 		// claimed, so the quit path can never close a stranger's session.
 		this.ownershipEnabled = this.backend !== "attach";
@@ -1883,6 +1885,7 @@ export class Renderer {
 		try {
 			spawnSync(this.bin, ["--session", this.session, "close"], {
 				timeout: 2_000,
+				env: this.env,
 			});
 		} catch {
 			/* already gone */

docs/readiness.md

@@ -36,13 +36,33 @@ own Chrome engine; a second bundled distribution is unnecessary.
 - Limit test discovery to this checkout's `tests/` directory; Node 20 otherwise
   traverses hidden nested worktrees and runs unrelated, stale test copies.
 
+## Automated readiness gates
+
+CI runs `npm run validate` on Linux with Node 20, 22, and 24. This checks source
+and shell syntax, the plugin manifest, ShellCheck, and the complete test suite.
+Separate browser jobs run on Linux and macOS with Node 22 and 24. They install
+pinned agent-browser 0.33.2 under Node 24, install its Chromium engine (including
+Linux system dependencies), and export the installed executable through
+`HERDR_BROWSER_CHROMIUM` before switching to the Node version under test.
+
+Every browser job runs `npm run doctor`, `npm run test:integration`, and
+`npm run test:qa`. The strict test commands require real local Chromium,
+shared-session streaming, and desktop/mobile saved QA coverage; missing
+prerequisites and installation failures fail the job instead of skipping that
+coverage. Existing tests use local fixtures and clean up their browser sessions.
+
+Readiness requires local validation and both strict browser commands to pass,
+plus a passing hosted matrix for the exact commit being reviewed. Configuring
+these gates does not establish that they have passed. Before release, manually
+verify Kitty graphics and symbol rendering in Herdr on macOS and Linux; hosted
+browser tests do not verify terminal display quality or pane interaction.
+
 ## Next recommendations, in priority order
 
-1. **Release compatibility matrix.** Exercise macOS and Linux, Node 22/24,
-   supported agent-browser versions, and Kitty/symbol rendering in Herdr.
-   Current CI has Node 20/22 but does not install agent-browser, so its passing
-   status alone cannot prove shared-session integration. Adopting the strict
-   integration command in hosted CI is a separate workflow change.
+1. **Release compatibility checks.** Complete the manual Kitty/symbol checks
+   in Herdr on macOS and Linux. Hosted CI now covers both platforms on Node
+   22/24 with agent-browser 0.33.2; expand agent-browser version coverage when
+   claiming support for additional versions.
 2. **CDP transport correctness.** HTTP discovery currently uses `node:http`
    even for an HTTPS input and assumes the local debugging port. Implement
    actual HTTPS discovery with transport tests before advertising secured

tests/renderer.test.mjs

@@ -752,7 +752,7 @@ test("cleanup closes only self-created sessions and removes shot files", () => {
 	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hb-close-"));
 	const stub = path.join(dir, "ab-stub");
 	const logf = path.join(dir, "log");
-	fs.writeFileSync(stub, `#!/usr/bin/env bash\necho "$@" >> "${logf}"\n`);
+	fs.writeFileSync(stub, `#!/bin/sh\necho "$@" >> "${logf}"\n`);
 	fs.chmodSync(stub, 0o755);
 	const mk = () => quiet(mkRenderer());
 	const own = mk();
@@ -1397,13 +1397,20 @@ test("e2e: goLive receives pushed frames and console from a real session", {
 }, async () => {
 	assert.ok(hasAgentBrowser && canCdp, "integration requires agent-browser and Node 22+");
 	const session = `hb-itest-${process.pid}`;
+	// Keep Unix socket paths below macOS's limit even with a long checkout HOME.
+	const socketDir = fs.mkdtempSync("/tmp/hb-s-");
+	const env = {
+		...process.env,
+		HERDR_BROWSER_SESSION: session,
+		AGENT_BROWSER_SOCKET_DIR: socketDir,
+	};
 	const { execFile: ef } = await import("node:child_process");
 	const ab = (args) =>
 		new Promise((res, rej) =>
 			ef(
 				"agent-browser",
 				["--session", session, ...args],
-				{ timeout: 15_000 },
+				{ timeout: 15_000, env },
 				(e, so) => (e ? rej(e) : res(so)),
 			),
 		);
@@ -1412,7 +1419,7 @@ test("e2e: goLive receives pushed frames and console from a real session", {
 		res.end("<!doctype html><title>Browser stream test</title><h1>Local browser fixture</h1><textarea aria-label='Text'></textarea>");
 	});
 	await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
-	const r = quiet(mkRenderer({ HERDR_BROWSER_SESSION: session }));
+	const r = quiet(mkRenderer(env));
 	const streamEvents = {};
 	const onStreamMessage = r.onStreamMessage.bind(r);
 	r.onStreamMessage = (message) => {
@@ -1472,7 +1479,9 @@ test("e2e: goLive receives pushed frames and console from a real session", {
 	} finally {
 		r.dropLive();
 		await ab(["close"]).catch(() => {});
+		r.cleanup();
 		await new Promise((resolve) => server.close(resolve));
+		fs.rmSync(socketDir, { recursive: true, force: true });
 	}
 });