@onepointfour-packs/flaredeck-agent 0.2.36 → 0.2.38

package/dist/serve.js

@@ -1,5 +1,7 @@
+import { EventEmitter } from 'node:events';
 import { createRequire } from 'node:module';
-import { START_SCRIPT as START_SCRIPT_NAME, browserBrief, crossWired, environmentBrief, notStartedBrief, startEnvironment } from './environment.js';
+import { ensureTmuxScrollback } from './tmux.js';
+import { START_SCRIPT as START_SCRIPT_NAME, browserBrief, crossWired, environmentBrief, notStartedBrief, startEnvironment, stopEnvironment, stopLeftoverEnvironments } from './environment.js';
 import { GIT_TOOL_NAMES, githubTools, publishBranch } from './github.js';
 import { freshGitHubToken } from './githubauth.js';
 import { loadBaseBranch, loadMergeConfig, preflight, preflightBrief } from './preflight.js';
@@ -24,6 +26,7 @@ import { managedPython, usingManagedPython } from './engine-antigravity.js';
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { configDir, saveConfig } from './config.js';
+import { boardArg, onMyBoards, outstandingCards } from './boards.js';
 import { browserTools } from './browser.js';
 import { watchForDesperation } from './desperation.js';
 import { note, recallWorktree, rememberWorktree, resumeBrief } from './journal.js';
