@agent-flow-board/bridge 0.3.0 → 0.4.0

package/README.md

@@ -34,15 +34,17 @@ Needs Node 20 or later. Run it with no arguments to see its usage; the list shou
 
 More check commands:
 
-| Command                                                                                   | What it does                                                                                                                                              |
-| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agent-flow-board check project <NAME> --org <slug> --repo <dir> [--app-dir web]`         | Registers a repo folder (and an optional app folder) for a board project, or a live site with `--url`. A repo must be inside a folder the owner approved. |
-| `agent-flow-board check approve --action <roots\|register\|secrets\|adopt-env\|pictures>` | The owner, on a terminal, gets a single-use code (10 minutes). Agents cannot make one.                                                                    |
-| `agent-flow-board check roots add\|list\|remove`                                          | The owner-approved parent folders a registration may live in (at most 5).                                                                                 |
-| `agent-flow-board check secrets import\|list\|forget`                                     | Seals test Supabase and mail values per registration (owner's code needed). Names only are ever printed.                                                  |
-| `agent-flow-board check login <NAME> --org <slug> --seeded`                               | Saves a sign in for a registration from `AFB_CHECKS_<NAME>_EMAIL` and `_PASSWORD`.                                                                        |
-| `agent-flow-board check service install\|status\|uninstall`                               | Windows: starts the worker when you sign in.                                                                                                              |
-| `agent-flow-board check import-legacy --from <afb-checks folder> --org <slug>`            | Read only: re-registers the old tool's projects and copies its check scripts.                                                                             |
+| Command                                                                                           | What it does                                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent-flow-board check project <NAME> --org <slug> --repo <dir> [--app-dir web]`                 | Registers a repo folder (and an optional app folder) for a board project, or a live site with `--url`. A repo must be inside a folder the owner approved.                                                                                                                                                                                            |
+| `agent-flow-board check approve --action <roots\|register\|secrets\|adopt-env\|pictures>`         | The owner, on a terminal, gets a single-use code (10 minutes). Agents cannot make one. `--many "roots:<dir>;register:<NAME>@<host>"` makes up to 15 at once.                                                                                                                                                                                         |
+| `agent-flow-board check approve --request --action <x> --target <t> [--why "..."] [--wait <min>]` | Asks the board for the owner's approval, no terminal. When the person has turned on "Let my agent handle approvals on its own" (Settings, Agent access) it is approved at once and the single-use code is printed. `--request-many "<action>:<target>;..."` (up to 20) is one ask; `--resume <id,id>` picks a wait up again. Exit 3 = still waiting. |
+| `agent-flow-board check login <NAME> --org <slug> --approval <code>`                              | Opens a window on the owner's own computer; the owner signs in once with whatever the site asks for (magic link, code, Google, two-factor). The session is saved sealed on this computer only (exit 4 window closed, 5 timed out).                                                                                                                   |
+| `agent-flow-board check roots add\|list\|remove`                                                  | The owner-approved parent folders a registration may live in (at most 5).                                                                                                                                                                                                                                                                            |
+| `agent-flow-board check secrets import\|list\|forget`                                             | Seals test Supabase and mail values per registration (owner's code needed). Names only are ever printed.                                                                                                                                                                                                                                             |
+| `agent-flow-board check login <NAME> --org <slug> --seeded`                                       | Saves a sign in for a registration from `AFB_CHECKS_<NAME>_EMAIL` and `_PASSWORD`.                                                                                                                                                                                                                                                                   |
+| `agent-flow-board check service install\|status\|uninstall`                                       | Windows: starts the worker when you sign in.                                                                                                                                                                                                                                                                                                         |
+| `agent-flow-board check import-legacy --from <afb-checks folder> --org <slug>`                    | Read only: re-registers the old tool's projects and copies its check scripts.                                                                                                                                                                                                                                                                        |
 
 Runs share the machine: a slot set, one browser per host set, one database container with a clone per run, and kept dependencies and builds.
 
@@ -61,3 +63,11 @@ The easy way to set everything up is the **Editor status** tab on the board's **
 ## Licence
 
 MIT. See `LICENSE`.
+
+## What the board approval channel protects, and what it does not
+
+- The person turns the switch on for themselves, signed in on the board with the manage role, after one warning. No MCP tool, no `/api/v1` call and no token can turn it on. It covers the agents on the computers that person owns, and the person loses it by losing manage. Each approval is still single use, for one action and one target on one machine, and lives 10 minutes.
+- The risk the person accepts: anything that holds their manage token, or any hidden instruction in text the agent reads (a file, a comment), can make the agent add folders, register live sites, import test keys or adopt a `.env` without anyone being asked. The board's history (an event for each batch, the rows for 30 days) shows what was done. A bridge-side refusal of drive roots, the home folder and secret folders stays.
+- The local audit line says `decided_via` and who, but it is a file the same user can write; the board's history is the authoritative audit.
+- Honest limit: an agent that runs as the owner's own OS user can read the local approval key. The switch stops an agent that goes through the CLI and the board, not one that edits local files.
+- Switch off or older board: `--request` says so once and the terminal path (`check approve --action ... --target ...`) still works.

package/dist/checks/approve.js

@@ -17,11 +17,15 @@ export const APPROVAL_ACTIONS = [
     'secrets',
     'adopt-env',
     'roots',
-    'pictures'
+    'pictures',
+    'login'
 ];
 /** A code is valid for ten minutes. */
 export const APPROVAL_TTL_MS = 10 * 60 * 1000;
+/** The most codes the file holds: the board's batch cap, so a whole batch is valid at once. */
 const MAX_CODES = 20;
+/** The decisions this module's own claim function returned. A decision that is not in here is never minted into a code. */
+const claimedDecisions = new WeakSet();
 const ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
 const CODE_LENGTH = 12;
 // -- FUNCTIONS -- //
@@ -121,13 +125,23 @@ function readEntries() {
         for (const e of list) {
             if (!e || typeof e !== 'object')
                 continue;
-            const { h, action, target, exp } = e;
+            const { h, action, target, exp, note } = e;
             if (typeof h === 'string' &&
                 typeof action === 'string' &&
                 isApprovalAction(action) &&
                 typeof target === 'string' &&
-                typeof exp === 'number')
-                out.push({ h, action, target, exp });
+                typeof exp === 'number') {
+                const n = note;
+                out.push({
+                    h,
+                    action,
+                    target,
+                    exp,
+                    ...(n && typeof n.by === 'string' && typeof n.at === 'string'
+                        ? { note: { by: n.by.slice(0, 80), at: n.at.slice(0, 40) } }
+                        : {})
+                });
+            }
         }
         return out;
     }
