@onepointfour-packs/flaredeck-agent 0.1.0 → 0.2.1

package/dist/serve.js

@@ -1,24 +1,32 @@
 import { createRequire } from 'node:module';
-import { environmentBrief, startEnvironment } from './environment.js';
-import { GIT_TOOL_NAMES, githubTools } from './github.js';
+import { START_SCRIPT as START_SCRIPT_NAME, browserBrief, crossWired, environmentBrief, notStartedBrief, startEnvironment } 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';
 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 { NOT_FOR_WORKERS, 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 { currentBranch, ensureWorktree, existingWorktree, produced, releaseWorktree, tooEarlyToFinish, uncommittedCount, worktreeBrief } from './worktree.js';
 import { askingForComponent, checkouts, resolveCheckout, voteByCode, workspaceBrief } from './workspace.js';
 import { intake, intakeText } from './intake.js';
+import { standingBrief } from './agent.js';
 import { startUi } from './ui.js';
 import { checkAndStage, installedSdkVersion, pendingUpdate, updatesEnabled } from './updater.js';
-import { saveConfig } from './config.js';
+import { updateSidecarSdk } from './updater-python.js';
+import { managedPython, usingManagedPython } from './engine-antigravity.js';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { configDir, saveConfig } from './config.js';
+import { browserTools } from './browser.js';
+import { watchForDesperation } from './desperation.js';
+import { note, recallWorktree, rememberWorktree, resumeBrief } from './journal.js';
 import { EventStream } from './stream.js';
 /**
  * The always-on agent.
@@ -48,12 +56,21 @@ export async function serve(opts) {
         lines: [],
     };
     let ui = null;
+    // Which card the lines being logged are about. The live line drops it the moment a turn ends,
+    // so without this a finished card leaves a page of work in the scrollback with nothing saying
+    // what it was for — the card number survived only in the branch name.
+    let tag = '';
     const log = (kind, text) => {
+        const line = tag ? { kind, text, card: tag } : { kind, text };
+        // Kept for the next session on this card. Tools and its own words say what it was doing;
+        // events are harness bookkeeping and would crowd out the work.
+        if (tag && (kind === 'tool' || kind === 'say' || kind === 'todo'))
+            note(tag, text);
         // Keep a bounded tail: a daemon runs for days and nobody scrolls back that far.
-        state.lines.push({ kind, text });
+        state.lines.push(line);
         if (state.lines.length > 400)
             state.lines.splice(0, state.lines.length - 400);
-        ui?.log({ kind, text });
+        ui?.log(line);
     };
     const updated = process.env['FLAREDECK_AGENT_UPDATED'];
     if (updated)
@@ -69,7 +86,124 @@ export async function serve(opts) {
         const looksForUpdates = () => void checkAndStage().then(waiting);
         setTimeout(looksForUpdates, 30_000).unref();
         setInterval(looksForUpdates, 6 * 60 * 60 * 1000).unref();
+        // The sidecar's Python SDK on the same schedule. It used to be pip-installed once, at first
+        // use, and never looked at again — one engine tracked upstream while the other aged. Only the
+        // venv the harness made for itself, and only once the engine in use is actually that one.
+        if (config.engine === 'antigravity') {
+            const looksForSidecarUpdates = () => void updateSidecarSdk(managedPython(), usingManagedPython(), (t) => log('tool', t));
+            setTimeout(looksForSidecarUpdates, 45_000).unref();
+            setInterval(looksForSidecarUpdates, 6 * 60 * 60 * 1000).unref();
+        }
     }
+    /**
+     * The scratch sandbox, which must EXIST before it is handed to anything. An engine that runs
+     * out of process starts its child there, and a child spawned with a cwd that is not there dies
+     * with ENOENT naming the interpreter — which reads as a broken Python install and is not one.
+     */
+    const scratchDir = () => {
+        const dir = join(configDir(), 'scratch');
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch { /* reported by whatever uses it */ }
+        return dir;
+    };
+    /** Cards already reported as left unfinished, so a quiet agent is not reported every turn. */
+    const toldAbout = new Set();
+    /**
+     * Work left behind when a session ended. Told to the lead, because the agent that stopped is
+     * by definition not going to say anything, and told once per card per state so a lead is not
+     * pestered about the same half-finished branch.
+     */
+    const reportUnfinished = async (card) => {
+        const tree = await existingWorktree(config.repo, card).catch(() => null);
+        if (!tree)
+            return;
+        let left;
+        try {
+            left = await produced(tree);
+        }
+        catch {
+            return;
+        }
+        const dirty = await uncommittedCount(tree.path);
+        if (!dirty && (left.commits === 0 || left.pushed))
+            return; // nothing hanging
+        const what = [
+            dirty ? `${dirty} file(s) changed and not committed` : '',
+            left.commits > 0 && !left.pushed ? `${left.commits} commit(s) not published` : '',
+        ].filter(Boolean).join(', ');
+        const stamp = `${card}:${what}`;
+        if (toldAbout.has(stamp))
+            return;
+        toldAbout.add(stamp);
+        log('warn', `${card} left unfinished — ${what}`);
+        if (!leadId)
+            return;
+        try {
+            await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'send-message', {
+                to: leadId,
+                message: `**${card}: my session ended with work unfinished.**\n\n` +
+                    `Branch \`${left.branch}\` — ${what}. The checkout is still there and nothing is lost; ` +
+                    `I stopped before finishing, so this did not reach you as a review.\n\n` +
+                    `The harness picks the card back up by itself shortly. Tell me if you want it differently.`,
+            });
+            log('tool', `told ${leadName} that ${card} was left unfinished`);
+        }
+        catch (e) {
+            log('warn', `could not tell ${leadName} about ${card}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    };
+    /**
+     * The checkout a message is about, when it names a card this agent already has one for.
+     *
+     * Nothing is created here. If there is no worktree the turn stays as it was — a conversation
+     * 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) => {
+        // `ask` too: a question typed in the pane is usually about the card in front of the person,
+        // and without this the turn has no checkout and therefore no publishing tools — so an agent
+        // asked to commit its work truthfully answers that it cannot.
+        if (!['message', 'commented', 'ask'].includes(event.event))
+            return null;
+        const text = `${event.line ?? ''} ${event.message ?? ''}`;
+        const codes = [...new Set(text.match(/\b[A-Z][A-Z0-9]{1,9}-\d{3,}\b/g) ?? [])];
+        for (const code of codes) {
+            // What the harness wrote down when it made the worktree, first: the directory is named from
+            // the card's internal id and the branch from whatever the agent chose, so neither can be
+            // matched against the code a message uses.
+            const known = recallWorktree(code);
+            // The branch is read from the checkout, never from what was written down: an agent may
+            // rename its branch, and telling it the name the harness cut months ago is worse than
+            // saying nothing. The PATH is the thing worth remembering.
+            const found = known
+                ? { path: known.path, branch: (await currentBranch({ path: known.path, branch: known.branch, created: false })).name, created: false }
+                : await existingWorktree(repo, code).catch(() => null);
+            if (found) {
+                onStep(`this is about ${code} — using its checkout, ${found.branch}`);
+                tag = code;
+                return found;
+            }
+        }
+        return null;
+    };
+    /** Said to the lead when an agent has started working around the harness instead of the card. */
+    const tellLeadItIsStuck = async (card, refusals) => {
+        if (!leadId)
+            return;
+        try {
+            await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'send-message', {
+                to: leadId,
+                message: `**${card}: I am stuck and I have stopped.**\n\n` +
+                    `${refusals} of my commands were refused this turn and I started looking for ways ` +
+                    `around them, which is never right. Something the harness told me to do, I cannot do ` +
+                    `here. I have said the details on the card.`,
+            });
+            log('tool', `told ${leadName} it is stuck on ${card}`);
+        }
+        catch { /* the pane already says it */ }
+    };
     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.
@@ -263,16 +397,31 @@ export async function serve(opts) {
     };
     /** Who this agent reports to, when it is a worker on a team: production runs go there first. */
     let leadId = null;
+    let leadName = '';
+    /** A lead's surface is wider than a worker's, so the tool list is too. */
+    let isLead = false;
+    const keepTool = (name) => isLead || !NOT_FOR_WORKERS.includes(name);
+    /** Cards already handed to the lead, so a retried tool call does not assign or message twice. */
+    const handedBack = new Set();
     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.
+        // A lead this agent was told to report to gets asked, whether or not it is a harness.
+        //
+        // This used to require the lead to have written a status record recently, which only a
+        // harness does — so a lead that is a plain session, driven by a person, read as "not
+        // running" and was routed around every time. Somebody set reportsTo on purpose; going over
+        // their head because they are not a daemon is the wrong default, and it means approvals
+        // reach people without the context the lead has.
+        //
+        // It is safe to assume, because asking the lead does not replace asking a person: an
+        // endorsement PROMOTES the request rather than answering it, and a lead that never responds
+        // lapses (see flaredeckDecider) and the request goes on to the approvers.
         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`);
+        leadId = team.you.reportsTo || null;
+        leadName = lead?.name ?? leadId ?? '';
+        if (leadId)
+            log('tool', `your lead is ${leadName} — ${leadName} verifies your work before it goes anywhere`);
+        isLead = team.you.role === 'lead';
         if (team.you.role === 'lead') {
             teamSet = {
                 // After a review the list changes — an endorsed request is now answerable, from THIS
@@ -437,11 +586,45 @@ export async function serve(opts) {
         && event.event !== 'review'
         && event.event !== 'ask'
         && !(event.event === 'commented' && event.cardDone && !event.mentioned)
+        // Someone else's card is not worth reading ahead. `drain` already declines to WORK these —
+        // a card this agent once touched keeps sending it every move and comment made by whoever
+        // holds it now — but that check happens when the event's turn comes, and reading ahead
+        // happens the moment it arrives. So an agent paid for a brief, a Jev call and a code search
+        // on cards belonging to other agents, to people, and on cards already done, before
+        // concluding it should ignore them. Same question, asked early enough to matter.
+        && needsMe(event)
+        // Named on somebody else's card is correspondence, not work. The agent is still woken —
+        // being addressed by name must do something, or @mentioning an agent is useless — but intake
+        // exists to brief and SIZE work, and there is no work here to size. One agent ran a full
+        // brief, a Jev classification and a code search on a card held by another agent, sitting in
+        // a signoff lane, and concluded it was "large · prod data". None of which it was going to do.
+        // It reads the card in its turn, as a person would, and answers.
+        && !(event.mentioned === true && event.forYou === false)
         && !sessions.has(event.cardKey);
+    /**
+     * How many cards may be read ahead at once.
+     *
+     * The point of reading ahead is that the NEXT card is ready when the current one ends — one
+     * card, not the whole queue. But this fired on every event as it arrived, so a backlog of
+     * thirty started thirty intakes at once, each a brief, a Jev call and a code search that takes
+     * seconds of git grep. That is a thundering herd against two providers at the same moment, and
+     * it showed: briefs fell back to Haiku and Jev came back off, with no error anywhere, because
+     * both were simply being rate-limited by this agent's own enthusiasm.
+     *
+     * Two: the next card, and one spare for when the next card turns out not to need this agent.
+     * Anything further back is read when its turn comes, which costs a few seconds of latency and
+     * nothing else — `handle` already falls back to reading the card itself when nothing was
+     * prepared for it.
+     */
+    const PREPARE_AHEAD_LIMIT = 2;
+    let preparing = 0;
     const prepareAhead = (event) => {
         if (!wantsIntake(event) || preparedAhead.has(event.id))
             return;
+        if (preparing >= PREPARE_AHEAD_LIMIT)
+            return;
         const label = event.cardCode || event.cardKey || '';
+        preparing++;
         preparedAhead.set(event.id, {
             at: Date.now(),
             // The repo this card belongs to, so the code search behind the brief searches the right
@@ -449,7 +632,16 @@ export async function serve(opts) {
             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),
+            })()
+                .catch(() => null)
+                .finally(() => {
+                preparing--;
+                // A slot just freed: warm the card actually next in line, rather than whichever event
+                // happened to arrive while the queue was full.
+                const next = queue.find((e) => !preparedAhead.has(e.id));
+                if (next)
+                    prepareAhead(next);
+            }),
         });
     };
     let working = false;
@@ -498,12 +690,55 @@ export async function serve(opts) {
         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.
+     *
+     * The sweep told the model "a card already in progress: say which one, and stop. It will come
+     * back to you." Nothing brought it back. A card sitting in the in-progress lane with this
+     * agent's name on it generates no further events, so it sat there until a person prodded —
+     * twice, usually, because the first prod produced the same observation.
+     *
+     * Finding it needs no model at all: the board knows, and `get-outstanding` answers. So the
+     * harness reads it and queues the card itself, as the ordinary card event it should always
+     * 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;
+        let mine = [];
+        try {
+            const out = await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'get-outstanding', {});
+            const text = typeof out === 'string' ? out : JSON.stringify(out);
+            // The codes it names, in the order it names them: priority order, which is the board's.
+            mine = [...new Set(text.match(/\b[A-Z][A-Z0-9]{1,9}-\d{3,}\b/g) ?? [])].map((code) => ({ code }));
+        }
+        catch {
+            return; // unreachable board is the stream's problem to report, not this timer's
+        }
+        const next = mine.find((c) => !sessions.has(c.code) && !live.has(c.code));
+        if (!next)
+            return;
+        log('tool', `picking ${next.code} back up — it is yours and already in progress`);
+        if (enqueue({
+            id: `resume-${next.code}-${Date.now()}`,
+            event: 'assigned',
+            line: `${next.code} is still yours and in progress`,
+            cardCode: next.code,
+            cardKey: next.code,
+        }))
+            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();
+    // Between sweeps, and offset from them so the two never race for the same card.
+    const resumeTimer = setInterval(() => void resumeOwnWork(), SWEEP_EVERY_MS);
+    resumeTimer.unref();
+    if (sweepsEnabled)
+        setTimeout(() => void resumeOwnWork(), 90_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,
@@ -522,6 +757,7 @@ export async function serve(opts) {
         stream.close();
         clearInterval(heartbeat);
         clearInterval(sweepTimer);
+        clearInterval(resumeTimer);
         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.
@@ -545,8 +781,22 @@ export async function serve(opts) {
                     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';
+                // What a person reading the pane wants to know is WHICH card, and a code alone is not
+                // that — you have to go and look it up. "a message" was worse: it did not even say who
+                // from, on a line that sits there for minutes.
+                const cardLabel = event.cardCode || event.cardKey || '';
+                const title = (event.cardName || '').trim();
+                current = event.event === 'ask'
+                    ? 'your question'
+                    : event.event === 'sweep'
+                        ? 'your outstanding work'
+                        : event.event === 'scheduled'
+                            ? event.scheduleName || 'a scheduled task'
+                            : cardLabel
+                                ? `${cardLabel}${title ? ` · ${title.length > 58 ? `${title.slice(0, 57)}…` : title}` : ''}`
+                                : `a message${event.actor ? ` from ${event.actor}` : ''}`;
                 state.working = current;
+                tag = cardLabel;
                 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.
@@ -584,8 +834,16 @@ export async function serve(opts) {
                     setTimeout(() => { if (enqueue(event, true))
                         void drain(); }, 60_000).unref();
                 }
+                // A session ends when the model stops talking, which is not the same as the work being
+                // done. HAL ended one with sixteen call sites edited, ten files modified, nothing
+                // committed and nobody told — and the next session, with the conversation gone, started
+                // the card from the beginning. The worktree answers "was this finished" without asking a
+                // model: uncommitted changes, or commits that never reached the remote.
+                if (tag)
+                    await reportUnfinished(tag);
                 current = '';
                 state.working = '';
+                tag = '';
                 delete state.branch;
                 delete state.base;
                 delete state.tasks;
@@ -768,10 +1026,19 @@ export async function serve(opts) {
             log('event', `working in ${chosen.name}`);
         if (fromCard)
             log('event', `base ${fromCard.branch} — ${fromCard.role} (${event.environment || 'no environment'}), from the board`);
+        // A card's own turn gets its worktree made. A turn that is ABOUT a card — a lead saying
+        // "commit and push what you have" — gets the one that already exists, and with it the job,
+        // 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.
         const tree = event.cardKey && (chosen || where.kind === 'none')
-            ? await ensureWorktree(repo, key, (t) => log('tool', t), startFrom)
-            : null;
+            ? await ensureWorktree(repo, key, (t) => log('tool', t), startFrom, config.worktreeLocalFiles)
+            : await worktreeTheMessageIsAbout(event, repo, (t) => log('tool', t));
         const cwd = tree?.path ?? repo;
+        // 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);
+        }
         // 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
@@ -802,7 +1069,71 @@ export async function serve(opts) {
         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));
+        // The gate on calling a card finished: it must have commits of its own, published. Checked
+        // here rather than trusted, because a turn that produced nothing still reports confidently.
+        const finishGate = async () => {
+            const why = await tooEarlyToFinish(tree);
+            if (why) {
+                log('warn', `refused a "done" on an empty branch: ${tree?.branch ?? '(no branch)'}`);
+                return why;
+            }
+            // If this agent reports to someone, it does not decide that its own work is finished. The
+            // lead said "I'll check its saved work myself before it goes anywhere" and then was never
+            // told: the card moved itself to Awaiting Deployment. A report hands back; the lead moves
+            // it, or comments and sends it back, which is what a lead is for.
+            if (!leadId)
+                return null;
+            const code = tag || event.cardCode || event.cardKey || '';
+            if (!code)
+                return null;
+            if (!handedBack.has(code)) {
+                handedBack.add(code);
+                const made = tree ? await produced(tree) : null;
+                const where = tree
+                    ? `Branch \`${tree.branch}\`${made ? ` — ${made.commits} commit(s), ${made.pushed ? 'pushed' : 'NOT pushed'}` : ''}.`
+                    : 'No branch: nothing of mine is in a checkout for this card.';
+                try {
+                    const token = await opts.auth();
+                    await callFlaredeckTool(config.mcpUrl, token, 'assign-card', { card_id: code, assignee: leadId });
+                    await callFlaredeckTool(config.mcpUrl, token, 'send-message', {
+                        to: leadId,
+                        message: `**${code} is ready for your review.**\n\n${where}\n\n` +
+                            `I have not moved it — it is assigned to you and still in its lane. ` +
+                            `Check the work and move it on, or comment on the card and I will fix it.`,
+                    });
+                    log('tool', `handed ${code} to ${leadName} for review`);
+                }
+                catch (e) {
+                    // A handback that did not happen must not read as one that did.
+                    handedBack.delete(code);
+                    const text = e instanceof Error ? e.message : String(e);
+                    log('warn', `could not hand ${code} to ${leadName}: ${text}`);
+                    return `Could not hand this card to ${leadName} for review (${text}). Do not move it; say so on the card instead.`;
+                }
+            }
+            return (`${code} is now ${leadName}'s to verify, not yours to close. It is assigned to them and ` +
+                `they have been told, with your branch. Leave the lane alone — they move it on, or comment ` +
+                `and send it back to you. Your part is done; say nothing further about it being finished.`);
+        };
+        // A turn woken by a message says "a message from JARVIS" for as long as it runs, even while
+        // it is plainly working a card. The card tools name the card; this takes it from there, and
+        // only when the turn had none of its own.
+        // Ground truth for the footer on anything this agent says. Null without a worktree: there is
+        // no branch to report on, and a footer saying "nothing committed" would be misleading rather
+        // than informative.
+        const savedSoFar = async () => {
+            if (!tree)
+                return null;
+            const { commits, pushed, branch, known } = await produced(tree);
+            return { branch, commits, pushed, known };
+        };
+        const noteCard = (code) => {
+            if (!code || tag)
+                return;
+            tag = code;
+            state.working = code;
+        };
+        const flaredeck = flaredeckProxy(config.mcpServerName, config.mcpUrl, opts.auth, check.discovered, (w) => log('warn', w), finishGate, noteCard, keepTool, savedSoFar);
         const held = live.get(key);
         if (held?.timer)
             clearTimeout(held.timer);
@@ -853,18 +1184,76 @@ export async function serve(opts) {
                 },
             }
             : null;
+        // 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.
+        //
+        // Both of these belong to a CARD's own checkout. Without a worktree there is no card being
+        // worked and `cwd` is the shared checkout itself — so a sweep asking "what is still assigned
+        // to me", or a question typed in the pane, was starting a scratch database, running
+        // migrations and bringing up an API and a web server, in the checkout everything else shares,
+        // to answer something that needs no running software at all. Every hour, on the hour.
+        const forACard = !!tree;
+        const checks = forACard ? await preflight(cwd, (t) => log('tool', t)) : [];
+        // Only bring the project UP when the card needs it running. Intake already judges that, and
+        // the judgement was being used to decide whether to MENTION the environment while starting it
+        // regardless — so a six-pixel CSS alignment fix paid for an install, a database and two
+        // 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
+            // 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)
+            : { ran: false, ok: true, endpoints: {}, detail: '' };
+        if (forACard && !needsRunning)
+            log('tool', 'environment not started — this card does not look like it needs one');
         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 } : {}),
+            //
+            // A SWEEP is the exception, and the reason is worth stating. It is a handover — find the
+            // next piece of work and start it moving — and it has no card, so no worktree. If it tried
+            // to do the work anyway it would be editing the shared checkout every worktree is cut from,
+            // on no branch, with no way to publish it. The brief says so; this makes it true. Pointing
+            // the sandbox at a directory that holds no source confines writes to scratch space (/tmp is
+            // always allowed) without pretending it has a checkout it does not have.
+            // There is ALWAYS a sandbox. It used to be set only for a card or a sweep, so a turn woken
+            // by a message had none — nothing confined — and an agent told "work HR-0621" by its lead
+            // did exactly that, in the shared checkout every worktree is cut from, on a branch of its
+            // own. Without a worktree there is nowhere legitimate to write, so the turn gets scratch
+            // space and has to hand the card back instead.
+            sandbox: tree ? tree.path : scratchDir(),
             decider,
+            // Both only reachable in-process, so an out-of-process engine is handed them explicitly
+            // rather than being left unable to publish and unchecked when it says it has.
+            ...(job ? { publish: async () => publishBranch(job) } : {}),
+            standing: standingBrief(!!teamSet, config.style ?? process.env['FLAREDECK_AGENT_STYLE']),
+            finish: finishGate,
+            noteCard,
+            keep: keepTool,
+            saved: savedSoFar,
             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 } } : {}),