@@ -173,7 +176,11 @@ export async function serve(opts) {
         if (!['message', 'commented', 'ask'].includes(event.event))
             return null;
         const text = `${event.line ?? ''} ${event.message ?? ''}`;
-        const codes = [...new Set(text.match(/\b[A-Z][A-Z0-9]{1,9}-\d{3,}\b/g) ?? [])];
+        // Prose a person typed, so there is no field to read and a pattern is the only way. The
+        // bound was ten characters before the dash, which silently excluded real boards —
+        // DOCUMENTREPOSITOR-0022 is seventeen. Where a TOOL answers, the code is read from the
+        // fields it prints instead; see outstandingCards.
+        const codes = [...new Set(text.match(/\b[A-Z][A-Z0-9]{1,23}-\d{3,}\b/g) ?? [])];
         for (const code of codes) {
             // What the harness wrote down when it made the worktree, first: the directory is named from
             // the card's internal id and the branch from whatever the agent chose, so neither can be
@@ -228,6 +235,12 @@ export async function serve(opts) {
         if (await releaseSharedPushGuard(c.path).catch(() => false))
             log('tool', `restored push on ${c.path} (a worktree's push guard had leaked into it)`);
     }
+    // Inside tmux, the history this pane prints is only reachable with tmux's mouse mode on.
+    void ensureTmuxScrollback((t) => log('tool', t)).catch(() => { });
+    // A restart begins with no environments: the last run's are nobody's now (see the function).
+    for (const path of new Set([config.repo, ...inScope.map((c) => c.path)])) {
+        void stopLeftoverEnvironments(path, (t) => log('tool', t)).catch(() => { });
+    }
     if (inScope.length > 1) {
         log('tool', `works in ${inScope.length} repositories: ${inScope.map((c) => c.name).join(', ')}`);
     }
@@ -332,13 +345,22 @@ export async function serve(opts) {
     const reader = opts.me ?? opts.deck ?? null;
     const answeredHere = new Map();
     let refreshing = null;
+    /** This agent's own id, and (on a lead) the agents that report to it — whose requests it sees. */
+    let selfId = '';
+    let teamIds = new Set();
     const refreshApprovals = () => {
         if (!reader)
             return Promise.resolve();
         if (refreshing)
             return refreshing;
         refreshing = reader.pendingApprovals().then((all) => {
-            const mine = all.filter((a) => a.tool_name === SCRIPT_REQUEST);
+            // Its own requests, and on a lead its team's. Every pending request in the workspace used
+            // to be listed on every pane, so CASE showed HAL's request as if it were CASE's business.
+            // Until this agent knows who it is (the team read failed), nothing is hidden.
+            const ours = (a) => !selfId
+                || a.sender_key === selfId
+                || (isLead && (a.review?.by === selfId || (!!a.sender_key && teamIds.has(a.sender_key))));
+            const mine = all.filter((a) => a.tool_name === SCRIPT_REQUEST && ours(a));
             state.approvals = mine.map((a) => {
                 const lines = (a.input_preview || '').split('\n');
                 const preview = lines.find((l) => l.startsWith('-- RAN') || /would_touch/.test(l))?.replace(/^-- /, '').replace(/^harness preview.*?:\s*/, '');
@@ -453,29 +475,58 @@ export async function serve(opts) {
                     return null;
                 return flagCard({ card: cur.card, board: cur.board, code: cur.code }, reason, kind);
             },
-            unflag: async () => {
-                const cur = onCard;
-                if (!cur)
-                    return;
+            unflag: async (cur) => {
                 parked.delete(cur.card);
                 await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'clear-needs-human', {
                     card_id: cur.code || cur.card,
                     ...(cur.board ? { board_id: cur.board } : {}),
                 }).catch((e) => log('warn', `could not clear needs-human: ${e instanceof Error ? e.message : String(e)}`));
             },
-        }, () => leadId, onAsk)
+        }, () => leadId, onAsk, (card, text) => resumeParked(card, text))
         : undefined;
     // Answering from this keyboard: the person's own login decides, through the same endpoint the
     // phone uses, so the agent waiting on it sees the verdict as any other.
-    const decide = opts.me
+    /**
+     * The person answering from this pane. Signed in once per machine, from the pane when nobody
+     * has: press a/d and it asks. Never the agent's own login — an approval is a person's decision,
+     * and the agent has a shell on this box and its own credentials in it.
+     */
+    let me = opts.me;
+    state.person = !!me;
+    const startSignIn = () => {
+        if (signingIn) {
+            log('event', 'still waiting for the sign-in — paste the address your browser ended on');
+            return;
+        }
+        if (!opts.signInMe) {
+            log('warn', 'nobody is signed in here to answer with — run: flaredeck-agent login --me');
+            return;
+        }
+        signingIn = true;
+        log('event', 'Sign in as YOURSELF to answer from this pane (once per machine). Open the address below, sign in, then paste the address your browser ends up on into the box here and press Enter.');
+        opts.signInMe((t) => { if (t.trim())
+            log('event', t); }, signInReader)
+            .then((client) => {
+            me = client ?? undefined;
+            state.person = !!me;
+            log(me ? 'event' : 'warn', me ? 'signed in — a approves, d denies, from this pane' : 'signed in, but that login has no workspace here');
+        })
+            .catch((e) => log('warn', `sign-in did not finish: ${e instanceof Error ? e.message : String(e)}`))
+            .finally(() => { signingIn = false; });
+    };
+    const decide = opts.signInMe || opts.me
         ? (requestId, verdict) => {
+            if (!me) {
+                startSignIn();
+                return;
+            }
             const row = (state.approvals ?? []).find((a) => a.requestId === requestId);
             if (!row || row.stage !== 'ready')
                 return;
             answeredHere.set(requestId, verdict);
             row.stage = 'answered';
             row.verdict = verdict;
-            void opts.me.decide(row.commentId, verdict)
+            void me.decide(row.commentId, verdict)
                 .then(() => log('you', `${verdict === 'allow' ? 'approved' : 'denied'} ${row.name} (${row.agent}, ${row.card}) from here`))
                 .catch((e) => { answeredHere.delete(requestId); log('warn', `could not record that: ${e instanceof Error ? e.message : String(e)}`); void refreshApprovals(); });
         }
@@ -559,6 +610,8 @@ export async function serve(opts) {
         if (leadId)
             log('tool', `your lead is ${leadName} — ${leadName} verifies your work before it goes anywhere`);
         isLead = team.you.role === 'lead';
+        selfId = team.you.agentId;
+        teamIds = new Set(team.agents.filter((a) => a.reportsTo === team.you.agentId).map((a) => a.agentId));
         if (team.you.role === 'lead') {
             teamSet = {
                 // After a review the list changes — an endorsed request is now answerable, from THIS
@@ -583,11 +636,34 @@ export async function serve(opts) {
      * Polled rather than pushed, because nothing streams another agent's status — and slowly,
      * since agents check in every five minutes, so a faster poll would show the same row again.
      */
+    /**
+     * An idle worker is the lead's problem, and the lead already knows within a minute.
+     *
+     * It polls its team every sixty seconds to draw the pane, so "CASE idle 4m ago" is sitting on
+     * its screen — and it did nothing with it. Dispatch waited for the hourly sweep, or for the
+     * worker to say it was free, which for a while it never did. Eleven cards waited in Ready For
+     * Dev while two agents sat idle and the lead reported "waiting for work".
+     *
+     * The poll is already happening, so noticing costs nothing. Rate-limited because an idle
+     * worker with genuinely nothing to give it stays idle, and a lead asked about it every minute
+     * learns to say "nothing" without looking.
+     */
+    const DISPATCH_AGAIN_MS = 10 * 60 * 1000;
+    let lastDispatch = 0;
+    const workersAreIdle = (team) => myTeam(team).mine.filter((a) => !a.card && a.state !== 'stopped' && !a.stale).map((a) => a.name);
     if (leadOfTeam) {
         const teamTimer = setInterval(() => {
             void (async () => {
                 try {
-                    showTeam(await fetchTeam(opts.baseUrl, await opts.auth()));
+                    const team = await fetchTeam(opts.baseUrl, await opts.auth());
+                    showTeam(team);
+                    const free = workersAreIdle(team);
+                    if (free.length && !working && !queue.length && Date.now() - lastDispatch > DISPATCH_AGAIN_MS) {
+                        lastDispatch = Date.now();
+                        log('event', `${free.join(', ')} ${free.length === 1 ? 'is' : 'are'} idle — looking for work to hand over`);
+                        if (enqueue({ id: `dispatch-${Date.now()}`, event: 'sweep', line: `${free.join(', ')} have nothing to do` }))
+                            void drain();
+                    }
                 }
                 catch {
                     // A team the lead briefly cannot see is not worth a line in the log every minute; the
@@ -619,12 +695,40 @@ export async function serve(opts) {
     if (engine.name !== 'claude')
         log('event', `${engine.name} is answering on this agent`);
     let liveRun = null;
+    /**
+     * This turn's browser, so it can be closed when the turn ends.
+     *
+     * A fresh tool set is built per turn, so without this the previous turn's Chromium was both
+     * unreachable and still running — a leaked browser tree for every turn that looked at
+     * anything, on a process that stays up for days.
+     */
+    let turnEyes = null;
     /**
      * Typed with nothing running: a question for the agent, answered now. It goes through the same
      * queue as a card event so it is serialised with real work, but it is local — never acknowledged
      * to the server, never a card — and it opens one long-lived session of its own so a follow-up
      * question remembers the last one.
      */
+    /**
+     * A parked card's request was answered: put the card back at the FRONT of the queue, resuming
+     * its own session in its own worktree, with what happened. The turn on whatever card is running
+     * now finishes first.
+     */
+    const resumeParked = (card, text) => {
+        const event = {
+            id: `run-${card.card}-${Date.now()}`,
+            event: 'run-answered',
+            line: text,
+            message: text,
+            cardKey: card.card,
+            ...(card.board ? { boardKey: card.board } : {}),
+            ...(card.code ? { cardCode: card.code } : {}),
+        };
+        log('event', `${card.code || card.card}: request answered — back at the front of the queue`);
+        if (enqueue(event, true)) {
+            void drain();
+        }
+    };
     const ask = (text) => {
         const event = { id: `ask-${Date.now()}`, event: 'ask', line: text, message: text };
         if (enqueue(event)) {
@@ -632,7 +736,74 @@ export async function serve(opts) {
             void drain();
         }
     };
+    /**
+     * `!command` runs in a shell, the way Claude Code's prompt does — for the person at this
+     * terminal, not the agent. It runs where the agent is working (the card's worktree, else the
+     * repo), so `!npm install` fixes the checkout the agent is stuck in. Async on purpose: a
+     * blocking call here would freeze the pane and the agent's own event stream for as long as the
+     * command took. The agent never sees it; say on the card or in a steer if it should know.
+     */
+    /** A person signing in from the pane: lines typed meanwhile go to the sign-in, not the agent. */
+    let signingIn = false;
+    const signInReader = Object.assign(new EventEmitter(), { prompt() { }, setPrompt() { }, close() { } });
+    /** The checkout the current turn is working in ('' for one that has none). */
+    let turnCwd = '';
+    /** Worktrees whose environment comes down unless a turn returns to them first. */
+    const idleStops = new Map();
+    const ENV_IDLE_MS = 20 * 60_000;
+    const scheduleEnvironmentStop = (cwd) => {
+        const before = idleStops.get(cwd);
+        if (before)
+            clearTimeout(before);
+        idleStops.set(cwd, setTimeout(() => {
+            idleStops.delete(cwd);
+            // Never the checkout a turn is in right now, even if the timer and the turn cross.
+            if (cwd === turnCwd && state.working)
+                return;
+            void stopEnvironment(cwd).then((ok) => { if (ok)
+                log('tool', `environment stopped in ${cwd.split('/').pop()} (idle 20m)`); }).catch(() => { });
+        }, ENV_IDLE_MS));
+        idleStops.get(cwd).unref?.();
+    };
+    const shell = (command) => {
+        const cwd = job?.cwd ?? config.repo;
+        log('you', `! ${command}`);
+        log('event', `running in ${cwd}`);
+        void import('node:child_process').then(({ spawn }) => {
+            const child = spawn('bash', ['-lc', command], { cwd, env: process.env });
+            const emit = (chunk, partial) => {
+                partial.s += chunk.toString('utf8');
+                const parts = partial.s.split(/\r?\n/);
+                partial.s = parts.pop() ?? '';
+                for (const ln of parts)
+                    log('shell', ln);
+            };
+            const out = { s: '' };
+            const err = { s: '' };
+            child.stdout.on('data', (c) => emit(c, out));
+            child.stderr.on('data', (c) => emit(c, err));
+            child.on('error', (e) => log('warn', `could not run it: ${e.message}`));
+            child.on('close', (code) => {
+                if (out.s)
+                    log('shell', out.s);
+                if (err.s)
+                    log('shell', err.s);
+                log(code === 0 ? 'event' : 'warn', `exit ${code ?? '?'}`);
+            });
+        });
+    };
     const steer = (text) => {
+        // Mid sign-in, the next line is the redirect address — for the sign-in, never the agent.
+        if (signingIn) {
+            signInReader.emit('line', text);
+            return;
+        }
+        if (text.startsWith('!')) {
+            const command = text.slice(1).trim();
+            if (command)
+                shell(command);
+            return;
+        }
         log('you', text);
         if (liveRun) {
             // Stamped human: the SDK treats an unattributed message as untrusted, and rightly — a line
@@ -697,6 +868,11 @@ export async function serve(opts) {
     const pending = new Set();
     /** Keep the pushed status in step with the queue — it is what a lead's pane reads. */
     const syncQueue = () => status.setQueue(queue.length, queue[0]?.cardCode || queue[0]?.cardKey || '');
+    /**
+     * The boards this agent works, by key. Empty means all of them, which is what every install
+     * did before this existed.
+     */
+    const myBoards = new Set((config.boards ?? []).map((b) => b.key));
     const enqueue = (event, front = false) => {
         if (pending.has(event.id))
             return false;
@@ -722,6 +898,8 @@ export async function serve(opts) {
     const wantsIntake = (event) => !!event.cardKey
         && event.event !== 'review'
         && event.event !== 'ask'
+        // A parked card coming back is the same work resuming, not a new card to brief.
+        && event.event !== 'run-answered'
         && !(event.event === 'commented' && event.cardDone && !event.mentioned)
         // Someone else's card is not worth reading ahead. `drain` already declines to WORK these —
         // a card this agent once touched keeps sending it every move and comment made by whoever
@@ -846,10 +1024,19 @@ export async function serve(opts) {
             return;
         let mine = [];
         try {
-            const out = await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'get-outstanding', {});
+            // Scoped, like every other account-wide question. This one is asked by the HARNESS rather
+            // than by the model, so the proxy that narrows the model's calls never saw it — and a
+            // board-scoped agent went straight back to picking up another team's cards: KD-1361, then
+            // KD-1362, from a board nobody had ticked. The card then 404s, because it is not on a
+            // board this agent works.
+            const out = await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'get-outstanding', { ...(boardArg([...myBoards]) !== undefined ? { board: boardArg([...myBoards]) } : {}) });
             const text = typeof out === 'string' ? out : JSON.stringify(out);
-            // The codes it names, in the order it names them: priority order, which is the board's.
-            mine = [...new Set(text.match(/\b[A-Z][A-Z0-9]{1,9}-\d{3,}\b/g) ?? [])].map((code) => ({ code }));
+            // Read from the fields the answer prints, and filtered here as well as asked for — the
+            // server is deployed separately from this, so the scope cannot depend on its version.
+            // In the order it names them: priority order, which is the board's.
+            mine = outstandingCards(text)
+                .filter((c) => onMyBoards(myBoards, c))
+                .map((c) => ({ code: c.code }));
         }
         catch {
             return; // unreachable board is the stream's problem to report, not this timer's
@@ -951,6 +1138,7 @@ export async function serve(opts) {
                 status.startCard(current, !!event.cardKey);
                 void report();
                 let didWork = true;
+                turnCwd = '';
                 try {
                     await handle(event);
                 }
@@ -964,7 +1152,7 @@ export async function serve(opts) {
                 status.finishCard(didWork);
                 void report();
                 pending.delete(event.id);
-                if (event.event === 'ask' || event.event === 'sweep') { /* local: nothing to acknowledge, nothing to retry */ }
+                if (event.event === 'ask' || event.event === 'sweep' || event.event === 'run-answered') { /* local: nothing to acknowledge, nothing to retry */ }
                 else if (didWork)
                     await stream.ack([event.id]);
                 else {
@@ -981,6 +1169,17 @@ export async function serve(opts) {
                 // model: uncommitted changes, or commits that never reached the remote.
                 if (tag)
                     await reportUnfinished(tag);
+                // A card's environment is kept warm for a while — the next comment on it usually comes
+                // soon — and then taken down, so a day of cards does not leave a day of servers running.
+                if (turnCwd && turnCwd !== config.repo)
+                    scheduleEnvironmentStop(turnCwd);
+                // The environment is kept warm; the browser is not. It holds a Chromium tree, the next
+                // turn builds its own, and a page left open is not something a later turn can reach.
+                if (turnEyes) {
+                    const e = turnEyes;
+                    turnEyes = null;
+                    await e.close().catch(() => { });
+                }
                 current = '';
                 delete state.plan;
                 state.working = '';
@@ -994,9 +1193,15 @@ export async function serve(opts) {
         finally {
             working = false;
         }
-        // The queue is empty and nothing is running: this agent has nothing to do. Tell its lead,
-        // once, rather than leaving them to notice.
-        if (!queue.length && !live.size)
+        // An empty queue at the end of a drain means nothing is running and nothing is waiting: this
+        // agent has nothing to do. Tell its lead, once, rather than leaving them to notice.
+        //
+        // This used to require `!live.size` as well, which reads like "nothing running" and is not.
+        // `live` holds sessions kept WARM for fifteen minutes so a follow-up on the same card costs
+        // a resume instead of a re-orientation — a cache, not work. So every agent went quiet for
+        // fifteen minutes after finishing anything, which is exactly the window in which it most
+        // needs a new card. Two sat idle and silent while eleven cards waited.
+        if (!queue.length)
             void offerToLead();
     }
     /**
@@ -1166,7 +1371,7 @@ export async function serve(opts) {
         // it may work in — one repo, or every repo in that folder — and the card says which of them
         // this work belongs to. See workspace.ts: the folder is the only declaration, so there is no
         // config list to go stale.
-        const where = await resolveCheckout(config.repo, event, config.repos);
+        const where = await resolveCheckout(config.repo, event, config.repos, opts.agent ?? '');
         let chosen = where.kind === 'repo' ? where.checkout : null;
         let fromCard = where.kind === 'repo' && where.branch ? { branch: where.branch, role: where.role } : null;
         if (where.kind === 'ambiguous') {
@@ -1243,6 +1448,13 @@ export async function serve(opts) {
             ? await ensureWorktree(repo, key, (t) => log('tool', t), startFrom, config.worktreeLocalFiles)
             : await worktreeTheMessageIsAbout(event, repo, (t) => log('tool', t));
         const cwd = tree?.path ?? repo;
+        // Back on this checkout: whatever was waiting to take its environment down can stand down.
+        turnCwd = cwd;
+        const pendingStop = idleStops.get(cwd);
+        if (pendingStop) {
+            clearTimeout(pendingStop);
+            idleStops.delete(cwd);
+        }
         // So a later message naming this card by its CODE can find the work. See rememberWorktree.
         if (tree && (event.cardCode || event.cardKey)) {
             rememberWorktree(event.cardCode || event.cardKey, tree.path, tree.branch);
@@ -1341,7 +1553,7 @@ export async function serve(opts) {
             tag = code;
             state.working = code;
         };
-        const flaredeck = flaredeckProxy(config.mcpServerName, config.mcpUrl, opts.auth, check.discovered, (w) => log('warn', w), finishGate, noteCard, keepTool, savedSoFar);
+        const flaredeck = flaredeckProxy(config.mcpServerName, config.mcpUrl, opts.auth, check.discovered, (w) => log('warn', w), finishGate, noteCard, keepTool, savedSoFar, [...myBoards]);
         const held = live.get(key);
         if (held?.timer)
             clearTimeout(held.timer);
@@ -1425,6 +1637,20 @@ export async function serve(opts) {
         // The guard is built once at startup; what this agent can reach changes per card. Handing it
         // the live picture is the difference between judging "$DATABASE_URL" as a scratch database
         // and judging it as a live one.
+        // Deployed addresses the board declared for this card's repository — the dev or UAT site. A
+        // card is usually about code that is already live somewhere, and an agent that can only see
+        // what it started locally cannot tell its own change from how the thing already behaved.
+        const declaredSites = where.kind === 'repo' ? where.sites ?? {} : {};
+        const eyes = forACard
+            ? turnEyes = browserTools({
+                repo: config.repo,
+                endpoints: () => env.endpoints,
+                sites: () => declaredSites,
+                contract: () => env.contract,
+                cwd,
+                onNote: (t) => log('tool', t),
+            })
+            : null;
         reachable = { cwd, endpoints: env.endpoints };
         if (forACard && !needsRunning)
             log('tool', 'environment not started — this card does not look like it needs one');
@@ -1460,19 +1686,12 @@ export async function serve(opts) {
             ...(prepared?.size ? { size: prepared.size } : {}),
             tools: {
                 ...(job ? { git: { server: gitServer, toolNames: GIT_TOOL_NAMES } } : {}),
-                // Eyes, when there is something running to look at. A card with no environment gets no
-                // browser tools and is told nothing about them.
-                ...(env.ran && Object.keys(env.endpoints).length
-                    ? {
-                        browser: browserTools({
-                            repo: config.repo,
-                            endpoints: () => env.endpoints,
-                            contract: () => env.contract,
-                            cwd,
-                            onNote: (t) => log('tool', t),
-                        }),
-                    }
-                    : {}),
+                // Eyes, for any card. They used to be mounted only when the harness had itself started
+                // something, which left an agent working alone unable to get them: no start script meant
+                // no browser AND no mention of one, so it could not know that writing the script it is
+                // perfectly able to write was the thing standing between it and seeing its own change.
+                // The endpoints are read through a getter, so something the agent starts mid-turn counts.
+                ...(eyes ? { browser: eyes } : {}),
                 team: teamSet,
                 flaredeck,
                 runs: runsSet,
@@ -1493,7 +1712,7 @@ export async function serve(opts) {
             freeWorkerBrief(event) +
             // Only tell an agent about the environment when the card actually needs one running.
             environmentBrief(env, cwd, needsRunning) + notStartedBrief(forACard && !needsRunning, cwd) +
-            browserBrief(env.ran && Object.keys(env.endpoints).length > 0, env.endpoints) +
+            browserBrief(env.endpoints, declaredSites, forACard) +
             (wrongEnv.length
                 ? `\n\nSTOP — the environment that started is not yours:\n${wrongEnv.map((w) => `  · ${w}`).join('\n')}\n\n` +
                     `Anything you test against it tells you about another card's code, and it will answer ` +
@@ -1757,11 +1976,26 @@ export async function serve(opts) {
                 beat();
                 continue;
             }
+            // Another board's work. Acknowledged so it does not come round again, and never read: no
+            // intake, no Jev call, no turn. One line, so it is visible that scope is doing something
+            // rather than that the agent has gone deaf.
+            if (!onMyBoards(myBoards, event)) {
+                log('tool', `not this agent's board (${event.boardName || event.boardKey}) — ${event.line}`);
+                await stream.ack([event.id]);
+                beat();
+                continue;
+            }
             // A review request for this lead: the model handles it as a turn, but the list can show
             // the row straight away.
             if (event.event === 'review')
                 void refreshApprovals();
-            if (enqueue(event)) {
+            // A review jumps the queue. It has a deadline and a worker blocked on it; behind a backlog
+            // it waited for every card ahead of it. HAL's request sat behind seven events on a freshly
+            // restarted JARVIS, listed in the pane as "with lead" and never looked at, while the hour
+            // ran down. Front, not interrupt: the turn already running finishes first.
+            if (enqueue(event, event.event === 'review')) {
+                if (event.event === 'review')
+                    log('event', `review waiting — taken next: ${event.line}`);
                 prepareAhead(event);
                 void drain();
             }
@@ -1825,6 +2059,16 @@ function prompt(event, isLead = false) {
                     'assign-card, newest bugs first. One each — an agent already on a card is refused a',
                     'second, and it messages you the moment it is free.',
                     '',
+                    'Then look at the balance. list_agents shows what each one holds and how many are',
+                    'queued behind it. Where one worker has several cards waiting and another has none,',
+                    'move a card across with assign-card: a card queued behind a busy agent is not being',
+                    'worked, and the idle one could finish it today.',
+                    '',
+                    'Each agent is shown with the repository it has checked out. Move a card only to an',
+                    'agent that has the repository the card is for — on a board where everyone works the',
+                    'same one they are interchangeable, and on a board with a ui agent and an api agent',
+                    'they are not.',
+                    '',
                 ]
                 : []),
             'If it returns nothing, say so in one line and stop. That is a perfectly good outcome and',
@@ -1835,11 +2079,13 @@ function prompt(event, isLead = false) {
             '',
             '- A card for one of the agents who report to you: assign it to the right one. That dispatch',
             '  IS the work, and this turn is done.',
-            '- A card that is yours and NOT already in progress: move it to the board\'s in-progress lane',
-            '  with update-card-status, and stop. Do not read it, do not start the work, do not comment',
-            '  on it. Moving it hands it back to you as a card of its own — with a checkout of your own,',
-            '  on its own branch — which is the only place the work can actually be done and published',
-            '  from. Working it here would edit the shared checkout and could not be pushed anywhere.',
+            '- A card that is yours and NOT already in progress: hand it to a worker if you have one free,',
+            '  with assign-card. You run one turn at a time, and a card takes minutes — for all of them you',
+            '  would be unable to assign anything or answer anyone, which is the one job only you can do.',
+            '  With nobody free, move it to the board\'s in-progress lane with update-card-status and stop:',
+            '  that hands it back to you as a card of its own, with a checkout and a branch, which is the',
+            '  only place work can be done and published from. Either way, stop here — reading it, starting',
+            '  it or commenting on it in this turn all edit the shared checkout, which publishes nowhere.',
             '- A card already in progress: say which one in a line, and stop. The harness picks those up',
             '  by itself, shortly, with a checkout of its own — you do not need to do anything for it.',
             '',