@@ -143,6 +157,34 @@ const writeEntries = (codes) => writeFileAtomic(approvalsFile(), JSON.stringify(
 export function mintApproval(action, target, opts) {
     if (!opts.isTTY)
         throw new Refusal('An approval code is made by the owner on an interactive terminal. This is not one, so no code was made.');
+    return mintCode(action, target, opts.now);
+}
+/**
+ * Makes a code from a board decision that this module's claim function returned. This is the only way besides a terminal: a decision that was not claimed through the
+ * board (a made-up object, a flag, a file) is refused. The code is for the decision's own action and target, and nothing else.
+ */
+export function mintFromDecision(claim, opts = {}) {
+    if (!claimedDecisions.has(claim))
+        throw new Refusal('An approval code is made from a decision the board gave, and this is not one.');
+    return mintCode(claim.action, claim.target, opts.now, {
+        by: claim.decidedBy,
+        at: claim.decidedAt
+    });
+}
+/** Claims the named approved decisions on the board (once) and marks what came back as claimed. A decision the board did not return is not here. */
+export async function claimBoardDecisions(board, ids) {
+    const got = await board.claimApprovals(ids);
+    const out = got.map((d) => ({ ...d }));
+    for (const d of out)
+        claimedDecisions.add(d);
+    return out;
+}
+/** The sentence for the owner's word when a code came from the board, or null when it came from a terminal. */
+export function boardSentence(note) {
+    return note ? `Approved by ${note.by} on the board at ${note.at}.` : null;
+}
+function mintCode(action, target, nowMs, note) {
+    const opts = { now: nowMs };
     if (!isApprovalAction(action))
         throw new Refusal(`"${action.slice(0, 30)}" is not an action (${APPROVAL_ACTIONS.join(', ')}).`);
     const now = opts.now ?? Date.now();
@@ -153,10 +195,21 @@ export function mintApproval(action, target, opts) {
     const exp = now + APPROVAL_TTL_MS;
     withLockSync('approvals', () => {
         const kept = readEntries().filter((e) => e.exp > now && !(e.action === action && e.target === norm));
-        kept.push({ h: macOf(action, norm, code), action, target: norm, exp });
+        kept.push({
+            h: macOf(action, norm, code),
+            action,
+            target: norm,
+            exp,
+            ...(note ? { note } : {})
+        });
         writeEntries(kept.slice(-MAX_CODES));
     });
-    appendAudit('approval minted', { action, target: norm, minutes: APPROVAL_TTL_MS / 60000 });
+    appendAudit('approval minted', {
+        action,
+        target: norm,
+        minutes: APPROVAL_TTL_MS / 60000,
+        ...(note ? { decided_via: 'board', decided_by: note.by } : {})
+    });
     return {
         code: `${code.slice(0, 4)}-${code.slice(4, 8)}-${code.slice(8)}`,
         expiresAt: new Date(exp).toISOString()
@@ -184,30 +237,38 @@ export function peekApproval(action, target, code, now = Date.now()) {
 }
 /** True once for a valid code of this action and target, and false for a wrong action, a wrong target, an expired, a used or an unknown code. */
 export function consumeApproval(action, target, code, now = Date.now()) {
+    return consumeApprovalNote(action, target, code, now).ok;
+}
+/** Like consumeApproval, and says who decided when the code came from the board (for the owner sentence and the audit line). */
+export function consumeApprovalNote(action, target, code, now = Date.now()) {
     if (!isApprovalAction(action))
-        return false;
+        return { ok: false };
     const plain = normaliseCode(code);
     if (!plain)
-        return false;
+        return { ok: false };
     let norm;
     try {
         norm = normaliseTarget(action, target);
     }
     catch {
-        return false;
+        return { ok: false };
     }
     const want = macOf(action, norm, plain);
-    let hit = false;
+    let found;
     withLockSync('approvals', () => {
         const all = readEntries();
         const live = all.filter((e) => e.exp > now);
-        const found = live.find((e) => e.action === action && sameMac(e.h, want));
-        hit = found !== undefined;
+        found = live.find((e) => e.action === action && sameMac(e.h, want));
         const rest = found ? live.filter((e) => e !== found) : live;
-        if (hit || rest.length !== all.length)
+        if (found || rest.length !== all.length)
             writeEntries(rest);
     });
+    const hit = found;
     if (hit)
-        appendAudit('approved with code', { action, target: norm });
-    return hit;
+        appendAudit('approved with code', {
+            action,
+            target: norm,
+            ...(hit.note ? { decided_via: 'board', decided_by: hit.note.by } : {})
+        });
+    return hit ? { ok: true, ...(hit.note ? { note: hit.note } : {}) } : { ok: false };
 }

package/dist/checks/askBoard.js

@@ -0,0 +1,143 @@
+// ASKING THE OWNER ON THE BOARD: THE AGENT FILES A REQUEST, THE OWNER CLICKS ONCE, THE BRIDGE CLAIMS THE ANSWER ONCE AND MAKES THE SAME LOCAL SINGLE-USE CODE A TERMINAL MAKES
+// Nothing here reads a terminal. A code is made only from a decision the board returned to the claim call (approve.ts keeps the list), never from an argument.
+// The board is injected, so the tests use a fake one. A board that does not know the path, or has approvals switched off, gives a plain message with the terminal fallback.
+// -- MODULES -- //
+import { APPROVAL_ACTIONS, Refusal, UsageError, claimBoardDecisions, isApprovalAction, mintFromDecision, normaliseTarget } from './approve.js';
+import { BoardError } from './board.js';
+// -- CONSTANTS -- //
+/** The most entries one ask holds (the board's cap). */
+export const ASK_LIMIT = 20;
+const FALLBACK = 'The owner can still make a code on a terminal: agent-flow-board check approve --action <action> --target <target>.';
+// -- FUNCTIONS -- //
+/** Reads `<action>:<target>;<action>:<target>` into entries. All of them are checked before anything is asked. */
+export function parseEntries(text) {
+    const entries = text
+        .split(';')
+        .map((e) => e.trim())
+        .filter(Boolean)
+        .map((e) => {
+        const at = e.indexOf(':');
+        const kind = at > 0 ? e.slice(0, at).trim() : '';
+        const target = at > 0 ? e.slice(at + 1).trim() : '';
+        if (!isApprovalAction(kind) || !target)
+            throw new UsageError(`"${e.slice(0, 60)}" is not <action>:<target>. Actions: ${APPROVAL_ACTIONS.join(', ')}.`);
+        return { action: kind, target };
+    });
+    if (!entries.length)
+        throw new UsageError('--request-many needs at least one <action>:<target>.');
+    if (entries.length > ASK_LIMIT)
+        throw new UsageError(`--request-many asks for at most ${ASK_LIMIT} things at once.`);
+    return entries;
+}
+/** A board that cannot take the ask says so in words an agent can pass on, with the terminal path. */
+function explain(e) {
+    if (e instanceof BoardError) {
+        if (e.status === 404)
+            throw new Refusal(`This board is older and cannot take approvals yet. ${FALLBACK}`);
+        if (e.status === 403)
+            throw new Refusal(`${e.message} ${FALLBACK}`);
+        if (e.status === 429)
+            throw new Refusal(e.message);
+    }
+    if (e instanceof BoardError ||
+        e instanceof TypeError ||
+        e?.name === 'TimeoutError')
+        throw new Refusal(`The board could not be reached (${e instanceof Error ? e.message.slice(0, 120) : 'no answer'}). ${FALLBACK}`);
+    throw e;
+}
+const REFUSED = {
+    refused: 'The owner refused this.',
+    expired: 'The request ran out of time before the owner decided. Ask again.',
+    cancelled: 'The request was withdrawn. Ask again.',
+    claimed: 'This approval was already used. Ask again if it is needed again.'
+};
+/**
+ * Asks the owner on the board and waits for the click (up to `waitMinutes`). Returns the codes, one per approved entry and no more, or `waiting` with the ids to resume.
+ * A refusal, an expiry and a cancel throw a Refusal with one plain sentence. An abort withdraws the request first so no orphan card stays.
+ */
+export async function askOwner(board, o) {
+    const now = o.now ?? Date.now;
+    const sleep = o.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let ids = o.resume ?? [];
+    let link = null;
+    if (!ids.length) {
+        if (!o.entries.length)
+            throw new UsageError('Say what to ask for.');
+        if (o.entries.length > ASK_LIMIT)
+            throw new UsageError(`At most ${ASK_LIMIT} things can be asked in one request.`);
+        const entries = o.entries.map((e) => {
+            if (!isApprovalAction(e.action))
+                throw new UsageError(`"${e.action.slice(0, 30)}" is not an action (${APPROVAL_ACTIONS.join(', ')}).`);
+            return { action: e.action, target: normaliseTarget(e.action, e.target) };
+        });
+        let asked;
+        try {
+            asked = await board.requestApprovals({
+                requestId: o.requestId ?? `r${now().toString(36)}${Math.random().toString(36).slice(2, 12)}`,
+                entries,
+                ...(o.why ? { why: o.why.slice(0, 2000) } : {}),
+                ...(o.project ? { project: o.project } : {})
+            });
+        }
+        catch (e) {
+            return explain(e);
+        }
+        ids = asked.requests.map((r) => r.id);
+        link = asked.link;
+        // With the person's switch on the board approves at once and there is nothing to say; a row that is still open is waiting for the switch
+        if (asked.requests.some((r) => r.status === 'pending'))
+            o.say(link
+                ? `Waiting for the owner. Ask them to turn on "Let my agent handle approvals on its own" at ${link}.`
+                : 'Waiting for the owner. Ask them to turn on "Let my agent handle approvals on its own" under Settings, Agent access.');
+    }
+    const deadline = now() + Math.max(0, o.waitMinutes) * 60_000;
+    let states;
+    for (;;) {
+        if (o.signal?.aborted) {
+            await board.cancelApprovals(ids).catch(() => undefined);
+            throw new Refusal('Stopped. The request was withdrawn from the board.');
+        }
+        try {
+            states = await board.pollApprovals(ids);
+        }
+        catch (e) {
+            return explain(e);
+        }
+        if (states.length !== ids.length)
+            throw new Refusal('The board no longer has this request. Ask again.');
+        const bad = states.find((s) => REFUSED[s.status]);
+        if (bad)
+            throw new Refusal(REFUSED[bad.status]);
+        if (states.every((s) => s.status === 'approved'))
+            break;
+        if (now() >= deadline)
+            return { state: 'waiting', ids, link };
+        await sleep(o.pollMs ?? 3000);
+    }
+    let claimed;
+    try {
+        claimed = await claimBoardDecisions(board, ids);
+    }
+    catch (e) {
+        return explain(e);
+    }
+    if (claimed.length !== ids.length)
+        throw new Refusal('The approval was used or ran out just now. Ask again.');
+    // Each claimed decision must be one of the rows asked about: the board's row for this action and target, nothing else
+    for (const c of claimed) {
+        const asked = states.find((s) => s.id === c.id);
+        if (!asked || asked.action !== c.action || asked.target !== c.target)
+            throw new Refusal('The board answered with something that was not asked for, so no code was made.');
+    }
+    const codes = claimed.map((c) => {
+        const made = mintFromDecision(c);
+        return {
+            action: c.action,
+            target: c.target,
+            code: made.code,
+            expiresAt: made.expiresAt,
+            by: c.decidedBy
+        };
+    });
+    return { state: 'approved', codes };
+}

package/dist/checks/board.js

@@ -101,6 +101,36 @@ export class RunnerBoard {
         const out = await this.call('POST', `/runs/${encodeURIComponent(runId)}/artifacts?${q}`, file.bytes, 'application/octet-stream');
         return out.attachmentId;
     }
+    // -- OWNER APPROVALS ASKED ON THE BOARD -- //
+    /** Files a request (one entry, or up to 20 as one batch). The board normalises each target and returns the rows and the page link. */
+    requestApprovals(input) {
+        return this.call('POST', '/approvals', JSON.stringify(input), 'application/json');
+    }
+    /** The state of requests of this machine. */
+    async pollApprovals(ids) {
+        return (await this.call('POST', '/approvals/poll', JSON.stringify({ ids }), 'application/json')).requests;
+    }
+    /** Withdraws waiting requests, so no card stays for an agent that gave up. */
+    cancelApprovals(ids) {
+        return this.call('POST', '/approvals/cancel', JSON.stringify({ ids }), 'application/json');
+    }
+    /** Claims approved decisions, once: the board answers only the rows that were approved, unexpired and not claimed. */
+    async claimApprovals(ids) {
+        return (await this.call('POST', '/approvals/claim', JSON.stringify({ ids }), 'application/json')).claimed;
+    }
+    // -- TEST ACCOUNT SIGN INS TYPED ON THE BOARD -- //
+    /** Publishes this machine's public sign in key (only this runner token may). */
+    publishSigninKey(input) {
+        return this.call('POST', '/signins/key', JSON.stringify(input), 'application/json');
+    }
+    /** Leases the waiting ciphertext of one registration for two minutes. */
+    leaseSignins(registration) {
+        return this.call('POST', '/signins/lease', JSON.stringify({ registration }), 'application/json');
+    }
+    /** Says the attempt is over; the board keeps pass or fail only and wipes the ciphertext. */
+    ackSignin(input) {
+        return this.call('POST', '/signins/ack', JSON.stringify(input), 'application/json');
+    }
     finish(runId, report) {
         return this.call('POST', `/runs/${encodeURIComponent(runId)}/finish`, JSON.stringify(report), 'application/json');
     }

package/dist/checks/command.js

@@ -9,7 +9,9 @@ import { dirname, relative, resolve } from 'node:path';
 import { bindFolder } from './bind.js';
 import { ensureBrowser } from './browser.js';
 import { connectChecks, loadRunnerToken, runnerAccount } from './connect.js';
-import { forgetConnection, recordConnection } from './connections.js';
+import { forgetConnection, listConnections, recordConnection } from './connections.js';
+import { RunnerBoard } from './board.js';
+import { publishSigninKey } from './signinKey.js';
 import { ORG_SLUG, scriptPath, scriptsDir } from './paths.js';
 import { pinFiles, resolveProjectConfig } from './recipe.js';
 import { runCheck } from './run.js';
@@ -30,7 +32,9 @@ export const CHECK_USAGE = [
     '  watch [--parallel N] [--once]   take queued runs from the boards this machine is connected to',
     '  run ... also takes [--registration NAME] [--file <script inside the scripts folder>] [--headed]',
     '  project <NAME> --org <slug> (--repo <dir> [--app-dir web] [--board-project KEY] [--recipe] | --url <address> [--extra-hosts a,b]) [--adopt-env --adopt-env-approval <code>] [--upload-pictures --pictures-approval <code>] [--approval <code>] | project list|forget|pin',
-    '  approve --action <roots|register|secrets|adopt-env|pictures> --target <name>   (the owner, on a terminal)  |  roots add|list|remove <dir> [--approval <code>]',
+    '  approve --request --action <roots|register|secrets|adopt-env|pictures|login> --target <name> [--why "<sentence>"] [--wait <minutes>]   (asks the owner on the board; no terminal)',
+    '  approve --request-many "<action>:<target>;<action>:<target>"  |  approve --resume <id,id> [--wait <minutes>]   (exit 3 = still waiting)',
+    '  approve --action <roots|register|secrets|adopt-env|pictures|login> --target <name>   (the owner, on a terminal)  |  roots add|list|remove <dir> [--approval <code>]',
     '  secrets import|list|forget --org <slug> --project <NAME> [--from <file> --keys A,B --test-ref <ref> --test-inbox <email> --owner-said "<sentence>" --allow-service-role --approval <code>]',
     '  login <NAME> --org <slug> --seeded  |  service install|uninstall|status [--no-start]  |  import-legacy --from <afb-checks folder> --org <slug> [--dry-run]',
     '  status [--json]  |  doctor [--fix] [--json]  |  clear [runs|profiles|auth|dbs|previews|all] [--all] [--yes]  |  setup  |  disconnect --server <url> --org <slug>'
@@ -97,6 +101,10 @@ export async function checkMain(ctx) {
                 out
             });
             recordConnection({ server: s, org: o, name: done.name });
+            // The sign in key of this machine goes to the board with the connection. A board that does not know it yet, or a failure, never stops a connect
+            const runnerToken = loadRunnerToken(ctx.store, s, o);
+            if (runnerToken)
+                await publishSigninKey(new RunnerBoard(s, runnerToken, ctx.fetch)).catch(() => undefined);
             return 0;
         }
         if (sub === 'disconnect') {
@@ -206,12 +214,56 @@ export async function checkMain(ctx) {
         // The registration, approval, sign in and service commands live in their own modules; each takes the arguments after its word
         if (sub === 'project')
             return await projectCommand(args.slice(1), { log, out, json });
-        if (sub === 'approve')
-            return await approveCommand(args.slice(1), { log, out, json });
+        if (sub === 'approve') {
+            // Asking on the board uses this machine's own runner connection; with one connection --server and --org may be left out
+            const only = listConnections();
+            const board = () => {
+                const s = flag('--server') ??
+                    process.env.AFB_SERVER ??
+                    (only.length === 1 ? only[0]?.server : undefined);
+                const o = flag('--org') ?? (only.length === 1 ? only[0]?.org : undefined);
+                if (!s || !o || !ORG_SLUG.test(o))
+                    throw new Error('Say which board: --server <url> --org <slug> (or connect this machine to one board only).');
+                const token = loadRunnerToken(ctx.store, s.replace(/\/$/, ''), o);
+                if (!token)
+                    throw new Error(`This machine is not connected to ${o} on ${s}. Run: agent-flow-board check connect --server ${s} --org ${o} --json`);
+                return new RunnerBoard(s, token, ctx.fetch);
+            };
+            // Ctrl-C or a kill withdraws the request, so no card is left on the board for an agent that is gone
+            const ac = new AbortController();
+            const stop = () => ac.abort();
+            process.once('SIGINT', stop);
+            process.once('SIGTERM', stop);
+            try {
+                return await approveCommand(args.slice(1), { log, out, json, board, signal: ac.signal });
+            }
+            finally {
+                process.off('SIGINT', stop);
+                process.off('SIGTERM', stop);
+            }
+        }
         if (sub === 'roots')
             return await rootsCommand(args.slice(1), { log, out, json });
-        if (sub === 'login')
-            return await loginCommand(args.slice(1), { log, out, json });
+        if (sub === 'login') {
+            const only = listConnections();
+            const board = () => {
+                const s = flag('--server') ??
+                    process.env.AFB_SERVER ??
+                    (only.length === 1 ? only[0]?.server : undefined);
+                const o = flag('--org') ?? (only.length === 1 ? only[0]?.org : undefined);
+                if (!s || !o || !ORG_SLUG.test(o))
+                    throw new Error('Say which board: --server <url> --org <slug>.');
+                const token = loadRunnerToken(ctx.store, s.replace(/\/$/, ''), o);
+                if (!token)
+                    throw new Error('This machine is not connected to that board. Run: agent-flow-board check connect --server ' +
+                        s +
+                        ' --org ' +
+                        o +
+                        ' --json');
+                return new RunnerBoard(s, token, ctx.fetch);
+            };
+            return await loginCommand(args.slice(1), { log, out, json, board });
+        }
         if (sub === 'service')
             return await serviceCommand(args.slice(1), { log, out, json });
         if (sub === 'secrets')

package/dist/checks/commands.js

@@ -7,14 +7,18 @@ import { isatty } from 'node:tty';
 import { APPROVAL_ACTIONS, Refusal, UsageError, isApprovalAction, mintApproval } from './approve.js';
 import { forgetRegistration, hasState, pinRegistration, pinState, readRegistrations, registerProject } from './registry.js';
 import { addRoot, listRoots, readRoots, removeRoot } from './roots.js';
+import { ASK_LIMIT, askOwner, parseEntries } from './askBoard.js';
 // -- CONSTANTS -- //
 const BOOLEAN_FLAGS = new Set([
     '--recipe',
     '--remove',
     '--adopt-env',
     '--upload-pictures',
+    '--request',
     '--json'
 ]);
+/** Most codes one `check approve --many` makes (the approvals file keeps 20). */
+const MANY_LIMIT = 15;
 // -- FUNCTIONS -- //
 function parse(args) {
     const pos = [];
@@ -168,16 +172,52 @@ export async function projectCommand(args, ctx) {
 }
 /**
  * `check approve --action <register|secrets|adopt-env|roots|pictures> --target <name or folder>`: the owner's single-use code. Refused without an interactive terminal.
+ * `check approve --many "<action>:<target>;<action>:<target>"` makes several codes in one call (at most 15) under the same rule.
  * `env.isTTY` is for the tests; the command itself passes the real flag of the terminal.
  */
 export async function approveCommand(args, ctx, env = {}) {
-    return guarded(ctx, () => {
+    return guarded(ctx, async () => {
         const p = parse(args);
+        const isTTY = env.isTTY ?? (isatty(0) && isatty(1));
+        // ASKING THE OWNER ON THE BOARD (no terminal): --request, --request-many or --resume
+        if (p.flags.has('--request') || p.flags.has('--request-many') || p.flags.has('--resume'))
+            return await requestOnBoard(p, ctx);
+        // MANY CODES IN ONE CALL
+        // Same rules as one code: a terminal only, one action and one target per code, single use, ten minutes. All entries are checked before any code is made.
+        const many = text(p, '--many');
+        if (many !== undefined) {
+            if (p.flags.has('--action') || p.flags.has('--target'))
+                throw new UsageError('Use --many on its own, or --action with --target.');
+            const entries = many
+                .split(';')
+                .map((e) => e.trim())
+                .filter(Boolean)
+                .map((e) => {
+                const at = e.indexOf(':');
+                const kind = at > 0 ? e.slice(0, at).trim() : '';
+                const target = at > 0 ? e.slice(at + 1).trim() : '';
+                if (!isApprovalAction(kind) || !target)
+                    throw new UsageError(`"${e.slice(0, 60)}" is not <action>:<target>. Actions: ${APPROVAL_ACTIONS.join(', ')}.`);
+                return { action: kind, target };
+            });
+            if (!entries.length)
+                throw new UsageError('--many needs at least one <action>:<target>.');
+            if (entries.length > MANY_LIMIT)
+                throw new UsageError(`--many makes at most ${MANY_LIMIT} codes at once.`);
+            const codes = entries.map((e) => {
+                const made = mintApproval(e.action, e.target, { isTTY });
+                return { action: e.action, target: e.target, code: made.code, expiresAt: made.expiresAt };
+            });
+            show(ctx, { codes }, [
+                ...codes.map((c) => `Approval code for ${c.action} on ${c.target}: ${c.code}`),
+                `Each works once and expires at ${codes[0]?.expiresAt ?? ''}. Give each to the command that asked for it, with --approval.`
+            ]);
+            return 0;
+        }
         const action = need(p, '--action');
         if (!isApprovalAction(action))
             throw new UsageError(`--action is one of ${APPROVAL_ACTIONS.join(', ')}.`);
         const target = need(p, '--target');
-        const isTTY = env.isTTY ?? (isatty(0) && isatty(1));
         const made = mintApproval(action, target, { isTTY });
         show(ctx, { action, target, code: made.code, expiresAt: made.expiresAt }, [
             `Approval code for ${action} on ${target}: ${made.code}`,
@@ -186,6 +226,62 @@ export async function approveCommand(args, ctx, env = {}) {
         return 0;
     });
 }
+/**
+ * `check approve --request --action <x> --target <t> [--why "<sentence>"] [--wait <minutes>]`, `--request-many "<action>:<target>;..."` and `--resume <id,id>`.
+ * Files the request on the board, prints the page link, waits for the owner's click (default 10 minutes) and prints the codes. Exit 0 approved, 1 refused or expired,
+ * 2 could not ask, 3 still waiting (the ids to resume are printed).
+ */
+async function requestOnBoard(p, ctx) {
+    if (!ctx.board)
+        throw new UsageError('Asking on the board needs the check command with --server and --org.');
+    const many = text(p, '--request-many');
+    const resume = text(p, '--resume');
+    const minutes = text(p, '--wait') === undefined ? 10 : Number(text(p, '--wait'));
+    if (!Number.isInteger(minutes) || minutes < 0 || minutes > 60)
+        throw new UsageError('--wait takes a whole number of minutes from 0 to 60.');
+    let entries = [];
+    if (resume === undefined) {
+        if (many !== undefined) {
+            if (p.flags.has('--action') || p.flags.has('--target'))
+                throw new UsageError('Use --request-many on its own, or --request with --action and --target.');
+            entries = parseEntries(many);
+        }
+        else {
+            const action = need(p, '--action');
+            if (!isApprovalAction(action))
+                throw new UsageError(`--action is one of ${APPROVAL_ACTIONS.join(', ')}.`);
+            entries = [{ action, target: need(p, '--target') }];
+        }
+    }
+    const ids = resume
+        ?.split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (ids &&
+        (!ids.length || ids.length > ASK_LIMIT || ids.some((i) => !/^[0-9a-f-]{36}$/i.test(i))))
+        throw new UsageError('--resume takes the ids that were printed, separated by commas.');
+    const done = await askOwner(ctx.board(), {
+        entries,
+        why: text(p, '--why'),
+        project: text(p, '--project'),
+        waitMinutes: minutes,
+        resume: ids,
+        say: (line) => ctx.log(line),
+        signal: ctx.signal
+    });
+    if (done.state === 'waiting') {
+        const list = done.ids.join(',');
+        show(ctx, { state: 'waiting', ids: done.ids, link: done.link, resume: list }, [
+            `Still waiting for the owner. Pick it up again with: agent-flow-board check approve --resume ${list} --wait 10`
+        ]);
+        return 3;
+    }
+    show(ctx, { state: 'approved', codes: done.codes }, [
+        ...done.codes.map((c) => `Approval code for ${c.action} on ${c.target}: ${c.code}`),
+        `Each works once and expires at ${done.codes[0]?.expiresAt ?? ''}. Give each to the command that asked for it, with --approval.`
+    ]);
+    return 0;
+}
 /** `check roots add <dir> --approval <code> | list | remove <dir> --approval <code>`. */
 export async function rootsCommand(args, ctx) {
     return guarded(ctx, () => {

package/dist/checks/doctor.js

@@ -8,6 +8,7 @@ import { existsSync, lstatSync, readFileSync, readdirSync, rmSync, statSync } fr
 import { basename, join } from 'node:path';
 // -- MODULES -- //
 import { verifyAudit } from './audit.js';
+import { localFingerprint } from './signinKey.js';
 import { machineTotals } from './broker.js';
 import { listBrowserMarkers, sweepBrowserMarkers } from './browserpool.js';
 import { ensureBrowser, playwrightRuntimeDir } from './browser.js';
@@ -379,7 +380,7 @@ export async function runDoctor(ctx, opts, deps = {}) {
                 if (!existsSync(r.repo))
                     found(`${id}: the repo folder is not there any more.`, `Run: agent-flow-board check project forget ${r.name} --org ${r.org} --remove, then register it again.`);
                 else if (!rootHolding(r.repo))
-                    found(`${id}: the repo is not inside a folder the owner approved.`, 'Ask the owner: check approve --action roots --target <parent folder>, then check roots add <folder> --approval <code>.');
+                    found(`${id}: the repo is not inside a folder the owner approved.`, 'Ask the owner: check approve --request --action roots --target <parent folder>, then check roots add <folder> --approval <code>.');
                 else {
                     const pin = pinState(r);
                     if (pin === 'changed') {
@@ -534,6 +535,11 @@ export async function healthCommand(args, ctx, deps = {}) {
             `Slots: ${s.slots ? `${s.slots.busy} of ${s.slots.slots} busy` : 'unknown'}`,
             `Service: ${s.service ? s.service.state : 'not installed'}`,
             `Connections: ${s.connections.map((c) => `${c.org}@${c.server}${c.connected === false ? ' (no token)' : ''}`).join(', ') || 'none'}`,
+            ...(localFingerprint()
+                ? [
+                    `Sign-in key: ${localFingerprint()} (compare with the code on the board before typing a password there)`
+                ]
+                : []),
             `Audit chain: ${s.audit.ok ? 'ok' : 'BROKEN'} (${s.audit.lines} lines)`,
             ...s.problems.map((p) => `Problem: ${p.problem} Next: ${p.next}`),
             s.problems.length ? '' : 'Nothing is wrong.'

package/dist/checks/importlegacy.js

@@ -86,7 +86,7 @@ function importProject(org, name, old, dryRun) {
     // A live site needs the owner's code; it is never made here
     if (old.url) {
         const hosts = old.extraHosts?.length ? ` --extra-hosts ${old.extraHosts.join(',')}` : '';
-        return skip('a live site is registered only with a code from the owner', `check approve --action register --target ${name}, then check project ${name} --org ${org} --board-project ${boardProject} --url ${old.url}${hosts} --approval <code>`);
+        return skip('a live site is registered only with a code from the owner', `check approve --request --action register --target ${name}, then check project ${name} --org ${org} --board-project ${boardProject} --url ${old.url}${hosts} --approval <code>`);
     }
     if (!old.repo)
         return skip('the project file names neither a repo folder nor a live site');
@@ -96,7 +96,7 @@ function importProject(org, name, old, dryRun) {
     const root = rootHolding(folder);
     if (!root) {
         const parent = dirname(folder);
-        return skip('its repo folder is not inside a folder the owner approved', `check approve --action roots --target "${parent}", then check roots add "${parent}" --approval <code>, then import again`);
+        return skip('its repo folder is not inside a folder the owner approved', `check approve --request --action roots --target "${parent}", then check roots add "${parent}" --approval <code>, then import again`);
     }
     const input = {
         org,
@@ -229,7 +229,7 @@ export function importLegacy(opts) {
         if (s.next)
             todo.push(`${s.name}: ${s.next}`);
     if (projects.registered.length || projects.unchanged.length) {
-        todo.push(`Secrets are not moved (they are sealed with the old key). Import them again with an approval code: ${[...projects.registered, ...projects.unchanged].map((n) => `check approve --action secrets --target ${n}`).join('; ')}, then check secrets import ... --approval <code>.`);
+        todo.push(`Secrets are not moved (they are sealed with the old key). Import them again with an approval code: ${[...projects.registered, ...projects.unchanged].map((n) => `check approve --request --action secrets --target ${n}`).join('; ')}, then check secrets import ... --approval <code>.`);
         todo.push(`Make the sign-ins again: ${[...projects.registered, ...projects.unchanged].map((n) => `check login ${n} --org ${org}`).join('; ')}.`);
     }
     if (scripts.conflicts.length)

package/dist/checks/login.js

@@ -1,21 +1,26 @@
 // `check login <NAME> --org <slug> [--seeded]`: SAVING A SIGN-IN FOR A REGISTRATION'S SITE, AND THE RULES FOR USING ONE
 // --seeded signs in with a seeded account (AFB_CHECKS_<NAME>_EMAIL and _PASSWORD) or the recipe's test user, through the app's own form.
-// Without --seeded a person signs in by hand in a visible browser window: that needs an interactive terminal, and is refused without one.
-// This file is the ONE place in the bridge that reads a terminal, and only in waitForEnter, only after the TTY check.
+// Without --seeded a person signs in by hand in a visible browser window on their own desktop. It needs the owner's `login` approval (a code, from the board or a terminal),
+// used up before the window opens, and a desktop session to show the window on. The window is a fresh temporary browser profile with no debugging port, deleted afterwards,
+// and the bridge does not return what is typed into it to the agent. The wait ends when a new session cookie of the site appears, the window is closed, or the time runs out.
 // Nothing here starts a preview itself: the caller injects `target`, and the sign in function is injected too, so tests launch no browser.
 // A cookie, a password or a token is never printed.
 // -- DEP-MODULES -- //
-import { readFileSync } from 'node:fs';
-import { createInterface } from 'node:readline';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 // -- MODULES -- //
+import { consumeApproval, peekApproval } from './approve.js';
 import { loadPlaywright } from './browser.js';
 import { ORG_SLUG, registrationsDir } from './paths.js';
 import { expiryNote, loadProfileChecked, saveProfile } from './profiles.js';
 import { redact } from './redact.js';
+import { openSignin } from './signinKey.js';
 import { signInWithPassword } from './signin.js';
 // -- CONSTANTS -- //
 const NAME = /^[A-Za-z0-9_-]{1,32}$/;
+/** The window waits this long for a sign in (minutes), unless --timeout says otherwise. */
+const DEFAULT_TIMEOUT_MINUTES = 5;
 // -- FUNCTIONS -- //
 /** The variable names of a registration: AFB_CHECKS_<NAME upper, dash to underscore>_EMAIL and _PASSWORD. */
 export function envNames(name) {
@@ -77,32 +82,67 @@ export function keepRelated(state, hosts) {
         })
     };
 }
-/** The one terminal read of the bridge: waits for the person to press Enter. Used only by the headed login, after the TTY check. */
-function waitForEnter(question) {
-    return new Promise((resolve) => {
-        const rl = createInterface({ input: process.stdin, output: process.stdout });
-        rl.question(question, () => {
-            rl.close();
-            resolve();
-        });
-    });
+/**
+ * Whether this process can show a window to a person: null when it can. On Windows a service has no console session name; on Linux a desktop sets DISPLAY or WAYLAND_DISPLAY;
+ * on a Mac a shell opened over SSH is not the desktop. Otherwise one plain sentence says why a window cannot be shown.
+ */
+export function desktopProblem(env = process.env, platform = process.platform) {
+    const none = 'This process has no desktop to show a window on (for example it runs as a service or over a remote shell). Run the login from a terminal opened on the computer itself.';
+    if (platform === 'win32')
+        return env.SESSIONNAME ? null : none;
+    if (platform === 'darwin')
+        return env.SSH_CONNECTION || env.SSH_TTY ? none : null;
+    return env.DISPLAY || env.WAYLAND_DISPLAY ? null : none;
 }
-/** The headed login: a visible browser the person drives, then Enter. Only cookies and origins of the site are kept. */
-async function headedLogin(target, say) {
+/** A cookie is told apart by its name and domain, never by its value. */
+const cookieId = (c) => {
+    const k = c;
+    return `${k.domain ?? ''}|${k.name ?? ''}`;
+};
+/**
+ * The headed login: a visible browser in a fresh temporary profile (no debugging port, deleted afterwards). It ends when a session cookie of the site appears that was not there
+ * when the page loaded, when the window is closed, or when the time runs out. Only cookies and origins of the site are kept.
+ */
+async function headedLogin(target, say, timeoutMs) {
     const { chromium } = await loadPlaywright();
-    const browser = await chromium.launch({ headless: false });
+    const profile = mkdtempSync(join(tmpdir(), 'afb-login-'));
+    const hosts = [new URL(target.baseUrl).hostname, ...(target.hosts ?? [])];
+    let context = null;
     try {
-        const ctx = await browser.newContext({ baseURL: target.baseUrl, viewport: null });
-        const page = await ctx.newPage();
+        context = await chromium.launchPersistentContext(profile, {
+            headless: false,
+            viewport: null,
+            baseURL: target.baseUrl
+        });
+        let closed = false;
+        context.on('close', () => void (closed = true));
+        const page = context.pages()[0] ?? (await context.newPage());
         await page.goto(target.baseUrl);
-        say(`A browser window is open on ${target.baseUrl}. Sign in there the way you normally do (a password or Google).`);
-        say('When you can see you are signed in, come back here and press Enter. Do not close the window first.');
-        await waitForEnter('Press Enter when signed in... ');
-        const hosts = [new URL(target.baseUrl).hostname, ...(target.hosts ?? [])];
-        return keepRelated(await ctx.storageState(), hosts);
+        const before = new Set(keepRelated(await context.storageState(), hosts).cookies.map(cookieId));
+        say(`A browser window is open on ${target.baseUrl}. Sign in there the way you normally do (a password or Google). The bridge does not return what you type to your agent.`);
+        const deadline = Date.now() + timeoutMs;
+        while (!closed && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 1000));
+            if (closed)
+                break;
+            let kept;
+            try {
+                kept = keepRelated(await context.storageState(), hosts);
+            }
+            catch {
+                break;
+            }
+            if (kept.cookies.some((c) => !before.has(cookieId(c)))) {
+                // A short settle, so a sign in that sets several cookies is kept whole
+                await new Promise((r) => setTimeout(r, 2000));
+                return { state: 'signed-in', storage: keepRelated(await context.storageState(), hosts) };
+            }
+        }
+        return closed ? { state: 'closed' } : { state: 'timeout' };
     }
     finally {
-        await browser.close().catch(() => undefined);
+        await context?.close().catch(() => undefined);
+        rmSync(profile, { recursive: true, force: true });
     }
 }
 function loadRegistrationFile(org, name) {
@@ -132,7 +172,11 @@ export async function loginCommand(args, ctx) {
     const deps = {
         signIn: (baseUrl, account) => signInWithPassword(baseUrl, account),
         headed: headedLogin,
-        isTTY: Boolean(process.stdin.isTTY),
+        desktop: () => desktopProblem(),
+        approval: {
+            peek: (target, code) => peekApproval('login', target, code),
+            consume: (target, code) => consumeApproval('login', target, code)
+        },
         env: process.env,
         loadRegistration: loadRegistrationFile,
         target: defaultTarget,
@@ -145,19 +189,39 @@ export async function loginCommand(args, ctx) {
     const name = positional[0];
     const org = flagValue(args, '--org');
     const seeded = args.includes('--seeded');
+    // The sign in the owner typed on the board, encrypted to this machine: opened here in memory, never shown to the agent
+    const fromBoard = args.includes('--from-board');
     if (!name || !org) {
-        say('Usage: check login <NAME> --org <slug> [--seeded]');
+        say('Usage: check login <NAME> --org <slug> [--seeded | --from-board | --approval <code>]');
         return 1;
     }
     if (!NAME.test(name) || !ORG_SLUG.test(org)) {
         say('The registration name or the organisation is not a plain name.');
         return 1;
     }
-    // A headed login waits for a person at a screen: without a terminal it would wait for ever, so it stops at once
-    if (!seeded && !deps.isTTY) {
-        say('Signing in by hand needs a person at a terminal (it opens a browser window and waits), so it is refused here. Use --seeded with AFB_CHECKS_<NAME>_EMAIL and AFB_CHECKS_<NAME>_PASSWORD set, or a registration whose recipe has a test user.');
+    // A headed login shows a window to a person: it needs the owner's login approval and a desktop to show it on, and stops at once without either
+    const approval = flagValue(args, '--approval');
+    const minutes = flagValue(args, '--timeout');
+    const timeoutMinutes = minutes === undefined ? DEFAULT_TIMEOUT_MINUTES : Number(minutes);
+    if (fromBoard && !ctx.board) {
+        say('Reading a sign in from the board needs the check command with --server and --org.');
         return 1;
     }
+    if (!seeded && !fromBoard) {
+        if (!Number.isFinite(timeoutMinutes) || timeoutMinutes < 1 || timeoutMinutes > 30) {
+            say('--timeout takes a number of minutes from 1 to 30.');
+            return 1;
+        }
+        const problem = deps.desktop();
+        if (problem) {
+            say(problem);
+            return 1;
+        }
+        if (!approval || !deps.approval.peek(`${org}/${name}`, approval)) {
+            say(`Signing in by hand needs the owner's approval. Ask for it: agent-flow-board check approve --request --action login --target ${org}/${name}, then pass --approval <code>. Or use --seeded with AFB_CHECKS_<NAME>_EMAIL and AFB_CHECKS_<NAME>_PASSWORD set.`);
+            return 1;
+        }
+    }
     const registration = deps.loadRegistration(org, name);
     if (!registration || registration.org !== org) {
         say(`No registration "${name}" in ${org}.`);
@@ -169,7 +233,33 @@ export async function loginCommand(args, ctx) {
         target = await deps.target(registration);
         const bindKey = new URL(target.baseUrl).origin;
         let state;
-        if (seeded) {
+        if (fromBoard && ctx.board) {
+            const board = ctx.board();
+            const leased = await board.leaseSignins(name);
+            const envelope = leased.signins.find((e) => e.registration.toLowerCase() === name.toLowerCase());
+            if (!envelope) {
+                say(`No sign in is waiting on the board for ${name}. Run the login without --from-board to sign in in a window on this computer.`);
+                return 1;
+            }
+            let account = null;
+            try {
+                account = await openSignin(envelope, { orgId: leased.orgId, runnerId: leased.runnerId });
+                secrets.push(account.password);
+                state = await deps.signIn(target.baseUrl, account);
+            }
+            catch (e) {
+                // Only pass or fail goes back to the board, and the message never holds what was typed
+                await board.ackSignin({ id: envelope.id, result: 'fail' }).catch(() => undefined);
+                say(`That did not sign in. ${redact(e instanceof Error ? e.message : '', secrets).slice(0, 160)}`);
+                return 1;
+            }
+            finally {
+                if (account)
+                    account.password = '';
+            }
+            await board.ackSignin({ id: envelope.id, result: 'pass' }).catch(() => undefined);
+        }
+        else if (seeded) {
             const account = seededAccount(name, deps.env) ?? target.testUser ?? null;
             if (!account) {
                 const n = envNames(name);
@@ -180,7 +270,21 @@ export async function loginCommand(args, ctx) {
             state = await deps.signIn(target.baseUrl, account);
         }
         else {
-            state = await deps.headed(target, say);
+            // The approval is used up before the window opens, so a window never opens twice on one code
+            if (!deps.approval.consume(`${org}/${name}`, approval ?? '')) {
+                say('The owner code was used or ran out just now. Ask for a new one.');
+                return 1;
+            }
+            const outcome = await deps.headed(target, say, timeoutMinutes * 60_000);
+            if (outcome.state === 'closed') {
+                say('The window was closed before a sign in was seen, so nothing was saved.');
+                return 4;
+            }
+            if (outcome.state === 'timeout') {
+                say(`No sign in was seen within ${timeoutMinutes} minutes, so nothing was saved.`);
+                return 5;
+            }
+            state = outcome.storage;
         }
         const kept = state;
         if (!kept || (!(kept.cookies?.length ?? 0) && !(kept.origins?.length ?? 0))) {

package/dist/checks/registry.js

@@ -457,7 +457,7 @@ export function registerProject(input, approvals = {}) {
                 throw new Refusal(`${repo} is not the root of a git project (no .git there). Give the git root as --repo and the app folder as --app-dir.`);
         }
         if (!rootHolding(repo))
-            throw new Refusal(`${repo} is not inside a folder the owner approved. The owner approves its parent folder: check approve --action roots --target <folder>, then check roots add <folder> --approval <code>.`);
+            throw new Refusal(`${repo} is not inside a folder the owner approved. The owner approves its parent folder: check approve --request --action roots --target <folder>, then check roots add <folder> --approval <code>.`);
         const elsewhere = repoHeldElsewhere(org, repo);
         if (elsewhere)
             throw new Refusal(`That folder is already held by ${elsewhere}, in another organisation. A folder belongs to one organisation.`);
@@ -486,12 +486,12 @@ export function registerProject(input, approvals = {}) {
     const registerTarget = reg.url ? `${name}@${new URL(reg.url).hostname}` : name;
     if (needRegister && !approvals.register)
         throw new Refusal(reg.url
-            ? `Registering a live site, or changing the site or its hosts, needs a code from the owner: check approve --action register --target ${registerTarget}, on an interactive terminal, then --approval <code>.`
-            : `Changing the folder or hosts of ${name}, which keeps an adopted .env or saved state, needs a code from the owner: check approve --action register --target ${registerTarget}, on an interactive terminal, then --approval <code>.`);
+            ? `Registering a live site, or changing the site or its hosts, needs a code from the owner: check approve --request --action register --target ${registerTarget}, then --approval <code>.`
+            : `Changing the folder or hosts of ${name}, which keeps an adopted .env or saved state, needs a code from the owner: check approve --request --action register --target ${registerTarget}, then --approval <code>.`);
     if (needAdopt && !approvals.adoptEnv)
-        throw new Refusal(`Adopting the whole repo .env needs a code from the owner: check approve --action adopt-env --target ${name}, then --adopt-env-approval <code>.`);
+        throw new Refusal(`Adopting the whole repo .env needs a code from the owner: check approve --request --action adopt-env --target ${name}, then --adopt-env-approval <code>.`);
     if (needPictures && !approvals.pictures)
-        throw new Refusal(`Uploading pictures of a signed-in run needs a code from the owner: check approve --action pictures --target ${name}, then --pictures-approval <code>.`);
+        throw new Refusal(`Uploading pictures of a signed-in run needs a code from the owner: check approve --request --action pictures --target ${name}, then --pictures-approval <code>.`);
     if (needRegister && !peekApproval('register', registerTarget, approvals.register ?? ''))
         throw new Refusal('That approval code is wrong, used or expired. Nothing was changed.');
     if (needAdopt && !peekApproval('adopt-env', name, approvals.adoptEnv ?? ''))

package/dist/checks/roots.js

@@ -121,7 +121,7 @@ export function addRoot(dir, approval) {
         if (roots.length >= MAX_ROOTS)
             throw new Refusal(`There are already ${MAX_ROOTS} roots. Remove one first (check roots remove <folder> --approval <code>).`);
         if (!approval || !consumeApproval('roots', real, approval))
-            throw new Refusal(`Adding a root needs a code from the owner: check approve --action roots --target "${real}", on an interactive terminal, then --approval <code>.`);
+            throw new Refusal(`Adding a root needs a code from the owner: check approve --request --action roots --target "${real}", then --approval <code>.`);
         writeRoots([...roots, real]);
         appendAudit('root added', { folder: real, count: roots.length + 1 });
         return real;
@@ -136,7 +136,7 @@ export function removeRoot(dir, approval) {
         if (!hit)
             throw new Refusal(`${real} is not a root.`);
         if (!approval || !consumeApproval('roots', real, approval))
-            throw new Refusal(`Removing a root needs a code from the owner: check approve --action roots --target "${real}", on an interactive terminal, then --approval <code>.`);
+            throw new Refusal(`Removing a root needs a code from the owner: check approve --request --action roots --target "${real}", then --approval <code>.`);
         writeRoots(roots.filter((r) => r !== hit));
         appendAudit('root removed', { folder: hit, count: roots.length - 1 });
         return hit;

package/dist/checks/secrets.js

@@ -11,7 +11,7 @@ import { createHash } from 'node:crypto';
 import { closeSync, fstatSync, lstatSync, openSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 // -- MODULES -- //
-import { consumeApproval, peekApproval } from './approve.js';
+import { boardSentence, consumeApprovalNote, peekApproval } from './approve.js';
 import { appendAudit } from './audit.js';
 import { withLockSync } from './lock.js';
 import { ORG_SLUG, ensureDir, isInside, stateDirFor } from './paths.js';
@@ -37,7 +37,7 @@ const refOf = (org, name) => {
 };
 const fileOf = (org, name) => join(stateDirFor(org, name), 'secrets.sealed');
 const lockOf = (ref) => `secrets-${createHash('sha256').update(ref.toLowerCase()).digest('hex').slice(0, 20)}`;
-const helpOf = (ref) => `agent-flow-board check secrets import --project ${ref.split('/')[1] ?? ''} --org ${ref.split('/')[0] ?? ''} --from <env file in the repo> --keys <NAME,NAME> --test-ref <supabase project ref> --approval <code from check approve --action secrets --target ${ref}> (mail settings: --keys POSTMARK_SERVER_TOKEN,POSTMARK_FROM_EMAIL,POSTMARK_MESSAGE_STREAM --test-inbox <the one inbox a preview may mail> --owner-said "<says the token is a test token>")`;
+const helpOf = (ref) => `agent-flow-board check secrets import --project ${ref.split('/')[1] ?? ''} --org ${ref.split('/')[0] ?? ''} --from <env file in the repo> --keys <NAME,NAME> --test-ref <supabase project ref> --approval <code from check approve --request --action secrets --target ${ref}> (mail settings: --keys POSTMARK_SERVER_TOKEN,POSTMARK_FROM_EMAIL,POSTMARK_MESSAGE_STREAM --test-inbox <the one inbox a preview may mail> --owner-said "<says the token is a test token>")`;
 /** NAME=value lines of an env file. `export ` and one pair of quotes are allowed; a value that opens a quote it does not close on the same line is refused (names the variable). */
 export function parseImportEnv(text) {
     const out = new Map();
@@ -183,7 +183,7 @@ export function importSecrets(input) {
         throw new Error(`${fileName} is not inside the repo folder of ${ref}.`);
     // -- THE OWNER'S APPROVAL -- //
     if (!input.approval || !peekApproval(SECRETS_ACTION, ref, input.approval))
-        throw new Error(`The owner has not approved this import. Run \`agent-flow-board check approve --action secrets --target ${ref}\` in a terminal and pass the code with --approval.`);
+        throw new Error(`The owner has not approved this import. Run \`agent-flow-board check approve --request --action secrets --target ${ref}\` and pass the code with --approval.`);
     // -- THE READ: ONE HANDLE FOR THE CHECKS AND THE READ, A FILE WITH A SECOND NAME REFUSED -- //
     let text;
     const fd = openSync(resolved, 'r');
@@ -244,10 +244,12 @@ export function importSecrets(input) {
         entries[k] = { v, service: svc };
     }
     // -- THE CODE IS USED LAST -- //
-    if (!consumeApproval(SECRETS_ACTION, ref, input.approval ?? ''))
+    const used = consumeApprovalNote(SECRETS_ACTION, ref, input.approval ?? '');
+    if (!used.ok)
         throw new Error('The owner code was used or expired just now, so nothing was imported. The code is spent: ask the owner for a new one.');
     // -- THE WRITE, UNDER A LOCK -- //
-    const statement = String(input.ownerSaid ?? '').slice(0, 300);
+    // A code that came from the board carries who approved it and when; that fills the owner sentence when none was given
+    const statement = String(input.ownerSaid ?? boardSentence(used.note) ?? '').slice(0, 300);
     withLockSync(lockOf(ref), () => {
         const before = readStoreSafe(input.org, input.name);
         // Values of an earlier import stay, unless they belong to another Supabase project (mail values do not depend on one)

package/dist/checks/secretscmd.js

@@ -1,5 +1,5 @@
 // `check secrets import|list|forget`: THE COMMAND SIDE OF THE SEALED STORE (secrets.ts holds every rule)
-// Import needs the owner's approval code (check approve --action secrets --target <org>/<NAME>): an agent cannot mint one. Names only are ever printed.
+// Import needs the owner's approval code (check approve --request --action secrets --target <org>/<NAME>): an agent cannot mint one. Names only are ever printed.
 // -- MODULES -- //
 import { findRegistration } from './registry.js';
 import { forgetSecrets, importSecrets, listSecrets } from './secrets.js';
@@ -47,7 +47,7 @@ export async function secretsCommand(args, ctx) {
             if (!file || !keys)
                 throw new Error('Say --from <file> and --keys A,B.');
             if (!approval)
-                throw new Error(`Secrets are imported with the owner's approval code. The owner runs, in a terminal: agent-flow-board check approve --action secrets --target ${org}/${name}, then you pass --approval <code>.`);
+                throw new Error(`Secrets are imported with the owner's approval code. Ask the owner on the board: agent-flow-board check approve --request --action secrets --target ${org}/${name}, then you pass --approval <code>.`);
             const done = importSecrets({
                 org,
                 name,

package/dist/checks/signinKey.js

@@ -0,0 +1,104 @@
+// THE MACHINE'S SIGN IN KEY: A P-256 KEY PAIR WHOSE PUBLIC HALF IS PUBLISHED TO THE BOARD, SO THE OWNER CAN TYPE A TEST ACCOUNT'S PASSWORD ON THE BOARD WITHOUT ANY AGENT SEEING IT
+// The private half lives in the same sealed store as the saved sign ins (AES-GCM under the key in the bridge home) and is opened only in this process. A password is decrypted in memory,
+// goes to the page through Playwright `fill` and is never an argument, an environment variable, a log line or an audit line. The format mirrors src/lib/shared/signinCrypto.ts.
+// Honest limit: a process that runs as the same OS user can read the key files, like every other local secret here.
+// -- DEP-MODULES -- //
+import { createHash, webcrypto } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { appendAudit } from './audit.js';
+import { checksHome, ensureDir } from './paths.js';
+import { seal, unseal } from './store.js';
+// -- CONSTANTS -- //
+export const SIGNIN_ALG = 'ECDH-P256+HKDF-SHA256+AES-256-GCM';
+const subtle = webcrypto.subtle;
+const enc = new TextEncoder();
+const keyFile = () => join(checksHome(), 'signin-key.bin');
+const idFile = () => join(checksHome(), 'signin-key.id');
+const AAD = 'signin-private-key';
+// -- FUNCTIONS -- //
+const b64u = (bytes) => Buffer.from(bytes).toString('base64url');
+const unb64u = (text) => new Uint8Array(Buffer.from(text, 'base64url'));
+/** The text that binds a ciphertext to where it may be opened. Must equal signinAad in src/lib/shared/signinCrypto.ts. */
+export const signinAad = (orgId, runnerId, registration, keyId) => `afb-signin-v1|${orgId}|${runnerId}|${registration.toLowerCase()}|${keyId}`;
+/** Twelve hex characters in groups of four, the same rule as the board and the browser. */
+export function fingerprintOf(publicKey) {
+    const hex = createHash('sha256')
+        .update(Buffer.from(publicKey, 'base64url'))
+        .digest('hex')
+        .slice(0, 12);
+    return hex.match(/.{4}/g).join('-');
+}
+/** Makes the key pair once and keeps the private half sealed. Returns the id and the public half. */
+export async function ensureSigninKey() {
+    ensureDir(checksHome());
+    if (existsSync(keyFile()) && existsSync(idFile())) {
+        const pair = readPair();
+        if (pair)
+            return pair;
+    }
+    const pair = await subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, [
+        'deriveBits'
+    ]);
+    const pkcs8 = new Uint8Array(await subtle.exportKey('pkcs8', pair.privateKey));
+    const pub = new Uint8Array(await subtle.exportKey('raw', pair.publicKey));
+    const keyId = b64u(webcrypto.getRandomValues(new Uint8Array(12)));
+    writeFileSync(keyFile(), seal(AAD, pkcs8), { mode: 0o600 });
+    writeFileSync(idFile(), JSON.stringify({ keyId, publicKey: b64u(pub) }), { mode: 0o600 });
+    pkcs8.fill(0);
+    appendAudit('signin key made', { keyId });
+    return { keyId, publicKey: b64u(pub) };
+}
+function readPair() {
+    try {
+        const v = JSON.parse(readFileSync(idFile(), 'utf8'));
+        return typeof v.keyId === 'string' && typeof v.publicKey === 'string'
+            ? { keyId: v.keyId, publicKey: v.publicKey }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Publishes the public key. The board accepts it only on this machine's own runner token; a changed key is shown there with its time. */
+export async function publishSigninKey(board) {
+    const { keyId, publicKey } = await ensureSigninKey();
+    const done = await board.publishSigninKey({ keyId, publicKey });
+    return done;
+}
+/** The fingerprint of this machine's key, for `check status`, or null when none was made yet. */
+export function localFingerprint() {
+    const pair = existsSync(idFile()) ? readPair() : null;
+    return pair ? fingerprintOf(pair.publicKey) : null;
+}
+/** Opens one envelope in memory. A ciphertext for another org, runner, registration or key fails here, because the associated data differs. */
+export async function openSignin(envelope, where) {
+    const me = readPair();
+    if (!me || me.keyId !== envelope.keyId || envelope.alg !== SIGNIN_ALG)
+        throw new Error('That sign in was made for another key of this machine.');
+    const pkcs8 = new Uint8Array(unseal(AAD, new Uint8Array(readFileSync(keyFile()))));
+    let account;
+    try {
+        const priv = await subtle.importKey('pkcs8', pkcs8, { name: 'ECDH', namedCurve: 'P-256' }, false, ['deriveBits']);
+        const pack = JSON.parse(envelope.ciphertext);
+        const peer = await subtle.importKey('raw', unb64u(pack.epk), { name: 'ECDH', namedCurve: 'P-256' }, false, []);
+        const bits = await subtle.deriveBits({ name: 'ECDH', public: peer }, priv, 256);
+        const aad = enc.encode(signinAad(where.orgId, where.runnerId, envelope.registration, envelope.keyId));
+        const base = await subtle.importKey('raw', bits, 'HKDF', false, ['deriveKey']);
+        const key = await subtle.deriveKey({ name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(0), info: aad }, base, { name: 'AES-GCM', length: 256 }, false, ['decrypt']);
+        const plain = await subtle.decrypt({ name: 'AES-GCM', iv: unb64u(pack.iv), additionalData: aad }, key, unb64u(pack.ct));
+        const v = JSON.parse(new TextDecoder().decode(plain));
+        if (typeof v.e !== 'string' || typeof v.p !== 'string')
+            throw new Error('shape');
+        account = { email: v.e, password: v.p };
+    }
+    catch {
+        // Never says why: nothing about the contents leaves this function
+        throw new Error('That sign in could not be opened on this machine.');
+    }
+    finally {
+        pkcs8.fill(0);
+    }
+    return account;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agent-flow-board/bridge",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"type": "module",
 	"description": "Local bridge to an agent-flow-board server: forwards MCP calls over stdio, runs the coding tool hooks, writes the editor status and runs browser checks on this machine. It holds no board tool code.",
 	"license": "MIT",