+                // Eyes, when there is something running to look at. A card with no environment gets no
+                // browser tools and is told nothing about them.
+                ...(env.ran && Object.keys(env.endpoints).length
+                    ? {
+                        browser: browserTools({
+                            repo: config.repo,
+                            endpoints: () => env.endpoints,
+                            contract: () => env.contract,
+                            cwd,
+                            onNote: (t) => log('tool', t),
+                        }),
+                    }
+                    : {}),
                 team: teamSet,
                 flaredeck,
                 runs: runsSet,
@@ -872,23 +1261,46 @@ export async function serve(opts) {
             },
             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));
+        // Before the agent believes a single thing the environment tells it: is this environment
+        // actually its own? A front end on an assumed port reaches another worktree's API and answers
+        // perfectly, which is the one failure here that looks like success.
+        const wrongEnv = tree && env.ran ? await crossWired(env.endpoints, tree.path) : [];
+        for (const w of wrongEnv)
+            log('warn', w);
         const brief = prompt(event) + intakeText(prepared) +
             workspaceBrief(config.repo, await checkouts(config.repo, config.repos), chosen) +
-            worktreeBrief(tree) + preflightBrief(checks) +
+            worktreeBrief(tree) + (await resumeBrief(event.cardCode || event.cardKey || '', 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);
+            environmentBrief(env, cwd, needsRunning) + notStartedBrief(forACard && !needsRunning, cwd) +
+            browserBrief(env.ran && Object.keys(env.endpoints).length > 0, env.endpoints) +
+            (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 ` +
+                    `normally while doing so. Do not work around it by picking a different port. Say this on ` +
+                    `the card, tell whoever owns the board that ${START_SCRIPT_NAME} does not survive parallel ` +
+                    `worktrees — it must take a free port AND pass that port to the parts that call it — and stop.`
+                : '');
         const run = engine.run(brief, engineContext);
         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(() => { });
+                    }
+                    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.
@@ -1129,20 +1541,30 @@ async function baseBranch(cwd) {
 function prompt(event) {
     if (event.event === 'sweep') {
         return [
-            'Nothing has arrived for a while, so this is a check of what you already hold.',
+            'Nothing has arrived for a while, so this is a check of what you already hold. It is a',
+            'HANDOVER, not a working turn: you find the next piece of work and start it moving, and it',
+            'comes back to you properly a moment later.',
             '',
             '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 it 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.',
+            '',
+            'Otherwise take the FIRST one by priority and, depending on what it is:',
+            '',
+            '- A card for one of the agents who report to you: assign it to the right one. That dispatch',
+            '  IS the work, and this turn is done.',
+            '- A card that is yours and NOT already in progress: move it to the board\'s in-progress lane',
+            '  with update-card-status, and stop. Do not read it, do not start the work, do not comment',
+            '  on it. Moving it hands it back to you as a card of its own — with a checkout of your own,',
+            '  on its own branch — which is the only place the work can actually be done and published',
+            '  from. Working it here would edit the shared checkout and could not be pushed anywhere.',
+            '- A card already in progress: say which one in a line, and stop. The harness picks those up',
+            '  by itself, shortly, with a checkout of its own — you do not need to do anything for it.',
             '',
-            '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.',
+            'Then stop. One handover per check — the rest are still there next time.',
         ].join('\n');
     }
     if (event.event === 'ask') {