@agent-flow-board/bridge 0.1.0 → 0.3.0

package/dist/checks/warm.js

@@ -0,0 +1,342 @@
+// WARM PREVIEWS: A PREVIEW THAT STAYS UP A FEW MINUTES SO THE NEXT CHECK ON THE SAME TREE USES IT WITH A FRESH BROWSER CONTEXT.
+// Opt in only (the recipe says "warm": true) and only for an app that cannot leak or lose anything: no database, no mail, no sealed secrets, no adopted .env.
+// The key is a hash of the registration, the tree, the pin, the recipe and the environment, so a changed tree or pin is a different key and never finds the old
+// preview. Each warm preview has a marker under poolDir()/warm (owner process, preview process, port, expiry) and one small file per user, so the count of users
+// survives separate processes. The preview is stopped by its owner when it expires, when the worker stops (stopAll), and by doctor (sweepWarm) when its owner is
+// gone or it expired. Only process ids recorded in a marker are ever killed, and only with killTree.
+// -- DEP-MODULES -- //
+import { createHash, randomBytes } from 'node:crypto';
+import { linkSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { pidAlive } from './lock.js';
+import { ensureDir, poolDir } from './paths.js';
+import { renameRetry } from './fsretry.js';
+import { killTree } from './scope.js';
+// -- CONSTANTS -- //
+/** How long a warm preview stays up after its last user, 5 minutes. AFB_CHECKS_WARM_TTL_MS overrides. */
+export const warmTtlMs = () => {
+    const v = Number(process.env.AFB_CHECKS_WARM_TTL_MS);
+    return Number.isFinite(v) && v > 0 ? v : 5 * 60_000;
+};
+const OWNER_START = Date.now() - Math.round(process.uptime() * 1000);
+// -- FUNCTIONS -- //
+/** The key of a warm preview. Any part empty (the registration, the tree or the recipe) is refused: such a key would match too much. */
+export function warmKey(p) {
+    if (!p.registration || !p.treeId || !p.recipeHash)
+        throw new Error('A warm key needs a registration, a tree and a recipe.');
+    const h = createHash('sha256');
+    for (const part of [p.registration, p.treeId, p.pin ?? '', p.recipeHash, p.envHash ?? ''])
+        h.update(`${part.length}:${part}\n`);
+    return h.digest('hex').slice(0, 40);
+}
+/** Whether a run may use a warm preview, and the plain reason when it may not. */
+export function warmAllowed(i) {
+    if (!i.recipeWarm)
+        return { allowed: false, why: 'The recipe does not ask for a warm preview.' };
+    if (i.adoptEnv)
+        return {
+            allowed: false,
+            why: 'A warm preview is never used when the registration adopts its .env.'
+        };
+    if (i.sealed)
+        return { allowed: false, why: 'A warm preview is never used with sealed secrets.' };
+    if (i.hasDatabase)
+        return { allowed: false, why: 'A warm preview is never used for an app with a database.' };
+    if (i.hasMailOrDbVars)
+        return {
+            allowed: false,
+            why: 'A warm preview is never used when the app has mail or database settings.'
+        };
+    if (i.readOnly === false)
+        return { allowed: false, why: 'A warm preview is only used for read-only checks.' };
+    return { allowed: true };
+}
+const KEY = /^[a-f0-9]{40}$/;
+function readText(file) {
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function parseMarker(text) {
+    if (text === null)
+        return null;
+    try {
+        const v = JSON.parse(text);
+        if (!v || v.v !== 1 || typeof v.key !== 'string' || !KEY.test(v.key))
+            return null;
+        if (typeof v.ownerPid !== 'number' ||
+            typeof v.expiresAt !== 'number' ||
+            typeof v.port !== 'number')
+            return null;
+        if (typeof v.baseUrl !== 'string')
+            return null;
+        return v;
+    }
+    catch {
+        return null;
+    }
+}
+function writeWhole(file, text, exclusive) {
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    writeFileSync(tmp, text, { mode: 0o600 });
+    try {
+        if (exclusive)
+            linkSync(tmp, file);
+        else
+            renameRetry(tmp, file);
+        return true;
+    }
+    catch (e) {
+        if (exclusive && e.code === 'EEXIST')
+            return false;
+        if (!exclusive)
+            return false;
+        throw e;
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}
+export class WarmStore {
+    deps;
+    /** The previews this process started and still owns. Only the owner stops one through its handle. */
+    owned = new Map();
+    timer = null;
+    constructor(deps = {}) {
+        this.deps = {
+            dir: deps.dir ?? join(poolDir(), 'warm'),
+            now: deps.now ?? (() => Date.now()),
+            pidAlive: deps.pidAlive ?? pidAlive,
+            kill: deps.kill ?? killTree,
+            ttlMs: deps.ttlMs ?? warmTtlMs()
+        };
+    }
+    marker = (key) => join(this.deps.dir, `${key}.json`);
+    useDir = (key) => join(this.deps.dir, `${key}.use`);
+    assertKey(key) {
+        if (!KEY.test(key))
+            throw new Error('That is not a warm key.');
+    }
+    /** How many live users the preview has. A use file of a dead process is removed. */
+    users(key) {
+        this.assertKey(key);
+        let n = 0;
+        let names;
+        try {
+            names = readdirSync(this.useDir(key));
+        }
+        catch {
+            return 0;
+        }
+        for (const name of names) {
+            const file = join(this.useDir(key), name);
+            let pid;
+            try {
+                pid = JSON.parse(readText(file) ?? '{}').pid ?? 0;
+            }
+            catch {
+                pid = 0;
+            }
+            if (pid && this.deps.pidAlive(pid))
+                n++;
+            else
+                rmSync(file, { force: true });
+        }
+        return n;
+    }
+    addUser(key) {
+        ensureDir(this.useDir(key));
+        const id = randomBytes(6).toString('hex');
+        writeFileSync(join(this.useDir(key), `${id}.json`), JSON.stringify({ pid: process.pid }), {
+            mode: 0o600
+        });
+        return id;
+    }
+    lease(m, id) {
+        let released = false;
+        return {
+            key: m.key,
+            baseUrl: m.baseUrl,
+            port: m.port,
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                rmSync(join(this.useDir(m.key), `${id}.json`), { force: true });
+                // The last user starts the time to live
+                if (this.users(m.key) === 0) {
+                    const cur = parseMarker(readText(this.marker(m.key)));
+                    if (cur)
+                        writeWhole(this.marker(m.key), JSON.stringify({ ...cur, expiresAt: this.deps.now() + this.deps.ttlMs }) + '\n', false);
+                }
+            }
+        };
+    }
+    /** Whether the marker describes a preview that can be used right now. */
+    usable(m) {
+        if (!this.deps.pidAlive(m.ownerPid))
+            return false;
+        if (m.previewPid && !this.deps.pidAlive(m.previewPid))
+            return false;
+        return this.deps.now() < m.expiresAt || this.users(m.key) > 0;
+    }
+    /** The warm preview of this exact key, or null. A different tree, pin, recipe or environment is a different key and finds nothing. */
+    acquire(key) {
+        this.assertKey(key);
+        const m = parseMarker(readText(this.marker(key)));
+        if (!m || m.key !== key || !this.usable(m))
+            return null;
+        const id = this.addUser(key);
+        // The marker may have been swept between the look and the use file: then there is nothing to use
+        const again = parseMarker(readText(this.marker(key)));
+        if (!again || again.key !== key) {
+            rmSync(join(this.useDir(key), `${id}.json`), { force: true });
+            return null;
+        }
+        return this.lease(again, id);
+    }
+    /**
+     * Records a running preview as the warm preview of `key` and counts the caller as its first user. Returns null when a usable one is there already (two runs built
+     * the same tree at once): the caller keeps its own preview as a plain one and stops it when it is done.
+     */
+    register(key, preview, registration) {
+        this.assertKey(key);
+        ensureDir(this.deps.dir);
+        const existing = parseMarker(readText(this.marker(key)));
+        if (existing && this.usable(existing))
+            return null;
+        if (existing)
+            rmSync(this.marker(key), { force: true });
+        const now = this.deps.now();
+        const m = {
+            v: 1,
+            key,
+            registration,
+            baseUrl: preview.baseUrl,
+            port: preview.port,
+            previewPid: preview.pid ?? null,
+            ownerPid: process.pid,
+            ownerStart: OWNER_START,
+            createdAt: now,
+            expiresAt: now + this.deps.ttlMs
+        };
+        if (!writeWhole(this.marker(key), JSON.stringify(m) + '\n', true))
+            return null;
+        this.owned.set(key, preview);
+        this.watch();
+        return this.lease(m, this.addUser(key));
+    }
+    /** Looks at every marker: an expired preview with no user, or one whose owner is gone, is stopped and forgotten. Returns how many were stopped. */
+    async sweep() {
+        let names;
+        try {
+            names = readdirSync(this.deps.dir).filter((f) => f.endsWith('.json'));
+        }
+        catch {
+            return 0;
+        }
+        let stopped = 0;
+        for (const name of names) {
+            const key = name.slice(0, -'.json'.length);
+            if (!KEY.test(key))
+                continue;
+            const m = parseMarker(readText(this.marker(key)));
+            if (!m || m.key !== key) {
+                // Damaged: no pid can be trusted, so only the file goes
+                rmSync(this.marker(key), { force: true });
+                continue;
+            }
+            const ownerGone = !this.deps.pidAlive(m.ownerPid);
+            const previewGone = m.previewPid !== null && !this.deps.pidAlive(m.previewPid);
+            const expired = this.deps.now() >= m.expiresAt && this.users(key) === 0;
+            if (!ownerGone && !previewGone && !expired)
+                continue;
+            await this.stop(key, m);
+            stopped++;
+        }
+        return stopped;
+    }
+    async stop(key, m) {
+        const handle = this.owned.get(key);
+        this.owned.delete(key);
+        try {
+            if (handle)
+                await handle.stop();
+            else if (m.previewPid && m.previewPid !== process.pid && this.deps.pidAlive(m.previewPid))
+                await this.deps.kill(m.previewPid);
+        }
+        catch {
+            /* A preview that will not stop is left to the next sweep: the marker is kept */
+            if (handle || (m.previewPid && this.deps.pidAlive(m.previewPid))) {
+                if (handle)
+                    this.owned.set(key, handle);
+                return;
+            }
+        }
+        rmSync(this.marker(key), { force: true });
+        rmSync(this.useDir(key), { recursive: true, force: true });
+    }
+    /** Stops every preview this process owns (the worker is stopping). */
+    async stopAll() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        let n = 0;
+        for (const [key, handle] of [...this.owned]) {
+            this.owned.delete(key);
+            try {
+                await handle.stop();
+            }
+            catch {
+                /* The sweep of the next worker or doctor stops it by its recorded process id */
+                continue;
+            }
+            rmSync(this.marker(key), { force: true });
+            rmSync(this.useDir(key), { recursive: true, force: true });
+            n++;
+        }
+        return n;
+    }
+    /** The owner looks at its previews now and then, so an expired one is stopped without anybody asking. */
+    watch() {
+        if (this.timer)
+            return;
+        const every = Math.max(1_000, Math.min(30_000, Math.floor(this.deps.ttlMs / 4)));
+        this.timer = setInterval(() => void this.sweep().catch(() => undefined), every);
+        this.timer.unref();
+    }
+    /** The markers on disk, for doctor and status. */
+    list() {
+        try {
+            return readdirSync(this.deps.dir)
+                .filter((f) => f.endsWith('.json'))
+                .map((f) => parseMarker(readText(join(this.deps.dir, f))))
+                .filter((m) => m !== null);
+        }
+        catch {
+            return [];
+        }
+    }
+}
+const stores = new Map();
+/** The warm store of this machine's pool folder. One object per folder, so the previews this process owns are found again. */
+export function warmStore() {
+    const dir = join(poolDir(), 'warm');
+    let s = stores.get(dir);
+    if (!s) {
+        s = new WarmStore({ dir });
+        stores.set(dir, s);
+    }
+    return s;
+}
+export const acquireWarm = (key, store = warmStore()) => store.acquire(key);
+export const releaseWarm = (lease) => lease.release();
+export const registerWarm = (key, preview, registration, store = warmStore()) => store.register(key, preview, registration);
+/** Called when the worker stops. */
+export const stopAll = (store = warmStore()) => store.stopAll();
+/** Called by doctor: stops expired previews and the previews of owners that are gone. */
+export const sweepWarm = (store = warmStore()) => store.sweep();

package/dist/checks/watch.js

@@ -0,0 +1,228 @@
+// `check watch`: TAKE QUEUED RUNS FROM EVERY CONNECTED BOARD (THE RUN BUTTON ON THE BOARD), ON THE MACHINE'S SLOTS
+// One worker per machine. The scheduler (scheduler.ts) decides how many runs to take: never more than the machine's slots, none while the disk or memory preflight
+// fails, registrations taking turns, a heartbeat to the board from the moment of the claim, a 40 minute limit, and only its own held runs given back when it stops.
+// A queued run for a project with a registration is routed by the registration rules (run.ts); a project with none runs in the folder where `check run` was used
+// before, and with neither the run ends "could not run" and the current directory is never a fallback.
+// -- DEP-MODULES -- //
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { appendAudit } from './audit.js';
+import { boundFolder, pinStatus } from './bind.js';
+import { BoardError, RunnerBoard } from './board.js';
+import { acquireSlot, canTake, machineTotals, maxSlots } from './broker.js';
+import { closeAllBrowsers } from './browserpool.js';
+import { listConnections } from './connections.js';
+import { loadRunnerToken } from './connect.js';
+import { closePoolIfIdle, configureDatabasePool } from './dbpool.js';
+import { machineLock } from './lock.js';
+import { checksHome } from './paths.js';
+import { renameRetry } from './fsretry.js';
+import { readRegistrations } from './registry.js';
+import { runCheck } from './run.js';
+import { createScheduler } from './scheduler.js';
+import { sweepOrphans } from './scope.js';
+// -- CONSTANTS -- //
+const STATUS_EVERY_MS = 15_000;
+/** The line the worker prints for a terminal stop. */
+export const terminalLine = (kind) => `AFB_TERMINAL: ${kind}`;
+// -- FUNCTIONS -- //
+/** worker.json: what the service and `status` read to see whether the worker is busy. Written whole, never half. */
+function writeWorkerStatus(slots, runs) {
+    try {
+        const file = join(checksHome(), 'worker.json');
+        mkdirSync(checksHome(), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        const totals = machineTotals();
+        writeFileSync(tmp, JSON.stringify({
+            pid: process.pid,
+            slots,
+            busy: totals.busy,
+            runs,
+            at: new Date().toISOString()
+        }));
+        renameRetry(tmp, file);
+    }
+    catch {
+        /* A status that cannot be written must never stop the worker */
+    }
+}
+/** Runs the worker until the signal aborts (or one pass with `once`). Returns how many runs it took. */
+export async function watchChecks(o) {
+    const lock = machineLock('watch');
+    if (!lock)
+        throw new Error('Another "check watch" is already running on this machine. Only one worker runs per machine.');
+    const slots = maxSlots(o.parallel);
+    // The database pool is sized to the slots (its max_connections) and kept warm by this worker between runs; it is closed when the worker stops
+    configureDatabasePool({ slots, removeWhenIdle: false });
+    const owners = new Map();
+    let taken = 0;
+    // A stop no restart can fix: the worker prints one sentinel line, then the plain sentence, and ends with that sentence as its error
+    const inner = new AbortController();
+    let terminal = null;
+    const stopFor = (kind, message) => {
+        if (terminal)
+            return;
+        terminal = { kind, message };
+        o.log(terminalLine(kind));
+        o.log(message);
+        inner.abort();
+    };
+    if (o.signal.aborted)
+        inner.abort();
+    else
+        o.signal.addEventListener('abort', () => inner.abort(), { once: true });
+    // The boards that answered 401, by the fingerprint of the token they refused: a new `check connect` gives a new token and clears it
+    const refused = new Map();
+    let known = new Map();
+    const noteBoardError = (key, fingerprint, e) => {
+        if (!(e instanceof BoardError))
+            return;
+        if (e.code === 'UPGRADE_REQUIRED') {
+            stopFor('needs-newer', `This machine needs a newer bridge to talk to this board. ${e.message}`);
+        }
+        else if (e.status === 401) {
+            refused.set(key, fingerprint);
+            if ([...known].every(([k, fp]) => refused.get(k) === fp))
+                stopFor('rejected', 'The board no longer accepts this machine for checks. Run: agent-flow-board check connect --server <url> --org <slug> --json');
+        }
+    };
+    // The same beat refreshes the worker lock, so a crashed worker whose process id was reused does not lock out the next `check watch`
+    const status = setInterval(() => {
+        writeWorkerStatus(slots, taken);
+        lock.touch();
+    }, STATUS_EVERY_MS);
+    status.unref();
+    try {
+        // A worker with nothing to serve is not a worker that will have something later: a restart cannot fix it, so it says so and stops (not for one pass with --once)
+        if (!o.once) {
+            const all = listConnections();
+            if (!all.length)
+                stopFor('not-set-up', 'Not set up: this machine is not connected to any board. Run: agent-flow-board check connect --server <url> --org <slug> --json');
+            else if (!all.some((c) => loadRunnerToken(o.store, c.server, c.org)))
+                stopFor('not-connected', 'Not connected: no connection of this machine has a runner token. Run: agent-flow-board check connect --server <url> --org <slug> --json');
+            if (terminal)
+                throw new Error(terminal.message);
+        }
+        await sweepOrphans(o.log);
+        appendAudit('watch-start', { slots });
+        writeWorkerStatus(slots, 0);
+        const scheduler = createScheduler({
+            // The connections are read again on every loop, so a new `check connect` is picked up without a restart
+            connections: () => {
+                known = new Map();
+                return listConnections().flatMap((c) => {
+                    const token = loadRunnerToken(o.store, c.server, c.org);
+                    if (!token)
+                        return [];
+                    const key = `${c.server}|${c.org}`;
+                    const fingerprint = token.slice(-8);
+                    known.set(key, fingerprint);
+                    const board = new RunnerBoard(c.server, token, o.fetch, () => ({
+                        'x-afb-tool-slots': `${machineTotals().slots}:${machineTotals().busy}`
+                    }));
+                    return [
+                        {
+                            key,
+                            fingerprint,
+                            peek: () => board.peek().catch((e) => {
+                                noteBoardError(key, fingerprint, e);
+                                throw e;
+                            }),
+                            claim: async () => {
+                                const job = await board.claimNext().catch((e) => {
+                                    noteBoardError(key, fingerprint, e);
+                                    throw e;
+                                });
+                                if (job) {
+                                    owners.set(job.id, { server: c.server, org: c.org, token });
+                                    taken++;
+                                }
+                                return job;
+                            },
+                            beat: (id) => board.beat(id),
+                            release: (ids) => board.release(ids)
+                        }
+                    ];
+                });
+            },
+            runner: {
+                // Copy, install and build happen inside the run itself; the overlap of the next run's build with this run's check is decided by the benchmark (step 5.7)
+                prepare: async () => null,
+                execute: async (job, _prepared, ctx) => {
+                    const owner = owners.get(job.id);
+                    if (!owner)
+                        throw new Error('The run is not known to this worker.');
+                    await handle(o, owner, job, ctx.log, ctx.signal);
+                },
+                fail: async (job, error) => {
+                    const owner = owners.get(job.id);
+                    if (!owner)
+                        return;
+                    await new RunnerBoard(owner.server, owner.token, o.fetch)
+                        .finish(job.id, { result: 'error', reason: error.message.slice(0, 1900) })
+                        .catch(() => undefined);
+                },
+                cleanup: async (job) => {
+                    owners.delete(job.id);
+                }
+            },
+            broker: {
+                acquire: (req, opts) => acquireSlot(req, opts),
+                ready: () => canTake(),
+                totals: () => machineTotals()
+            },
+            log: o.log
+        }, { slots, prefetch: 0 });
+        await scheduler.run({ signal: inner.signal, once: o.once });
+        // A worker that stopped for a reason a restart cannot fix ends with that reason, so the command exits with it
+        if (terminal)
+            throw new Error(terminal.message);
+        return taken;
+    }
+    finally {
+        clearInterval(status);
+        // The scheduler gave back only its own unreported runs. The browsers and the database pool container this worker kept warm are closed now
+        await closeAllBrowsers().catch(() => undefined);
+        await closePoolIfIdle().catch(() => undefined);
+        appendAudit('watch-stop', { taken });
+        lock.release();
+    }
+}
+async function handle(o, owner, job, log, signal) {
+    const board = new RunnerBoard(owner.server, owner.token, o.fetch);
+    const fail = (reason) => board.finish(job.id, { result: 'error', reason }).catch(() => undefined);
+    const projectKey = job.project.key;
+    const read = readRegistrations(owner.org);
+    const registered = read.registrations.some((r) => r.boardProject === projectKey);
+    let dir = process.cwd();
+    if (!registered && read.problems.length)
+        // A registration that is damaged or was changed by hand is not "no registration": the folder of an earlier `check run` is not taken in its place
+        return void (await fail(`${read.problems.join(' ')} No other registration serves ${projectKey}, so the run was not started. Register the project again with: agent-flow-board check project`));
+    if (!registered) {
+        // No registration for this project: the folder where `check run` was used before, and only if its files did not change since
+        const bound = boundFolder(owner.org, projectKey);
+        if (!bound || !existsSync(bound.folder))
+            return void (await fail(`This machine has no folder for ${projectKey}. In the project's folder run: agent-flow-board check run ${job.item.ref} ${job.check.key} --org ${owner.org}`));
+        if (pinStatus(owner.org, projectKey) !== 'ok')
+            return void (await fail(`The files that decide what runs in ${bound.folder} changed since they were approved. In that folder run: agent-flow-board check run ${job.item.ref} ${job.check.key} --org ${owner.org}`));
+        dir = bound.folder;
+    }
+    log(`${owner.org}: running ${job.item.ref} ${job.check.key}`);
+    const outcome = await runCheck({
+        server: owner.server,
+        org: owner.org,
+        item: job.item.ref,
+        key: job.check.key,
+        dir,
+        step: job.stepKey ?? undefined,
+        claimed: job,
+        scheduled: true,
+        signal,
+        runnerToken: owner.token,
+        personalToken: null,
+        fetch: o.fetch,
+        log
+    });
+    log(`${owner.org}: ${job.item.ref} ${job.check.key}: ${outcome.message}`);
+}

package/dist/checks/wire.js

@@ -0,0 +1,87 @@
+// WHAT THE BOARD IS TOLD ABOUT THE REGISTRATIONS. Every call carries the header x-afb-tool-registrations: a base64url JSON list of {p: board project, n: NAME, r: folder name, b: branch}, at most 16,
+// only this organisation's, refreshed every 20 seconds. The board reads the text of whoever holds the token, so each field is checked against the board's own plain pattern first. A bad
+// r or b is dropped from its entry (the board would call the whole header damaged); the entry stays. Never a path, a command or a secret.
+// -- DEP-MODULES -- //
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+// -- MODULES -- //
+import { PROJECT_KEY, REGISTRATION_NAME } from './registry.js';
+// -- CONSTANTS -- //
+export const REGISTRATIONS_HEADER = 'x-afb-tool-registrations';
+/** How often the list is sent again, in milliseconds. */
+export const REGISTRATIONS_REFRESH_MS = 20_000;
+export const MAX_WIRE_REGISTRATIONS = 16;
+/** The board refuses a header longer than this. */
+const MAX_HEADER_CHARS = 6000;
+const REPO = /^[A-Za-z0-9 ._-]{1,100}$/;
+const BRANCH = /^[A-Za-z0-9._/-]{1,100}$/;
+// -- FUNCTIONS -- //
+/** The checked out branch of a repo, read from .git/HEAD without starting git. Null for a detached HEAD, no repo or a head it cannot read. */
+export function readBranch(repo) {
+    try {
+        let gitDir = join(repo, '.git');
+        if (statSync(gitDir).isFile()) {
+            const m = /^gitdir:\s*(.+)$/m.exec(readFileSync(gitDir, 'utf8'));
+            if (!m?.[1])
+                return null;
+            const target = m[1].trim();
+            gitDir = isAbsolute(target) ? target : resolve(dirname(gitDir), target);
+        }
+        const head = readFileSync(join(gitDir, 'HEAD'), 'utf8').trim();
+        const ref = /^ref:\s*refs\/heads\/(.+)$/.exec(head);
+        return ref?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The registrations of one organisation as board entries, with the fields that do not match dropped. */
+export function wireEntries(org, registrations) {
+    const out = [];
+    for (const r of registrations) {
+        if (r.org !== org)
+            continue;
+        // An entry without a valid project key or name cannot be sent at all: the board would refuse the whole header
+        if (!PROJECT_KEY.test(r.boardProject) || !REGISTRATION_NAME.test(r.name))
+            continue;
+        const entry = { p: r.boardProject, n: r.name };
+        const folder = r.repoName ?? (r.repo ? basename(r.repo) : null);
+        if (folder && REPO.test(folder))
+            entry.r = folder;
+        if (r.branch && BRANCH.test(r.branch))
+            entry.b = r.branch;
+        out.push(entry);
+        if (out.length === MAX_WIRE_REGISTRATIONS)
+            break;
+    }
+    return out;
+}
+/** The header value for one organisation, or '' when it has none. The list is cut from the end until it fits what the board accepts. */
+export function registrationsHeader(org, registrations) {
+    const list = wireEntries(org, registrations);
+    while (list.length) {
+        const value = Buffer.from(JSON.stringify(list)).toString('base64url');
+        if (value.length <= MAX_HEADER_CHARS)
+            return value;
+        list.pop();
+    }
+    return '';
+}
+/** Gives a registration its branch from the repo (no git process), for the header and the report. */
+export function withBranch(reg) {
+    return { ...reg, branch: reg.repo && existsSync(reg.repo) ? readBranch(reg.repo) : null };
+}
+/**
+ * Cleans the registration fields of a run report before it is sent: a registration that is not a plain name, and a folder name or branch that does not match the board's pattern,
+ * are removed from the report (the rest of the report stays).
+ */
+export function sanitiseReport(report) {
+    const out = { ...report };
+    if (out.registration !== undefined && !REGISTRATION_NAME.test(out.registration))
+        delete out.registration;
+    if (out.repoName !== undefined && !REPO.test(out.repoName))
+        delete out.repoName;
+    if (out.branch !== undefined && !BRANCH.test(out.branch))
+        delete out.branch;
+    return out;
+}