@onepointfour-packs/flaredeck-agent 0.2.37 → 0.2.39

package/dist/serve.js

@@ -1,5 +1,8 @@
+import { execFile } from 'node:child_process';
+import { EventEmitter } from 'node:events';
 import { createRequire } from 'node:module';
-import { START_SCRIPT as START_SCRIPT_NAME, browserBrief, crossWired, environmentBrief, notStartedBrief, startEnvironment, stopEnvironment, stopLeftoverEnvironments } from './environment.js';
+import { ensureTmuxScrollback } from './tmux.js';
+import { START_SCRIPT as START_SCRIPT_NAME, webPart, 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';
@@ -10,10 +13,14 @@ import { preflightFlaredeck } from './flaredeck-check.js';
 import { NOT_FOR_WORKERS, REPLACED_BY_HARNESS, callFlaredeckTool, flaredeckProxy } from './flaredeck-proxy.js';
 import { SCRIPT_REQUEST, allTargets, resumeApprovedRuns, runTools } from './runs.js';
 import { deliverDecision, flaredeckDecider } from './approval.js';
+import { subscriptionsForAgent } from './subscriptions.js';
 import { CouldNotWork, engineFor } from './engine.js';
+/** The run failed on its Claude subscription — capped or token rejected — not on its work. */
+class RetryOnAnotherPlan extends CouldNotWork {
+}
 import { jevGuard } from './jevguard.js';
 import { loadProviders } from './providers.js';
-import { currentBranch, ensureWorktree, releaseSharedPushGuard, existingWorktree, produced, releaseWorktree, tooEarlyToFinish, uncommittedCount, worktreeBrief } from './worktree.js';
+import { currentBranch, ensureWorktree, freeDiskBytes, sweepWorktrees, releaseSharedPushGuard, existingWorktree, produced, releaseWorktree, tooEarlyToFinish, uncommittedCount, worktreeBrief } from './worktree.js';
 import { askingForComponent, checkouts, resolveCheckout, voteByCode, workspaceBrief } from './workspace.js';
 import { intake, intakeText, unclearBrief } from './intake.js';
 import { standingBrief } from './agent.js';
@@ -21,13 +28,16 @@ import { startUi } from './ui.js';
 import { checkAndStage, harnessVersion, installedSdkVersion, pendingUpdate, updatesEnabled } from './updater.js';
 import { updateSidecarSdk } from './updater-python.js';
 import { managedPython, usingManagedPython } from './engine-antigravity.js';
-import { mkdirSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { configDir, saveConfig } from './config.js';
-import { browserTools } from './browser.js';
+import { configDir, loadGitHub, saveConfig } from './config.js';
+import { boardArg, onMyBoards, outstandingCards } from './boards.js';
+import { browserTools, ensureBrowser } from './browser.js';
+import { environmentTools } from './envtools.js';
 import { watchForDesperation } from './desperation.js';
 import { note, recallWorktree, rememberWorktree, resumeBrief } from './journal.js';
-import { EventStream } from './stream.js';
+import { EventStream, describeFailure } from './stream.js';
+import { canPublish, canPushTo } from './githubauth.js';
 /**
  * The always-on agent.
  *
@@ -43,8 +53,64 @@ import { EventStream } from './stream.js';
 const VERSION = createRequire(import.meta.url)('../package.json').version;
 /** How often the agent says it is alive, whether or not anything is happening. */
 const HEARTBEAT_MS = 5 * 60 * 1000;
+/** A card worktree unused this long, with nothing unpublished on it, is released. */
+const WORKTREE_IDLE_MS = 12 * 60 * 60 * 1000;
+/** Short of disk, an hour unused is enough: the card comes back from what it pushed. */
+/**
+ * Every pane line, full length, on disk: `<config>/agent.log`.
+ *
+ * The pane truncates and scrolls away, and the per-card journal keeps only 40 short lines and
+ * only while a card runs — so anything between cards (startup, usage reads, pauses) existed
+ * nowhere once it left the screen, and "what did it say?" meant a screenshot. Rotated at 5 MB to
+ * one `.1`, so a daemon that runs for weeks cannot fill the disk it is also guarding.
+ */
+const AGENT_LOG_MAX = 5 * 1024 * 1024;
+function writeAgentLog(line) {
+    try {
+        const path = join(configDir(), 'agent.log');
+        if (existsSync(path) && statSync(path).size > AGENT_LOG_MAX)
+            renameSync(path, `${path}.1`);
+        appendFileSync(path, `${new Date().toISOString()} ${line.kind.padEnd(5)} ${line.card ? `[${line.card}] ` : ''}${line.text.replace(/\n/g, '\n  ')}\n`);
+    }
+    catch { /* a log that cannot be written must never stop the agent */ }
+}
+const WORKTREE_IDLE_LOW_DISK_MS = 60 * 60 * 1000;
+/** Below this, idle worktrees are released early. */
+const DISK_LOW = 30e9;
+/** Below this, no card is started. */
+const DISK_MIN = 10e9;
 export async function serve(opts) {
     const { config } = opts;
+    /** The tenant the agent's own token is for. Reads the claim rather than the config file,
+     *  because the token is what the server authorises against. */
+    const tenantFromToken = (token) => {
+        try {
+            const part = token.split('.')[1] ?? '';
+            return JSON.parse(Buffer.from(part, 'base64url').toString('utf8')).tenantId ?? null;
+        }
+        catch {
+            return null;
+        }
+    };
+    /** When each plan's usage was last read, so a burst of short events does not read it each time. */
+    const usageReadAt = new Map();
+    const USAGE_REFRESH_MS = 5 * 60_000;
+    /** The plan the event being handled ran on, so its usage can be read once the event is done. */
+    let turnPlan = null;
+    /** Events parked until a Claude plan resets, by event id — one timer each, never two. */
+    const waitingForPlan = new Map();
+    /** The run reported its plan's usage itself, so no separate read is needed after it. */
+    let turnSawUsage = false;
+    /**
+     * Plans that failed on an event, by event id, so its retry is offered a different one.
+     *
+     * A plan that hits its cap or has its token rejected used to fail the card outright while the
+     * other plans sat unused. Now the event goes straight back on the queue and `choose` is told
+     * what not to hand out. Bounded by the plans that exist — each retry spends one — and by
+     * MAX_PLAN_SWITCHES as a backstop.
+     */
+    const failedPlans = new Map();
+    const MAX_PLAN_SWITCHES = 4;
     const stream = new EventStream(opts.baseUrl, opts.auth);
     const state = {
         version: harnessVersion(),
@@ -72,6 +138,7 @@ export async function serve(opts) {
         if (state.lines.length > 400)
             state.lines.splice(0, state.lines.length - 400);
         ui?.log(line);
+        writeAgentLog(line);
     };
     const updated = process.env['FLAREDECK_AGENT_UPDATED'];
     if (updated)
@@ -166,14 +233,20 @@ export async function serve(opts) {
      * with no code in it — which is right: a message is not authority to start work, only to carry
      * on with work that exists.
      */
-    const worktreeTheMessageIsAbout = async (event, repo, onStep) => {
+    const worktreeTheMessageIsAbout = async (event, repo, onStep, 
+    /** Makes one when none exists — see the note where this is called. */
+    make) => {
         // `ask` too: a question typed in the pane is usually about the card in front of the person,
         // and without this the turn has no checkout and therefore no publishing tools — so an agent
         // asked to commit its work truthfully answers that it cannot.
         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
@@ -190,6 +263,22 @@ export async function serve(opts) {
                 tag = code;
                 return found;
             }
+            /**
+             * Nothing there yet, and the person at this machine named it — so make it.
+             *
+             * This is what stopped "work KAN-0074" working: a card nobody had touched had no checkout,
+             * and the agent rightly refused to run it from the shared one, which was on another branch
+             * with uncommitted changes. Only for a pane ask: a comment or a message naming a card is
+             * usually talking ABOUT it, and a card event makes its own.
+             */
+            if (event.event === 'ask') {
+                const made = await make(code).catch(() => null);
+                if (made) {
+                    onStep(`made a checkout for ${code}, ${made.branch}`);
+                    tag = code;
+                    return made;
+                }
+            }
         }
         return null;
     };
@@ -228,6 +317,63 @@ 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)`);
     }
+    // Worktrees left by earlier cards — see sweepWorktrees. In the background: nothing waits on it.
+    void (async () => {
+        for (const c of [{ path: config.repo }, ...inScope])
+            await sweepWorktrees(c.path, WORKTREE_IDLE_MS, (t) => log('tool', t)).catch(() => { });
+    })();
+    // Inside tmux, the history this pane prints is only reachable with tmux's mouse mode on.
+    void ensureTmuxScrollback((t) => log('tool', t)).catch(() => { });
+    // The browser, fetched while nothing is waiting on it. 186MB is a long pause to take in the
+    // middle of the first card that needs eyes, and the agent is idle right now.
+    void ensureBrowser((t) => log('tool', `browser: ${t}`)).catch(() => { });
+    /**
+     * The workspace's MCP servers, so `flaredeck-agent login` is the only credential step on a
+     * machine. Connect Sceneflo once in FlareDeck and every agent has it; rotate its token there
+     * and every agent follows on its next start.
+     *
+     * Awaited, unlike the browser fetch above, because the first card must not run with a list
+     * that is about to change underneath it — an agent that starts without a server it should
+     * have reports a missing tool, which reads as a product fault rather than a race.
+     */
+    /**
+     * Re-fetched before every session, not only at start: a signed-in server's access token lasts
+     * about an hour, so a list fetched once at 08:00 hands out a dead token by 09:00. FlareDeck
+     * refreshes it centrally; asking again is all it takes. Merged over the machine's ORIGINAL local
+     * list each time, so a server removed in FlareDeck does not linger as "local".
+     *
+     * Returns the REQUIRED servers that could not be connected — null when FlareDeck could not be
+     * asked, which must never pause an agent: not knowing is not the same as knowing one is missing.
+     */
+    const localMcp = [...(config.mcpServers ?? [])];
+    let lastMcpNote = '';
+    const refreshMcp = async () => {
+        try {
+            const { hydrateMcpServers, mcpConfigFetcher } = await import('./hydrate.js');
+            const tenantForMcp = tenantFromToken(await opts.auth());
+            if (!tenantForMcp)
+                return null;
+            const hydrated = await hydrateMcpServers({ mcpServers: localMcp }, mcpConfigFetcher(config.mcpUrl, tenantForMcp, () => opts.auth()));
+            config.mcpServers = hydrated.mcpServers;
+            if (hydrated.note && hydrated.note !== lastMcpNote) {
+                lastMcpNote = hydrated.note;
+                log('tool', hydrated.note);
+            }
+            return hydrated.missingRequired ?? null;
+        }
+        catch (e) {
+            // Never fatal: the machine's own list still works, which is what every agent had before.
+            log('warn', `could not fetch the MCP list: ${e instanceof Error ? e.message : String(e)}`);
+            return null;
+        }
+    };
+    const mcpWallFor = (missing) => ({
+        check: 'mcp',
+        reason: `A required MCP server is not connected — ${missing.map((m) => `${m.name}: ${m.why}`).join('; ')}. ` +
+            `Nothing is worked until it is; I resume by myself within a minute of it being connected.`,
+    });
+    // Awaited, because the first card must not run with a list about to change underneath it.
+    await refreshMcp();
     // 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(() => { });
@@ -336,13 +482,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*/, '');
@@ -368,7 +523,7 @@ export async function serve(opts) {
             for (const id of [...answeredHere.keys()])
                 if (!mine.some((a) => a.request_id === id))
                     answeredHere.delete(id);
-        }).catch((e) => log('warn', `could not read the approvals list: ${e instanceof Error ? e.message : String(e)}`))
+        }).catch((e) => log('warn', `could not read the approvals list: ${describeFailure(e)}`))
             .finally(() => { refreshing = null; });
         return refreshing;
     };
@@ -451,35 +606,65 @@ export async function serve(opts) {
     // configured production targets are added to the shell every machine already has.
     const runsSet = opts.deck
         ? runTools(config.runs ?? {}, () => onCard, opts.deck, (t) => log('tool', t), {
-            flag: async (reason, kind) => {
+            attach: (card, path, comment) => attachFile(card, path, comment),
+            flag: async (reason, kind, ask) => {
                 const cur = onCard;
                 if (!cur)
                     return null;
-                return flagCard({ card: cur.card, board: cur.board, code: cur.code }, reason, kind);
+                return flagCard({ card: cur.card, board: cur.board, code: cur.code }, reason, kind, ask);
             },
-            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(); });
         }
@@ -563,6 +748,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
@@ -587,11 +774,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
@@ -623,14 +833,188 @@ export async function serve(opts) {
     if (engine.name !== 'claude')
         log('event', `${engine.name} is answering on this agent`);
     let liveRun = null;
+    /** The checkout this agent's current or last card is in — never swept from under it. */
+    let currentTree = null;
+    const activeTrees = () => new Set(currentTree ? [currentTree] : []);
+    /**
+     * Paused: a wall this agent cannot get past by itself, so it does no work at all — no turns,
+     * no tokens — until its lead resumes it. See flaredeck-mcp/src/mcp/pause.ts for the why.
+     */
+    let paused = null;
+    let readyReported = false;
+    /** Walls the agent cannot climb, checked in code — never by asking the model. */
+    const walls = async () => {
+        config.github = loadGitHub() ?? config.github;
+        const login = await canPublish(config.github).catch(() => null);
+        if (login)
+            return { check: 'github', reason: `GitHub refuses this machine's login, so nothing I write can be published. Somebody signs it in again on this machine: \`flaredeck-agent login --github-token ghp_…\` (a classic token with repo and workflow scope does not expire).` };
+        if (config.github?.accessToken) {
+            for (const c of [{ path: config.repo }, ...(await checkouts(config.repo, config.repos))]) {
+                const remote = await new Promise((resolve) => {
+                    execFile('git', ['remote', 'get-url', 'origin'], { cwd: c.path }, (err, out) => resolve(err ? '' : String(out).trim()));
+                });
+                const why = remote ? await canPushTo(config.github.accessToken, remote) : null;
+                if (why)
+                    return { check: 'github', reason: `${why} Nothing I write in ${c.path} could be published. Fix the access, or sign this machine in with an account that has it.` };
+            }
+        }
+        const missing = await refreshMcp();
+        if (missing?.length)
+            return mcpWallFor(missing);
+        const free = freeDiskBytes(config.repo);
+        if (free !== null && free < DISK_MIN) {
+            await sweepWorktrees(config.repo, WORKTREE_IDLE_LOW_DISK_MS, (t) => log('tool', t), activeTrees()).catch(() => { });
+            const after = freeDiskBytes(config.repo);
+            if (after !== null && after < DISK_MIN) {
+                return { check: 'disk', reason: `This machine has only ${(after / 1e9).toFixed(1)} GB of disk free, and builds, Docker and test environments all fail when it fills. Idle worktrees are already cleared; free space (Docker images, caches, old checkouts).` };
+            }
+        }
+        return null;
+    };
+    const enterPause = async (wall) => {
+        if (paused?.check === wall.check)
+            return;
+        paused = wall;
+        readyReported = false;
+        state.paused = wall.reason;
+        log('warn', `PAUSED (${wall.check}): ${wall.reason}`);
+        void liveRun?.stop().catch(() => { });
+        try {
+            const r = await opts.deck?.pause(wall.check, wall.reason);
+            /* A solo agent has no lead: its cards stay with it (each gets a comment) and nobody is
+               messaged. Saying "told the lead, handed back …" then described something that never
+               happened. */
+            if (r && !r.already) {
+                log('event', r.lead
+                    ? `told the lead${r.handedBack.length ? `, handed back ${r.handedBack.join(', ')}` : ''} — doing nothing until resumed`
+                    : `no lead to tell — ${r.handedBack.length ? `left a note on ${r.handedBack.join(', ')}; they stay mine` : 'nothing handed back'}. ${wall.check === 'disk' ? 'I resume myself once the disk is clear.' : wall.check === 'mcp' ? 'I resume myself once it is connected.' : 'A person resumes me.'}`);
+            }
+        }
+        catch (e) {
+            log('warn', `could not tell FlareDeck I am paused: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    };
+    // While paused: ask FlareDeck every minute whether the lead has resumed this agent (one REST
+    // call, no model), and re-check the wall every ten, saying once when it is gone.
+    let lastWallCheck = 0;
+    const pauseTick = setInterval(() => {
+        if (!paused)
+            return;
+        void (async () => {
+            const server = await opts.deck?.pauseState().catch(() => undefined);
+            if (server === null) {
+                const still = await walls();
+                if (still) {
+                    paused = null;
+                    await enterPause(still);
+                    return;
+                }
+                log('event', `resumed by the lead — back to work`);
+                paused = null;
+                state.paused = undefined;
+                void resumeOwnWork();
+                return;
+            }
+            /* Disk is a statfs call, so it is checked every tick; the others ask GitHub, so every ten
+               minutes. A disk wall that has cleared resumes the agent at once — there is nothing for a
+               lead to decide about a number, and waiting for one left the agent idle for hours after
+               the space had already been freed. */
+            const selfClearing = paused.check === 'disk' || paused.check === 'mcp';
+            if (selfClearing) {
+                let cleared = '';
+                if (paused.check === 'disk') {
+                    const free = freeDiskBytes(config.repo);
+                    if (free === null || free < DISK_MIN)
+                        return;
+                    cleared = `disk is clear (${(free / 1e9).toFixed(0)} GB free)`;
+                }
+                else {
+                    // One HTTP call a minute while paused; null (FlareDeck unreachable) is not "connected".
+                    const missing = await refreshMcp();
+                    if (missing === null || missing.length)
+                        return;
+                    cleared = 'the required MCP servers are connected';
+                }
+                const r = await opts.deck?.resumeSelf().catch(() => null);
+                if (r?.resumed) {
+                    log('event', `${cleared} — resumed myself and told the lead`);
+                    paused = null;
+                    state.paused = undefined;
+                    readyReported = false;
+                    void resumeOwnWork();
+                    return;
+                }
+                // An older server without self-resume: fall through to telling the lead, as before.
+            }
+            if ((!selfClearing && Date.now() - lastWallCheck < 10 * 60 * 1000) || readyReported)
+                return;
+            lastWallCheck = Date.now();
+            if (!(await walls())) {
+                readyReported = true;
+                log('event', `${paused.check} is fixed — told the lead; waiting to be resumed`);
+                await opts.deck?.ready().catch(() => { });
+            }
+        })();
+    }, 60 * 1000);
+    pauseTick.unref?.();
+    /**
+     * 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();
+        }
+    };
+    /**
+     * A question typed in this pane.
+     *
+     * Whatever it says is passed through untouched, with one line in front of it saying who is
+     * speaking. Nothing here tries to work out whether it is a question or an instruction: a
+     * pattern that guessed got it wrong both ways — "work KAN-0074" did nothing because a bare
+     * question never makes a worktree, and anything clever enough to catch that also caught
+     * "work out why KAN-0074 failed" and started a build nobody asked for. The model reads English
+     * better than a regular expression does; it only needed telling whose English it is.
+     *
+     * The authority is real and worth stating plainly. This person is at the machine. They can do
+     * anything the agent can do and more, directly, without asking — so there is nothing to
+     * protect here, and treating their instruction as a suggestion only wastes their time.
+     */
     const ask = (text) => {
-        const event = { id: `ask-${Date.now()}`, event: 'ask', line: text, message: text };
+        const event = {
+            id: `ask-${Date.now()}`,
+            event: 'ask',
+            line: text,
+            message: 'This was typed by the person at this machine, in the agent\'s own terminal. They have ' +
+                'every permission you have and more, and they are not waiting on anyone to approve it. ' +
+                'Read it as what it plainly says: answer it if it is a question, do it if it is an ' +
+                'instruction, and do not ask whether you may.\n\n' + text,
+        };
         if (enqueue(event)) {
             prepareAhead(event);
             void drain();
@@ -643,6 +1027,9 @@ export async function serve(opts) {
      * 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. */
@@ -690,6 +1077,11 @@ export async function serve(opts) {
         });
     };
     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)
@@ -707,7 +1099,21 @@ export async function serve(opts) {
             // every in-process FlareDeck call comes back on. From then until the turn ends, every
             // FlareDeck call fails as "interrupted" and the agent concludes FlareDeck is down. 'next'
             // waits for the tool batch to return and lands at the boundary, with nothing cut off.
-            void liveRun.steer(text).catch(() => log('warn', 'could not deliver that to the running turn'));
+            /* A run that was stopped (a pause stops it) can still be referenced here for a moment. If
+               it will not take the line, it is not running: answer it as a question instead of
+               dropping what the person typed. */
+            const run = liveRun;
+            void run.steer(text).then((heard) => {
+                if (heard !== false)
+                    return;
+                if (liveRun === run)
+                    liveRun = null;
+                ask(text);
+            }).catch(() => {
+                if (liveRun === run)
+                    liveRun = null;
+                ask(text);
+            });
         }
         else {
             ask(text);
@@ -734,7 +1140,13 @@ export async function serve(opts) {
      * which point the SDK compacts silently. So the live turn is told, once, to wrap up: finish
      * the step, leave the handover, stop. Deliberate, and it happens while there is still room.
      */
-    const CONTEXT_WRAP_UP_TOKENS = 150_000;
+    //
+    // OFF by default now. Stopping an agent part-way through a card cost more than compaction did:
+    // the card was handed to a fresh session that re-read everything to get back to where the old
+    // one already was. The end-of-card handover still happens. Set FLAREDECK_AGENT_WRAP_UP_AT to a
+    // token count to bring the mid-turn nudge back.
+    const wrapUpAt = Number(process.env['FLAREDECK_AGENT_WRAP_UP_AT']);
+    const CONTEXT_WRAP_UP_TOKENS = Number.isFinite(wrapUpAt) && wrapUpAt > 0 ? wrapUpAt : Infinity;
     const keepAlive = (key, cwd, tokens) => {
         const prev = live.get(key);
         if (prev?.timer)
@@ -760,6 +1172,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;
@@ -785,6 +1202,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
@@ -882,15 +1301,85 @@ export async function serve(opts) {
     const sweepMinutes = Number(process.env['FLAREDECK_AGENT_SWEEP_MINUTES']);
     const SWEEP_EVERY_MS = Math.max(5, Number.isFinite(sweepMinutes) ? sweepMinutes : 60) * 60 * 1000;
     const sweepsEnabled = process.env['FLAREDECK_AGENT_NO_SWEEP'] !== '1';
+    /**
+     * Read a plan's usage and post every window to the ledger.
+     *
+     * This is what the Secrets bars and `choose` route on. It used to happen only when `choose`
+     * handed a plan over, at most once an hour, in the background — so the plans a run did not get
+     * stayed "not measured yet" for days, and `choose` ranked on nothing and handed out a plan that
+     * was already at its weekly cap. Now: every plan at startup, and the plan a card used once the
+     * card is done, which is when its numbers have just moved.
+     *
+     * Never throws and never blocks work: a failed reading costs a little routing accuracy.
+     */
+    const measurePlan = async (subs, plan, force = false) => {
+        if (!subs)
+            return;
+        const last = usageReadAt.get(plan.id) ?? 0;
+        if (!force && Date.now() - last < USAGE_REFRESH_MS)
+            return;
+        usageReadAt.set(plan.id, Date.now());
+        try {
+            const { readUsage } = await import('./usage.js');
+            let why = '';
+            const windows = await readUsage({ token: plan.token, onEmpty: (w) => { why = w; } });
+            if (!windows.length) {
+                log('warn', `claude usage: ${plan.label} — could not read it (${why || 'no detail'})`);
+                return;
+            }
+            for (const w of windows)
+                await subs.seen(plan.id, w.window, w.utilization, w.resetsAt);
+            log('tool', `claude usage: ${plan.label} · ${windows.map((w) => `${w.window} ${w.utilization}%`).join(' · ')}`);
+        }
+        catch { /* bookkeeping must never interrupt work */ }
+    };
+    /** Every plan, one after another — each read starts a Claude process, so not all at once. */
+    const measureAll = async () => {
+        const subs = await subscriptionsForAgent(config.mcpUrl, () => opts.auth(), () => { }).catch(() => null);
+        if (!subs)
+            return;
+        const plans = await subs.measure().catch(() => []);
+        // Said, because a plan missing here — a revoked token — is otherwise invisible.
+        log('tool', `claude usage: measuring ${plans.length ? plans.map((p) => p.label).join(', ') : 'nothing (no readable subscription tokens)'}`);
+        for (const plan of plans)
+            await measurePlan(subs, plan, true);
+    };
+    void measureAll();
+    // The walls, checked once at start — before any card is picked up. A restart while paused
+    // picks the pause back up from FlareDeck rather than re-announcing it.
+    void (async () => {
+        const server = await opts.deck?.pauseState().catch(() => undefined);
+        if (server) {
+            paused = { check: server.check, reason: server.reason };
+            readyReported = !!server.ready;
+            state.paused = server.reason;
+            log('warn', `PAUSED since ${server.since.slice(0, 16).replace('T', ' ')} (${server.check}) — doing nothing until the lead resumes me`);
+            return;
+        }
+        const wall = await walls();
+        if (wall)
+            await enterPause(wall);
+    })();
     const sweepNow = () => {
-        if (!sweepsEnabled || stopping)
+        if (paused || !sweepsEnabled || stopping)
             return;
         // Busy is reason enough to wait: the next tick is minutes away and the work is not going
-        // anywhere. `live.size` covers a card whose session is parked between events.
-        if (working || queue.length || live.size)
+        // anywhere.
+        if (working || queue.length)
             return;
-        if (enqueue({ id: 'sweep', event: 'sweep', line: 'checking what is still assigned to you' }))
-            void drain();
+        void (async () => {
+            /* A card already in progress IS the answer to "what next" — no model needed. Asking the
+               model instead had it try to start a second card every sweep, be refused by FlareDeck's
+               one-card rule, say "the harness will pick up KAN-0074", and stop — for an hour, because
+               nothing did. So the harness resumes it first, and only sweeps when nothing is held. */
+            if (await resumeOwnWork())
+                return;
+            // `live.size` covers a card whose session is parked between events.
+            if (working || queue.length || live.size)
+                return;
+            if (enqueue({ id: 'sweep', event: 'sweep', line: 'checking what is still assigned to you' }))
+                void drain();
+        })();
     };
     /**
      * A card of mine already in progress, picked up again without being asked.
@@ -905,21 +1394,46 @@ export async function serve(opts) {
      * have been — with a worktree, a branch, and everything else a card turn gets.
      */
     const resumeOwnWork = async () => {
-        if (!sweepsEnabled || stopping || working || queue.length || live.size)
-            return;
+        /* Not `live.size`: a session kept WARM for a follow-up is a cache, not work, and blocking on
+           it meant the card in progress was never resumed within fifteen minutes of any turn. */
+        if (paused || !sweepsEnabled || stopping || working || queue.length)
+            return false;
         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
+            return false; // unreachable board is the stream's problem to report, not this timer's
+        }
+        /* IN PROGRESS by the lane's TYPE — the same test FlareDeck's one-card rule uses. This took the
+           first outstanding card in priority order whatever its lane, so it picked KAN-0080 out of
+           Review while KAN-0074 sat in "In dev" untouched: the model was told "the harness picks up
+           the card in progress" and the harness picked a different one, and the agent went round
+           that loop for an hour. Lane NAMES differ per board ("In dev", "Doing"); the type does not. */
+        let next;
+        for (const c of mine) {
+            if (sessions.has(c.code) || live.has(c.code))
+                continue;
+            const card = await opts.deck?.card(c.code).catch(() => null);
+            if (String(card?.lane?.type ?? '').toLowerCase() === 'inprogress') {
+                next = c;
+                break;
+            }
         }
-        const next = mine.find((c) => !sessions.has(c.code) && !live.has(c.code));
         if (!next)
-            return;
+            return false;
         log('tool', `picking ${next.code} back up — it is yours and already in progress`);
         if (enqueue({
             id: `resume-${next.code}-${Date.now()}`,
@@ -929,6 +1443,7 @@ export async function serve(opts) {
             cardKey: next.code,
         }))
             void drain();
+        return true;
     };
     const sweepTimer = setInterval(sweepNow, SWEEP_EVERY_MS);
     sweepTimer.unref();
@@ -1014,6 +1529,8 @@ export async function serve(opts) {
                 status.startCard(current, !!event.cardKey);
                 void report();
                 let didWork = true;
+                /** Set when the turn failed on its Claude plan, not its work: run it again at once. */
+                let switchPlan = false;
                 turnCwd = '';
                 try {
                     await handle(event);
@@ -1022,13 +1539,30 @@ export async function serve(opts) {
                     // One bad event must not take the daemon down — that is the failure it exists to fix.
                     didWork = !(e instanceof CouldNotWork);
                     log('warn', `${current}: ${e instanceof Error ? e.message : String(e)}`);
+                    if (e instanceof RetryOnAnotherPlan)
+                        switchPlan = true;
                 }
                 // Acknowledged only after the work, and only if the work could happen at all. A crash
                 // mid-turn redelivers; so does a turn that never had what it needed.
                 status.finishCard(didWork);
                 void report();
                 pending.delete(event.id);
-                if (event.event === 'ask' || event.event === 'sweep') { /* local: nothing to acknowledge, nothing to retry */ }
+                // The plan this event ran on has just moved: read it now, so the next `choose` and the
+                // Secrets tab see where it stands. Not after a plan switch — that plan is filed already.
+                // Skipped when the run already reported usage on its own — a separate read would cost a
+                // probe request to learn what the run just said.
+                if (turnPlan && !switchPlan && !turnSawUsage) {
+                    const plan = turnPlan;
+                    void subscriptionsForAgent(config.mcpUrl, () => opts.auth(), () => { })
+                        .then((subs) => measurePlan(subs, plan))
+                        .catch(() => { });
+                }
+                turnPlan = null;
+                turnSawUsage = false;
+                // Before the ask/sweep branch: a sweep that hit a dead plan is retried like any other event.
+                if (switchPlan)
+                    enqueue(event, true);
+                else 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 {
@@ -1049,6 +1583,13 @@ export async function serve(opts) {
                 // 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 = '';
@@ -1062,9 +1603,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();
     }
     /**
@@ -1153,7 +1700,59 @@ export async function serve(opts) {
      * needs-human" over the top of it. An agent said it had asked for help, a person was never told,
      * and the card sat.
      */
-    const flagCard = async (ref, reason, kind) => {
+    /**
+     * Put a local file on a card, done here rather than by the agent's shell. The upload is a PUT of
+     * bytes to FlareDeck's own upload address, and the auto-mode classifier refused it as
+     * "destructive, reaching production" — so an agent with seven screenshots asked a person to
+     * upload them. Same three steps the tools describe (mint a link, PUT, wire it in), no curl.
+     */
+    const attachFile = async (card, path, comment) => {
+        const { existsSync, readFileSync, realpathSync, statSync } = await import('node:fs');
+        const { basename, extname, isAbsolute, resolve } = await import('node:path');
+        const { tmpdir } = await import('node:os');
+        const full = isAbsolute(path) ? path : resolve(card.cwd, path);
+        if (!existsSync(full))
+            throw new Error(`there is no file at ${full}`);
+        const real = realpathSync(full);
+        const roots = [card.cwd, '/tmp', '/private/tmp', tmpdir()].map((r) => { try {
+            return realpathSync(r);
+        }
+        catch {
+            return r;
+        } });
+        if (!roots.some((r) => real === r || real.startsWith(`${r}/`)))
+            throw new Error('only files inside your checkout or /tmp can be attached');
+        const size = statSync(real).size;
+        if (size > 30 * 1024 * 1024)
+            throw new Error(`the file is ${Math.round(size / 1048576)} MB; the limit is 30 MB`);
+        const types = {
+            '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp',
+            '.pdf': 'application/pdf', '.csv': 'text/csv', '.txt': 'text/plain', '.log': 'text/plain', '.json': 'application/json',
+            '.md': 'text/markdown', '.html': 'text/html', '.mp4': 'video/mp4', '.webm': 'video/webm',
+        };
+        const contentType = types[extname(real).toLowerCase()] ?? 'application/octet-stream';
+        const ids = { card_id: card.code || card.card, ...(card.board ? { board_id: card.board } : {}) };
+        const minted = await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'get-attachment-upload-url', {
+            ...ids, file_name: basename(real), content_type: contentType,
+        });
+        const uploadUrl = /https?:\/\/[^\s"`]+\/upload\/[^\s"`]+/.exec(minted)?.[0];
+        const objectPath = /`object_path`: `([^`]+)`/.exec(minted)?.[1];
+        if (!uploadUrl || !objectPath)
+            throw new Error('FlareDeck did not return an upload address');
+        const put = await fetch(uploadUrl, { method: 'PUT', body: readFileSync(real), headers: { 'Content-Type': contentType } });
+        if (!put.ok)
+            throw new Error(`the upload was refused (${put.status})`);
+        const wired = await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'attach-uploaded-file', {
+            ...ids, object_path: objectPath, attach_to: 'comment', ...(comment ? { comment } : {}),
+        });
+        log('tool', `attached ${basename(real)} to ${card.code || card.card}`);
+        return `Attached ${basename(real)} to ${card.code || card.card}. ${wired.split('\n')[0]}`;
+    };
+    const flagCard = async (ref, reason, kind, 
+    /** The one-line ask and its answer buttons — what the person actually sees on a phone. */
+    ask, 
+    /** Somewhere for the person to GO, which is what a sign-in request is mostly made of. */
+    links) => {
         const label = ref.code || ref.card || 'card';
         try {
             const out = await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'set-needs-human', {
@@ -1162,6 +1761,8 @@ export async function serve(opts) {
                 ...(ref.board ? { board_id: ref.board } : {}),
                 reason,
                 ...(kind ? { kind } : {}),
+                ...(ask ? { question: ask.question, options: ask.options } : {}),
+                ...(links?.length ? { links } : {}),
             });
             if (out.trimStart().startsWith('\u274c') || out.trimStart().startsWith('\ud83d\udeab')) {
                 log('warn', `${label}: FlareDeck did not flag this card \u2014 ${out.split('\n')[0]}`);
@@ -1218,7 +1819,7 @@ export async function serve(opts) {
             log('event', `${event.cardCode || event.cardKey}: comment on a finished card — nothing to do`);
             return;
         }
-        const key = event.cardKey || (event.event === 'ask' ? 'ask' : event.event === 'sweep' ? 'sweep' : event.event === 'scheduled' ? `schedule-${event.scheduleId}` : 'inbox');
+        let key = event.cardKey || (event.event === 'ask' ? 'ask' : event.event === 'sweep' ? 'sweep' : event.event === 'scheduled' ? `schedule-${event.scheduleId}` : 'inbox');
         let turnTokens = 0;
         let nudged = false;
         // A checkout of its own per card, so it cannot edit a working tree someone else is in.
@@ -1307,9 +1908,42 @@ export async function serve(opts) {
         // the publishing tools and the journal. Without this, HAL committed its work on a message
         // turn, was told to publish with push_branch, and went looking for push_branch on the
         // filesystem: the harness had named a tool that turn did not have.
+        // Room on the disk before a card gets a checkout. An agent left alone overnight filled one to
+        // 762 MB free, and from there nothing works and nothing says why: Docker cannot make a
+        // container, builds die half-written, the machine swaps. Below LOW the idle worktrees go first
+        // (sooner than usual); below MIN the card is not started, and a person is told what to clear.
+        if (event.cardKey && willChange && (chosen || where.kind === 'none')) {
+            let free = freeDiskBytes(repo);
+            if (free !== null && free < DISK_LOW) {
+                await sweepWorktrees(repo, WORKTREE_IDLE_LOW_DISK_MS, (t) => log('tool', t), activeTrees()).catch(() => { });
+                free = freeDiskBytes(repo);
+            }
+            if (free !== null && free < DISK_MIN) {
+                const wall = await walls();
+                if (wall) {
+                    await enterPause(wall);
+                    return;
+                }
+            }
+        }
         const tree = event.cardKey && (chosen || where.kind === 'none')
             ? await ensureWorktree(repo, key, (t) => log('tool', t), startFrom, config.worktreeLocalFiles)
-            : await worktreeTheMessageIsAbout(event, repo, (t) => log('tool', t));
+            : await worktreeTheMessageIsAbout(event, repo, (t) => log('tool', t), (code) => ensureWorktree(repo, code, (t) => log('tool', t), startFrom, config.worktreeLocalFiles));
+        /**
+         * Questions about a CARD get their own session, not the shared one.
+         *
+         * Every pane ask used the single key 'ask', and a session keeps the tools it was built with.
+         * So the first question asked before a card had a checkout built a session with no browser
+         * and no publishing tools — and every later question about that card resumed it and
+         * inherited the lack. The agent reported it precisely ("the browser tools aren't mounted
+         * this session") and went looking for headless Chrome in the shell instead, which is both
+         * worse and the kind of workaround the guards exist to stop.
+         *
+         * Keyed on the checkout, so a question about a card shares a session with other questions
+         * about THAT card and nothing else.
+         */
+        if (event.event === 'ask' && tree)
+            key = `ask:${tree.path}`;
         const cwd = tree?.path ?? repo;
         // Back on this checkout: whatever was waiting to take its environment down can stand down.
         turnCwd = cwd;
@@ -1321,6 +1955,7 @@ export async function serve(opts) {
         // 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);
+            currentTree = tree.path;
         }
         // No worktree, but this turn is going to change something. That used to carry on in whatever
         // directory happened to be the fallback — no branch, no isolation, and no word said. An agent
@@ -1416,7 +2051,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);
@@ -1448,6 +2083,19 @@ export async function serve(opts) {
         if (!resume && event.cardKey && event.event !== 'review' && event.event !== 'ask') {
             await startOnBoard(event.cardCode || event.cardKey);
         }
+        /**
+         * Which card this turn is about — including when nobody dispatched it.
+         *
+         * This was set only from the event's own cardKey, so a question typed in the pane about a
+         * card had none: the agent had the card, its checkout and its environment, hit a sign-in it
+         * could not pass, and was told "there is no card being worked, so there is nobody to ask
+         * about it". It fell back to leaving a comment, which nobody is notified about. The one
+         * moment the escalation exists for, and it was unavailable.
+         *
+         * `tag` is the code the turn resolved to — from the event, or from the card a pane question
+         * named. FlareDeck takes a human code wherever it takes a card id, so the code alone is
+         * enough to flag, comment and clear.
+         */
         onCard = event.cardKey
             ? {
                 card: event.cardKey,
@@ -1455,7 +2103,9 @@ export async function serve(opts) {
                 ...(event.boardKey ? { board: event.boardKey } : {}),
                 ...(event.cardCode ? { code: event.cardCode } : {}),
             }
-            : null;
+            : tag
+                ? { card: tag, cwd, code: tag, ...(event.boardKey ? { board: event.boardKey } : {}) }
+                : null;
         job = tree
             ? {
                 cwd,
@@ -1464,7 +2114,13 @@ export async function serve(opts) {
                 // back to the repo's default branch when it has not.
                 base: startFrom ?? (await baseBranch(cwd)),
                 card: event.cardCode || key,
+                onAuthFailure: (why) => {
+                    void enterPause({ check: 'github', reason: `GitHub refused this machine's login when I pushed (${why.slice(0, 160)}), so nothing I write can be published. Somebody signs it in again on this machine: \`flaredeck-agent login --github-token ghp_…\` (a classic token with repo and workflow scope does not expire).` });
+                },
                 token: async () => {
+                    // Read fresh at every push: the login is the machine's, so signing in again from
+                    // any pane fixes an agent that has been running all day with the old one.
+                    config.github = loadGitHub() ?? config.github;
                     if (!config.github)
                         throw new Error('This machine has no GitHub login — run flaredeck-agent login.');
                     return freshGitHubToken(config.github, (next) => {
@@ -1492,7 +2148,7 @@ export async function serve(opts) {
         // servers before it was allowed to look at a stylesheet. An agent that finds it does need
         // something running can start it itself; the brief says how.
         const needsRunning = (prepared?.jev?.needs_running ?? 0) >= 0.5;
-        const env = forACard && needsRunning
+        let env = forACard && needsRunning
             // The script this board declared for the repository this card is in, if it declared one.
             // Matched on the remote, the same way the base branch is.
             ? await startEnvironment(cwd, (t) => log('tool', t), where.kind === 'repo' ? where.script : undefined)
@@ -1500,10 +2156,259 @@ 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 ?? {} : {};
+        // Which started part is the app itself — asked of the parts, since boards rarely name them.
+        const web = Object.keys(env.endpoints).length ? await webPart(env.endpoints).catch(() => undefined) : undefined;
+        if (web)
+            log('tool', `browser: "${web}" serves the app — open_page opens it by default`);
+        /**
+         * Starting the project, as something the agent can ASK FOR.
+         *
+         * It was decided once, before the turn, by a classifier not even consulted for a question
+         * typed in the pane — so the answer defaulted to "no" however plainly the card said
+         * otherwise, and the agent had to find the script and start it detached by hand. Now it can
+         * ask, and a failure hands back the error together with what it may do about it.
+         */
+        const envTools = environmentTools({
+            cwd: () => cwd,
+            script: () => (where.kind === 'repo' ? where.script : undefined),
+            running: () => (env.ran ? env : null),
+            // The same deployed addresses the browser gets, so a sign-in can be asked for the dev or
+            // UAT site and not only for something this card started.
+            sites: () => declaredSites,
+            // Straight onto the live picture: the browser reads its addresses through a getter, so
+            // open_page works the moment this returns — no new turn, nothing to re-read.
+            onStarted: (started) => {
+                env = started;
+                reachable = { cwd, endpoints: env.endpoints };
+            },
+            onNote: (t) => log('tool', t),
+            /**
+             * Turning "ask somebody" into something that actually asks.
+             *
+             * Three pieces already worked and were never joined up: open_page DETECTS a sign-in wall
+             * and says which kind it is, signInSession captures a session a person completes by hand,
+             * and loadSession replays it for every later card. The gap was the middle. All wallBrief
+             * could do was tell the agent in prose to ask, with no tool to call — so the agent wrote a
+             * comment, flagged the card and stopped. That was the only thing available to it, and it
+             * read like a model that would not try.
+             *
+             * So: start the viewer, flag the card with the address (a flag is what reaches a phone),
+             * and when the session lands, store it, clear the flag and put the card back at the front
+             * of the queue. The agent's next turn opens the app already signed in.
+             *
+             * The viewer is LOOPBACK, deliberately: it drives a browser part-way through somebody's
+             * sign-in, which is not a thing to publish on a reachable port. So the person has to be at
+             * this machine. That is the case this is for — an agent testing localhost on a developer's
+             * own box — and for a cloud agent it is a stated limit rather than a silent failure.
+             */
+            ...(onCard
+                ? {
+                    requestSignIn: async ({ part, url, why }) => {
+                        const card = onCard;
+                        if (!card)
+                            return { asked: false, why: 'the card went away while this was being asked' };
+                        if (!(await ensureBrowser((t) => log('tool', `browser: ${t}`)))) {
+                            return { asked: false, why: 'this machine has no browser and could not fetch one' };
+                        }
+                        const { chromium } = await import('playwright-core');
+                        const { signInSession } = await import('./signin.js');
+                        const { rememberSignInNow, HEADLESS_FULL } = await import('./browser.js');
+                        const { randomBytes } = await import('node:crypto');
+                        /* Through FlareDeck, not through a port on this machine. The person may be on a
+                           phone and the agent may be on a cloud box, which is the case this exists for;
+                           loopback only ever served the one where they are in the same room. */
+                        const id = `sgn_${randomBytes(9).toString('base64url')}`;
+                        /* agent-service, not the MCP. The relay was first built onto flaredeck-mcp, which
+                           cannot host it: the MCP deploys as a Firebase Function, and a Function hands you
+                           (req, res) with no http.Server underneath, so a WebSocket upgrade can never
+                           complete there. agent-service is a real Cloud Run service and already the one
+                           this harness holds an event stream open to. */
+                        const serviceUrl = process.env['FLAREDECK_RELAY_URL'] ?? config.agentServiceUrl;
+                        if (!serviceUrl) {
+                            // Configured by default, so this means somebody blanked it. Say which setting.
+                            return { asked: false, why: 'this harness has no agentServiceUrl, so a sign-in cannot be relayed' };
+                        }
+                        const relayBase = serviceUrl.replace(/^http/, 'ws').replace(/\/+$/, '');
+                        const appBase = (process.env['FLAREDECK_APP_URL'] ?? 'https://app.flaredeck.app').replace(/\/+$/, '');
+                        const viewerUrl = (t) => `${appBase}/signin/${id}?t=${encodeURIComponent(t)}`;
+                        /* Resolve as far as the ADDRESS and no further. Waiting for the sign-in itself would
+                           hold the agent's tool call open for as long as a person takes to get to their
+                           machine, and not waiting is the whole point: the card parks, the turn ends. */
+                        let settle;
+                        const ready = new Promise((r) => { settle = r; });
+                        const ref = {
+                            card: card.card,
+                            ...(card.board ? { board: card.board } : {}),
+                            ...(card.code ? { code: card.code } : {}),
+                        };
+                        void signInSession({
+                            url,
+                            launch: () => chromium.launch(HEADLESS_FULL),
+                            relay: { url: relayBase, token: await opts.auth(), id, viewerUrl },
+                            onReady: (viewer) => {
+                                log('tool', `sign-in wanted for "${part}" — ${viewer}`);
+                                void flagCard(ref, `${url} needs someone to sign in before this card can go on. ${why}\n\n` +
+                                    `Open the sign-in below and do it there. It is this agent's real browser, ` +
+                                    `shown live — click and type in the picture, then press Save & finish. The ` +
+                                    `session is kept for the whole project, so this is once, not once per card.`, 'sign_in', undefined, [{ url: viewer, label: 'Sign in' }]);
+                                settle({ asked: true, where: viewer });
+                            },
+                            onNote: (t) => log('tool', `sign-in: ${t}`),
+                        })
+                            .then(async (r) => {
+                            if (!r.ok || !r.session) {
+                                log('warn', `sign-in for "${part}" did not finish: ${r.why ?? 'nothing was saved'}`);
+                                /* Say so ON THE CARD. The flag already raised carries a link to a viewer
+                                   that is now dead, and a person coming back to it an hour later would find
+                                   a page that cannot connect and no indication why — which reads as the
+                                   feature being broken rather than as a window having closed. */
+                                void flagCard(ref, `The sign-in for ${url} expired before anyone did it — the link in the ` +
+                                    `earlier request no longer works.\n\n${why}\n\nNothing is broken: ask ` +
+                                    `the agent to try again and a fresh sign-in is offered.`, 'sign_in');
+                                settle({ asked: false, why: r.why ?? 'nothing was saved' });
+                                return;
+                            }
+                            /* Awaited, and the failure is handled. Sessions live only in FlareDeck now —
+                               there is no copy on this machine — so a failed write means the sign-in is
+                               GONE. Announcing "Signed in" and resuming the card would wake an agent that
+                               meets the same wall and asks again: a loop that reads as the feature being
+                               broken rather than as one write having failed. */
+                            const saved = await rememberSignInNow(config.repo, part, r.session, (t) => log('tool', `sign-in: ${t}`));
+                            if (!saved.ok) {
+                                log('warn', `sign-in for "${part}" completed but was NOT saved: ${saved.message ?? 'no reason given'}`);
+                                void flagCard(ref, `Someone signed in to ${url}, but the session could not be saved to FlareDeck ` +
+                                    `(${saved.message ?? 'no reason given'}). Credentials are kept only in FlareDeck, ` +
+                                    `so nothing was retained here and the sign-in has been lost.\n\n${why}\n\n` +
+                                    `Once FlareDeck is reachable, ask the agent to try again.`, 'sign_in');
+                                settle({ asked: false, why: saved.message ?? 'the session could not be saved' });
+                                return;
+                            }
+                            const site = saved.id;
+                            log('tool', `signed in — kept for ${site}; every card on this project opens straight in`);
+                            await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'clear-needs-human', {
+                                card_id: card.code || card.card,
+                                ...(card.board ? { board_id: card.board } : {}),
+                            }).catch((e) => log('warn', `could not clear needs-human: ${e instanceof Error ? e.message : String(e)}`));
+                            parked.delete(card.card);
+                            resumeParked(card, `Signed in. The session is kept for ${site}, so open_page opens the app signed ` +
+                                `in from now on. Carry on with what you were going to check: ${why}`);
+                        })
+                            .catch((e) => {
+                            const why2 = e instanceof Error ? e.message : String(e);
+                            log('warn', `sign-in for "${part}" failed: ${why2}`);
+                            settle({ asked: false, why: why2 });
+                        });
+                        return ready;
+                    },
+                }
+                : {}),
+        });
+        /**
+         * Always mounted. Mounting it only when something was already running is what cached a
+         * stale toolset for a whole session: the first question about a card came before its
+         * checkout existed, so that session had no browser, and every later question resumed it and
+         * inherited the lack — the agent went looking for headless Chrome in the shell instead. An
+         * agent with nothing to look at simply does not call these; the brief says what to do first.
+         */
+        const eyes = turnEyes = browserTools({
+            repo: config.repo,
+            endpoints: () => env.endpoints,
+            ...(web ? { defaultPart: () => web } : {}),
+            sites: () => declaredSites,
+            contract: () => env.contract,
+            cwd,
+            onNote: (t) => log('tool', t),
+        });
         reachable = { cwd, endpoints: env.endpoints };
-        if (forACard && !needsRunning)
-            log('tool', 'environment not started — this card does not look like it needs one');
+        /**
+         * Say which it is, because they are not the same and the difference matters.
+         *
+         * "this card does not look like it needs one" was printed whenever the project was not
+         * started — including when nothing had looked. Intake does not run for a question typed in
+         * the pane, so `needs_running` defaulted to 0 and the agent was told a judgement had been
+         * made about its card that had not been made at all.
+         */
+        if (forACard && !needsRunning) {
+            log('tool', prepared
+                ? 'environment not started — this card does not look like it needs one'
+                : 'environment not started — nothing judged whether it is needed; call start_environment if it is');
+        }
+        // A lead's sweep is a JOB, not a nudge: clear the ready column by running the team. A nudge
+        // got one look and "nothing to do"; a goal keeps the lead going, turn after turn, until the
+        // board itself says it is done — proven by get-portfolio, not by the lead's own say-so.
+        const leadGoal = isLead && event.event === 'sweep' && process.env['FLAREDECK_AGENT_LEAD_GOAL'] !== '0'
+            ? LEAD_SWEEP_GOAL
+            : undefined;
+        if (leadGoal)
+            log('tool', 'sweep with a goal: clear the ready column by dispatching (≤8 turns)');
+        /**
+         * Which Claude subscription pays for this run.
+         *
+         * Three subscriptions and twenty-odd agents, with daily and weekly caps that trip at
+         * different times, used to mean going round the machines logging in again. FlareDeck holds
+         * the tokens and the ledger now and picks one per run.
+         *
+         * Not reaching FlareDeck is NOT the same as having nothing left: `machine` means carry on
+         * with whatever this box is logged in as, exactly as before any of this existed. Only
+         * `none` — every subscription genuinely spent or paused — stops the run, and it says when
+         * one frees up rather than failing blankly.
+         */
+        /* The MCP list, fresh for this session — and a required server that is not connected stops
+           the work here, before a plan is spent on a card that cannot be done properly. */
+        const missingMcp = await refreshMcp();
+        if (missingMcp?.length) {
+            await enterPause(mcpWallFor(missingMcp));
+            return;
+        }
+        const subs = await subscriptionsForAgent(config.mcpUrl, () => opts.auth(), (t) => log('tool', t));
+        const claudePlan = subs ? await subs.choose(failedPlans.get(event.id) ?? []) : null;
+        if (claudePlan?.use === 'token') {
+            log('tool', `claude: ${claudePlan.label}`);
+            // On the identity line too, not only in the scrollback: the scrollback moves on, and
+            // "which account is this agent spending" is a thing you glance at, not search for.
+            state.claudeAccount = claudePlan.label;
+            // Measured again once this event is done — see measurePlan.
+            turnPlan = { id: claudePlan.id, label: claudePlan.label, token: claudePlan.token };
+        }
+        if (claudePlan?.use === 'none') {
+            const when = claudePlan.availableAt ? new Date(claudePlan.availableAt).toLocaleString() : 'later';
+            const tried = failedPlans.get(event.id)?.length ?? 0;
+            failedPlans.delete(event.id);
+            /**
+             * Spent, not paused: the harness knows to the minute when a plan comes back — FlareDeck's
+             * answer carries the soonest reset — so it waits for it and carries on by itself. Nobody is
+             * asked to do anything about a clock. Only a fleet with NO reset coming (every plan paused,
+             * which only a person undoes) is flagged.
+             */
+            if (claudePlan.availableAt && claudePlan.availableAt > Date.now()) {
+                const at = claudePlan.availableAt;
+                if (!waitingForPlan.has(event.id)) {
+                    // A little after the reset, so the first request is not refused for being a second early.
+                    const timer = setTimeout(() => {
+                        waitingForPlan.delete(event.id);
+                        log('event', `a Claude subscription is back — resuming ${event.cardCode || event.line}`);
+                        if (enqueue(event, true))
+                            void drain();
+                    }, at - Date.now() + 60_000);
+                    timer.unref?.();
+                    waitingForPlan.set(event.id, timer);
+                }
+                log('warn', `every Claude subscription is spent${tried ? ` (${tried} failed on this turn)` : ''} — waiting, resuming at ${new Date(at).toLocaleTimeString()}`);
+                return;
+            }
+            log('warn', `every Claude subscription is spent or paused${tried ? ` (${tried} failed on this turn)` : ''} — the soonest frees up ${when}`);
+            await flagCard({ card: event.cardKey ?? '', ...(event.boardKey ? { board: event.boardKey } : {}), ...(event.cardCode ? { code: event.cardCode } : {}) }, `I cannot start this card: every Claude subscription in FlareDeck is spent, paused` +
+                `${tried ? ', or just failed on this card' : ''}. ` +
+                `The soonest one frees up ${when}.\n\nNothing is wrong with the card. Add or unpause a ` +
+                `subscription on the Integrations page, or wait for the window to reset.`, 'technical');
+            return;
+        }
         const engineContext = {
+            ...(leadGoal ? { goal: leadGoal } : {}),
             config: { ...config, repo: cwd },
             // Only a real worktree confines anything; without one nothing is enforced here, and the
             // guard below makes sure a turn that would CHANGE code never gets that far.
@@ -1533,21 +2438,16 @@ export async function serve(opts) {
             ...(resume ? { resume } : {}),
             ...(prepared?.model ? { model: prepared.model } : {}),
             ...(prepared?.size ? { size: prepared.size } : {}),
+            ...(claudePlan?.use === 'token' ? { claudeToken: claudePlan.token } : {}),
             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.
+                browser: eyes,
+                env: envTools,
                 team: teamSet,
                 flaredeck,
                 runs: runsSet,
@@ -1568,7 +2468,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, web) +
             (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 ` +
@@ -1580,82 +2480,149 @@ export async function serve(opts) {
         liveRun = run;
         // An agent that has started fighting the tools is not going to stop on its own.
         const struggling = watchForDesperation();
-        for await (const out of run.events) {
-            status.observe(out);
-            if (out.kind === 'tool') {
-                const stepBack = struggling.saw(out.name);
-                if (stepBack) {
-                    log('warn', `${struggling.refusals()} refusals this turn — telling it to stop and ask`);
-                    const heard = await run.steer(stepBack).catch(() => false);
-                    // An engine that cannot be steered gets stopped instead: letting it carry on is how a
-                    // turn becomes twenty minutes of working around a guard.
-                    if (!heard) {
-                        log('warn', 'cannot steer this engine — ending the turn');
-                        await run.stop().catch(() => { });
+        /**
+         * One cap is usually seen two or three times in a run: the structured `rate_limit_event`
+         * (which knows the window and the reset), then the error on the assistant message and the
+         * result text (which know neither). Reporting all of them filed an `unknown` window with a
+         * guessed five-hour block on top of the real one — keeping a plan out hours past its actual
+         * reset. Once a run has reported a named window, the anonymous echoes are dropped.
+         */
+        let spentNamed = false;
+        let spentAny = false;
+        const spentReports = [];
+        let doneText = '';
+        let runError = null;
+        try {
+            for await (const out of run.events) {
+                status.observe(out);
+                if (out.kind === 'done' && !out.ok)
+                    doneText = String(out.result ?? '');
+                if (out.kind === 'limits' && claudePlan?.use === 'token') {
+                    /* Reported, never interpreted here. 'allowed_warning' arrives while the plan is still
+                       working — treating it as spent would retire every subscription at about half capacity
+                       and leave the agents with nothing while each account still had headroom. */
+                    if (out.spent) {
+                        const named = !!out.window && out.window !== 'unknown';
+                        spentAny = true;
+                        if (named || !spentNamed) {
+                            spentNamed ||= named;
+                            spentReports.push(subs?.spent(claudePlan.id, out.window, out.resetsAt, out.why ?? `hit during ${event.cardCode ?? event.cardKey ?? 'a run'}`) ?? Promise.resolve());
+                            log('warn', `claude: ${claudePlan.label} hit its ${out.window ?? 'usage'} limit (${out.source ?? 'unknown signal'})`);
+                        }
+                    }
+                    else if (out.window && typeof out.utilization === 'number') {
+                        turnSawUsage = true;
+                        void subs?.seen(claudePlan.id, out.window, out.utilization, out.resetsAt);
                     }
-                    if (tag)
-                        void tellLeadItIsStuck(tag, struggling.refusals());
                 }
-            }
-            state.tasks = status.snapshot().tasks;
-            // An answer to a question typed here is the whole point of the turn, so it is shown whole;
-            // a card turn's narration is one line each, the card holds the full account.
-            if (out.kind === 'text')
-                log(event.event === 'ask' ? 'answer' : 'say', out.text);
-            else if (out.kind === 'tool')
-                log('tool', out.name);
-            // A changed plan is the most informative thing an agent emits, so it is pushed at once
-            // rather than waiting for the timer.
-            else if (out.kind === 'todo') {
-                log('todo', out.text);
-                void report();
-            }
-            // The plan replaces the previous one — TodoWrite always sends the whole list.
-            else if (out.kind === 'plan') {
-                state.plan = out.items;
-                state.tasks = {
-                    done: out.items.filter((t) => t.status === 'completed').length,
-                    total: out.items.length,
-                };
-                void report();
-            }
-            else if (out.kind === 'ready') {
-                if (out.sessionId)
-                    sessions.set(key, out.sessionId);
-                // The preflight proved the server answers; this proves the SESSION got it. The SDK will
-                // start the model with a server still 'pending' or 'needs-auth' and list its tools from
-                // memory, so a count alone is not enough — the status has to say connected. Refuse the
-                // turn otherwise: the event stays queued and comes back once the tools are really there.
-                const fd = out.mcp.find((s) => s.name === config.mcpServerName);
-                log('tool', `session: FlareDeck ${fd?.status ?? 'absent'} · ${out.tools.length} tools · ${out.permissionMode}`);
-                if (!fd || fd.status !== 'connected' || out.tools.length === 0) {
-                    throw new CouldNotWork(`this session's FlareDeck server is ${fd?.status ?? 'absent'}, so the card cannot be read — leaving the event queued`);
+                if (out.kind === 'tool') {
+                    const stepBack = struggling.saw(out.name);
+                    if (stepBack) {
+                        log('warn', `${struggling.refusals()} refusals this turn — telling it to stop and ask`);
+                        const heard = await run.steer(stepBack).catch(() => false);
+                        // An engine that cannot be steered gets stopped instead: letting it carry on is how a
+                        // turn becomes twenty minutes of working around a guard.
+                        if (!heard) {
+                            log('warn', 'cannot steer this engine — ending the turn');
+                            await run.stop().catch(() => { });
+                        }
+                        if (tag)
+                            void tellLeadItIsStuck(tag, struggling.refusals());
+                    }
                 }
-            }
-            else if (out.kind === 'usage') {
-                turnTokens = out.contextTokens;
-                if (!nudged && turnTokens >= CONTEXT_WRAP_UP_TOKENS && liveRun) {
-                    nudged = true;
-                    log('warn', `context at ${Math.round(turnTokens / 1000)}k — asking it to wrap up before the window fills`);
-                    const wrapUpText = `Your context is at ${Math.round(turnTokens / 1000)}k tokens and will be compacted soon, which loses detail. ` +
-                        'Finish the step you are on, then stop: comment on the card with where things stand, put anything half-done ' +
-                        'and anything that did NOT work into set-card-notes, and end the turn. A fresh session will pick the card up from the note.';
-                    void liveRun.steer(wrapUpText);
+                state.tasks = status.snapshot().tasks;
+                // An answer to a question typed here is the whole point of the turn, so it is shown whole;
+                // a card turn's narration is one line each, the card holds the full account.
+                if (out.kind === 'text')
+                    log(event.event === 'ask' ? 'answer' : 'say', out.text);
+                else if (out.kind === 'tool')
+                    log('tool', out.name);
+                // A changed plan is the most informative thing an agent emits, so it is pushed at once
+                // rather than waiting for the timer.
+                else if (out.kind === 'todo') {
+                    log('todo', out.text);
+                    void report();
                 }
-            }
-            else if (out.kind === 'compacted')
-                log('warn', 'the SDK compacted this session mid-turn — detail before this point is summarised, not kept');
-            else if (out.kind === 'done') {
-                if (!out.ok)
-                    log('warn', 'the turn did not finish cleanly');
-                if (out.contextTokens)
+                // The plan replaces the previous one — TodoWrite always sends the whole list.
+                else if (out.kind === 'plan') {
+                    state.plan = out.items;
+                    state.tasks = {
+                        done: out.items.filter((t) => t.status === 'completed').length,
+                        total: out.items.length,
+                    };
+                    void report();
+                }
+                else if (out.kind === 'ready') {
+                    if (out.sessionId)
+                        sessions.set(key, out.sessionId);
+                    // The preflight proved the server answers; this proves the SESSION got it. The SDK will
+                    // start the model with a server still 'pending' or 'needs-auth' and list its tools from
+                    // memory, so a count alone is not enough — the status has to say connected. Refuse the
+                    // turn otherwise: the event stays queued and comes back once the tools are really there.
+                    const fd = out.mcp.find((s) => s.name === config.mcpServerName);
+                    log('tool', `session: FlareDeck ${fd?.status ?? 'absent'} · ${out.tools.length} tools · ${out.permissionMode}`);
+                    if (!fd || fd.status !== 'connected' || out.tools.length === 0) {
+                        throw new CouldNotWork(`this session's FlareDeck server is ${fd?.status ?? 'absent'}, so the card cannot be read — leaving the event queued`);
+                    }
+                }
+                else if (out.kind === 'usage') {
                     turnTokens = out.contextTokens;
-                // The number the intake step is meant to move: how big this turn's context got.
-                if (turnTokens)
-                    log('tool', `turn: ${Math.round(turnTokens / 1000)}k context${prepared?.size ? ` · ${prepared.size} work` : ''}`);
+                    if (!nudged && turnTokens >= CONTEXT_WRAP_UP_TOKENS && liveRun) {
+                        nudged = true;
+                        log('warn', `context at ${Math.round(turnTokens / 1000)}k — asking it to wrap up before the window fills`);
+                        const wrapUpText = `Your context is at ${Math.round(turnTokens / 1000)}k tokens and will be compacted soon, which loses detail. ` +
+                            'Finish the step you are on, then stop: comment on the card with where things stand, put anything half-done ' +
+                            'and anything that did NOT work into set-card-notes, and end the turn. A fresh session will pick the card up from the note.';
+                        void liveRun.steer(wrapUpText);
+                    }
+                }
+                else if (out.kind === 'compacted')
+                    log('warn', 'the SDK compacted this session mid-turn — detail before this point is summarised, not kept');
+                else if (out.kind === 'done') {
+                    if (!out.ok)
+                        log('warn', 'the turn did not finish cleanly');
+                    if (out.contextTokens)
+                        turnTokens = out.contextTokens;
+                    // The number the intake step is meant to move: how big this turn's context got.
+                    if (turnTokens)
+                        log('tool', `turn: ${Math.round(turnTokens / 1000)}k context${prepared?.size ? ` · ${prepared.size} work` : ''}`);
+                }
             }
         }
+        catch (e) {
+            runError = e;
+        }
         liveRun = null;
+        /**
+         * The plan failed, not the work: switch plans and run this event again, now.
+         *
+         * Two causes, told apart because they are fixed differently. A spent window is already filed
+         * above (awaited here, so `choose` sees it). A rejected token — "401 Invalid bearer token",
+         * a mis-pasted or revoked setup-token — is not capacity and is not filed as spent; it is
+         * excluded for this event, and says plainly that the token needs replacing.
+         *
+         * The retry resumes the same session, so work already done in the turn is not lost; it costs
+         * the prompt cache, which is the price of carrying on at all.
+         */
+        if (claudePlan?.use === 'token') {
+            const said = `${runError instanceof Error ? runError.message : runError ?? ''} ${doneText}`;
+            const rejected = /API Error: 401|invalid bearer token|OAuth token has expired|OAuth token (was )?revoked/i.test(said);
+            if (rejected || spentAny) {
+                await Promise.allSettled(spentReports);
+                const tried = [...(failedPlans.get(event.id) ?? []), claudePlan.id];
+                if (rejected) {
+                    log('warn', `claude: ${claudePlan.label} — its token was rejected. Replace it on Integrations → Secrets.`);
+                }
+                if (tried.length <= MAX_PLAN_SWITCHES) {
+                    failedPlans.set(event.id, tried);
+                    throw new RetryOnAnotherPlan(`${claudePlan.label} ${rejected ? 'rejected its token' : 'is at its limit'} — switching subscription and trying again`);
+                }
+                failedPlans.delete(event.id);
+            }
+        }
+        failedPlans.delete(event.id);
+        if (runError)
+            throw runError;
         // A question from the pane: no card to hand over to. Its session is kept so the next question
         // can build on this one, and simply dropped once it has grown too large to be worth carrying.
         if (event.event === 'ask') {
@@ -1817,8 +2784,8 @@ export async function serve(opts) {
     ui = startUi({ state: () => ({ ...state, queued: queue.length }), onSteer: steer, onQuit: shutdown, ...(decide ? { onDecide: decide } : {}) });
     try {
         for await (const event of stream.events((s) => {
-            state.connected = s === 'listening';
-            log(s === 'listening' ? 'tool' : 'warn', s);
+            state.connected = s.startsWith('listening');
+            log(state.connected ? 'tool' : 'warn', s);
         })) {
             // A verdict on a request this agent is waiting on. Handled HERE, not in drain(): the turn
             // that asked is still running — blocked inside the tool call — and drain is serialised
@@ -1832,11 +2799,34 @@ export async function serve(opts) {
                 beat();
                 continue;
             }
+            // Paused: nothing is worked. Acknowledged, because its cards went back to the lead and the
+            // lead decides what happens to them; carrying a backlog through a pause would replay it.
+            if (paused) {
+                log('tool', `paused — left for the lead: ${event.line}`);
+                await stream.ack([event.id]);
+                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();
             }
@@ -1879,6 +2869,18 @@ async function baseBranch(cwd) {
         c.on('error', () => resolve('main'));
     });
 }
+/**
+ * What a lead's sweep must achieve, as a `/goal` condition (under 4000 characters). Judged by a
+ * small model from the transcript alone, so the proof has to be IN the transcript: a final
+ * get-portfolio, quoted. Bounded, because a column that cannot be emptied (no free worker, every
+ * card blocked) must end in reasons, not in a loop.
+ */
+const LEAD_SWEEP_GOAL = 'Every card in your board\'s ready-for-work column (the lane FlareDeck calls Ready For Dev — its ' +
+    'type is todo) has been dealt with: handed to a worker that reports to you and is free, with ' +
+    'assign-card, or left there with a one-line reason it must wait (no free worker, blocked, ' +
+    'waiting on a person). You dispatch; you do not build cards yourself. The goal is met only when ' +
+    'your most recent turn called get-portfolio and you quoted, from that output, how many cards ' +
+    'are in the ready column and, for each card still there, its one-line reason. Or stop after 8 turns.';
 function prompt(event, isLead = false) {
     if (event.event === 'sweep') {
         return [
@@ -1900,6 +2902,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',
@@ -1910,11 +2922,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.',
             '',