@matt82198/aesop 0.1.0-beta.5 → 0.1.0

package/tools/verify_agent_inspector.py

@@ -0,0 +1,289 @@
+"""Browser-level proof for the Agent Inspector drawer (ui/web/dist/ + /api/agent).
+
+Drives the BUILT React app served by `python ui/serve.py` and exercises the
+whole vertical slice of the inspector in a real Chromium via Playwright:
+route + AgentsPanel mount, the real get_fleet_agents() → agents list (fed by a
+stubbed dash-extra.mjs), and the real GET /api/agent?id= endpoint reading a
+stubbed transcript. Everything is stubbed via a temp AESOP_ROOT so the proof is
+deterministic and never touches the operator's real fleet.
+
+One populated phase asserts:
+  (a) console clean (no errors / no XSS side effects)
+  (b) an agent row's "Inspect" button opens the drawer (role=dialog)
+  (c) the transcript TAIL renders (distinctive stub line is present)
+  (d) status is shown as TEXT ("running"), not color alone
+  (e) an XSS payload in the transcript is rendered as escaped TEXT — no <script>
+      /<img> element is injected and no onerror side effect fires
+  (f) focus moves INTO the dialog on open (activeElement inside it)
+  (g) Escape closes the drawer AND focus returns to the Inspect trigger
+
+Run: python tools/verify_agent_inspector.py             (exit 0 = proven, 1 = failed)
+     python tools/verify_agent_inspector.py --allow-skip (exit 0 = proven or skipped)
+
+Fails with exit 1 if playwright/chromium is unavailable (unless --allow-skip).
+"""
+import argparse
+import json
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+SERVE = REPO / "ui" / "serve.py"
+
+# Generous, CI-safe waits. A cold ubuntu runner (cold chromium, cold `node`
+# spawn for dash-extra.mjs, shared CPU) is much slower than a warm dev box, so
+# every server/selector wait below is sized for the slow path, env-overridable.
+SERVER_BOOT_TRIES = int(os.environ.get("AESOP_VERIFY_BOOT_TRIES", "150"))   # *0.2s = 30s
+SERVER_BOOT_SLEEP = 0.2
+SEL_TIMEOUT_MS = int(os.environ.get("AESOP_VERIFY_SEL_TIMEOUT_MS", "30000"))
+
+# The stub agent id (also the transcript filename stem). Full id — the frontend
+# fetches /api/agent?id=<this> and the backend prefix-globs agent-<id>*.jsonl.
+AGENT_ID = "inspectme12345abc"
+
+# A distinctive tail line the proof asserts on, plus an XSS payload that must be
+# rendered as inert text (never injected as real DOM).
+TAIL_MARKER = "DISTINCTIVE_TAIL_LINE_42"
+XSS_PAYLOAD = "<img src=x onerror=\"window.__xss_fired=true\"><script>window.__xss_fired=true</script>"
+
+# dash-extra.mjs stub: emits one agent so get_fleet_agents() lists a row.
+DASH_EXTRA_STUB = (
+    "console.log(JSON.stringify(["
+    + json.dumps({
+        "id": AGENT_ID,
+        "project": "aesop",
+        "status": "running",
+        "age_s": 12,
+        "hint": "wave-31 agent inspector drawer",
+        "startedAt": "2026-07-17T14:02:11.000Z",
+        "lastActivity": "2026-07-17T14:31:47.000Z",
+        "runtimeSeconds": 1776,
+        "tokensUsed": 48213,
+        "taskLabel": "Build the Agent Inspector drawer for aesop.",
+    })
+    + "]));\n"
+)
+
+
+def _real_console_errors(console_errors, failed_urls):
+    """Drop favicon/urlless-resource noise; surface real broken assets."""
+    non_favicon = [u for u in failed_urls if "favicon" not in u.lower()]
+    real = []
+    for e in console_errors:
+        low = e.lower()
+        if "favicon" in low:
+            continue
+        if "failed to load resource" in low and not non_favicon:
+            continue
+        real.append(e)
+    real.extend(f"failed resource: {u}" for u in non_favicon)
+    return real
+
+
+def free_port():
+    s = socket.socket()
+    s.bind(("127.0.0.1", 0))
+    port = s.getsockname()[1]
+    s.close()
+    return port
+
+
+def copy_dist(root: Path):
+    real_dist = REPO / "ui" / "web" / "dist"
+    if real_dist.is_dir():
+        shutil.copytree(real_dist, root / "ui" / "web" / "dist")
+
+
+def build_root():
+    """Fresh temp root with dist + a dash-extra stub + a stub transcript."""
+    root = Path(tempfile.mkdtemp(prefix="aesop-verify-inspector-"))
+    (root / "state").mkdir(exist_ok=True)
+    transcripts = root / "transcripts"
+    transcripts.mkdir(exist_ok=True)
+    (root / "dash").mkdir(exist_ok=True)
+    copy_dist(root)
+    (root / "dash" / "dash-extra.mjs").write_text(DASH_EXTRA_STUB, encoding="utf-8")
+
+    lines = [
+        json.dumps({"type": "user", "parentUuid": None,
+                    "message": {"content": "Build the Agent Inspector drawer for aesop."}}),
+        json.dumps({"type": "assistant", "model": "claude-haiku-4-5",
+                    "message": {"content": [{"type": "text", "text": "Reading the plan first."}]}}),
+        json.dumps({"type": "assistant",
+                    "message": {"content": f"{TAIL_MARKER} — progress update"}}),
+        json.dumps({"type": "assistant",
+                    "message": {"content": XSS_PAYLOAD}}),
+    ]
+    (transcripts / f"agent-{AGENT_ID}.jsonl").write_text(
+        "\n".join(lines) + "\n", encoding="utf-8")
+    return root
+
+
+def start_server(root: Path, port: int):
+    state_root = root / "state"
+    real_state = Path.home() / "aesop" / "state"
+    if state_root.resolve() == real_state.resolve():
+        raise RuntimeError("state dir resolved to real repo state (~aesop/state)")
+    env = dict(os.environ,
+               AESOP_ROOT=str(root),
+               AESOP_STATE_ROOT=str(state_root),
+               AESOP_TRANSCRIPTS_ROOT=str(root / "transcripts"),
+               AESOP_UI_COLLECT_INTERVAL="0.3",
+               PORT=str(port))
+    server = subprocess.Popen([sys.executable, str(SERVE)], env=env,
+                              stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    for _ in range(SERVER_BOOT_TRIES):
+        try:
+            socket.create_connection(("127.0.0.1", port), timeout=0.2).close()
+            return server
+        except OSError:
+            time.sleep(SERVER_BOOT_SLEEP)
+    server.kill()
+    raise RuntimeError("server never came up")
+
+
+def stop_server(server):
+    server.terminate()
+    try:
+        server.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        server.kill()
+
+
+def run_populated(pw, failures):
+    root = build_root()
+    port = free_port()
+    server = start_server(root, port)
+    browser = pw.chromium.launch(headless=True)
+    page = browser.new_page()
+    console_errors, failed_urls = [], []
+    page.on("console", lambda m: console_errors.append(m.text) if m.type == "error" else None)
+    page.on("pageerror", lambda e: console_errors.append(str(e)))
+    page.on("response", lambda r: failed_urls.append(r.url) if r.status >= 400 else None)
+    try:
+        page.goto(f"http://127.0.0.1:{port}/", wait_until="domcontentloaded")
+        try:
+            page.wait_for_selector("[data-testid='health-header']", timeout=SEL_TIMEOUT_MS)
+            page.evaluate("location.hash = '#/'")
+            # Agents panel is on Overview; the Inspect trigger appears per row.
+            page.wait_for_selector("[data-testid='agent-inspect-open']", timeout=SEL_TIMEOUT_MS)
+        except Exception as e:
+            failures.append(f"(b) agent row / inspect trigger never mounted: {e}")
+            return
+
+        # (b) open the drawer
+        try:
+            page.click("[data-testid='agent-inspect-open']")
+            page.wait_for_selector("[data-testid='agent-inspector']", timeout=SEL_TIMEOUT_MS)
+            dialog = page.locator("[data-testid='agent-inspector']")
+            assert dialog.get_attribute("role") == "dialog", "drawer is not role=dialog"
+            assert dialog.get_attribute("aria-modal") == "true", "drawer not aria-modal"
+        except Exception as e:
+            failures.append(f"(b) drawer did not open as a modal dialog: {e}")
+            return
+
+        # (c) transcript tail rendered (wait for the fetched detail)
+        try:
+            page.wait_for_selector("[data-testid='agent-inspector-transcript']", timeout=SEL_TIMEOUT_MS)
+            tail_text = page.inner_text("[data-testid='agent-inspector-transcript']")
+            assert TAIL_MARKER in tail_text, f"tail marker missing; got: {tail_text[:200]!r}"
+        except Exception as e:
+            failures.append(f"(c) transcript tail not rendered: {e}")
+
+        # (d) status shown as TEXT (not color alone)
+        try:
+            status_text = page.inner_text("[data-testid='agent-inspector-status']")
+            assert "running" in status_text.lower(), f"status text missing: {status_text!r}"
+        except Exception as e:
+            failures.append(f"(d) status not shown as text: {e}")
+
+        # (e) XSS payload is inert: no injected element, no side effect, text present
+        try:
+            xss_fired = page.evaluate("window.__xss_fired === true")
+            assert not xss_fired, "XSS onerror/script side effect fired"
+            injected = page.evaluate(
+                "document.querySelectorAll('[data-testid=\"agent-inspector-transcript\"] img,"
+                " [data-testid=\"agent-inspector-transcript\"] script').length")
+            assert injected == 0, f"{injected} raw HTML nodes injected from transcript"
+            body_has_text = page.evaluate(
+                "document.querySelector('[data-testid=\"agent-inspector-transcript\"]')"
+                ".textContent.includes('onerror')")
+            assert body_has_text, "XSS payload not rendered as visible text"
+        except Exception as e:
+            failures.append(f"(e) XSS not neutralised: {e}")
+
+        # (f) focus moved INTO the dialog on open
+        try:
+            focus_inside = page.evaluate(
+                "(() => { const d = document.querySelector('[data-testid=\"agent-inspector\"]');"
+                " return !!d && d.contains(document.activeElement); })()")
+            assert focus_inside, "focus did not move into the dialog"
+        except Exception as e:
+            failures.append(f"(f) focus not trapped into dialog: {e}")
+
+        # (g) Escape closes AND focus returns to the Inspect trigger
+        try:
+            page.keyboard.press("Escape")
+            page.wait_for_selector("[data-testid='agent-inspector']", state="detached", timeout=10000)
+            focus_on_trigger = page.evaluate(
+                "document.activeElement && document.activeElement.getAttribute('data-testid')"
+                " === 'agent-inspect-open'")
+            assert focus_on_trigger, "focus did not return to the Inspect trigger after close"
+        except Exception as e:
+            failures.append(f"(g) Escape-close / focus-restore failed: {e}")
+
+        # (a) console clean
+        time.sleep(0.4)
+        real = _real_console_errors(console_errors, failed_urls)
+        if real:
+            failures.append(f"(a) console errors: {real[:3]}")
+    finally:
+        browser.close()
+        stop_server(server)
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Browser-level proof for the Agent Inspector drawer")
+    parser.add_argument("--allow-skip", action="store_true",
+                        help="Allow skipping if playwright/chromium is unavailable")
+    args = parser.parse_args()
+
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        msg = "playwright missing — run `python -m playwright install chromium`, or pass --allow-skip"
+        print(f"SKIP: {msg}" if args.allow_skip else f"FAIL: {msg}")
+        return 0 if args.allow_skip else 1
+
+    failures = []
+    with sync_playwright() as pw:
+        try:
+            pw.chromium.launch(headless=True).close()
+        except Exception as e:
+            msg = f"chromium unavailable ({e}); run: python -m playwright install chromium"
+            print(f"SKIP: {msg}" if args.allow_skip else f"FAIL: {msg}")
+            return 0 if args.allow_skip else 1
+        run_populated(pw, failures)
+
+    if failures:
+        print("FAIL:")
+        for f in failures:
+            print("  -", f)
+        return 1
+
+    print("PROVEN: (a) console clean (b) Inspect opens a modal dialog "
+          "(c) transcript tail renders (d) status shown as text "
+          "(e) XSS payload rendered inert (no injected node/side effect) "
+          "(f) focus trapped into dialog (g) Escape closes + focus restored")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/verify_prboard.py

@@ -0,0 +1,344 @@
+"""Browser-level proof for the Wave PR Board view (ui/web/dist/ + /api/wave/prs).
+
+Drives the BUILT React app served by `python ui/serve.py` and exercises the
+full stack of the PR board — route wiring, component mount, the real
+GET /api/wave/prs endpoint (which runs `gh`), and rendering — in a real
+Chromium via Playwright. `gh` is stubbed through the AESOP_GH_BIN seam so the
+proof is deterministic regardless of the box's real GitHub state.
+
+Three phases, each a fresh server boot with its own fake gh:
+
+  Populated: fake gh emits fixture PRs (passing/failing/pending/draft) →
+    (a) console clean
+    (b) #/prs route renders the view + table with one row per PR
+    (c) CI status is color-INDEPENDENT: the words Passing/Failing/Pending are
+        present as text (not conveyed by color alone)
+    (d) top-blocker text ("CI failing") is shown
+    (e) a PR title is a real, keyboard-focusable <a> to the PR url
+    (f) no javascript: href leaks into the DOM
+
+  Empty (gh ok, zero PRs): fake gh emits [] →
+    (g) the "No open PRs" empty state renders, no table, clean console
+
+  Unavailable (gh un-authenticated): fake gh exits non-zero with an auth error →
+    (h) the "GitHub CLI unavailable" callout renders with the backend reason,
+        clean console
+
+Run: python tools/verify_prboard.py            (exit 0 = proven, 1 = failed)
+     python tools/verify_prboard.py --allow-skip (exit 0 = proven or skipped)
+
+Fails with exit 1 if playwright/chromium is unavailable (unless --allow-skip).
+"""
+import argparse
+import os
+import shutil
+import socket
+import stat
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+SERVE = REPO / "ui" / "serve.py"
+
+# Generous, CI-safe waits. A cold ubuntu runner (cold chromium, cold python
+# import, shared CPU) is much slower than a warm dev box, so every server/
+# selector wait below is sized for the slow path, overridable via env.
+SERVER_BOOT_TRIES = int(os.environ.get("AESOP_VERIFY_BOOT_TRIES", "150"))   # *0.2s = 30s
+SERVER_BOOT_SLEEP = 0.2
+SEL_TIMEOUT_MS = int(os.environ.get("AESOP_VERIFY_SEL_TIMEOUT_MS", "30000"))
+
+# Fixture PRs the fake `gh pr list` emits in the populated phase. Covers every
+# CI rollup state + a draft so the board's whole status vocabulary is exercised.
+FIXTURE_PR_JSON = """import json
+print(json.dumps([
+  {"number": 501, "title": "feat: PR board passing case", "headRefName": "feat/wave30-a",
+   "mergeable": "MERGEABLE", "isDraft": False, "url": "https://github.com/example/aesop/pull/501",
+   "createdAt": "2026-07-17T08:00:00Z", "reviewDecision": "REVIEW_REQUIRED",
+   "statusCheckRollup": [{"conclusion": "SUCCESS"}, {"conclusion": "SUCCESS"}]},
+  {"number": 502, "title": "fix: PR board failing case", "headRefName": "feat/wave30-b",
+   "mergeable": "CONFLICTING", "isDraft": False, "url": "https://github.com/example/aesop/pull/502",
+   "createdAt": "2026-07-16T18:00:00Z", "reviewDecision": "",
+   "statusCheckRollup": [{"conclusion": "SUCCESS"}, {"conclusion": "FAILURE"}]},
+  {"number": 503, "title": "wip: PR board pending draft", "headRefName": "feat/wave30-c",
+   "mergeable": "MERGEABLE", "isDraft": True, "url": "https://github.com/example/aesop/pull/503",
+   "createdAt": "2026-07-17T07:30:00Z", "reviewDecision": "",
+   "statusCheckRollup": [{"status": "IN_PROGRESS"}]}
+]))
+"""
+
+FIXTURE_EMPTY_JSON = "print('[]')\n"
+
+FIXTURE_AUTH_FAIL = """import sys
+sys.stderr.write("gh: To get started with GitHub CLI, please run: gh auth login\\n")
+sys.exit(1)
+"""
+
+
+def _real_console_errors(console_errors, failed_urls):
+    """Drop favicon/urlless-resource noise; surface real broken assets."""
+    non_favicon = [u for u in failed_urls if "favicon" not in u.lower()]
+    real = []
+    for e in console_errors:
+        low = e.lower()
+        if "favicon" in low:
+            continue
+        if "failed to load resource" in low and not non_favicon:
+            continue
+        real.append(e)
+    real.extend(f"failed resource: {u}" for u in non_favicon)
+    return real
+
+
+def free_port():
+    s = socket.socket()
+    s.bind(("127.0.0.1", 0))
+    port = s.getsockname()[1]
+    s.close()
+    return port
+
+
+def copy_dist(root: Path):
+    real_dist = REPO / "ui" / "web" / "dist"
+    if real_dist.is_dir():
+        shutil.copytree(real_dist, root / "ui" / "web" / "dist")
+
+
+def make_fake_gh(bin_dir: Path, script_body: str) -> Path:
+    """Write a fake `gh` executable and return its path — Linux-CI robust.
+
+    wave_prs.py invokes AESOP_GH_BIN directly as ``argv[0]`` via subprocess, so
+    the stub must be a file the *current* OS can exec on its own:
+
+      * Windows: a full-path ``gh.cmd`` batch that shells out to a python stub
+        (a bare extension-less script is not runnable by subprocess on Windows).
+      * POSIX (ubuntu CI): a python script whose first line is a ``#!`` shebang
+        pointing at this very interpreter, marked executable (chmod +x). The
+        previous ``gh.cmd`` was NOT executable on Linux — the kernel refused it
+        with EACCES, ``gh pr list`` failed, /api/wave/prs degraded to empty, and
+        the PR-table selector timed out. That was the CI failure this fixes.
+
+    Either way the stub ignores its args and emits the fixture, which is all
+    ``gh pr list`` needs for the proof.
+    """
+    bin_dir.mkdir(parents=True, exist_ok=True)
+    if os.name == "nt":
+        stub = bin_dir / "gh_stub.py"
+        stub.write_text(script_body, encoding="utf-8")
+        gh_cmd = bin_dir / "gh.cmd"
+        gh_cmd.write_text('@python "%~dp0gh_stub.py" %*\n', encoding="utf-8")
+        return gh_cmd
+    # POSIX: shebang + executable bit so the ubuntu runner can exec it directly.
+    gh = bin_dir / "gh"
+    gh.write_text(f"#!{sys.executable}\n{script_body}", encoding="utf-8")
+    gh.chmod(gh.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return gh
+
+
+def build_root(gh_script: str):
+    """Fresh temp root with dist + a fake gh; returns (root, gh_path)."""
+    root = Path(tempfile.mkdtemp(prefix="aesop-verify-prboard-"))
+    (root / "state").mkdir(exist_ok=True)
+    (root / "transcripts").mkdir(exist_ok=True)
+    (root / "dash").mkdir(exist_ok=True)
+    copy_dist(root)
+    (root / "dash" / "dash-extra.mjs").write_text(
+        "console.log(JSON.stringify([]));\n", encoding="utf-8")
+    gh_path = make_fake_gh(root / "fakebin", gh_script)
+    return root, gh_path
+
+
+def start_server(root: Path, port: int, gh_path: Path):
+    state_root = root / "state"
+    real_state = Path.home() / "aesop" / "state"
+    if state_root.resolve() == real_state.resolve():
+        raise RuntimeError("state dir resolved to real repo state (~aesop/state)")
+    env = dict(os.environ,
+               AESOP_ROOT=str(root),
+               AESOP_STATE_ROOT=str(state_root),
+               AESOP_TRANSCRIPTS_ROOT=str(root / "transcripts"),
+               AESOP_UI_COLLECT_INTERVAL="0.3",
+               AESOP_GH_BIN=str(gh_path),
+               PORT=str(port))
+    server = subprocess.Popen([sys.executable, str(SERVE)], env=env,
+                              stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    for _ in range(SERVER_BOOT_TRIES):
+        try:
+            socket.create_connection(("127.0.0.1", port), timeout=0.2).close()
+            return server
+        except OSError:
+            time.sleep(SERVER_BOOT_SLEEP)
+    server.kill()
+    raise RuntimeError("server never came up")
+
+
+def stop_server(server):
+    server.terminate()
+    try:
+        server.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        server.kill()
+
+
+def _boot(pw, gh_script):
+    """Boot a fresh server+page for one phase. Returns (server, root, browser,
+    page, console_errors, failed_urls). Caller must goto + assert + teardown."""
+    root, gh_path = build_root(gh_script)
+    port = free_port()
+    server = start_server(root, port, gh_path)
+    browser = pw.chromium.launch(headless=True)
+    page = browser.new_page()
+    console_errors, failed_urls = [], []
+    page.on("console", lambda m: console_errors.append(m.text) if m.type == "error" else None)
+    page.on("pageerror", lambda e: console_errors.append(str(e)))
+    page.on("response", lambda r: failed_urls.append(r.url) if r.status >= 400 else None)
+    page.goto(f"http://127.0.0.1:{port}/", wait_until="domcontentloaded")
+    return server, root, browser, page, console_errors, failed_urls, port
+
+
+def run_populated(pw, failures):
+    server, root, browser, page, console_errors, failed_urls, _ = _boot(pw, FIXTURE_PR_JSON)
+    try:
+        try:
+            page.wait_for_selector("[data-testid='health-header']", timeout=SEL_TIMEOUT_MS)
+            page.evaluate("location.hash = '#/prs'")
+            page.wait_for_selector("[data-testid='view-prboard']", timeout=SEL_TIMEOUT_MS)
+        except Exception as e:
+            failures.append(f"(b) PR board view never mounted: {e}")
+            return
+        # (b) table + one row per PR
+        try:
+            page.wait_for_selector("[data-testid='prboard-table']", timeout=SEL_TIMEOUT_MS)
+            rows = page.locator("[data-testid='prboard-row']").count()
+            assert rows == 3, f"expected 3 rows, got {rows}"
+        except Exception as e:
+            failures.append(f"(b) PR board table/rows wrong: {e}")
+        # (c) color-independent CI text labels present
+        try:
+            body = page.inner_text("[data-testid='prboard-table']")
+            for word in ("Passing", "Failing", "Pending"):
+                assert word in body, f"CI label '{word}' not shown as text"
+        except Exception as e:
+            failures.append(f"(c) CI status not color-independent: {e}")
+        # (d) top blocker text
+        try:
+            body = page.inner_text("[data-testid='prboard-table']")
+            assert "CI failing" in body, "top blocker 'CI failing' not shown"
+        except Exception as e:
+            failures.append(f"(d) blocker not shown: {e}")
+        # (e) PR title is a real, keyboard-focusable link to the url
+        try:
+            link = page.get_by_role("link", name="feat: PR board passing case")
+            assert link.get_attribute("href") == "https://github.com/example/aesop/pull/501"
+            link.focus()
+            focused_tag = page.evaluate("document.activeElement && document.activeElement.tagName")
+            assert focused_tag == "A", f"PR link not keyboard-focusable (active={focused_tag})"
+        except Exception as e:
+            failures.append(f"(e) PR title link/focus failed: {e}")
+        # (f) no javascript: href leaked
+        try:
+            bad = page.evaluate(
+                "Array.from(document.querySelectorAll('a[href]'))"
+                ".filter(a => a.href.toLowerCase().startsWith('javascript:')).length")
+            assert bad == 0, f"{bad} javascript: anchors present"
+        except Exception as e:
+            failures.append(f"(f) javascript: href leaked: {e}")
+        # (a) console clean
+        time.sleep(0.4)
+        real = _real_console_errors(console_errors, failed_urls)
+        if real:
+            failures.append(f"(a) populated console errors: {real[:3]}")
+    finally:
+        browser.close()
+        stop_server(server)
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def run_empty(pw, failures):
+    server, root, browser, page, console_errors, failed_urls, _ = _boot(pw, FIXTURE_EMPTY_JSON)
+    try:
+        try:
+            page.wait_for_selector("[data-testid='health-header']", timeout=SEL_TIMEOUT_MS)
+            page.evaluate("location.hash = '#/prs'")
+            page.wait_for_selector("[data-testid='prboard-empty']", timeout=SEL_TIMEOUT_MS)
+            text = page.inner_text("[data-testid='prboard-empty']")
+            assert "No open PRs" in text or "feature branch" in text, \
+                f"empty state text unexpected: {text!r}"
+            assert page.locator("[data-testid='prboard-table']").count() == 0, \
+                "table should not render in the empty state"
+        except Exception as e:
+            failures.append(f"(g) empty state failed: {e}")
+        time.sleep(0.4)
+        real = _real_console_errors(console_errors, failed_urls)
+        if real:
+            failures.append(f"(g) empty console errors: {real[:3]}")
+    finally:
+        browser.close()
+        stop_server(server)
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def run_unavailable(pw, failures):
+    server, root, browser, page, console_errors, failed_urls, _ = _boot(pw, FIXTURE_AUTH_FAIL)
+    try:
+        try:
+            page.wait_for_selector("[data-testid='health-header']", timeout=SEL_TIMEOUT_MS)
+            page.evaluate("location.hash = '#/prs'")
+            page.wait_for_selector("[data-testid='prboard-empty']", timeout=SEL_TIMEOUT_MS)
+            text = page.inner_text("[data-testid='prboard-empty']")
+            assert "GitHub CLI" in text, f"gh-unavailable callout missing: {text!r}"
+            assert "authenticated" in text.lower(), f"backend reason not surfaced: {text!r}"
+        except Exception as e:
+            failures.append(f"(h) gh-unavailable state failed: {e}")
+        time.sleep(0.4)
+        real = _real_console_errors(console_errors, failed_urls)
+        if real:
+            failures.append(f"(h) unavailable console errors: {real[:3]}")
+    finally:
+        browser.close()
+        stop_server(server)
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Browser-level proof for the Wave PR Board")
+    parser.add_argument("--allow-skip", action="store_true",
+                        help="Allow skipping if playwright/chromium is unavailable")
+    args = parser.parse_args()
+
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        msg = "playwright missing — run `python -m playwright install chromium`, or pass --allow-skip"
+        print(f"SKIP: {msg}" if args.allow_skip else f"FAIL: {msg}")
+        return 0 if args.allow_skip else 1
+
+    failures = []
+    with sync_playwright() as pw:
+        try:
+            pw.chromium.launch(headless=True).close()
+        except Exception as e:
+            msg = f"chromium unavailable ({e}); run: python -m playwright install chromium"
+            print(f"SKIP: {msg}" if args.allow_skip else f"FAIL: {msg}")
+            return 0 if args.allow_skip else 1
+        run_populated(pw, failures)
+        run_empty(pw, failures)
+        run_unavailable(pw, failures)
+
+    if failures:
+        print("FAIL:")
+        for f in failures:
+            print("  -", f)
+        return 1
+
+    print("PROVEN: (a) console clean (b) #/prs table renders row-per-PR "
+          "(c) CI status color-independent text (d) top blocker shown "
+          "(e) PR title keyboard-focusable link (f) no javascript: href "
+          "(g) empty state (no PRs) (h) gh-unavailable callout with reason")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/watch.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+/**
+ * Aesop watch — Launch the watchdog daemon
+ *
+ * Spawns bash daemons/run-watchdog.sh with inherited stdio (foreground mode).
+ * The daemon will run continuously and inherit the parent's stdin/stdout/stderr.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const CURRENT_DIR = process.cwd();
+
+(async function main() {
+  try {
+    // Verify we're in an aesop repo
+    const watchdogScript = path.join(CURRENT_DIR, 'daemons', 'run-watchdog.sh');
+    if (!fs.existsSync(watchdogScript)) {
+      console.error(`Error: watchdog script not found at ${watchdogScript}`);
+      console.error('Are you running this from the aesop root directory?');
+      process.exitCode = 1;
+      return;
+    }
+
+    console.log('Starting aesop watchdog daemon...\n');
+
+    // Spawn the watchdog script in foreground (inherit stdio)
+    const proc = spawn('bash', [watchdogScript], {
+      cwd: CURRENT_DIR,
+      stdio: 'inherit',
+      shell: true
+    });
+
+    // Exit with the watchdog process's exit code
+    proc.on('exit', (code) => {
+      process.exitCode = code || 0;
+    });
+
+    proc.on('error', (err) => {
+      console.error(`Error spawning watchdog: ${err.message}`);
+      process.exitCode = 1;
+    });
+  } catch (err) {
+    console.error(`Error launching watchdog: ${err.message}`);
+    process.exitCode = 1;
+  }
+})();