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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arben Apura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @agent-flow-board/bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The local bridge to an [Agent Flow Board](https://afb.arbenger.com) server. It forwards the board's MCP over stdio, runs the hooks of your coding tool (Claude Code, Antigravity, Gemini CLI) so the board stays true, and writes the status file that the editor status line reads. It holds no board tool code: every MCP tool lives on the server. It also runs browser checks on this machine (see Browser checks below).
+
+## Install
+
+```
+npm install -g @agent-flow-board/bridge
+agent-flow-board
+```
+
+Needs Node 20 or later. Run it with no arguments to see its usage; the list should include `setup`. Install it globally: the hooks call the command several times per tool call, and a command started through `npx` each time is too slow.
+
+## Commands
+
+| Command                                                           | What it does                                                                                                                                                                                               |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent-flow-board login --server <url> --org <slug>`              | Signs in with a device code. The sign in is kept in your keychain, one entry per server and organisation.                                                                                                  |
+| `agent-flow-board login --json --server <url> --org <slug>`       | For an agent: line 1 holds the code and a verifier, so the agent can approve it through the board's MCP. It never prints a token.                                                                          |
+| `agent-flow-board setup --org <slug> --server <url>`              | Writes the Claude Code hooks into this repository's `.claude/settings.local.json` (`--shared` writes `settings.json`). It merges, keeps your other hooks and backs the old file up outside the repository. |
+| `agent-flow-board hooks print claude --server <url> --org <slug>` | Prints the hook settings to paste by hand.                                                                                                                                                                 |
+| `agent-flow-board mcp --server <url> --org <slug>`                | Forwards MCP over stdio, for tools that only speak stdio.                                                                                                                                                  |
+| `agent-flow-board queue list`                                     | Shows writes held while the board could not be reached.                                                                                                                                                    |
+
+### Browser checks
+
+| Command                                                                             | What it does                                                                                                                                                                                 |
+| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent-flow-board check connect --server <url> --org <slug> --json`                 | Makes this machine a check runner of the organisation. An agent approves the printed code with the board's MCP. Only the runner token is kept.                                               |
+| `agent-flow-board check run <item> <key> --server <url> --org <slug> [--step 1.2]`  | Asks for the run, claims that run only, builds a private copy of the repo in the current folder, previews it, runs the check in a sandbox and reports. Exit 0 pass, 1 fail, 2 could not run. |
+| `agent-flow-board check pull <item> <key> --server <url> --org <slug>`              | Shows the board's copy of a check script as data. `--accept-hash <sha256>` writes exactly that text.                                                                                         |
+| `agent-flow-board check watch [--parallel N] [--once]`                              | Takes runs started from the board's Run button, for folders where `check run` was used before.                                                                                               |
+| `agent-flow-board check status`, `check doctor --fix`, `check clear`, `check setup` | Reads and repairs the state, removes old runs, installs the browser. All take `--json`.                                                                                                      |
+
+Check scripts and run state live in `~/.agent-flow-board/checks/`, never in a repo. Playwright is not installed with the bridge: the first run installs it there.
+
+The easy way to set everything up is the **Editor status** tab on the board's **Connect a tool** page: copy its prompt into Claude Code and the agent does the steps, asking you once before it writes anything.
+
+## What it writes
+
+- Your sign in: in the operating system keychain (an encrypted file where there is none).
+- `~/.agent-flow-board/status/<conversation id>.json`: what the board says a conversation works on. It holds no token and is removed when the conversation ends.
+- `~/.agent-flow-board/backups/`: backups of settings files that `setup` changed.
+
+## Licence
+
+MIT. See `LICENSE`.

package/dist/bridge.js

@@ -0,0 +1,256 @@
+// THE BRIDGE CORE (ADR-030): READS JSON-RPC LINES FROM A TOOL'S STDIN, FORWARDS EACH TO THE SERVER'S /mcp, WRITES THE REPLIES TO STDOUT.
+// It holds no tool code, schemas or workflow text, so a server update never needs a reconnect. It only adds three things:
+// sign in by device code, an offline queue for writes, and a protocol version check on start.
+// -- DEP-MODULES -- //
+import { createInterface } from 'node:readline';
+// -- CONSTANTS -- //
+export const BRIDGE_PROTOCOL_MAX = 1;
+/** The longest one request may take. A tool call can wait up to 50 seconds for a run, so this sits above that. */
+export const POST_TIMEOUT_MS = 90_000;
+const NETWORK_CODES = new Set([
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'ETIMEDOUT',
+    'ENETUNREACH',
+    'EHOSTUNREACH',
+    'EPIPE',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_SOCKET'
+]);
+// -- FUNCTIONS -- //
+/** A request that timed out: the board may or may not have taken it, so it is never treated as offline. */
+const isTimeout = (e) => e?.name === 'TimeoutError' ||
+    e?.name === 'AbortError';
+/** Only a real failure to reach the board counts. Any other TypeError is a bug and must be shown, not hidden as offline. */
+export const isNetworkError = (e) => {
+    if (!e || typeof e !== 'object')
+        return false;
+    const err = e;
+    if (err.code && NETWORK_CODES.has(err.code))
+        return true;
+    if (err.cause?.code && NETWORK_CODES.has(err.cause.code))
+        return true;
+    // Node's fetch reports a failed connection as a TypeError whose message is exactly this
+    return (e instanceof TypeError &&
+        /^(fetch failed|failed to fetch|network request failed)/i.test(String(err.message)));
+};
+/** The board refused the saved sign in. The person has to sign in again, which the bridge starts in the background. */
+class SignInNeeded extends Error {
+}
+/** Runs until stdin closes. */
+export async function runBridge(o) {
+    let token = o.getToken();
+    const postTimeout = o.postTimeoutMs ?? POST_TIMEOUT_MS;
+    let loginRunning = null;
+    /** Starts the device code sign in once. It runs in the background, so no call waits for the person to type a code. */
+    const startLogin = () => {
+        if (loginRunning)
+            return;
+        loginRunning = o
+            .login()
+            .then((t) => {
+            token = t;
+        })
+            .catch((err) => o.log(`Sign in failed: ${String(err?.message ?? err)}`))
+            .finally(() => {
+            loginRunning = null;
+        });
+    };
+    if (!token) {
+        o.log('No saved sign in. Starting the sign in.');
+        startLogin();
+    }
+    const protocolMax = o.protocolMax ?? BRIDGE_PROTOCOL_MAX;
+    let warnedProtocol = false;
+    /** Tool names known to only read, from the server's own annotations. Anything else is treated as a write. */
+    let readOnly = new Set();
+    let toolsKnown = false;
+    const write = (msg) => o.stdout.write(JSON.stringify(msg) + '\n');
+    const post = async (body) => {
+        const send = () => o.fetch(`${o.server}/mcp${o.org ? `/${o.org}` : ''}`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json, text/event-stream',
+                authorization: `Bearer ${token}`
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(postTimeout)
+        });
+        if (!token)
+            throw new SignInNeeded();
+        const res = await send();
+        if (res.status === 401) {
+            // The token expired or was revoked. The sign in starts in the background and this call says so, instead of waiting for it
+            o.log('The saved sign in is no longer valid. Starting the sign in.');
+            token = null;
+            startLogin();
+            throw new SignInNeeded();
+        }
+        return res;
+    };
+    const parse = async (res) => {
+        const text = await res.text();
+        if (!text.trim())
+            return null;
+        if ((res.headers.get('content-type') ?? '').includes('text/event-stream')) {
+            const line = text.split('\n').find((l) => l.startsWith('data:'));
+            return line ? JSON.parse(line.slice(5)) : null;
+        }
+        return JSON.parse(text);
+    };
+    const checkProtocol = (res) => {
+        const v = Number(res.headers.get('x-afb-protocol') ?? 0);
+        if (v > protocolMax && !warnedProtocol) {
+            warnedProtocol = true;
+            o.log(`This server speaks protocol ${v} and the bridge understands up to ${protocolMax}. Update it with: npx -y @agent-flow-board/bridge@latest`);
+        }
+    };
+    /** Sends one queued write as a real tools/call and says whether the board took it. */
+    const sendQueued = async (e) => {
+        try {
+            const res = await post({
+                jsonrpc: '2.0',
+                id: `replay-${Date.now()}`,
+                method: 'tools/call',
+                params: { name: e.name, arguments: e.args }
+            });
+            const body = await parse(res);
+            const result = body?.result;
+            if (res.status >= 500)
+                return { kind: 'offline' };
+            if (!res.ok || body?.error || result?.isError)
+                return {
+                    kind: 'refused',
+                    reason: result?.structuredContent?.error?.message ?? `The board answered ${res.status}.`
+                };
+            return { kind: 'ok' };
+        }
+        catch (err) {
+            if (err instanceof SignInNeeded || isTimeout(err) || isNetworkError(err))
+                return { kind: 'offline' };
+            return { kind: 'refused', reason: String(err.message) };
+        }
+    };
+    const replay = async () => {
+        if (o.queue.list().length === 0)
+            return;
+        const r = await o.queue.replay(sendQueued);
+        if (r.sent || r.held)
+            o.log(`Replayed ${r.sent} queued write${r.sent === 1 ? '' : 's'}${r.held ? `, ${r.held} held back (see: agent-flow-board queue list)` : ''}.`);
+    };
+    async function handle(msg) {
+        try {
+            const res = await post(msg);
+            checkProtocol(res);
+            const body = await parse(res);
+            if (msg.id === undefined)
+                return;
+            if (body) {
+                if (msg.method === 'tools/list') {
+                    const tools = body.result?.tools;
+                    if (tools) {
+                        readOnly = new Set(tools.filter((t) => t.annotations?.readOnlyHint).map((t) => t.name));
+                        toolsKnown = true;
+                    }
+                }
+                // An answer that failed before the server read the request (a refusal such as FORBIDDEN) carries no id: it answers this one
+                write(body.error && body.id == null ? { ...body, id: msg.id } : body);
+                void replay();
+            }
+            else
+                write({
+                    jsonrpc: '2.0',
+                    id: msg.id,
+                    error: { code: -32603, message: `The board answered ${res.status} with no body.` }
+                });
+        }
+        catch (err) {
+            if (msg.id === undefined)
+                return;
+            if (err instanceof SignInNeeded) {
+                const text = 'The board did not accept the saved sign in. A sign in was started: open the address printed by the agent-flow-board bridge (or run "agent-flow-board login" in a terminal), type the code, then try again.';
+                if (msg.method === 'tools/call')
+                    write({
+                        jsonrpc: '2.0',
+                        id: msg.id,
+                        result: {
+                            isError: true,
+                            content: [{ type: 'text', text }],
+                            structuredContent: { error: { code: 'SIGN_IN_NEEDED', message: text } }
+                        }
+                    });
+                else
+                    write({ jsonrpc: '2.0', id: msg.id, error: { code: -32001, message: text } });
+                return;
+            }
+            if (isTimeout(err)) {
+                write({
+                    jsonrpc: '2.0',
+                    id: msg.id,
+                    error: {
+                        code: -32000,
+                        message: `The board did not answer within ${Math.round(postTimeout / 1000)} seconds. The request may or may not have been applied: read the item before sending it again.`
+                    }
+                });
+                return;
+            }
+            if (!isNetworkError(err)) {
+                write({
+                    jsonrpc: '2.0',
+                    id: msg.id,
+                    error: { code: -32603, message: String(err.message) }
+                });
+                return;
+            }
+            // The board cannot be reached. Reads say so, writes are queued and say they are queued.
+            const name = msg.params?.name;
+            if (msg.method === 'tools/call' && name && toolsKnown && !readOnly.has(name)) {
+                const q = o.queue.enqueue(name, msg.params?.arguments ?? {});
+                const out = {
+                    queued: true,
+                    queueId: q.id,
+                    message: 'The board cannot be reached. This write was saved on this computer and will be sent when it is back, in order. Nothing was recorded yet.'
+                };
+                write({
+                    jsonrpc: '2.0',
+                    id: msg.id,
+                    result: { content: [{ type: 'text', text: JSON.stringify(out) }], structuredContent: out }
+                });
+            }
+            else {
+                write({
+                    jsonrpc: '2.0',
+                    id: msg.id,
+                    error: {
+                        code: -32000,
+                        message: 'offline: the board cannot be reached, so this cannot be read right now.'
+                    }
+                });
+            }
+        }
+    }
+    const rl = createInterface({ input: o.stdin });
+    let chain = Promise.resolve();
+    rl.on('line', (line) => {
+        if (!line.trim())
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+            return;
+        }
+        // One message at a time keeps the order of writes exactly as the tool sent them
+        chain = chain.then(() => handle(msg));
+    });
+    const timer = o.replayEveryMs === 0 ? null : setInterval(() => void replay(), o.replayEveryMs ?? 15_000);
+    await new Promise((resolve) => rl.on('close', resolve));
+    await chain;
+    if (timer)
+        clearInterval(timer);
+}

