@agent-flow-board/bridge 0.1.0 → 0.3.0

package/dist/checks/run.js

@@ -0,0 +1,443 @@
+// `check run <item> <key>`: ASK FOR THE RUN, CLAIM THAT RUN BY ITS ID, BUILD A PRIVATE PREVIEW, RUN THE CHECK IN A SANDBOX, REPORT
+// The run is requested with the person's own sign in (the one the hooks and MCP use), claimed with this machine's runner token, and finished
+// with it. The folder is the repo the agent is in: running a check there is the approval of that folder for `check watch`.
+// -- DEP-MODULES -- //
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+// -- MODULES -- //
+import { appendAudit, verifyAudit } from './audit.js';
+import { bindFolder } from './bind.js';
+import { BoardError, RunnerBoard } from './board.js';
+import { ensureBrowser } from './browser.js';
+import { acquireBrowser } from './browserpool.js';
+import { JPEG_MAGIC, MAX_SHOT_BYTES, readPlainFile } from './evidence.js';
+import { acquireSlot, slotsHeader } from './broker.js';
+import { closePoolIfIdle } from './dbpool.js';
+import { lintCheck } from './guard.js';
+import { assertName, ORG_SLUG, runsDir, scriptPath, scriptsDir } from './paths.js';
+import { liveSiteGuardOptions } from './live.js';
+import { pictureUploadAllowed, savedStateFor } from './login.js';
+import { startPreview } from './preview.js';
+import { redact } from './redact.js';
+import { pinFiles, resolveProjectConfig } from './recipe.js';
+import { configFor, listRegistrations, pinRegistration, pinState, readRegistrations } from './registry.js';
+import { registrationHeader, routeRun } from './routing.js';
+import { registrationsHeader, sanitiseReport, withBranch } from './wire.js';
+import { runCheckInSandbox } from './sandbox.js';
+import { installSignalHandlers, RunScope, sweepOrphans } from './scope.js';
+import { signInWithPassword, stateNeedles } from './signin.js';
+// -- CONSTANTS -- //
+const BEAT_EVERY_MS = 30_000;
+const MAX_EVIDENCE = 8;
+/** A run started by hand (not by the worker, whose scheduler has its own limit) stops after this long. */
+const DEFAULT_RUN_LIMIT_MS = 40 * 60_000;
+// -- FUNCTIONS -- //
+/** The run limit of a standalone run in ms: AFB_CHECKS_RUN_LIMIT_MS when it is a positive number, else 40 minutes. */
+export function runLimitMs(env = process.env) {
+    const v = Number(env.AFB_CHECKS_RUN_LIMIT_MS);
+    return Number.isFinite(v) && v > 0 ? v : DEFAULT_RUN_LIMIT_MS;
+}
+/** The sentence for a run stopped by its limit. */
+export function limitSentence(ms) {
+    return ms < 60_000
+        ? `The run took longer than ${Math.round(ms / 1000)} seconds and was stopped.`
+        : `The run took longer than ${Math.round(ms / 60_000)} minutes and was stopped.`;
+}
+/** Writes an audit line, and never lets a failure of the log change the outcome of a run. */
+function auditSafely(log, action, detail) {
+    try {
+        appendAudit(action, detail);
+    }
+    catch {
+        log('The audit log could not be written for this run.');
+    }
+}
+/** The registrations of this organisation, for the board to route a run that names one (at most 16, refreshed by every call). */
+function registrationsHeaderFor(org) {
+    try {
+        const value = registrationsHeader(org, listRegistrations(org).map(withBranch));
+        return value ? { 'x-afb-tool-registrations': value } : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The registration of a run: the one the board names, else the one asked for with --registration, else the check script's own header, else the board
+ * project's only registration. With none registered for the board project the folder of the current directory is used, as before registrations existed.
+ */
+export function configForRun(o, job, source, log, fromWatch) {
+    const read = readRegistrations(o.org);
+    const all = read.registrations;
+    const mine = all.filter((r) => r.boardProject === job.project.key);
+    if (!mine.length) {
+        // A registration that is damaged or was changed by hand is not "no registration": the folder of the current directory is never taken in its place
+        if (read.problems.length)
+            throw new Error(`${read.problems.join(' ')} No other registration serves ${job.project.key}, so the run was not started. Register the project again with: agent-flow-board check project`);
+        const cfg = resolveProjectConfig(o.dir);
+        // Running a check in a folder is the approval of that folder (and of the files that decide what runs) for `check watch`
+        bindFolder(o.org, job.project.key, cfg.repo, pinFiles(cfg.repo));
+        return { cfg, registration: null, scriptRegistration: null };
+    }
+    const registration = routeRun({
+        org: o.org,
+        boardProject: job.project.key,
+        run: job.registration ?? o.registration ?? null,
+        script: source,
+        all
+    });
+    if (registration.repo) {
+        if (fromWatch) {
+            // The board's Run button never re-approves: a changed or missing pin needs a `check run` in the folder first
+            if (pinState(registration) !== 'ok')
+                throw new Error(`The files that decide what runs in ${registration.name} changed since they were approved. In that folder run: agent-flow-board check run <item> <key> --org ${o.org}`);
+        }
+        else {
+            const pin = pinRegistration(o.org, registration.name);
+            if (pin.changed)
+                log(`The files that decide what runs in ${registration.name} changed and were pinned again (${pin.files.length} files).`);
+        }
+    }
+    return {
+        cfg: configFor(registration),
+        registration,
+        scriptRegistration: registrationHeader(source)
+    };
+}
+function auditHeaders() {
+    try {
+        const v = verifyAudit();
+        return v.ok ? { 'x-afb-tool-audit': `${v.lines}:${v.head}` } : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Asks the board for a preview run of this check. Returns the run id, or throws one plain sentence. */
+export async function requestRunOnBoard(o) {
+    if (!o.personalToken)
+        throw new Error(`Not signed in to ${o.org} on ${o.server}, so the run cannot be asked for. Run: agent-flow-board login --json --server ${o.server} --org ${o.org}, or ask for the run with check_run and pass --run <id>.`);
+    const res = await o.fetch(`${o.server}/api/v1/orgs/${encodeURIComponent(o.org)}/items/${encodeURIComponent(o.item)}/browser-checks/runs`, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${o.personalToken}`,
+            'content-type': 'application/json'
+        },
+        body: JSON.stringify({
+            check: o.key,
+            target: 'preview',
+            ...(o.step ? { step: o.step } : {})
+        }),
+        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} when asking for the run.`);
+    if (!body.run?.id)
+        throw new Error('The board has no machine online for this project. Run: agent-flow-board check connect --server <url> --org <slug> --json');
+    return body.run.id;
+}
+/** Up to MAX_EVIDENCE pictures, the last one always kept. */
+function pickShots(steps) {
+    const wanted = steps.filter((s) => s.shot);
+    return wanted.length > MAX_EVIDENCE
+        ? [...wanted.slice(0, MAX_EVIDENCE - 1), wanted[wanted.length - 1]]
+        : wanted;
+}
+/** Runs one check end to end. Never throws: every failure is an outcome with a plain message. */
+export async function runCheck(o) {
+    let lastStop = '';
+    let finished = false;
+    const stop = (message, runId = null) => {
+        lastStop = message;
+        return { exitCode: 2, runId, resultPath: null, message };
+    };
+    let runId = null;
+    let board = null;
+    let scope = null;
+    let beat = null;
+    let uninstall = () => undefined;
+    let claimed = false;
+    let slot = null;
+    // Everything the run must never print, filled in as it becomes known; the reasons that go to the board are redacted with it
+    const needlesAll = [];
+    let limitTimer = null;
+    let limitHit = false;
+    // A run the worker's scheduler holds is stopped, timed out or given up on by the scheduler, which gives it back or reports it by id
+    const schedulerOwns = () => Boolean(o.scheduled && o.signal?.aborted);
+    const reasonFor = (text) => redact(text, needlesAll).slice(0, 1900);
+    try {
+        if (o.claimed)
+            claimed = true;
+        if (!ORG_SLUG.test(o.org))
+            return stop('--org takes an organisation slug: lowercase letters, digits and dashes.');
+        assertName(o.item, 'item reference');
+        assertName(o.key, 'check key');
+        // -- THE FOLDER AND THE SCRIPT -- //
+        const script = scriptPath(o.org, o.item, o.key);
+        if (!existsSync(script))
+            return stop(`There is no check file for ${o.item} ${o.key} at ${script}. Write it there, or read the board's copy with: agent-flow-board check pull ${o.item} ${o.key} --org ${o.org}`);
+        const source = readFileSync(script, 'utf8');
+        const unsafe = lintCheck(source);
+        if (unsafe.length)
+            return stop(`This check uses ${unsafe.join(', ')}, which a check has no business doing, so it was not run. Rewrite it.`);
+        // -- THE RUN -- //
+        board = new RunnerBoard(o.server, o.runnerToken, o.fetch, () => ({
+            'x-afb-tool-slots': slotsHeader(),
+            ...auditHeaders(),
+            ...registrationsHeaderFor(o.org)
+        }));
+        await sweepOrphans(o.log);
+        runId = o.claimed?.id ?? o.runId ?? (await requestRunOnBoard(o));
+        const job = o.claimed ?? (await board.claim(runId));
+        if (!job)
+            return stop(`The board did not give this machine the run ${runId}. It is not queued for this machine, or this machine does not serve that project (check connect --project), or another tool took it.`, runId);
+        claimed = true;
+        auditSafely(o.log, 'run-claimed', { run: runId });
+        if (job.item.ref !== o.item || job.check.key !== o.key) {
+            await board.release([runId]).catch(() => undefined);
+            claimed = false;
+            return stop(`The run ${runId} is for ${job.item.ref} ${job.check.key}, not ${o.item} ${o.key}, so it was given back.`, runId);
+        }
+        const thisBoard = board;
+        const thisRun = runId;
+        const abort = new AbortController();
+        // A run the worker's scheduler holds is beaten (and limited) by the scheduler from the moment of its claim; its stop reaches this run through the signal
+        if (o.signal) {
+            if (o.signal.aborted)
+                abort.abort();
+            else
+                o.signal.addEventListener('abort', () => abort.abort(), { once: true });
+        }
+        if (!o.scheduled) {
+            beat = setInterval(() => {
+                thisBoard.beat(thisRun).catch((e) => {
+                    // The board gave up on the run: stop working on it
+                    if (e instanceof BoardError && e.status === 409)
+                        abort.abort();
+                });
+            }, BEAT_EVERY_MS);
+            beat.unref();
+            // A run started by hand has the same limit the worker gives its runs
+            const limit = runLimitMs();
+            limitTimer = setTimeout(() => {
+                limitHit = true;
+                abort.abort();
+            }, limit);
+            limitTimer.unref();
+        }
+        scope = new RunScope(runId, o.log);
+        scope.start();
+        const thisScope = scope;
+        // The worker's runs never install their own handlers: its stop reaches them through the signal, and each closes only its own scope. A handler per run
+        // would finish every run as an error and end the whole process before the scheduler has given the others back
+        if (!o.scheduled)
+            uninstall = installSignalHandlers(scope, () => {
+                void thisBoard
+                    .finish(thisRun, { result: 'error', reason: 'The run was stopped before it finished.' })
+                    .catch(() => undefined)
+                    .finally(() => process.exit(2));
+            });
+        // -- WHICH REGISTRATION, AND A PLACE ON THIS MACHINE -- //
+        // A registration the board or the script names is chosen here, never guessed; a refusal ends the run with its code and the list
+        const routed = configForRun(o, job, source, o.log, Boolean(o.claimed));
+        const cfg = routed.cfg;
+        const registration = routed.registration;
+        // The heartbeat already runs, so a run that waits for a slot, the preflight or another run's build keeps beating and never looks stuck to the board
+        // (a scheduled run already holds its slot)
+        if (!o.scheduled)
+            slot = await acquireSlot({ runId, kind: 'check', registration: registration?.name ?? job.project.key }, { signal: abort.signal });
+        await ensureBrowser(o.log);
+        const preview = await startPreview(cfg, {
+            runId,
+            scope,
+            log: o.log,
+            signal: abort.signal,
+            needles: needlesAll
+        });
+        needlesAll.push(...preview.secrets);
+        if (preview.note)
+            o.log(preview.note);
+        // -- SIGN IN: A SAVED SIGN IN OF THIS REGISTRATION, ELSE THE RECIPE'S TEST USER -- //
+        let state = null;
+        // Only a sign in the owner SAVED counts for the picture rule: the recipe's test user belongs to a throwaway preview and holds nothing worth hiding
+        let usedSavedSignIn = false;
+        if (registration) {
+            const saved = savedStateFor({
+                org: o.org,
+                registration: registration.name,
+                scriptRegistration: routed.scriptRegistration,
+                bindKey: new URL(preview.baseUrl).origin
+            });
+            if (saved) {
+                state = saved.profile?.state ?? null;
+                usedSavedSignIn = state !== null;
+                if (saved.note)
+                    o.log(saved.note);
+            }
+        }
+        if (!state && preview.testUser) {
+            o.log(`Signing in as ${preview.testUser.email.replace(/^(.).*(@.*)$/, '$1***$2')}...`);
+            state = await signInWithPassword(preview.baseUrl, preview.testUser);
+        }
+        const needles = [
+            ...preview.secrets,
+            ...(preview.testUser ? [preview.testUser.password, preview.testUser.email] : []),
+            ...stateNeedles(state)
+        ];
+        needlesAll.push(...needles);
+        const runDir = join(runsDir(), runId);
+        // The browser may reach this machine and the hosts of this registration only (a live site's hosts, the sealed test project's host); a live
+        // site or a signed in run always has its own browser, and a live site never allows writes
+        const extraHosts = [
+            ...new Set([
+                ...(cfg.url ? liveSiteGuardOptions(cfg).extraHosts : (cfg.extraHosts ?? [])),
+                ...(preview.extraHosts ?? [])
+            ])
+        ];
+        const browser = await acquireBrowser({
+            hosts: extraHosts,
+            headed: o.headed,
+            dedicated: Boolean(cfg.url) || state !== null
+        });
+        thisScope.add('browser', () => browser.release());
+        const childJob = {
+            baseUrl: preview.baseUrl,
+            ws: browser.wsEndpoint(),
+            storageState: state,
+            checkFile: script,
+            runDir,
+            viewport: { width: 1280, height: 800 },
+            extraHosts,
+            needles
+        };
+        const ran = await runCheckInSandbox({
+            job: childJob,
+            scriptsRoot: scriptsDir(),
+            log: o.log,
+            signal: abort.signal
+        });
+        if (!ran.result) {
+            const why = limitHit
+                ? limitSentence(runLimitMs())
+                : redact(ran.stderr || 'The check did not finish.', needlesAll).slice(-1200);
+            // A run the scheduler stopped is given back by the scheduler, not reported here
+            if (!schedulerOwns()) {
+                await board.finish(runId, {
+                    result: 'error',
+                    reason: reasonFor(`The check did not finish. ${why}`)
+                });
+                finished = true;
+                claimed = false;
+            }
+            return stop(`The check did not finish. ${why}`, runId);
+        }
+        // -- REPORT -- //
+        const ids = [];
+        // Pictures of a signed in run are not uploaded unless the owner opted in for the registration: a compressed picture cannot be searched for a secret
+        const uploadPictures = pictureUploadAllowed(registration ?? { uploadSignedInPictures: false }, usedSavedSignIn);
+        if (!uploadPictures)
+            o.log('The pictures of a signed in run are not uploaded for this registration.');
+        for (const s of uploadPictures ? pickShots(ran.result.steps) : []) {
+            if (!s.shot)
+                continue;
+            // The child wrote this file, so it is only read when it is a plain JPEG inside the shots folder (never a link it planted to a key file)
+            const read = readPlainFile(join(runDir, 'shots'), s.shot, {
+                maxBytes: MAX_SHOT_BYTES,
+                magic: JPEG_MAGIC
+            });
+            if ('refused' in read) {
+                o.log(`  A picture was not uploaded: ${read.refused}.`);
+                continue;
+            }
+            const bytes = read.bytes;
+            // A picture that holds a secret (found as bytes or text) is not uploaded
+            if (needles.some((n) => n.length >= 6 && Buffer.from(bytes).includes(n))) {
+                o.log('  A picture held a secret value, so it was not uploaded.');
+                continue;
+            }
+            ids.push(await board.upload(runId, {
+                filename: s.shot,
+                caption: `${s.status === 'fail' ? 'Failed: ' : ''}${s.name}`.slice(0, 120),
+                bytes
+            }));
+        }
+        const result = ran.result;
+        const wire = registration ? withBranch(registration) : null;
+        const report = sanitiseReport({
+            result: result.result,
+            ...(registration
+                ? {
+                    registration: registration.name,
+                    ...(registration.repo ? { repoName: basename(registration.repo) } : {}),
+                    ...(wire?.branch ? { branch: wire.branch } : {})
+                }
+                : {}),
+            durationMs: Math.min(result.durationMs, 24 * 3600 * 1000),
+            url: preview.baseUrl.slice(0, 300),
+            commit: preview.commit,
+            diffHash: preview.diffHash,
+            ...(result.result === 'pass'
+                ? {}
+                : { reason: reasonFor(result.reason ?? 'The check failed.') }),
+            ...(preview.commit ? {} : { unverified: true }),
+            log: redact(result.log, needlesAll).slice(0, 390_000),
+            evidence: ids
+        });
+        // A run the scheduler stopped is given back by the scheduler: what it found is not reported
+        if (schedulerOwns())
+            return stop('The run was stopped.', runId);
+        await board.finish(runId, report);
+        finished = true;
+        claimed = false;
+        auditSafely(o.log, 'run-finished', { run: runId, result: result.result });
+        return {
+            exitCode: result.result === 'pass' ? 0 : 1,
+            runId,
+            resultPath: join(runDir, 'result.json'),
+            message: result.result === 'pass'
+                ? 'The check passed.'
+                : `The check failed: ${result.reason ?? 'see the log'}`
+        };
+    }
+    catch (e) {
+        const said = e instanceof Error ? e.message : String(e);
+        const reason = limitHit ? limitSentence(runLimitMs()) : said;
+        // Nothing that reaches the board is unredacted: not a build log tail, not the message of an error
+        if (board && runId && claimed && !schedulerOwns()) {
+            await board
+                .finish(runId, { result: 'error', reason: reasonFor(reason) })
+                .catch(() => undefined);
+            finished = true;
+        }
+        return stop(reasonFor(reason), runId);
+    }
+    finally {
+        if (beat)
+            clearInterval(beat);
+        if (limitTimer)
+            clearTimeout(limitTimer);
+        uninstall();
+        if (scope)
+            await scope.close();
+        // The slot goes back to the machine, and a pool container that no run needs any more is removed (a worker keeps it warm)
+        try {
+            await slot?.release();
+        }
+        catch {
+            /* A slot that cannot be released is cleared by its stale heartbeat */
+        }
+        if (!o.claimed)
+            await closePoolIfIdle().catch(() => undefined);
+        // A run that `check watch` already claimed must never be left running when this ends early (no script, a changed folder, a refusal)
+        if (o.claimed && !finished && !schedulerOwns()) {
+            const b = board ?? new RunnerBoard(o.server, o.runnerToken, o.fetch);
+            await b
+                .finish(o.claimed.id, {
+                result: 'error',
+                reason: reasonFor(lastStop || 'The run stopped early.')
+            })
+                .catch(() => undefined);
+        }
+    }
+}

package/dist/checks/sandbox.js

@@ -0,0 +1,208 @@
+// THE SANDBOX OF A CHECK: A SEPARATE NODE PROCESS STARTED WITH THE PERMISSION MODEL ON.
+// A check script is arbitrary Node code written by an agent, and board text can talk an agent into writing anything. The bridge keeps its
+// sign-in (the key file and the token files) in the bridge home, and the check state in its checks folder. So the child can read ONLY the
+// scripts folder, its own run folder, the folder of its own code and the Playwright runtime, and can write ONLY its run folder. It starts no
+// program and no worker, loads no addon, and gets an environment of PATH, SystemRoot, TEMP, TMP and AFB_PLAYWRIGHT_DIR and nothing else.
+// -- DEP-MODULES -- //
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// -- MODULES -- //
+import { playwrightRuntimeDir } from './browser.js';
+import { MAX_RESULT_BYTES, findLink, isPlainFile, readPlainFile } from './evidence.js';
+import { ensureDir, isInside, runsDir } from './paths.js';
+import { redact } from './redact.js';
+import { killTree } from './scope.js';
+// -- CONSTANTS -- //
+/** The hard limit of a whole check run. The child has its own 2 minute limit for the check itself, this is the backstop. */
+export const RUN_TIMEOUT_MS = 5 * 60_000;
+const SHOT = /^\d{2}\.jpg$/;
+const MAX_STDERR = 4000;
+const MAX_STDOUT = 2_000_000;
+// -- FUNCTIONS -- //
+/** The name of the permission flag of this Node: --permission since Node 23.5, --experimental-permission before. Null when it has neither. */
+export function permissionFlag() {
+    const flags = process.allowedNodeEnvironmentFlags;
+    if (flags.has('--permission'))
+        return '--permission';
+    if (flags.has('--experimental-permission'))
+        return '--experimental-permission';
+    return null;
+}
+/** The environment of a sandboxed process: the least a Node program needs, a temp folder inside the run folder, and what the caller adds. */
+export function sandboxEnv(tmpDir, extra = {}) {
+    const env = {};
+    if (process.env.PATH)
+        env.PATH = process.env.PATH;
+    if (process.env.SystemRoot)
+        env.SystemRoot = process.env.SystemRoot;
+    env.TEMP = tmpDir;
+    env.TMP = tmpDir;
+    return { ...env, ...extra };
+}
+/** Runs a Node script with the permission model on: it reads readDirs, writes writeDir, and starts nothing. */
+export async function runNodeInSandbox(opts) {
+    const flag = permissionFlag();
+    if (!flag)
+        throw new Error(`This Node (${process.version}) has no permission model, so a check cannot be run safely. Use Node 22 or newer.`);
+    const args = [flag, ...opts.readDirs.map((d) => `--allow-fs-read=${d}`)];
+    if (opts.writeDir)
+        args.push(`--allow-fs-write=${opts.writeDir}`);
+    args.push(opts.entry);
+    const child = spawn(process.execPath, args, {
+        cwd: opts.writeDir ?? dirname(opts.entry),
+        env: opts.env,
+        windowsHide: true,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        shell: false
+    });
+    let stdout = '';
+    let stderr = '';
+    let buf = '';
+    let timedOut = false;
+    const stop = () => {
+        if (child.pid !== undefined)
+            void Promise.resolve(killTree(child.pid)).catch(() => { });
+        child.kill();
+    };
+    const timer = setTimeout(() => {
+        timedOut = true;
+        stop();
+    }, opts.timeoutMs);
+    const onAbort = () => stop();
+    if (opts.signal) {
+        if (opts.signal.aborted)
+            stop();
+        else
+            opts.signal.addEventListener('abort', onAbort, { once: true });
+    }
+    child.stdout.on('data', (d) => {
+        const text = d.toString('utf8');
+        if (stdout.length < MAX_STDOUT)
+            stdout += text;
+        buf += text;
+        let i;
+        while ((i = buf.indexOf('\n')) >= 0) {
+            const line = buf.slice(0, i).replace(/\r$/, '');
+            buf = buf.slice(i + 1);
+            opts.onLine?.(line);
+        }
+    });
+    child.stderr.on('data', (d) => {
+        stderr = (stderr + d.toString('utf8')).slice(-MAX_STDERR);
+    });
+    // A child that dies before reading its stdin must not crash the parent
+    child.stdin.on('error', () => { });
+    const exitCode = await new Promise((resolve, reject) => {
+        child.on('error', reject);
+        child.on('close', (code) => resolve(code));
+        child.stdin.end(opts.stdin ?? '');
+    }).finally(() => {
+        clearTimeout(timer);
+        opts.signal?.removeEventListener('abort', onAbort);
+    });
+    return { exitCode, stdout, stderr, timedOut };
+}
+const redactDeep = (text, needles, max) => redact(String(text ?? ''), needles).slice(0, max);
+/** The result the child wrote is data, not trusted: its shape is rebuilt, names are checked and every text goes through the redaction again. */
+export function cleanResult(raw, needles, shotsDir) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const r = raw;
+    const steps = Array.isArray(r.steps) ? r.steps : [];
+    return {
+        schema: 1,
+        result: r.result === 'pass' ? 'pass' : 'fail',
+        reason: typeof r.reason === 'string' && r.reason ? redactDeep(r.reason, needles, 700) : null,
+        durationMs: Number(r.durationMs) || 0,
+        steps: steps
+            .filter((s) => typeof s === 'object' && s !== null)
+            .slice(0, 200)
+            .map((s) => ({
+            name: redactDeep(s.name, needles, 200),
+            status: s.status === 'pass' || s.status === 'fail' ? s.status : 'shot',
+            ms: Number(s.ms) || 0,
+            // A picture that is not a plain file (a link the child planted) is dropped, not reported
+            shot: SHOT.test(String(s.shot ?? '')) && (!shotsDir || isPlainFile(shotsDir, String(s.shot)))
+                ? String(s.shot)
+                : null,
+            ...(s.error ? { error: redactDeep(s.error, needles, 500) } : {})
+        })),
+        log: redactDeep(r.log, needles, 20_000),
+        blockedWrites: Number(r.blockedWrites) || 0,
+        blockedOutside: Number(r.blockedOutside) || 0
+    };
+}
+/** Runs one check script in the sandbox and returns what it wrote. The browser is already running; the job names its address. */
+export async function runCheckInSandbox({ job, scriptsRoot, log, signal }) {
+    if (!isInside(scriptsRoot, job.checkFile))
+        throw new Error('That check is not inside the scripts folder, so it was not run.');
+    if (!isInside(runsDir(), job.runDir))
+        throw new Error('The run folder is not inside the runs folder, so the check was not run.');
+    // The permission model follows links, so a link in a folder the check may read or write would reach files outside it: none is allowed there
+    for (const folder of [job.runDir, scriptsRoot]) {
+        const link = findLink(folder);
+        if (link)
+            throw new Error(`There is a link or a file with several names in a folder the check may use (${basename(link)}), so the check was not run. Remove it.`);
+    }
+    const pwDir = playwrightRuntimeDir();
+    if (!pwDir)
+        throw new Error('Playwright is not installed yet. Run "agent-flow-board check setup" and it will install it.');
+    const childFile = join(dirname(fileURLToPath(import.meta.url)), 'child.js');
+    if (!existsSync(childFile))
+        throw new Error('The check runner (child.js) is missing from this install. Build the bridge again.');
+    const needles = job.needles ?? [];
+    const tmpDir = ensureDir(join(job.runDir, 'tmp'));
+    const run = await runNodeInSandbox({
+        entry: childFile,
+        readDirs: [scriptsRoot, job.runDir, dirname(childFile), pwDir],
+        writeDir: job.runDir,
+        env: sandboxEnv(tmpDir, { AFB_PLAYWRIGHT_DIR: pwDir }),
+        stdin: JSON.stringify(job),
+        timeoutMs: RUN_TIMEOUT_MS,
+        signal,
+        onLine: (line) => {
+            if (!line.startsWith('EVENT '))
+                return;
+            try {
+                const e = JSON.parse(line.slice(6));
+                if (e.type === 'step') {
+                    const secs = Math.round((Number(e.ms) || 0) / 100) / 10;
+                    log(redact(`  ${e.status === 'pass' ? 'PASS' : 'FAIL'} ${String(e.name ?? '')} (${secs}s)${e.error ? `: ${String(e.error)}` : ''}`, needles));
+                }
+                else if (e.type === 'log')
+                    log(redact(`  ${String(e.text ?? '')}`, needles));
+            }
+            catch {
+                /* Not an event */
+            }
+        }
+    });
+    let stderr = redact(run.stderr, needles);
+    // A link made during the run is as bad as one made before it: nothing the check wrote is read
+    const planted = [job.runDir, scriptsRoot].map((d) => findLink(d)).find(Boolean);
+    if (planted) {
+        log('A link appeared in a folder the check may use, so what it wrote was not read.');
+        stderr = `A link appeared in the run folder (${basename(planted)}). ${stderr}`.slice(-4000);
+        return { exitCode: run.exitCode, stderr, result: null };
+    }
+    const file = join(job.runDir, 'result.json');
+    let result = null;
+    if (existsSync(file)) {
+        const read = readPlainFile(job.runDir, 'result.json', { maxBytes: MAX_RESULT_BYTES });
+        if ('refused' in read)
+            log(`The result file of the check was not read: ${read.refused}.`);
+        else {
+            try {
+                result = cleanResult(JSON.parse(read.bytes.toString('utf8')), needles, join(job.runDir, 'shots'));
+            }
+            catch {
+                result = null;
+            }
+        }
+    }
+    if (run.timedOut)
+        log('The check ran for 5 minutes and was stopped.');
+    return { exitCode: run.exitCode, stderr, result };
+}