ci: stabilize bridge e2e

Use prebuilt bridge binaries in the e2e path so CI does not wait on cold go run startup, and restore the README as a fuller usage guide.

Author: bgwastu

.github/workflows/ci.yml

@@ -45,5 +45,9 @@ jobs:
         env:
           BUILD_TARGETS: windows_amd64
 
+      - name: Test bridge
+        working-directory: bridge
+        run: go test ./...
+
       - name: Run tests
         run: bun test

README.md

@@ -1,5 +1,51 @@
 # CYA
 
-AI agent shell relay. **Dev:** `bun install && bun dev` (needs **Go ≥ 1.22** so the bridge binaries can compile into `public/bin/`).
+Connect Your Agent. Give an AI agent temporary, user-approved command access to a machine.
 
-**Docker:** `docker build -t cya . && docker run --rm -p 8765:8765 -e BASE_URL=http://localhost:8765 cya`
+CYA starts an in-memory session, shows a one-line install command for the target machine, and gives you a prompt URL to paste into Claude Code, Codex, OpenClaw, or another agent. The bridge connects back over WebSocket and executes one command at a time through the HTTP API.
+
+## Quick Start
+
+```sh
+bun install
+bun dev
+```
+
+Open `http://localhost:8765`, create a session, run the displayed command on the target machine, then paste the generated prompt into your agent.
+
+The bridge binaries are built with Go, so local development needs **Go 1.22+**.
+
+## Docker
+
+```sh
+docker build -t cya .
+docker run --rm -p 8765:8765 -e BASE_URL=http://localhost:8765 cya
+```
+
+## Supported Targets
+
+- macOS Intel / Apple Silicon
+- Linux x64 / arm64
+- OpenWrt-style Linux MIPS / MIPS64, big-endian and little-endian
+- Windows x64
+
+## How It Works
+
+1. Browser creates a short-lived session code.
+2. Target machine runs the install command for its OS.
+3. The Go bridge connects to `/ws` and joins the session.
+4. Agents call `/api/session/:code/run` with `cmd`, `cmd_b64`, and optional `timeout`.
+5. The response includes merged stdout/stderr, `exit_code`, and `truncated`.
+
+Sessions are in-memory only. Nothing is persisted by the server.
+
+## Development
+
+```sh
+bun run typecheck
+bun test
+(cd bridge && go test ./...)
+bun run build
+```
+
+`bun run build` compiles bridge binaries into `public/bin/`.

server/app.test.ts

@@ -269,11 +269,8 @@ const wsUrl = `ws://127.0.0.1:${port}/ws`;
 let server: Bun.Subprocess | null = null;
 let bridge: Bun.Subprocess | null = null;
 
-const bridgeModuleDir = join(
-  dirname(fileURLToPath(import.meta.url)),
-  "..",
-  "bridge",
-);
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const bridgeModuleDir = join(repoRoot, "bridge");
 
 beforeAll(async () => {
   server = Bun.spawn(["bun", "run", "server/index.ts"], {
@@ -298,8 +295,9 @@ describe("full local server and bridge flow", () => {
     const session = await postJson(`${baseUrl}/api/session`, {}) as { code: string };
     expect(session.code).toMatch(/^[0-9a-f]{12}$/);
 
-    bridge = Bun.spawn(["go", "run", ".", session.code], {
-      cwd: bridgeModuleDir,
+    const bridgeCommand = await bridgeSpawnCommand(session.code);
+    bridge = Bun.spawn(bridgeCommand.argv, {
+      cwd: bridgeCommand.cwd,
       stdout: "inherit",
       stderr: "inherit",
       env: { ...process.env, BRIDGE_WS_URL: wsUrl },
@@ -396,3 +394,16 @@ function sleepCommand(seconds: number): string {
   }
   return `sleep ${seconds}`;
 }
+
+async function bridgeSpawnCommand(code: string): Promise<{
+  argv: string[];
+  cwd: string;
+}> {
+  const os = process.platform === "win32" ? "windows" : process.platform;
+  const exe = os === "windows" ? ".exe" : "";
+  const binary = join(repoRoot, "public", "bin", `cya-bridge-${os}-${process.arch}${exe}`);
+  if (await Bun.file(binary).exists()) {
+    return { argv: [binary, code], cwd: repoRoot };
+  }
+  return { argv: ["go", "run", ".", code], cwd: bridgeModuleDir };
+}