@agent-flow-board/bridge 0.0.0-stage → 0.2.0

package/dist/checks/browser.js

@@ -0,0 +1,170 @@
+// THE BROWSER OF A CHECK: ONE CHROMIUM SERVER STARTED BY THE PARENT, WHICH THE SANDBOXED CHILD ONLY CONNECTS TO.
+// Playwright is not a dependency of the bridge (it is large and most people never run a check). It is found next to the bridge when it is there,
+// and otherwise installed once into ~/.agent-flow-board/checks/runtime. Nothing in this file imports Playwright at load time.
+// -- DEP-MODULES -- //
+import { execFile, spawn } from 'node:child_process';
+import { existsSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+// -- MODULES -- //
+import { checksHome, ensureDir } from './paths.js';
+// -- CONSTANTS -- //
+/** The Playwright version the runtime install pins, so a check behaves the same on every machine. */
+const PLAYWRIGHT_VERSION = '1.64.0';
+const INSTALL_TIMEOUT_MS = 10 * 60_000;
+// -- FUNCTIONS -- //
+/** Where the runtime install lives. It is a folder of the bridge's own state, never a repo. */
+const runtimeDir = () => join(checksHome(), 'runtime');
+const looksInstalled = (nodeModules) => existsSync(join(nodeModules, 'playwright-core', 'package.json'));
+/**
+ * The node_modules folder that holds playwright-core (and @playwright/test when it is there): next to the bridge first, then the runtime
+ * install. The sandboxed child is allowed to read this folder and nothing else outside its own. Null when Playwright is not installed anywhere.
+ */
+export function playwrightRuntimeDir() {
+    try {
+        const pkg = createRequire(import.meta.url).resolve('playwright-core/package.json');
+        // .../node_modules/playwright-core/package.json -> .../node_modules
+        return dirname(dirname(pkg));
+    }
+    catch {
+        /* Not next to the bridge: try the runtime install */
+    }
+    const own = join(runtimeDir(), 'node_modules');
+    return looksInstalled(own) ? own : null;
+}
+/** Loads playwright-core from the folder playwrightRuntimeDir names, by absolute path. */
+export async function loadPlaywright() {
+    const dir = playwrightRuntimeDir();
+    if (!dir)
+        throw new Error('Playwright is not installed yet. Run "agent-flow-board check setup" and it will install it.');
+    const req = createRequire(join(dir, 'package.json'));
+    return req(join(dir, 'playwright-core'));
+}
+/**
+ * A browser the parent starts, so a check's process only connects to it and never has to start a program itself.
+ * Every host except the preview's (and the hosts named) is unresolvable, whatever a check does with routes.
+ */
+export async function launchBrowserServer({ headed = false, hosts = [] } = {}) {
+    const { chromium } = await loadPlaywright();
+    const exclude = [...new Set(['127.0.0.1', 'localhost', ...hosts])]
+        .map((h) => `EXCLUDE ${h}`)
+        .join(', ');
+    const server = await chromium.launchServer({
+        headless: !headed,
+        args: [
+            `--host-resolver-rules=MAP * ~NOTFOUND, ${exclude}`,
+            '--disable-background-networking',
+            '--no-first-run'
+        ]
+    });
+    return { wsEndpoint: () => server.wsEndpoint(), close: () => server.close() };
+}
+/** Says whether an installer failure looks like no network or a proxy, so the one-line error can tell the person what to look at. */
+export function describeInstallFailure(output) {
+    if (/proxy|407|tunnel|ECONNRESET|self[- ]signed|certificate/i.test(output))
+        return 'it looks like a proxy problem (check HTTPS_PROXY and the proxy settings)';
+    if (/ENOTFOUND|EAI_AGAIN|ENETUNREACH|ECONNREFUSED|ETIMEDOUT|getaddrinfo|offline|network/i.test(output))
+        return 'it looks like this machine is offline';
+    return 'see the last lines above';
+}
+/** Runs a program with the exact arguments (no shell, no stdin) and sends every output line to `log`. Resolves with the exit code and the last output. */
+function runLogged(file, args, log, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(file, args, {
+            cwd,
+            shell: false,
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        let tail = '';
+        const feed = (chunk) => {
+            for (const line of chunk.toString('utf8').split(/\r?\n/)) {
+                const t = line.trim();
+                if (!t)
+                    continue;
+                tail = `${tail}\n${t}`.slice(-2000);
+                log(t);
+            }
+        };
+        child.stdout.on('data', feed);
+        child.stderr.on('data', feed);
+        const timer = setTimeout(() => child.kill(), INSTALL_TIMEOUT_MS);
+        child.on('error', (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({ code, tail });
+        });
+    });
+}
+/** The npm that belongs to this Node: its npm-cli.js, so no shell is needed. Null when it is not where Node keeps it. */
+function npmCli() {
+    const root = dirname(process.execPath);
+    const candidates = [
+        join(root, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+        join(root, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js')
+    ];
+    return candidates.find((c) => existsSync(c)) ?? null;
+}
+/**
+ * Installs Playwright into the runtime folder of the bridge's state.
+ * This is the ONE place npm is used: it installs a runtime for the installed bridge into ~/.agent-flow-board, never into a repo,
+ * so the Yarn-only rule of the repos does not apply here.
+ */
+async function installRuntime(log) {
+    const dir = ensureDir(runtimeDir());
+    const manifest = join(dir, 'package.json');
+    if (!existsSync(manifest))
+        writeFileSync(manifest, JSON.stringify({ private: true }, null, 2));
+    log(`Installing Playwright ${PLAYWRIGHT_VERSION} into ${dir} (first use only)...`);
+    // @playwright/test brings the expect that checks use; playwright-core is what the parent drives
+    const npmArgs = [
+        'install',
+        '--no-audit',
+        '--no-fund',
+        '--prefix',
+        dir,
+        `playwright-core@${PLAYWRIGHT_VERSION}`,
+        `@playwright/test@${PLAYWRIGHT_VERSION}`
+    ];
+    const cli = npmCli();
+    const out = await new Promise((resolve) => {
+        const done = (error, stdout, stderr) => resolve({ error, text: `${stdout}\n${stderr}` });
+        if (cli)
+            execFile(process.execPath, [cli, ...npmArgs], { windowsHide: true, timeout: INSTALL_TIMEOUT_MS, shell: false }, (e, so, se) => done(e, so, se));
+        else
+            execFile('npm', npmArgs, { windowsHide: true, timeout: INSTALL_TIMEOUT_MS, shell: process.platform === 'win32' }, (e, so, se) => done(e, so, se));
+    });
+    if (out.error || !looksInstalled(join(dir, 'node_modules'))) {
+        const last = out.text.trim().split('\n').slice(-3).join(' ').slice(0, 300);
+        throw new Error(`Could not install Playwright: ${describeInstallFailure(out.text)}. ${last}`);
+    }
+}
+/**
+ * Makes sure Playwright and its Chromium are there. The first use installs them (a few hundred megabytes, with progress lines in `log`);
+ * later uses return at once. Never prompts. A failure is one Error that says whether it looks like offline or a proxy.
+ */
+export async function ensureBrowser(log = () => { }) {
+    if (!playwrightRuntimeDir())
+        await installRuntime(log);
+    const dir = playwrightRuntimeDir();
+    if (!dir)
+        throw new Error('Playwright was installed but cannot be found.');
+    const { chromium } = await loadPlaywright();
+    try {
+        if (existsSync(chromium.executablePath()))
+            return;
+    }
+    catch {
+        /* No executable path known yet: install below */
+    }
+    log('Installing the Chromium browser for Playwright (first use only)...');
+    const cli = join(dir, 'playwright-core', 'cli.js');
+    if (!existsSync(cli))
+        throw new Error('Playwright is installed but its installer (cli.js) is missing. Remove the runtime folder and try again.');
+    const { code, tail } = await runLogged(process.execPath, [cli, 'install', 'chromium'], log).catch((e) => ({ code: -1, tail: String(e) }));
+    if (code !== 0)
+        throw new Error(`Could not install the Chromium browser: ${describeInstallFailure(tail)}. ${tail.split('\n').slice(-2).join(' ').trim().slice(0, 300)}`);
+}

package/dist/checks/child.js

@@ -0,0 +1,211 @@
+// RUNS ONE CHECK FILE IN ITS OWN PROCESS, started by sandbox.ts with Node's permission model on (dist/checks/child.js).
+// It reads one job from stdin (the saved sign-in is handed over there, never written to disk here), drives the page, writes its
+// result and its pictures into the run folder, and prints one line per event. It never sees the board or any token.
+// Under the permission model there are no child processes, no worker threads and no file access outside the folders sandbox.ts names,
+// and the only environment variable it reads is AFB_PLAYWRIGHT_DIR. It imports nothing that touches the bridge's token store.
+// -- DEP-MODULES -- //
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+// -- MODULES -- //
+import { guardContext, pageForCheck, unwrap } from './guard.js';
+import { redact } from './redact.js';
+// -- CONSTANTS -- //
+const CHECK_LIMIT_MS = 120_000;
+const MAX_SHOT_HEIGHT = 2400;
+// -- FUNCTIONS -- //
+const readStdin = () => new Promise((resolve) => {
+    let s = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (d) => (s += d));
+    process.stdin.on('end', () => resolve(s));
+});
+const messageOf = (e) => (e instanceof Error ? e.message : String(e));
+async function main() {
+    const job = JSON.parse(await readStdin());
+    const needles = job.needles ?? [];
+    const extraHosts = job.extraHosts ?? [];
+    const origin = new URL(job.baseUrl).origin;
+    // PLAYWRIGHT: the parent names the node_modules folder that holds it; it is the only place outside the run folder this process can read
+    const pwDir = process.env.AFB_PLAYWRIGHT_DIR;
+    if (!pwDir)
+        throw new Error('The parent did not say where Playwright is.');
+    const req = createRequire(import.meta.url);
+    const { chromium } = req(join(pwDir, 'playwright-core'));
+    // expect() comes with @playwright/test. Without it a check that calls expect gets one plain sentence
+    let realExpect;
+    try {
+        realExpect = req(join(pwDir, '@playwright', 'test')).expect;
+    }
+    catch {
+        realExpect = () => {
+            throw new Error('expect() needs @playwright/test, which is not installed next to Playwright. Run "agent-flow-board check setup".');
+        };
+    }
+    // expect() needs the real locator, so it is given one here, and the check only ever sees the matchers
+    const checkExpect = Object.assign((value, message) => realExpect(unwrap(value), message), {
+        soft: (value, message) => realExpect.soft?.(unwrap(value), message),
+        poll: (fn, options) => realExpect.poll?.(fn, options)
+    });
+    const out = (event) => process.stdout.write(`EVENT ${JSON.stringify(event)}\n`);
+    const say = (m) => out({ type: 'log', text: redact(String(m), needles).slice(0, 600) });
+    const shotsDir = join(job.runDir, 'shots');
+    mkdirSync(shotsDir, { recursive: true });
+    const steps = [];
+    const lines = [];
+    let n = 0;
+    let page;
+    let expiredSeen = false;
+    let counts = { writes: 0, outside: 0 };
+    async function takeShot(caption) {
+        if (!page)
+            return null;
+        const file = `${String(++n).padStart(2, '0')}.jpg`;
+        try {
+            const height = await page.evaluate(() => document.documentElement.scrollHeight);
+            const bytes = await page.screenshot({
+                type: 'jpeg',
+                quality: 55,
+                fullPage: true,
+                ...(height > MAX_SHOT_HEIGHT
+                    ? { clip: { x: 0, y: 0, width: job.viewport.width, height: MAX_SHOT_HEIGHT } }
+                    : {})
+            });
+            writeFileSync(join(shotsDir, file), bytes);
+            return { file, caption };
+        }
+        catch {
+            return null;
+        }
+    }
+    let result = 'pass';
+    let reason;
+    const started = Date.now();
+    // The browser was started by the tool; this process only connects to it, so it never has to start a program itself
+    const browser = await chromium.connect(job.ws);
+    try {
+        const ctx = await browser.newContext({
+            baseURL: job.baseUrl,
+            viewport: job.viewport,
+            storageState: job.storageState ?? undefined,
+            serviceWorkers: 'block'
+        });
+        // ChildJob has no allowWrites: a check run in the sandbox never writes
+        counts = await guardContext(ctx, { origin, allowWrites: false, extraHosts, onBlocked: say });
+        const real = await ctx.newPage();
+        page = real;
+        let violation = null;
+        // A page that ends up anywhere but the app under test (file:, chrome:, view-source:) fails the run
+        real.on('framenavigated', (f) => {
+            try {
+                const u = new URL(f.url());
+                if (u.protocol !== 'about:' &&
+                    (!['http:', 'https:'].includes(u.protocol) ||
+                        (u.origin !== origin && !extraHosts.includes(u.hostname))))
+                    violation = `The page went to ${u.protocol}//${u.host}, which is not the app under test.`;
+            }
+            catch {
+                /* about:blank and the like */
+            }
+        });
+        // A signed-in run that is sent to a sign-in page has an expired sign-in
+        real.on('framenavigated', (f) => {
+            try {
+                if (f === real.mainFrame() &&
+                    job.storageState &&
+                    /\/(sign-?in|log-?in|login|auth)(\/|$|\?)/i.test(new URL(f.url()).pathname))
+                    expiredSeen = true;
+            }
+            catch {
+                /* about:blank and the like */
+            }
+        });
+        const step = async (name, fn) => {
+            const t0 = Date.now();
+            try {
+                await fn();
+                const shot = await takeShot(name);
+                steps.push({ name, status: 'pass', ms: Date.now() - t0, shot: shot?.file ?? null });
+                out({ type: 'step', name, status: 'pass', ms: Date.now() - t0 });
+            }
+            catch (e) {
+                const shot = await takeShot(`${name} (failed)`);
+                const error = redact(messageOf(e).split('\n').slice(0, 4).join(' '), needles).slice(0, 500);
+                steps.push({ name, status: 'fail', ms: Date.now() - t0, shot: shot?.file ?? null, error });
+                out({ type: 'step', name, status: 'fail', ms: Date.now() - t0, error });
+                throw e;
+            }
+        };
+        const shot = async (caption = 'Shot') => {
+            const s = await takeShot(caption);
+            if (s)
+                steps.push({ name: caption, status: 'shot', ms: 0, shot: s.file });
+        };
+        const log = (m) => {
+            const t = redact(String(m), needles);
+            lines.push(t);
+            say(t);
+        };
+        const fn = (await import(pathToFileURL(job.checkFile).href)).default;
+        if (typeof fn !== 'function')
+            throw new Error('A check file must export default an async function({ page, step, shot, expect, log, baseUrl }).');
+        let timer;
+        try {
+            await Promise.race([
+                fn({
+                    page: pageForCheck(real, { origin, extraHosts }),
+                    step,
+                    shot,
+                    expect: checkExpect,
+                    log,
+                    baseUrl: job.baseUrl
+                }),
+                new Promise((_, rej) => (timer = setTimeout(() => rej(new Error('The check took longer than 2 minutes.')), CHECK_LIMIT_MS)))
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (violation)
+            throw new Error(violation);
+        if (!steps.length) {
+            const s = await takeShot('End of the check');
+            if (s)
+                steps.push({ name: 'End of the check', status: 'shot', ms: 0, shot: s.file });
+        }
+    }
+    catch (e) {
+        result = 'fail';
+        reason = redact(messageOf(e).split('\n').slice(0, 4).join(' '), needles).slice(0, 700);
+        if (!steps.some((s) => s.status === 'fail') && page) {
+            const s = await takeShot('Where it stopped');
+            if (s)
+                steps.push({ name: 'Where it stopped', status: 'shot', ms: 0, shot: s.file });
+        }
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+    if (result === 'fail' && expiredSeen)
+        reason =
+            `The saved sign-in no longer works: the app sent the browser to its sign-in page. Sign in again and rerun. (${reason ?? ''})`.trim();
+    const final = {
+        schema: 1,
+        result,
+        reason: reason ?? null,
+        durationMs: Date.now() - started,
+        steps,
+        log: lines.join('\n'),
+        blockedWrites: counts.writes,
+        blockedOutside: counts.outside
+    };
+    writeFileSync(join(job.runDir, 'result.json'), JSON.stringify(final, null, 1));
+    out({ type: 'done', result });
+}
+main().then(
+// Nothing else is waiting, so end now instead of waiting for stray timers
+() => process.exit(0), (e) => {
+    process.stderr.write(`${messageOf(e).slice(0, 600)}\n`);
+    process.exit(1);
+});

package/dist/checks/command.js

@@ -0,0 +1,280 @@
+// THE `check` COMMAND GROUP: connect, run, pull, bind, watch, status, doctor, clear, setup
+// Loaded only when the first argument is `check`, so the hooks and the MCP forwarder never load any of it (and never load Playwright).
+// Nothing here waits on a terminal: every command takes its input from flags and ends on its own.
+// -- DEP-MODULES -- //
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+// -- MODULES -- //
+import { verifyAudit } from './audit.js';
+import { bindFolder, listBindings, pinStatus } from './bind.js';
+import { ensureBrowser, playwrightRuntimeDir } from './browser.js';
+import { connectChecks, loadRunnerToken, runnerAccount } from './connect.js';
+import { forgetConnection, listConnections, recordConnection } from './connections.js';
+import { ORG_SLUG, checksHome, scriptPath } from './paths.js';
+import { pinFiles, resolveProjectConfig } from './recipe.js';
+import { runCheck } from './run.js';
+import { clearRuns, sweepOrphans } from './scope.js';
+import { permissionFlag } from './sandbox.js';
+import { watchChecks } from './watch.js';
+// -- CONSTANTS -- //
+export const CHECK_USAGE = [
+    'Usage: agent-flow-board check <command>',
+    '  connect --server <url> --org <slug> [--project KEY,KEY] [--json]   make this machine a runner (an agent approves the code)',
+    '  run <item> <key> --server <url> --org <slug> [--step 1.2] [--run <id>] [--dir <repo>] [--json]   run one check in this repo',
+    '  pull <item> <key> --server <url> --org <slug> [--accept-hash <sha256>]   read the board copy of a script; accept it by hash',
+    '  bind --org <slug> --project <KEY> [--dir <repo>]   remember the folder of a board project for "check watch"',
+    '  watch [--parallel N] [--once]   take queued runs from the boards this machine is connected to',
+    '  status [--json]  |  doctor [--fix] [--json]  |  clear [--all]  |  setup  |  disconnect --server <url> --org <slug>'
+].join('\n');
+// -- FUNCTIONS -- //
+/** Runs one check command and returns the exit code: 0 done, 1 a check failed or a problem was listed, 2 could not run. */
+export async function checkMain(ctx) {
+    const { args, log, out } = ctx;
+    const sub = args[0];
+    const flag = (name) => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined);
+    const has = (name) => args.includes(name);
+    const json = has('--json');
+    const need = (name) => {
+        const v = flag(name);
+        if (!v || v.startsWith('--'))
+            throw new Error(`Say ${name} <value>.`);
+        return v;
+    };
+    const server = () => {
+        const s = flag('--server') ?? process.env.AFB_SERVER;
+        if (!s)
+            throw new Error('Say which board to use: --server https://board.example.com (or set AFB_SERVER).');
+        return s.replace(/\/$/, '');
+    };
+    const org = () => {
+        const o = need('--org');
+        if (!ORG_SLUG.test(o))
+            throw new Error('--org takes an organisation slug: lowercase letters, digits and dashes.');
+        return o;
+    };
+    try {
+        if (sub === 'connect') {
+            const s = server();
+            const o = org();
+            const projects = flag('--project')
+                ?.split(',')
+                .map((p) => p.trim())
+                .filter(Boolean);
+            const done = await connectChecks({
+                server: s,
+                org: o,
+                projects,
+                json,
+                store: ctx.store,
+                fetch: ctx.fetch,
+                log,
+                out
+            });
+            recordConnection({ server: s, org: o, name: done.name });
+            return 0;
+        }
+        if (sub === 'disconnect') {
+            const s = server();
+            const o = org();
+            ctx.store.delete(runnerAccount(s, o));
+            forgetConnection(s, o);
+            log('Disconnected. The runner on the board is removed from the board settings.');
+            return 0;
+        }
+        if (sub === 'run') {
+            const item = args[1];
+            const key = args[2];
+            if (!item || !key || item.startsWith('--') || key.startsWith('--'))
+                throw new Error('Usage: agent-flow-board check run <item> <key> --server <url> --org <slug>');
+            const s = server();
+            const o = org();
+            const token = loadRunnerToken(ctx.store, s, o);
+            if (!token)
+                throw new Error(`This machine is not connected to ${o} on ${s}. Run: agent-flow-board check connect --server ${s} --org ${o} --json`);
+            const outcome = await runCheck({
+                server: s,
+                org: o,
+                item,
+                key,
+                dir: resolve(flag('--dir') ?? process.cwd()),
+                step: flag('--step'),
+                runId: flag('--run'),
+                runnerToken: token,
+                personalToken: ctx.personalToken(s, o),
+                fetch: ctx.fetch,
+                log,
+                headed: has('--headed')
+            });
+            if (json)
+                out(JSON.stringify({
+                    ok: outcome.exitCode === 0,
+                    runId: outcome.runId,
+                    message: outcome.message
+                }));
+            else
+                log(outcome.message);
+            // The last line is always the result file, so an agent can read it
+            if (outcome.resultPath)
+                out(`RESULT ${outcome.resultPath}`);
+            return outcome.exitCode;
+        }
+        if (sub === 'pull') {
+            const item = args[1];
+            const key = args[2];
+            if (!item || !key)
+                throw new Error('Usage: agent-flow-board check pull <item> <key> --server <url> --org <slug> [--accept-hash <sha256>]');
+            const s = server();
+            const o = org();
+            const personal = ctx.personalToken(s, o);
+            if (!personal)
+                throw new Error(`Not signed in to ${o} on ${s}. Run: agent-flow-board login --json --server ${s} --org ${o}`);
+            const res = await ctx.fetch(`${s}/api/v1/orgs/${encodeURIComponent(o)}/items/${encodeURIComponent(item)}/browser-checks`, {
+                headers: { authorization: `Bearer ${personal}` },
+                signal: AbortSignal.timeout(30_000)
+            });
+            const body = (await res.json().catch(() => ({})));
+            if (!res.ok)
+                throw new Error(body.error?.message ?? `The board answered ${res.status}.`);
+            const script = body.checks?.find((c) => c.key === key)?.script;
+            if (!script)
+                throw new Error(`The board has no saved script for ${item} ${key}.`);
+            const hash = createHash('sha256').update(script).digest('hex');
+            const target = scriptPath(o, item, key);
+            const local = existsSync(target) ? readFileSync(target, 'utf8') : null;
+            const accept = flag('--accept-hash');
+            if (accept) {
+                if (accept !== hash)
+                    throw new Error('The board script changed since you read it (its hash is different), so nothing was written. Pull again.');
+                mkdirSync(dirname(target), { recursive: true });
+                writeFileSync(target, script);
+                log(`Wrote ${target}.`);
+                return 0;
+            }
+            // The script is text written by someone else: it is shown as data and never run until it is accepted by its hash
+            out(JSON.stringify({
+                item,
+                key,
+                hash,
+                local: local === null ? 'none' : local === script ? 'same' : 'different',
+                target,
+                script
+            }));
+            return 0;
+        }
+        if (sub === 'bind') {
+            const o = org();
+            const project = need('--project');
+            const dir = resolve(flag('--dir') ?? process.cwd());
+            const cfg = resolveProjectConfig(dir);
+            bindFolder(o, project, cfg.repo, pinFiles(cfg.repo));
+            log(`Bound ${o}/${project} to ${cfg.repo}.`);
+            return 0;
+        }
+        if (sub === 'watch') {
+            const ac = new AbortController();
+            const stop = () => ac.abort();
+            process.once('SIGINT', stop);
+            process.once('SIGTERM', stop);
+            const n = await watchChecks({
+                store: ctx.store,
+                fetch: ctx.fetch,
+                log,
+                parallel: Number(flag('--parallel') ?? 3) || 3,
+                once: has('--once'),
+                signal: ac.signal
+            });
+            log(`Took ${n} run(s).`);
+            return 0;
+        }
+        if (sub === 'setup') {
+            await ensureBrowser(log);
+            log('The browser is ready.');
+            return 0;
+        }
+        if (sub === 'status' || sub === 'doctor')
+            return await statusOrDoctor(ctx, sub === 'doctor', has('--fix'), json);
+        if (sub === 'clear') {
+            const r = clearRuns({ all: has('--all') });
+            log(`Removed ${r.removed} finished run folder(s).`);
+            return 0;
+        }
+        log(CHECK_USAGE);
+        return 2;
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        if (json)
+            out(JSON.stringify({ ok: false, event: 'error', error: message }));
+        else
+            log(message);
+        return 2;
+    }
+}
+async function statusOrDoctor(ctx, doctor, fix, json) {
+    const problems = [];
+    const audit = verifyAudit();
+    if (!audit.ok)
+        problems.push({
+            problem: 'The audit log does not verify (it was edited or cut).',
+            next: 'Do not edit it. Move checks/audit.log aside to start a new chain.'
+        });
+    if (!permissionFlag())
+        problems.push({
+            problem: 'This Node has no permission model, so check scripts cannot be sandboxed.',
+            next: 'Install Node 20.18 or later (or any Node 22).'
+        });
+    if (!playwrightRuntimeDir()) {
+        if (doctor && fix)
+            await ensureBrowser(ctx.log);
+        else
+            problems.push({
+                problem: 'The browser is not installed.',
+                next: 'Run: agent-flow-board check setup'
+            });
+    }
+    const swept = doctor && fix ? await sweepOrphans(ctx.log) : 0;
+    const connections = listConnections().map((c) => ({
+        ...c,
+        connected: Boolean(loadRunnerToken(ctx.store, c.server, c.org))
+    }));
+    for (const c of connections)
+        if (!c.connected)
+            problems.push({
+                problem: `${c.org} on ${c.server} has no runner token.`,
+                next: `Run: agent-flow-board check connect --server ${c.server} --org ${c.org} --json`
+            });
+    const bindings = listBindings().map((b) => ({
+        org: b.org,
+        project: b.projectKey,
+        folder: b.folder,
+        pin: pinStatus(b.org, b.projectKey)
+    }));
+    for (const b of bindings)
+        if (b.pin !== 'ok')
+            problems.push({
+                problem: `${b.org}/${b.project}: the files that decide what runs changed in ${b.folder}.`,
+                next: `In that folder run a check once: agent-flow-board check run <item> <key> --org ${b.org}`
+            });
+    const state = {
+        home: checksHome(),
+        connections,
+        bindings,
+        audit: { ok: audit.ok, lines: audit.lines },
+        browser: Boolean(playwrightRuntimeDir()),
+        swept,
+        problems
+    };
+    if (json)
+        ctx.out(JSON.stringify(state));
+    else {
+        ctx.log(`State folder: ${state.home}`);
+        ctx.log(`Connections: ${connections.map((c) => `${c.org}@${c.server}${c.connected ? '' : ' (no token)'}`).join(', ') || 'none'}`);
+        ctx.log(`Bound folders: ${bindings.map((b) => `${b.org}/${b.project} -> ${b.folder} (${b.pin})`).join('; ') || 'none'}`);
+        for (const p of problems)
+            ctx.log(`Problem: ${p.problem} Next: ${p.next}`);
+        if (!problems.length)
+            ctx.log('Nothing is wrong.');
+    }
+    return doctor && problems.length ? 1 : 0;
+}