@onepointfour-packs/flaredeck-agent 0.2.38 → 0.2.39

package/dist/serve.js

@@ -1,7 +1,8 @@
+import { execFile } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 import { createRequire } from 'node:module';
 import { ensureTmuxScrollback } from './tmux.js';
-import { START_SCRIPT as START_SCRIPT_NAME, browserBrief, crossWired, environmentBrief, notStartedBrief, startEnvironment, stopEnvironment, stopLeftoverEnvironments } from './environment.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';
@@ -12,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';
@@ -23,14 +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 { configDir, loadGitHub, saveConfig } from './config.js';
 import { boardArg, onMyBoards, outstandingCards } from './boards.js';
-import { browserTools } from './browser.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.
  *
@@ -46,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(),
@@ -75,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)
@@ -169,7 +233,9 @@ 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.
@@ -197,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;
     };
@@ -235,8 +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(() => { });
@@ -386,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;
     };
@@ -469,11 +606,12 @@ 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 (cur) => {
                 parked.delete(cur.card);
@@ -695,6 +833,130 @@ 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.
      *
@@ -729,8 +991,30 @@ export async function serve(opts) {
             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();
@@ -815,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);
@@ -842,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)
@@ -997,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.
@@ -1020,8 +1394,10 @@ 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 {
             // Scoped, like every other account-wide question. This one is asked by the HARNESS rather
@@ -1039,11 +1415,25 @@ export async function serve(opts) {
                 .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()}`,
@@ -1053,6 +1443,7 @@ export async function serve(opts) {
             cardKey: next.code,
         }))
             void drain();
+        return true;
     };
     const sweepTimer = setInterval(sweepNow, SWEEP_EVERY_MS);
     sweepTimer.unref();
@@ -1138,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);
@@ -1146,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' || event.event === 'run-answered') { /* 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 {
@@ -1290,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', {
@@ -1299,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]}`);
@@ -1355,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.
@@ -1444,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;
@@ -1458,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
@@ -1585,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,
@@ -1592,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,
@@ -1601,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) => {
@@ -1629,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)
@@ -1641,20 +2160,255 @@ export async function serve(opts) {
         // card is usually about code that is already live somewhere, and an agent that can only see
         // what it started locally cannot tell its own change from how the thing already behaved.
         const declaredSites = where.kind === 'repo' ? where.sites ?? {} : {};
-        const eyes = forACard
-            ? turnEyes = browserTools({
-                repo: config.repo,
-                endpoints: () => env.endpoints,
-                sites: () => declaredSites,
-                contract: () => env.contract,
-                cwd,
-                onNote: (t) => log('tool', t),
-            })
-            : null;
+        // 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.
@@ -1684,6 +2438,7 @@ 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, for any card. They used to be mounted only when the harness had itself started
@@ -1691,7 +2446,8 @@ export async function serve(opts) {
                 // no browser AND no mention of one, so it could not know that writing the script it is
                 // perfectly able to write was the thing standing between it and seeing its own change.
                 // The endpoints are read through a getter, so something the agent starts mid-turn counts.
-                ...(eyes ? { browser: eyes } : {}),
+                browser: eyes,
+                env: envTools,
                 team: teamSet,
                 flaredeck,
                 runs: runsSet,
@@ -1712,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.endpoints, declaredSites, forACard) +
+            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 ` +
@@ -1724,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') {
@@ -1961,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
@@ -1976,6 +2799,14 @@ 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.
@@ -2038,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 [