package/dist/checks/audit.js

@@ -0,0 +1,125 @@
+// A HASH-CHAINED AUDIT LOG OF WHAT THE CHECK COMMANDS DID. Each line carries the MAC of the line before it (HMAC-SHA256 with a key that only this machine has),
+// so an edited line or a cut shows. It is evidence, not prevention. Only short action words and plain numbers are logged: never a token, a password, a secret's
+// path or a command text.
+// -- DEP-MODULES -- //
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { appendFileSync, existsSync, linkSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { withLockSync } from './lock.js';
+import { auditFile, checksHome, ensureDir } from './paths.js';
+// -- CONSTANTS -- //
+const MAX_ACTION = 40;
+const MAX_VALUE = 200;
+// -- FUNCTIONS -- //
+const keyFile = () => join(checksHome(), 'audit.key');
+/** The head file keeps the MAC and the count of the last line, which is what shows a cut tail (the chain of the lines left is still true). */
+const headFile = () => `${auditFile()}.head`;
+/** The key, created once with mode 0600. It is written whole into a temporary file and linked into place, so another process never reads half of it. */
+function homeKey() {
+    ensureDir(checksHome());
+    const file = keyFile();
+    if (!existsSync(file)) {
+        const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+        writeFileSync(tmp, randomBytes(32).toString('hex'), { mode: 0o600, flag: 'wx' });
+        try {
+            linkSync(tmp, file);
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+        }
+        finally {
+            rmSync(tmp, { force: true });
+        }
+    }
+    return Buffer.from(readFileSync(file, 'utf8').trim(), 'hex');
+}
+const lineMac = (key, prev, text) => createHmac('sha256', Buffer.concat([Buffer.from('afb check audit:'), key]))
+    .update(`${prev}\n${text}`)
+    .digest('hex');
+const readLines = () => existsSync(auditFile()) ? readFileSync(auditFile(), 'utf8').split(/\r?\n/).filter(Boolean) : [];
+function tail(lines) {
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const e = JSON.parse(lines[i] ?? '');
+            if (e && typeof e === 'object' && typeof e.mac === 'string')
+                return e.mac;
+        }
+        catch {
+            /* A damaged line is skipped, and verifyAudit reports it */
+        }
+    }
+    return '';
+}
+function clean(detail) {
+    const out = {};
+    for (const [k, v] of Object.entries(detail)) {
+        const name = k.replace(/[^A-Za-z0-9_]/g, '').slice(0, 40);
+        if (name)
+            out[name] = typeof v === 'string' ? v.slice(0, MAX_VALUE) : v;
+    }
+    return out;
+}
+/** Adds one line to the chain. Reading the last line and appending the next one is one step under a lock, so two writers never fork the chain. */
+export function appendAudit(action, detail = {}) {
+    const key = homeKey();
+    const word = action.replace(/[^A-Za-z0-9 _.:-]/g, '').slice(0, MAX_ACTION) || 'action';
+    withLockSync('audit', () => {
+        const lines = readLines();
+        const prev = tail(lines);
+        const text = JSON.stringify({
+            at: new Date().toISOString(),
+            action: word,
+            detail: clean(detail),
+            prev
+        });
+        const mac = lineMac(key, prev, text);
+        appendFileSync(auditFile(), JSON.stringify({ ...JSON.parse(text), mac }) + '\n', {
+            mode: 0o600
+        });
+        const head = { lines: lines.length + 1, head: mac };
+        const tmp = `${headFile()}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(head), { mode: 0o600 });
+        renameSync(tmp, headFile());
+    });
+}
+function readHead() {
+    try {
+        const v = JSON.parse(readFileSync(headFile(), 'utf8'));
+        return typeof v.lines === 'number' && typeof v.head === 'string'
+            ? { lines: v.lines, head: v.head }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+const same = (a, b) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+/** True when every line holds the MAC of the line before it and the last line is the one the head file names (a cut tail shows there). */
+export function verifyAudit() {
+    const lines = readLines();
+    const head = readHead();
+    if (!lines.length)
+        return { ok: head === null || head.lines === 0, lines: 0, head: '' };
+    const key = homeKey();
+    let prev = '';
+    for (let i = 0; i < lines.length; i++) {
+        let e;
+        try {
+            e = JSON.parse(lines[i] ?? '');
+        }
+        catch {
+            return { ok: false, lines: lines.length, head: prev };
+        }
+        const { mac, ...rest } = e;
+        if (typeof mac !== 'string' || e.prev !== prev)
+            return { ok: false, lines: lines.length, head: prev };
+        if (!same(lineMac(key, prev, JSON.stringify(rest)), mac))
+            return { ok: false, lines: lines.length, head: prev };
+        prev = mac;
+    }
+    // A cut tail, or a line added by hand after the last one, is not what the head file recorded
+    const matches = head !== null && head.lines === lines.length && head.head === prev;
+    return { ok: matches, lines: lines.length, head: prev };
+}

package/dist/checks/bind.js

@@ -0,0 +1,99 @@
+// THE FOLDER BINDING OF `check watch`: WHICH REAL FOLDER BUILDS THE PROJECT <org>/<KEY>, AND THE PIN OF THE FILES THAT DECIDED WHAT RUNS.
+// When the pin changes (a new script, a changed recipe, a new lockfile) the watcher stops and tells the person to run `check run` in that
+// folder, which looks at the new setup and pins it again. Nothing in the repo can re-pin by itself.
+// -- DEP-MODULES -- //
+import { existsSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+// -- MODULES -- //
+import { bindingsFile, ensureDir, ORG_SLUG } from './paths.js';
+import { checkRepoFolder } from './guardrails.js';
+import { pinFiles } from './recipe.js';
+// -- CONSTANTS -- //
+const PROJECT_KEY = /^[A-Z][A-Z0-9]{1,9}$/;
+// -- FUNCTIONS -- //
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+function idOf(org, projectKey) {
+    if (!ORG_SLUG.test(org))
+        throw new Error('The organisation is not a slug.');
+    if (!PROJECT_KEY.test(projectKey))
+        throw new Error('The project key must be 2 to 10 capital letters or digits, starting with a letter.');
+    return `${org}/${projectKey}`;
+}
+function readAll() {
+    const file = bindingsFile();
+    if (!existsSync(file))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new Error(`${file} is not valid JSON. Fix or remove it.`);
+    }
+    const out = {};
+    if (isRecord(parsed) && isRecord(parsed.bindings))
+        for (const [id, v] of Object.entries(parsed.bindings))
+            if (isRecord(v) && typeof v.folder === 'string' && typeof v.pin === 'string')
+                out[id] = { folder: v.folder, pin: v.pin };
+    return out;
+}
+/** Writes a temp file in the same folder, then renames it over the real one, so a reader never sees half a file. */
+function writeAll(bindings) {
+    const file = bindingsFile();
+    ensureDir(dirname(file));
+    const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        writeFileSync(temp, JSON.stringify({ version: 1, bindings }, null, 2) + '\n', { mode: 0o600 });
+        renameSync(temp, file);
+    }
+    catch (e) {
+        rmSync(temp, { force: true });
+        throw e;
+    }
+}
+/** Binds a project to a folder. Refuses a folder the guardrails refuse. Stores the real path and the given pin. */
+export function bindFolder(org, projectKey, folder, pin) {
+    const id = idOf(org, projectKey);
+    const problem = checkRepoFolder(folder);
+    if (problem)
+        throw new Error(problem);
+    const all = readAll();
+    all[id] = { folder: realpathSync.native(folder), pin };
+    writeAll(all);
+}
+/** The folder and pin of a project, or null when it has none. */
+export function boundFolder(org, projectKey) {
+    const found = readAll()[idOf(org, projectKey)];
+    return found ? { folder: found.folder, pin: found.pin } : null;
+}
+/** Every binding, sorted by org and key. */
+export function listBindings() {
+    return Object.entries(readAll())
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([id, v]) => {
+        const [org = '', projectKey = ''] = id.split('/');
+        return { org, projectKey, folder: v.folder, pin: v.pin };
+    });
+}
+/** Removes a binding. True when there was one. */
+export function unbind(org, projectKey) {
+    const id = idOf(org, projectKey);
+    const all = readAll();
+    if (!(id in all))
+        return false;
+    delete all[id];
+    writeAll(all);
+    return true;
+}
+/**
+ * Whether the files that decide what runs are still the ones the person approved. `changed` also covers a folder that is gone or no longer
+ * allowed: the caller tells the person to run `check run` in that folder, which looks again and re-pins.
+ */
+export function pinStatus(org, projectKey) {
+    const found = boundFolder(org, projectKey);
+    if (!found)
+        return 'unbound';
+    if (checkRepoFolder(found.folder))
+        return 'changed';
+    return pinFiles(join(found.folder)) === found.pin ? 'ok' : 'changed';
+}

package/dist/checks/board.js

@@ -0,0 +1,107 @@
+// THE BOARD, SEEN FROM THE CHECK COMMANDS: THE RUNNER API WITH THE TOOL'S OWN RUNNER TOKEN
+// A runner token is not a personal token. It can take a queued run, beat for it, upload evidence and report a result, and nothing else.
+// -- MODULES -- //
+import { TOOL_PROTOCOL } from './paths.js';
+// -- CONSTANTS -- //
+/** One call to the board may take this long, uploads included. A half open connection must not hang the run for ever. */
+export const CALL_TIMEOUT_MS = 120_000;
+/** Asking for a run waits a short while only. */
+export const CLAIM_TIMEOUT_MS = 20_000;
+/** Raised when the board refuses a call. Carries the board's own words and code. */
+export class BoardError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'BoardError';
+    }
+}
+// -- FUNCTIONS -- //
+/** The calls of the runner API, as the check commands make them. */
+export class RunnerBoard {
+    server;
+    token;
+    doFetch;
+    extraHeaders;
+    constructor(server, token, doFetch = (input, init) => fetch(input, init), 
+    /** Extra headers sent with every call: the audit head and the slots, built by the caller, never required. */
+    extraHeaders = () => ({})) {
+        this.server = server;
+        this.token = token;
+        this.doFetch = doFetch;
+        this.extraHeaders = extraHeaders;
+    }
+    async call(method, path, body, type, timeoutMs = CALL_TIMEOUT_MS) {
+        let res;
+        let text;
+        try {
+            res = await this.doFetch(`${this.server.replace(/\/$/, '')}/api/v1/runner${path}`, {
+                method,
+                headers: {
+                    authorization: `Bearer ${this.token}`,
+                    'x-afb-tool-protocol': String(TOOL_PROTOCOL),
+                    ...this.extraHeaders(),
+                    ...(type ? { 'content-type': type } : {})
+                },
+                body: body,
+                signal: AbortSignal.timeout(timeoutMs)
+            });
+            text = await res.text();
+        }
+        catch (e) {
+            const name = e?.name;
+            if (name === 'TimeoutError' || name === 'AbortError')
+                throw new BoardError(0, 'TIMEOUT', `The board did not answer within ${Math.round(timeoutMs / 1000)} seconds.`);
+            throw e;
+        }
+        let json = null;
+        try {
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            /* Not JSON */
+        }
+        if (!res.ok) {
+            const err = json?.error;
+            if (res.status === 401)
+                throw new BoardError(401, 'UNAUTHENTICATED', 'The board no longer accepts this machine for checks. Run: agent-flow-board check connect --server <url> --org <slug> --json');
+            throw new BoardError(res.status, err?.code ?? 'ERROR', err?.message ?? `The board answered ${res.status}.`);
+        }
+        return json;
+    }
+    /** Takes the run with this id, and no other. Null when it is not queued for this runner. */
+    async claim(runId) {
+        const out = await this.call('POST', '/claim', JSON.stringify({ runId }), 'application/json', CLAIM_TIMEOUT_MS);
+        return out.job;
+    }
+    /** Takes the oldest queued run this runner may take, for `check watch`. */
+    async claimNext() {
+        const out = await this.call('POST', '/claim', undefined, undefined, CLAIM_TIMEOUT_MS);
+        return out.job;
+    }
+    /** How many runs wait for this runner. Nothing is taken. */
+    async peek() {
+        return (await this.call('POST', '/peek')).waiting;
+    }
+    /** Says the process is alive and still on this run. A conflict means the board gave up on it. */
+    beat(runId) {
+        return this.call('POST', `/runs/${encodeURIComponent(runId)}/beat`);
+    }
+    /** Gives back the named runs only, never the runs of another process of the same runner. */
+    async release(runIds) {
+        if (!runIds.length)
+            return 0;
+        return (await this.call('POST', '/release', JSON.stringify({ runIds }), 'application/json')).released;
+    }
+    /** Stores a file of a run as evidence and returns its attachment id. */
+    async upload(runId, file) {
+        const q = `filename=${encodeURIComponent(file.filename)}&caption=${encodeURIComponent(file.caption)}`;
+        const out = await this.call('POST', `/runs/${encodeURIComponent(runId)}/artifacts?${q}`, file.bytes, 'application/octet-stream');
+        return out.attachmentId;
+    }
+    finish(runId, report) {
+        return this.call('POST', `/runs/${encodeURIComponent(runId)}/finish`, JSON.stringify(report), 'application/json');
+    }
+}