@onepointfour-packs/flaredeck-agent 0.1.0

package/dist/serve.js

@@ -0,0 +1,1206 @@
+import { createRequire } from 'node:module';
+import { environmentBrief, startEnvironment } from './environment.js';
+import { GIT_TOOL_NAMES, githubTools } from './github.js';
+import { freshGitHubToken } from './githubauth.js';
+import { loadBaseBranch, loadMergeConfig, preflight, preflightBrief } from './preflight.js';
+import { pushStatus, StatusTracker } from './status.js';
+import { fetchTeam, myTeam, teamTools, TEAM_TOOL_NAMES } from './team.js';
+import { scheduleTools, SCHEDULE_TOOL_NAMES } from './schedules.js';
+import { preflightFlaredeck } from './flaredeck-check.js';
+import { callFlaredeckTool, flaredeckProxy } from './flaredeck-proxy.js';
+import { resumeApprovedRuns, runTools } from './runs.js';
+import { deliverDecision, flaredeckDecider } from './approval.js';
+import { CouldNotWork, engineFor } from './engine.js';
+import { jevGuard } from './jevguard.js';
+import { loadProviders } from './providers.js';
+import { ensureWorktree, releaseWorktree, worktreeBrief } from './worktree.js';
+import { askingForComponent, checkouts, resolveCheckout, voteByCode, workspaceBrief } from './workspace.js';
+import { intake, intakeText } from './intake.js';
+import { startUi } from './ui.js';
+import { checkAndStage, installedSdkVersion, pendingUpdate, updatesEnabled } from './updater.js';
+import { saveConfig } from './config.js';
+import { EventStream } from './stream.js';
+/**
+ * The always-on agent.
+ *
+ * Everything the old arrangement asked an agent to remember — arm the monitor, re-arm it when it
+ * lapses, notice you were assigned something, say you are still alive — is plain code here, so it
+ * cannot be forgotten the way an instruction in a prompt can.
+ *
+ * Work is serialised on purpose. One card at a time means no two turns racing over the same
+ * worktree, and it is the honest shape for v1: a busy agent with a queue is easy to reason about,
+ * two half-finished cards are not.
+ */
+/** Reported alongside status, so a stale agent on an old build is identifiable as such. */
+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;
+export async function serve(opts) {
+    const { config } = opts;
+    const stream = new EventStream(opts.baseUrl, opts.auth);
+    const state = {
+        agent: opts.agent ?? 'flaredeck-agent',
+        repo: config.repo,
+        working: '',
+        since: Date.now(),
+        queued: 0,
+        connected: false,
+        lines: [],
+    };
+    let ui = null;
+    const log = (kind, text) => {
+        // Keep a bounded tail: a daemon runs for days and nobody scrolls back that far.
+        state.lines.push({ kind, text });
+        if (state.lines.length > 400)
+            state.lines.splice(0, state.lines.length - 400);
+        ui?.log({ kind, text });
+    };
+    const updated = process.env['FLAREDECK_AGENT_UPDATED'];
+    if (updated)
+        log('tool', updated);
+    const waiting = () => {
+        const v = pendingUpdate();
+        if (v && state.update !== v)
+            log('warn', `SDK ${v} downloaded — restart to apply (now ${installedSdkVersion()})`);
+        state.update = v || undefined;
+    };
+    if (updatesEnabled()) {
+        waiting();
+        const looksForUpdates = () => void checkAndStage().then(waiting);
+        setTimeout(looksForUpdates, 30_000).unref();
+        setInterval(looksForUpdates, 6 * 60 * 60 * 1000).unref();
+    }
+    const say = (text) => log('say', text);
+    // The job the publishing tools act on. Set when a card starts, so those tools cannot name a
+    // branch — they read this instead.
+    let job = null;
+    // The merge tool exists only where the project declares a merge command. A repo with no such
+    // script has no merge tool, so "workers do not merge" needs no rule — there is nothing to call.
+    // Read from the checkout the job is in, not from the one this agent started in: a workspace of
+    // several repos has a merge script per repo, and running one project's promote script over
+    // another project's branch is exactly the kind of irreversible mistake nothing downstream
+    // would catch. The TOOL exists if any repo here declares one; a job in a repo that declares
+    // none has nothing to call.
+    const mergeFor = () => loadMergeConfig(job?.cwd ?? config.repo);
+    const inScope = await checkouts(config.repo, config.repos);
+    if (inScope.length > 1) {
+        log('tool', `works in ${inScope.length} repositories: ${inScope.map((c) => c.name).join(', ')}`);
+    }
+    else if (!inScope.length) {
+        log('warn', `${config.repo} holds no git checkout — this agent can read and comment, but cannot branch or publish.`);
+    }
+    const anyMerge = inScope.some((c) => loadMergeConfig(c.path)) || !!loadMergeConfig(config.repo);
+    const gitServer = githubTools(() => job, 
+    // Deferred, not the value: the decider is defined below, once the approvals list it refreshes
+    // exists. The merge tool only calls it when someone actually merges, which is long after.
+    anyMerge ? { config: mergeFor, decider: (req, opt) => decider(req, opt) } : undefined);
+    // Production runs exist only where this machine's config names a target, and the request needs
+    // the harness's own FlareDeck client to post the approval — the model's tools cannot approve
+    // themselves. The card being worked is what the approval is asked on.
+    let onCard = null;
+    /**
+     * The pane's list of production runs waiting on a person: this agent's own request and, on a
+     * lead's pane, its team's. Read from the server — the one place every request and verdict
+     * lands — and refreshed whenever the stream says something changed, never on a timer worth
+     * noticing. Rows a person answered here are marked until the next refresh drops them.
+     */
+    const reader = opts.me ?? opts.deck ?? null;
+    const answeredHere = new Map();
+    let refreshing = null;
+    const refreshApprovals = () => {
+        if (!reader)
+            return Promise.resolve();
+        if (refreshing)
+            return refreshing;
+        refreshing = reader.pendingApprovals().then((all) => {
+            const mine = all.filter((a) => a.tool_name === 'request_production_run');
+            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*/, '');
+                const script = lines.filter((l) => !l.startsWith('-- ')).join('\n').trim();
+                const answered = answeredHere.get(a.request_id);
+                const desc = a.description || '';
+                return {
+                    requestId: a.request_id,
+                    commentId: a.comment_id,
+                    agent: a.sender_name ?? '?',
+                    card: a.card.code ?? a.card.key,
+                    name: desc.split('"')[1] ?? a.request_id,
+                    target: desc.split(' on ')[1]?.split(' — ')[0] ?? '',
+                    purpose: desc.split(' — ').slice(1).join(' — ') || desc,
+                    ...(preview ? { preview: preview.slice(0, 60) } : {}),
+                    script,
+                    stage: answered ? 'answered' : a.review && a.review.state !== 'endorsed' ? 'lead' : 'ready',
+                    ...(a.review?.state === 'endorsed' ? { endorsedBy: `${a.review.decided_by_name ?? 'lead'}${a.review.note ? `: ${a.review.note}` : ''}` } : {}),
+                    ...(answered ? { verdict: answered } : {}),
+                    ...(a.expires_at ? { expiresAt: Date.parse(a.expires_at) } : {}),
+                };
+            });
+            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)}`))
+            .finally(() => { refreshing = null; });
+        return refreshing;
+    };
+    const onAsk = (e) => { void refreshApprovals(); if (e.kind === 'answered')
+        setTimeout(() => void refreshApprovals(), 1500); };
+    /**
+     * What answers a tool call the agent is not already allowed to make.
+     *
+     * The daemon used to hand these to whatever `deciderFor` built, and with no `--card` and no
+     * `--ask` that is `denyingDecider` — a decider that can only refuse. So every gated call died
+     * here: merge_and_promote's own human gate could never say yes, and the agent's only remaining
+     * move was to report itself blocked and wait for somebody to type the command into this pane.
+     * That is the opposite of unattended.
+     *
+     * The ask now goes where the person already is — posted on the card being worked, as the same
+     * Approve/Deny the production-run flow uses (web, phone, push) — and the turn waits for the
+     * verdict. Nobody has to be at this keyboard. It is routed through the lead first when this
+     * agent has one, exactly as a production run is.
+     *
+     * With no card to ask on (a pane question, the idle sweep) there is nowhere to post, so it
+     * falls back to the configured decider and the old refusal stands.
+     */
+    const decider = async (request, options) => {
+        const card = onCard?.card;
+        if (!opts.deck || !card)
+            return opts.decider(request, options);
+        return flaredeckDecider(opts.deck, card, undefined, leadId ? { review_by: leadId } : {}, () => void refreshApprovals(), () => void refreshApprovals())(request, options);
+    };
+    /**
+     * The command gate. ALWAYS on.
+     *
+     * It used to be installed only when this machine had an OpenRouter key, on the reasoning that a
+     * missing key must not quietly change what is allowed. That reasoning was backwards: what it
+     * actually meant was that a machine nobody had set up ran `rm -rf` and `DROP TABLE` with no
+     * check at all, and the machines least likely to have been set up are exactly the ones running
+     * unattended. A guard you can switch off by not creating a file is not a guard.
+     *
+     * Without a key, judgeCommand's existing unreachable path takes over: a command that looks
+     * interesting goes to a PERSON instead of to Jev. Slower and more annoying, which is the right
+     * way round — the answer to "no key" is to ask someone, not to stop asking.
+     *
+     * Its refusals and its asks both end up in decisions.jsonl beside the config.
+     */
+    const jevKey = loadProviders().openrouter?.apiKey;
+    const guard = jevGuard({
+        apiKey: jevKey ?? '',
+        decider: (req, opt) => decider(req, opt),
+        log: (t) => log('tool', t),
+        agent: opts.agent ?? 'flaredeck-agent',
+        repo: config.repo,
+        card: () => onCard?.card ?? null,
+    });
+    log('tool', jevKey
+        ? 'jev guard on — irreversible commands are refused, the rest run'
+        : 'jev guard on, with NO OpenRouter key — every risky command will interrupt a person. Set one: flaredeck-agent providers --openrouter <key>');
+    const runsSet = Object.keys(config.runs ?? {}).length
+        ? runTools(config.runs, () => onCard, opts.deck ?? null, (t) => log('tool', t), () => leadId, onAsk)
+        : 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
+        ? (requestId, verdict) => {
+            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)
+                .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(); });
+        }
+        : undefined;
+    // A slow safety net only — the stream is what keeps this current.
+    const approvalsTimer = setInterval(() => void refreshApprovals(), 5 * 60 * 1000);
+    approvalsTimer.unref();
+    void refreshApprovals();
+    // Anything a person approved while this harness was not waiting runs now, before the first
+    // event — so the approval the pane showed as "picking it up" is actually picked up.
+    if (runsSet && opts.deck) {
+        void resumeApprovedRuns(config.runs, opts.deck, config.repo, (t) => log('tool', t))
+            .then((n) => { if (n) {
+            log('event', `ran ${n} approved production run(s) owed from before this restart`);
+            void refreshApprovals();
+        } });
+    }
+    // Recurring tasks. Registering one is only a request: a person approves it before it ever runs.
+    const schedulesSet = opts.deck
+        ? { server: scheduleTools(opts.deck, () => onCard?.card ?? null), toolNames: SCHEDULE_TOOL_NAMES }
+        : undefined;
+    if (runsSet && !opts.deck)
+        log('warn', 'runs are configured but the harness has no FlareDeck client — requests will be refused');
+    /**
+     * Lead or worker. FlareDeck owns the answer — it is a property of the ACCOUNT, set once where
+     * the team is managed, not a flag on a command line that a machine could disagree with. Asked
+     * here, at startup, so the harness mounts the right tools before the first card arrives.
+     *
+     * If the lookup fails we carry on as a worker. A lead that briefly cannot see its team is a
+     * lesser problem than an agent that refuses to start work because of it.
+     */
+    let teamSet;
+    /** Set once this agent is known to be a lead — the id its reports point at. */
+    let leadOfTeam = null;
+    const teamTimers = [];
+    /** Keep only this lead's own reports, in a stable order, shaped for the pane. */
+    const showTeam = (team) => {
+        state.team = myTeam(team).mine
+            .map((a) => ({
+            name: a.name,
+            card: a.card,
+            state: a.state,
+            summary: a.summary,
+            tasks: a.tasks ?? { done: 0, total: 0 },
+            queued: a.queued ?? 0,
+            next: a.next ?? '',
+            quietFor: a.quietFor,
+            stale: a.stale,
+            errorsInARow: a.errorsInARow,
+        }))
+            .sort((x, y) => x.name.localeCompare(y.name));
+    };
+    /** Who this agent reports to, when it is a worker on a team: production runs go there first. */
+    let leadId = null;
+    try {
+        const team = await fetchTeam(opts.baseUrl, await opts.auth());
+        // Only a lead that is actually running can review: one that has never checked in, or has
+        // gone quiet, would hold every request until it expired. Then the request goes straight to
+        // the people who can approve it, as it would with no lead at all.
+        const lead = team.you.reportsTo ? team.agents.find((a) => a.agentId === team.you.reportsTo) : undefined;
+        const leadAlive = !!lead && lead.quietFor !== null && !lead.stale;
+        leadId = leadAlive ? team.you.reportsTo : null;
+        if (team.you.reportsTo && !leadAlive)
+            log('warn', `your lead (${lead?.name ?? team.you.reportsTo}) is not running — production runs will go straight to the approvers`);
+        if (team.you.role === 'lead') {
+            teamSet = {
+                // After a review the list changes — an endorsed request is now answerable, from THIS
+                // keyboard as likely as any: the lead's pane is where a team is watched from.
+                server: teamTools(opts.baseUrl, opts.auth, opts.deck ?? null, () => void refreshApprovals()),
+                toolNames: TEAM_TOOL_NAMES,
+            };
+            const mine = team.agents.filter((a) => a.reportsTo === team.you.agentId).length;
+            log('event', `You are the lead here — ${mine} agent(s) report to you.`);
+            leadOfTeam = team.you.agentId;
+            showTeam(team);
+        }
+    }
+    catch {
+        log('warn', 'Could not read your role from FlareDeck — running as a worker.');
+    }
+    /**
+     * A lead's pane shows its team continuously, so one terminal answers "what is everyone doing"
+     * without opening four more. Their own reported state, not this machine's guess: each agent
+     * pushes its status to FlareDeck, and this reads the same record `team·list_agents` reads.
+     *
+     * 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.
+     */
+    if (leadOfTeam) {
+        const teamTimer = setInterval(() => {
+            void (async () => {
+                try {
+                    showTeam(await fetchTeam(opts.baseUrl, await opts.auth()));
+                }
+                catch {
+                    // A team the lead briefly cannot see is not worth a line in the log every minute; the
+                    // rows simply age in place and their dots go yellow, which is the honest picture.
+                }
+            })();
+        }, 60_000);
+        teamTimer.unref();
+        teamTimers.push(teamTimer);
+    }
+    const status = new StatusTracker(config.repo);
+    // Pushed when something changes, and on a slow timer so silence itself is informative: a record
+    // that stops updating is how FlareDeck will know a machine has gone, which no signal FROM the
+    // machine could ever tell it.
+    const report = () => pushStatus(opts.baseUrl, opts.auth, status.snapshot(), VERSION);
+    const reporter = setInterval(() => void report(), 5 * 60 * 1000);
+    reporter.unref();
+    // Say hello at once. Waiting for the first tick would leave a just-started agent invisible for
+    // five minutes — and "no record" is exactly how a dead machine looks, so a live one must not.
+    void report();
+    /** The live turn, when there is one — what typing gets delivered to. */
+    /**
+     * The engine that runs a turn, behind one interface — so a second engine is a second
+     * implementation rather than a second harness. Nothing else in this file needs to know
+     * which model answered.
+     */
+    const engine = await engineFor(config);
+    state.engine = engine.name;
+    if (engine.name !== 'claude')
+        log('event', `${engine.name} is answering on this agent`);
+    let liveRun = 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.
+     */
+    const ask = (text) => {
+        const event = { id: `ask-${Date.now()}`, event: 'ask', line: text, message: text };
+        if (enqueue(event)) {
+            prepareAhead(event);
+            void drain();
+        }
+    };
+    const steer = (text) => {
+        log('you', text);
+        if (liveRun) {
+            // Stamped human: the SDK treats an unattributed message as untrusted, and rightly — a line
+            // someone typed here deserves more weight than a comment left on a card by anyone.
+            //
+            // 'next', never 'now'. A 'now' message interrupts whatever tools are in flight, and the
+            // CLI closes that turn with a result; streamInput() then treats that result as the end of
+            // the conversation and closes the CLI's stdin — the channel every permission verdict and
+            // 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'));
+        }
+        else {
+            ask(text);
+        }
+    };
+    /** One session per card, so an agent picking a card back up remembers starting it. */
+    const sessions = new Map();
+    /**
+     * Sessions kept open between events on the same card.
+     *
+     * A session used to close after every event: turn, handover to the card, gone. Deliberate,
+     * and right for a card leaving the agent's hands — but a lead's follow-up comment three
+     * minutes later then cost a whole re-orientation (~90k tokens of guide, card and repo) to
+     * answer a question the agent had just finished thinking about. So a session now lives for a
+     * STINT: it stays until the card has been quiet for a while, or the context has grown large,
+     * or the daemon stops. Each of those still ends with the handover. What changed is when.
+     */
+    const live = new Map();
+    const IDLE_CLOSE_MS = 15 * 60 * 1000;
+    const CONTEXT_CLOSE_TOKENS = 120_000;
+    /**
+     * Inside a turn the close check cannot run, and one long turn can climb from a hundred
+     * thousand tokens to the window's edge on its own — a reproduction did, 117k to 199k — at
+     * 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;
+    const keepAlive = (key, cwd, tokens) => {
+        const prev = live.get(key);
+        if (prev?.timer)
+            clearTimeout(prev.timer);
+        const timer = setTimeout(() => {
+            log('event', `${key}: quiet for ${IDLE_CLOSE_MS / 60000} min — handing over and closing the session`);
+            void closeSession(key);
+        }, IDLE_CLOSE_MS);
+        timer.unref();
+        live.set(key, { cwd, tokens, timer });
+    };
+    const closeSession = async (key) => {
+        const s = live.get(key);
+        if (!s)
+            return;
+        if (s.timer)
+            clearTimeout(s.timer);
+        live.delete(key);
+        await wrapUp(key, s.cwd);
+    };
+    const queue = [];
+    /** Ids queued or in flight, so a redelivery and a local retry cannot both run the same card. */
+    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 || '');
+    const enqueue = (event, front = false) => {
+        if (pending.has(event.id))
+            return false;
+        pending.add(event.id);
+        if (front)
+            queue.unshift(event);
+        else
+            queue.push(event);
+        syncQueue();
+        return true;
+    };
+    /**
+     * Intake starts when the event ARRIVES, not when its turn comes. It is HTTP calls and one small
+     * model call with nothing in common with the running turn, so the next card is already read,
+     * briefed, sized and mapped by the time the current one ends — the queue holds work ready to
+     * start, not work waiting to be read. A result older than this is redone: the thread moved on.
+     */
+    const PREPARED_FRESH_MS = 15 * 60 * 1000;
+    const preparedAhead = new Map();
+    // Reading a card ahead of the turn is a model call of its own, so it is skipped for exactly what
+    // the turn skips — otherwise the saving is only half taken: no turn runs, but the card was
+    // still read and paid for.
+    const wantsIntake = (event) => !!event.cardKey
+        && event.event !== 'review'
+        && event.event !== 'ask'
+        && !(event.event === 'commented' && event.cardDone && !event.mentioned)
+        && !sessions.has(event.cardKey);
+    const prepareAhead = (event) => {
+        if (!wantsIntake(event) || preparedAhead.has(event.id))
+            return;
+        const label = event.cardCode || event.cardKey || '';
+        preparedAhead.set(event.id, {
+            at: Date.now(),
+            // The repo this card belongs to, so the code search behind the brief searches the right
+            // project — at a workspace root there is no git to grep, and it would silently find nothing.
+            promise: (async () => {
+                const w = await resolveCheckout(config.repo, event, config.repos);
+                return intake(opts.deck, event.cardCode || event.cardKey, (t) => log('tool', `${label}: ${t}`), false, w.kind === 'repo' ? w.checkout.path : config.repo);
+            })().catch(() => null),
+        });
+    };
+    let working = false;
+    let current = '';
+    let lastBeat = 0;
+    const beat = () => {
+        if (Date.now() - lastBeat < HEARTBEAT_MS)
+            return;
+        lastBeat = Date.now();
+        // Today this is a log line. It is the hook the card lease will hang from: the point is that
+        // the harness emits it on a timer, so a wedged model cannot stop it.
+        // The header shows this continuously now, so the heartbeat only needs to mark the passage of
+        // time in the log — and only when something is actually running.
+        if (working)
+            log('tool', `still on ${current} · ${queue.length} queued`);
+    };
+    // unref: a timer must not be the reason the process stays alive once everything else is done.
+    const heartbeat = setInterval(beat, 30_000);
+    heartbeat.unref();
+    /**
+     * The stream only says what CHANGED. A card assigned a fortnight ago fired its event once, it
+     * was acknowledged, and nothing re-sends it — so an agent holding real work sat reporting
+     * "waiting for work", correctly, for as long as nobody touched its cards. That is how R2-D2 held
+     * four cards, one of them fifteen days old, while looking perfectly healthy.
+     *
+     * So: on a slow timer, ask. One fixed event id, so a sweep can never be queued twice, and only
+     * when genuinely idle — a sweep while a card is in flight would have the model start a second
+     * piece of work on top of the one it is already doing.
+     *
+     * What is outstanding is NOT decided here. The turn calls `get-outstanding`, which already owns
+     * the lane rules, the priority logic and the comment gating; duplicating any of that in the
+     * harness would give two answers that drift. The harness owns only WHEN to look.
+     */
+    // Guarded, not just clamped: Math.max(5, NaN) is NaN, and setInterval(NaN) fires every tick —
+    // a typo in the env var would have turned the slow safety net into a busy loop.
+    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';
+    const sweepNow = () => {
+        if (!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)
+            return;
+        if (enqueue({ id: 'sweep', event: 'sweep', line: 'checking what is still assigned to you' }))
+            void drain();
+    };
+    const sweepTimer = setInterval(sweepNow, SWEEP_EVERY_MS);
+    sweepTimer.unref();
+    // Not at once: let the stream connect and deliver anything it is holding first, so a sweep
+    // never races a redelivery of the very cards it would pick up.
+    if (sweepsEnabled)
+        setTimeout(sweepNow, 30_000).unref();
+    // Ctrl-C must actually stop it. The first press closes the stream and lets a turn in progress
+    // finish; the second gives up on that and exits. A daemon that has to be hunted down with
+    // pkill is worse than one that occasionally abandons a turn — the events are unacknowledged,
+    // so whatever it was doing comes back.
+    let stopping = false;
+    const shutdown = () => {
+        if (stopping) {
+            say('stopping now');
+            process.exit(130);
+        }
+        stopping = true;
+        say(working ? 'stopping — finishing the turn in progress (Ctrl-C again to stop now)' : 'stopping');
+        // Close the stream and let the loop unwind normally, so the cleanup in `finally` runs — it
+        // is what tells FlareDeck this agent stopped. Exiting here instead left the last record
+        // saying "idle", which reads as a live agent doing nothing rather than one that is gone.
+        stream.close();
+        clearInterval(heartbeat);
+        clearInterval(sweepTimer);
+        teamTimers.forEach(clearInterval);
+        // Belt and braces: if unwinding wedges, do not hang forever pretending to shut down. Longer
+        // when cards are still open, because their handovers run first and each is a short turn.
+        setTimeout(() => process.exit(0), live.size ? 120_000 : 8000).unref();
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    async function drain() {
+        if (working)
+            return;
+        working = true;
+        try {
+            while (queue.length) {
+                const event = queue.shift();
+                // Only what needs this agent. A card it once touched keeps sending it every move and
+                // comment made by whoever has it now, and each one cost a full turn — guide, card,
+                // orientation — to conclude "not mine". Acknowledge those without waking the model.
+                if (!needsMe(event)) {
+                    log('tool', `ignored ${event.event}: ${event.cardCode || 'card'} is not assigned to you (${event.actor || 'someone'})`);
+                    pending.delete(event.id);
+                    await stream.ack([event.id]);
+                    continue;
+                }
+                current = event.event === 'ask' ? 'your question' : event.event === 'sweep' ? 'your outstanding work' : event.event === 'scheduled' ? event.scheduleName || 'a scheduled task' : event.cardCode || event.cardKey || 'a message';
+                state.working = current;
+                state.since = Date.now();
+                state.tasks = { done: 0, total: 0 };
+                // What it starts the moment this one is done — so a long turn does not read as a stall.
+                state.nextCard = queue[0]?.cardCode || queue[0]?.cardKey || '';
+                syncQueue();
+                // Everything that ARRIVES is announced; a question typed here already appeared as the
+                // `»` line the moment it was typed, and announcing it again just repeated the words back
+                // with a different arrow.
+                if (event.event !== 'ask')
+                    log('event', event.line);
+                // A sweep or a typed question is work, but it is not a card — see startCard.
+                status.startCard(current, !!event.cardKey);
+                void report();
+                let didWork = true;
+                try {
+                    await handle(event);
+                }
+                catch (e) {
+                    // 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)}`);
+                }
+                // 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 */ }
+                else if (didWork)
+                    await stream.ack([event.id]);
+                else {
+                    // Not acknowledged, so the server will redeliver on reconnect — but that can be a long
+                    // way off. Try again here in a minute as well; the id set stops the two colliding.
+                    log('warn', 'left queued — retrying in 60s, and on reconnect');
+                    setTimeout(() => { if (enqueue(event, true))
+                        void drain(); }, 60_000).unref();
+                }
+                current = '';
+                state.working = '';
+                delete state.branch;
+                delete state.base;
+                delete state.tasks;
+                state.nextCard = queue[0]?.cardCode || queue[0]?.cardKey || '';
+            }
+        }
+        finally {
+            working = false;
+        }
+    }
+    /**
+     * Does this event need THIS agent? A direct message or a mention always does. Being assigned
+     * does. A move, comment or creation does only while the card is assigned to this agent —
+     * `forYou` is the server's word on that. Anything else is news about someone else's work.
+     */
+    function needsMe(event) {
+        if (event.event === 'ask' || event.event === 'sweep' || event.event === 'message' || event.event === 'mentioned' || event.event === 'scheduled' || event.mentioned === true)
+            return true;
+        // The server now delivers a card event only to the card's holder or to whoever a comment
+        // names, so being sent it at all is the strong signal. Ignore only when the server said,
+        // explicitly and with the holder's key in hand, that the holder is someone else — a missing
+        // key means it did not know, and "did not know" must not read as "not you". That reading
+        // cost a lead a card that had just been created for it.
+        if (!event.assigneeKey)
+            return true;
+        return event.forYou !== false;
+    }
+    async function startOnBoard(card) {
+        const deck = opts.deck;
+        if (!deck)
+            return;
+        try {
+            const c = await deck.card(card);
+            const type = String(c?.lane?.type ?? '').toLowerCase();
+            if (!['backlog', 'todo', 'bug'].includes(type))
+                return;
+            const board = (await deck.boards()).find((b) => b.id === c.board_id);
+            const lanes = (board?.lanes ?? []).map((l, i) => ({ l, i }));
+            lanes.sort((a, b) => (a.l.order ?? a.i) - (b.l.order ?? b.i));
+            const target = lanes.find(({ l }) => String(l.type ?? '').toLowerCase() === 'inprogress')?.l;
+            if (!target)
+                return;
+            await deck.move(card, target.key, true);
+            log('event', `${card}: moved to ${target.name} (In Progress)`);
+        }
+        catch (e) {
+            log('warn', `${card}: could not move to In Progress (${e instanceof Error ? e.message : String(e)})`);
+        }
+    }
+    /**
+     * Flag a card for a person, and be sure it actually happened.
+     *
+     * Two things went wrong here and they hid each other. The call sent a bare Firestore key with no
+     * board, which that tool cannot resolve — it wants board + key, or a card CODE — so every
+     * needs-human the harness raised was refused. And the refusal came back as an ordinary result
+     * with a ❌ in the text rather than as an error, so nothing threw and the pane logged "flagged
+     * 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 flagForHuman = async (event, reason, kind) => {
+        const label = event.cardCode || event.cardKey || 'card';
+        try {
+            const out = await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'set-needs-human', {
+                // The code when there is one — it resolves on its own. The board always goes with the key.
+                card_id: event.cardCode || event.cardKey,
+                ...(event.boardKey ? { board_id: event.boardKey } : {}),
+                reason,
+                ...(kind ? { kind } : {}),
+            });
+            if (out.trimStart().startsWith('❌') || out.trimStart().startsWith('🚫')) {
+                log('warn', `${label}: FlareDeck did not flag this card — ${out.split('\n')[0]}`);
+                return;
+            }
+            // Say who was told, which the tool reports back, so the pane shows whether anyone heard it.
+            const told = out.split('\n').find((l) => l.startsWith('**Told**'));
+            log('warn', `${label}: flagged needs-human — ${reason.split('.')[0]}${told ? ` · ${told.replace(/\*\*/g, '')}` : ''}`);
+        }
+        catch (e) {
+            log('warn', `${label}: could not flag the card (${e instanceof Error ? e.message : String(e)}) — ${reason}`);
+        }
+    };
+    async function handle(event) {
+        // A scheduled run that sat in the queue past its window (this machine was off, the pane was
+        // busy) is dropped, not run late: a "7am summary" at noon is worse than none. Acknowledged by
+        // the caller, because skipping it is the finished outcome.
+        if (event.event === 'scheduled' && event.validUntil && Date.now() > Date.parse(event.validUntil)) {
+            log('warn', `${event.scheduleName || 'scheduled task'}: skipped, it was due ${event.validUntil} and that has passed`);
+            return;
+        }
+        // A comment on a finished card is news, not work. The server stopped sending these to a
+        // card's holder — this is the same rule on this side, for an older server and for any other
+        // producer that has not learned it. Being NAMED still wakes the agent: pulling it back to a
+        // closed card is a deliberate act. Acknowledged by the caller, because ignoring it IS the
+        // finished outcome.
+        if (event.event === 'commented' && event.cardDone && !event.mentioned) {
+            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 turnTokens = 0;
+        let nudged = false;
+        // A checkout of its own per card, so it cannot edit a working tree someone else is in.
+        // Falls back to the repo itself when there is no git or the worktree cannot be made —
+        // better to work than to refuse, but the agent is told either way.
+        // Cut from where this project says work starts — the same branch a pull request targets.
+        // The repo's own answer wins — it is reviewed and shared — then the one chosen at login.
+        // Where this card's work starts. The card's own world wins: FlareDeck resolved a branch per
+        // repository from the board's config and the card's Environment, and the entry for THIS
+        // remote is the answer — a production fix is cut from the fix branch, everything else from
+        // the feature branch. Only when the board says nothing does the branch chosen at login apply.
+        // WHICH repo first, then which branch of it. The folder this agent was started in says what
+        // it may work in — one repo, or every repo in that folder — and the card says which of them
+        // this work belongs to. See workspace.ts: the folder is the only declaration, so there is no
+        // config list to go stale.
+        const where = await resolveCheckout(config.repo, event, config.repos);
+        let chosen = where.kind === 'repo' ? where.checkout : null;
+        let fromCard = where.kind === 'repo' && where.branch ? { branch: where.branch, role: where.role } : null;
+        if (where.kind === 'ambiguous') {
+            // The board left the question open. The code can often answer it for nothing, and only a
+            // clear answer counts — see voteByCode.
+            //
+            // Voted on the CARD, not on the event. The event carries a title and a line of English
+            // ("now assigned to you as Developer"); the description is where someone writes the file,
+            // the service or the error that says which repository this is. Voting on the event alone
+            // found nothing on a card whose description named exactly one file in exactly one repo.
+            let voteText = [event.cardName, event.line, event.message].filter(Boolean).join('\n');
+            if (event.cardKey && opts.deck) {
+                try {
+                    const full = await opts.deck.card(event.cardCode || event.cardKey);
+                    const body = [full?.name, full?.description, ...(full?.comments ?? []).slice(-3).map((c) => c?.message)]
+                        .filter(Boolean).join('\n');
+                    if (body.trim())
+                        voteText = body;
+                }
+                catch { /* the event's own words are still something to go on */ }
+            }
+            const voted = await voteByCode(where.candidates, voteText);
+            if (voted) {
+                chosen = voted.checkout;
+                fromCard = voted.branch ? { branch: voted.branch, role: voted.role } : null;
+                log('event', `${event.cardCode || key}: no component set — the code points at ${voted.checkout.name}`);
+            }
+        }
+        // A card whose repo cannot be established is flagged, not guessed at. Falling back to this
+        // agent's own first repo is how work lands in the wrong repository, and nothing downstream
+        // notices: the branch is made, the change is committed, the PR is opened on the wrong project.
+        //
+        // Only for a turn that will CHANGE something. Being asked a question on a card, reviewing
+        // one, or being mentioned on someone else's — none of those need a checkout, and flagging
+        // them for want of one would make the agent unable to answer about a repo it can plainly
+        // read. Those turns simply run without a worktree, and the brief says so.
+        const willChange = !!event.cardKey && event.event !== 'review' && event.event !== 'ask' && event.forYou !== false;
+        if (!chosen && willChange && (where.kind === 'ambiguous' || where.kind === 'unknown')) {
+            const reason = askingForComponent(where);
+            await flagForHuman(event, reason);
+            return;
+        }
+        // A FIX with no branch of its own is the one case worth stopping for.
+        //
+        // The board knows this card's repository — it said so — but names no branch for the
+        // environment the card is in. For ordinary work that is survivable: the repo's own default is
+        // a reasonable base and the agent is told it was a fallback. For a fix to what is LIVE it is
+        // not, because the fallback is the feature branch: the fix would be cut from unreleased work,
+        // carry it along, and the pull request would look like a much bigger change than the fix.
+        // Nobody reviewing it would know which part was the fix.
+        if (chosen && where.kind === 'repo' && where.role === 'fix' && !where.branch && willChange && event.cardKey) {
+            const reason = `This card is a fix to what is live in ${chosen.name}, but the board does not say which branch ` +
+                `${event.environment || 'that environment'} work is cut from for that repository. Cutting it from the ` +
+                `feature branch would base the fix on unreleased work. Set the branch for ${event.environment || 'this environment'} ` +
+                `on the board's repository configuration and this will be picked up.`;
+            await flagForHuman(event, reason, 'technical');
+            return;
+        }
+        const repo = chosen?.path ?? config.repo;
+        const startFrom = fromCard?.branch ?? loadBaseBranch(repo) ?? config.baseBranch ?? undefined;
+        if (chosen && where.kind === 'repo' && !where.branch && event.environment) {
+            log('warn', `the board names no branch for ${event.environment} in ${chosen.name} — using ${startFrom ?? "the repo's default"}`);
+        }
+        if (chosen && where.kind !== 'repo')
+            log('event', `working in ${chosen.name}`);
+        if (fromCard)
+            log('event', `base ${fromCard.branch} — ${fromCard.role} (${event.environment || 'no environment'}), from the board`);
+        const tree = event.cardKey && (chosen || where.kind === 'none')
+            ? await ensureWorktree(repo, key, (t) => log('tool', t), startFrom)
+            : null;
+        const cwd = tree?.path ?? repo;
+        // 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
+        // did exactly that and ended up reading production out of a worktree belonging to someone
+        // else; it only read, which was luck. A card that cannot get its own checkout waits for a
+        // person instead.
+        if (!tree && willChange && event.cardKey) {
+            await flagForHuman(event, `I could not make a checkout of my own for this card in ${chosen?.name ?? repo}, so there is nowhere ` +
+                `safe to do the work. Everything I changed would land in a checkout somebody else may be using. ` +
+                `Something is wrong with the repository or the branch this card asks for — a person needs to look.`, 'technical');
+            return;
+        }
+        if (tree) {
+            state.branch = tree.branch;
+            state.base = startFrom;
+        }
+        // In a workspace of several repos the header's repo name is the one fact a person cannot get
+        // from anywhere else: which project this card is actually being changed in.
+        if (chosen)
+            state.repo = chosen.path;
+        // FlareDeck must be there before the model is. Without it the turn cannot read the card,
+        // comment, or ask for help — and it would still run, answer fluently that it could not do
+        // the work, and be acknowledged. The card would be gone. So: no FlareDeck, no turn.
+        const check = await preflightFlaredeck(config.mcpUrl, await opts.auth());
+        if (!check.ok) {
+            log('warn', check.reason);
+            throw new CouldNotWork(`${check.reason} — event left queued`);
+        }
+        log('tool', `FlareDeck reachable · ${check.discovered.tools.length} tools`);
+        // Served from in here for this turn: a fresh token per call, so a card that outlives the
+        // token's hour keeps its tools, and nothing on this machine can shadow the server by name.
+        const flaredeck = flaredeckProxy(config.mcpServerName, config.mcpUrl, opts.auth, check.discovered, (w) => log('warn', w));
+        const held = live.get(key);
+        if (held?.timer)
+            clearTimeout(held.timer);
+        const resume = sessions.get(key);
+        if (resume)
+            log('tool', `resuming this card's session${held ? ` (${Math.round(held.tokens / 1000)}k tokens)` : ''}`);
+        // Intake: digest the card and have a small model write the brief and size the work, so the
+        // real turn starts oriented and on a model that fits. Only when a session STARTS — a resumed
+        // session already knows the card, and switching its model mid-conversation helps nobody.
+        const ahead = preparedAhead.get(event.id);
+        preparedAhead.delete(event.id);
+        const prepared = !resume && event.cardKey && event.event !== 'review' && event.event !== 'ask'
+            ? ahead && Date.now() - ahead.at < PREPARED_FRESH_MS
+                ? await ahead.promise
+                : await intake(opts.deck, event.cardCode || event.cardKey, (t) => log('tool', t), false, repo)
+            : null;
+        if (prepared)
+            log('tool', `${prepared.summary}${ahead && Date.now() - ahead.at < PREPARED_FRESH_MS ? ' · prepared while the last card ran' : ''}`);
+        // Evidence the harness could not read means a turn that would guess. Flag the card for a
+        // person with exactly what is missing and stop; the event is done with, not retried, and a
+        // person clearing needs-human is what brings the card back.
+        if (prepared?.blocked) {
+            await flagForHuman(event, `Cannot start: ${prepared.blocked}`);
+            return;
+        }
+        // Work starting is work in progress: a card still waiting in backlog, to-do or bug moves to the
+        // board's first In Progress lane. Only on a fresh start, and only out of the waiting lanes —
+        // a card in feedback, sign-off, blocked or done is where a person put it.
+        if (!resume && event.cardKey && event.event !== 'review' && event.event !== 'ask') {
+            await startOnBoard(event.cardCode || event.cardKey);
+        }
+        onCard = event.cardKey ? { card: event.cardKey, cwd } : null;
+        job = tree
+            ? {
+                cwd,
+                branch: tree.branch,
+                // Declared beats guessed: a project that merges to `dev` says so, and only falls
+                // back to the repo's default branch when it has not.
+                base: startFrom ?? (await baseBranch(cwd)),
+                card: event.cardCode || key,
+                token: async () => {
+                    if (!config.github)
+                        throw new Error('This machine has no GitHub login — run flaredeck-agent login.');
+                    return freshGitHubToken(config.github, (next) => {
+                        config.github = next;
+                        saveConfig(config);
+                    });
+                },
+            }
+            : null;
+        const engineContext = {
+            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.
+            ...(tree ? { sandbox: tree.path } : {}),
+            decider,
+            token: await opts.auth(),
+            ...(resume ? { resume } : {}),
+            ...(prepared?.model ? { model: prepared.model } : {}),
+            ...(prepared?.size ? { size: prepared.size } : {}),
+            tools: {
+                ...(job ? { git: { server: gitServer, toolNames: GIT_TOOL_NAMES } } : {}),
+                team: teamSet,
+                flaredeck,
+                runs: runsSet,
+                schedules: schedulesSet,
+            },
+            guard,
+        };
+        // Declared checks are OPTIONAL: no .flaredeck/agent.yaml means none, and that is the normal
+        // case. Judging what a task needs is the agent's job — it can read the card and the repo, and
+        // most cards need nothing. This is only for the few things a project wants hard-gated
+        // regardless of what any agent thinks.
+        const checks = await preflight(cwd, (t) => log('tool', t));
+        // Bring the project up the way it says to, and tell the agent where things ended up — a
+        // script that takes a free port for parallel worktrees leaves nothing to guess from.
+        const env = await startEnvironment(cwd, (t) => log('tool', t));
+        const brief = prompt(event) + intakeText(prepared) +
+            workspaceBrief(config.repo, await checkouts(config.repo, config.repos), chosen) +
+            worktreeBrief(tree) + preflightBrief(checks) +
+            // Only tell an agent about the environment when the card actually needs one running.
+            environmentBrief(env, cwd, (prepared?.jev?.needs_running ?? 0) >= 0.5);
+        const run = engine.run(brief, engineContext);
+        liveRun = run;
+        for await (const out of run.events) {
+            status.observe(out);
+            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 === '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;
+                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` : ''}`);
+            }
+        }
+        liveRun = null;
+        // 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') {
+            if (turnTokens >= CONTEXT_CLOSE_TOKENS) {
+                sessions.delete(key);
+                log('tool', 'question session grew large — the next question starts fresh');
+            }
+            return;
+        }
+        // Each scheduled run starts from nothing and leaves nothing: no card to write a handover on.
+        if (event.event === 'scheduled') {
+            sessions.delete(key);
+            return;
+        }
+        // A message is not a card: nothing to hand over, nothing to keep. A card's session stays open
+        // for the next event unless it has grown past the point where a fresh start beats carrying on.
+        if (!event.cardKey) {
+            await wrapUp(key, cwd);
+            return;
+        }
+        // A finished card does not need its checkout kept. Worktrees accumulate — one repository here
+        // had fourteen, nearly all of them done — and each is a full copy on disk. releaseWorktree
+        // refuses unless there is genuinely nothing to lose: no uncommitted change, no untracked file,
+        // no commit that is not already on the remote. When it refuses it says why, because an orphan
+        // somebody finds next month is worse than one they were told about today.
+        if (tree && chosen) {
+            try {
+                // The LANE decides, not the card's `done` flag. That flag is older than the lane types and
+                // drifts from them — a card can sit in a lane the board calls done with the flag still
+                // false, which is exactly what this card did. The board's own configuration is the only
+                // thing that knows what a lane means, here as everywhere else.
+                const c = await opts.deck?.card(event.cardCode || event.cardKey);
+                const finished = String(c?.lane?.type ?? '').toLowerCase() === 'done' || c?.done === true;
+                if (finished) {
+                    const { removed, why } = await releaseWorktree(chosen.path, key, (t) => log('tool', t));
+                    if (!removed && why !== 'there was no worktree') {
+                        log('warn', `${event.cardCode || key}: kept its checkout — ${why}`);
+                    }
+                }
+            }
+            catch { /* housekeeping must never fail a card that is otherwise finished */ }
+        }
+        if (turnTokens >= CONTEXT_CLOSE_TOKENS) {
+            log('event', `${key}: context at ${Math.round(turnTokens / 1000)}k tokens — handing over and starting fresh next time`);
+            // closeSession runs the handover itself; calling wrapUp again here found no session.
+            if (live.has(key))
+                await closeSession(key);
+            else
+                await wrapUp(key, cwd);
+            return;
+        }
+        keepAlive(key, cwd, turnTokens);
+    }
+    /**
+     * Close the session deliberately rather than letting it grow until something compacts it.
+     *
+     * Auto-compaction keeps a session alive by quietly throwing detail away — nobody chooses what
+     * goes, and nobody is told. A card is a natural boundary, so the session ends with it: the
+     * agent writes down what the next session would need, and then the conversation is dropped
+     * rather than trimmed.
+     *
+     * What it writes goes on the CARD, not into the harness. FlareDeck is where a person looks, and
+     * a note the next agent reads on the card is one a human can read too, correct, or delete.
+     */
+    /** The handover writes to the card, so it needs FlareDeck as much as the turn did. */
+    async function proxyForWrapUp() {
+        const check = await preflightFlaredeck(config.mcpUrl, await opts.auth());
+        if (!check.ok) {
+            log('warn', `${check.reason} — the handover will have no FlareDeck tools`);
+            return undefined;
+        }
+        return flaredeckProxy(config.mcpServerName, config.mcpUrl, opts.auth, check.discovered);
+    }
+    async function wrapUp(key, cwd) {
+        // Resume the session the work actually happened in — NOT the options the turn started with.
+        // On a new card those carry no resume id, so reusing them would open a third session and ask
+        // an agent with no memory of the work to summarise it. It would answer, too.
+        const resume = sessions.get(key);
+        if (!resume) {
+            log('warn', 'no session to write a handover from');
+            return;
+        }
+        // Same working directory the card was worked in, so anything it looks at while writing the
+        // handover is what it actually changed.
+        try {
+            const wrapUp = engine.run([
+                'That is this card done for now. Before the session closes, leave the card in a state',
+                'someone else can pick up — a person, or you with no memory of this.',
+                '',
+                'Use set-card-notes ONCE, now, to record — briefly, replacing whatever is there, and only',
+                'if it is actually worth knowing:',
+                '  · where the work got to, and anything half-finished',
+                '  · what you tried that did NOT work, so nobody repeats it',
+                '  · anything about this environment that cost you time',
+                '',
+                'Keep it short. If there is genuinely nothing worth passing on, say so and write nothing —',
+                'an empty note is better than a paragraph restating the card.',
+            ].join('\n'), {
+                config: { ...config, repo: cwd },
+                decider,
+                token: await opts.auth(),
+                ...(resume ? { resume } : {}),
+                tools: { team: teamSet, flaredeck: await proxyForWrapUp() },
+            });
+            liveRun = wrapUp;
+            for await (const out of wrapUp.events) {
+                if (out.kind === 'text')
+                    log('say', out.text);
+                else if (out.kind === 'tool')
+                    log('tool', out.name);
+            }
+        }
+        catch (e) {
+            log('warn', `handover note failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        finally {
+            liveRun = null;
+            // The session ends here. The next event on this card starts fresh and reads the note.
+            sessions.delete(key);
+            log('tool', 'session closed');
+        }
+    }
+    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);
+        })) {
+            // 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
+            // behind it, so queueing the answer would wait for the answer. The wait resolves at once,
+            // the event is acknowledged, and the pane is told what happened.
+            if (event.event === 'decided') {
+                const taken = deliverDecision(event.message || '');
+                log(taken ? 'event' : 'tool', `${event.line}${taken ? '' : ' (not waiting on it here)'}`);
+                await stream.ack([event.id]);
+                void refreshApprovals();
+                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)) {
+                prepareAhead(event);
+                void drain();
+            }
+            beat();
+        }
+    }
+    finally {
+        clearInterval(heartbeat);
+        clearInterval(reporter);
+        // Open sessions get their handover before the record says stopped. Sequential and capped:
+        // this is a stop, not a shift.
+        if (live.size) {
+            say(`handing over ${live.size} open card(s) before stopping`);
+            for (const key of [...live.keys()]) {
+                await Promise.race([closeSession(key), new Promise((r) => setTimeout(r, 45_000))]);
+            }
+        }
+        status.stop();
+        // Awaited, not fired and forgotten: the process is about to exit, and a 'stopped' record
+        // that never arrives leaves the agent looking alive to everyone reading FlareDeck.
+        await report();
+        ui?.stop();
+    }
+}
+/**
+ * What the agent is actually asked.
+ *
+ * The event's own one-line rendering is the instruction — it already says what happened and to
+ * whom — with only enough added to make clear that acting is expected and that stopping quietly
+ * is not an option.
+ */
+/** What a pull request should target — the repo's own default, not a guess. */
+async function baseBranch(cwd) {
+    const { spawn } = await import('node:child_process');
+    return new Promise((resolve) => {
+        const c = spawn('git', ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], { cwd });
+        let out = '';
+        c.stdout.on('data', (d) => (out += String(d)));
+        c.on('close', (code) => resolve(code === 0 && out.trim() ? out.trim().replace(/^origin\//, '') : 'main'));
+        c.on('error', () => resolve('main'));
+    });
+}
+function prompt(event) {
+    if (event.event === 'sweep') {
+        return [
+            'Nothing has arrived for a while, so this is a check of what you already hold.',
+            '',
+            'Call get-outstanding. It lists the cards assigned to you that are not done, and the comments',
+            'addressed to you that nobody has actioned.',
+            '',
+            'Then, in order of priority, PICK UP THE FIRST ONE AND WORK IT — read the card including its',
+            'agent notes, do the work, comment on the card as you go. If what you hold is for the agents',
+            'who report to you rather than for you, assign it to the right one instead; that dispatch is',
+            'the work. If a card cannot move without a decision or an approval, call set-needs-human and',
+            'say what you need, then go to the next one.',
+            '',
+            'If get-outstanding returns nothing, say so in one line and stop. That is a perfectly good',
+            'outcome and costs nothing — do NOT go looking for work elsewhere, do not scan logs, and do',
+            'not invent a task to justify the turn.',
+        ].join('\n');
+    }
+    if (event.event === 'ask') {
+        return [
+            'The person watching this pane typed a question for you:',
+            '',
+            event.line,
+            '',
+            'Answer it here, in the pane, briefly and concretely — they are reading this terminal, not a',
+            'card. Use your FlareDeck tools to look things up: list-boards and get-board-info for the',
+            'board and its columns, get-cards-by-column for what sits in a column, get-card-details and',
+            'get-outstanding for who holds a card and whether anyone is on it, read-messages for a',
+            'thread. Look, then say what you found. Do NOT change anything — no comments, no moves, no',
+            'claims, no assignments, no needs-human — unless the question explicitly asks you to do it.',
+        ].join('\n');
+    }
+    if (event.event === 'scheduled') {
+        return [
+            `A scheduled task has come due: "${event.scheduleName || 'unnamed'}". A person approved this schedule,`,
+            'and FlareDeck is running it now. It is not a card — do what it says and report the result where it',
+            'says to (an email, a message, a comment). If it names nobody or nowhere to report, post a comment',
+            'on the most relevant card or send a direct message to the person who would care.',
+            '',
+            'The instruction:',
+            '',
+            event.prompt || event.message || event.line,
+            '',
+            'You have no memory of earlier runs, and nothing here may be undone by waiting: act, then finish.',
+            'Do not create further schedules from this run.',
+        ].join('\n');
+    }
+    if (event.event === 'review') {
+        return [
+            'A worker that reports to you is asking to run a script against production, and it cannot',
+            'go to a person until you have reviewed it:',
+            '',
+            event.line,
+            '',
+            'Read the card with get-card-details. The request is the newest comment carrying an approval,',
+            'with its comment id, the script, the worker\'s own account of it, and the harness\'s row-count',
+            'preview. Check that the WHERE clause matches the stated purpose and that the preview matches',
+            'the expected effect. Then call review_production_run with that comment id: endorse, and the',
+            'people who can approve it are asked; reject, and the worker is refused with your note. Do not',
+            'dispatch, re-assign, or change anything else — this is a review, not a card to work.',
+        ].join('\n');
+    }
+    return [
+        `A FlareDeck event just arrived for you:`,
+        '',
+        event.line,
+        '',
+        'Deal with it. Read the card before you change anything — INCLUDING its agent notes, where a',
+        'previous session may have left you a handover: what it got to, what it tried that failed,',
+        'what about this environment cost it time. Keep your todo list in step with the',
+        'work, and comment on the card so a person can follow what you did. If you cannot finish —',
+        'you need a decision, an approval, or something is blocking you — call set-needs-human and say',
+        'what you need. Nobody is watching this terminal, so stopping without saying so is the one',
+        'thing that does not work.',
+    ].join('\n');
+}
+//# sourceMappingURL=serve.js.map