@bridge4dev/runner 0.11.0

package/dist/supervisor.js

@@ -0,0 +1,1648 @@
+import { log } from './log.js';
+import { maskSecrets, maskString } from './policy.js';
+import { JournalStore } from './journal.js';
+import { deleteSessionBranch, ensureSessionWorktree, removeSessionWorktree, repoKeyFor, sessionWorktreePath, validateWorkspacePath, } from './git.js';
+import { applySession, gitCommit, gitDiff, gitLog, gitShow, gitStatus, revertApply, } from './gitops.js';
+import { fsView } from './fsview.js';
+import { agentAuthStatuses, AuthRelay } from './auth-relay.js';
+import { selfUpdate } from './self-update.js';
+import { composeMessageWithAttachments, saveAttachments, } from './attachments.js';
+export class Supervisor {
+    ws;
+    opts;
+    static ORPHAN_MESSAGE_CAP = 10;
+    /** A finished session's journal is kept this long for a late reconnect. */
+    static JOURNAL_TTL_MS = 72 * 3_600_000;
+    /** Backstop: events the API will never accept must not pile up forever. */
+    static JOURNAL_HARD_TTL_MS = 30 * 24 * 3_600_000;
+    sessions = new Map();
+    /**
+     * How many agents may run at once, as told by the API (session 8). Starts at
+     * 1 so a runner talking to an API that predates the field behaves exactly as
+     * it did before: one agent, others parked.
+     */
+    serverMaxSessions = 1;
+    /** Messages for sessions this runner does not track yet, keyed by session. */
+    orphanMessages = new Map();
+    journals;
+    authRelay = new AuthRelay();
+    /** Serialises repo-mutating git commands per workspace repo (QA-99 MAJOR-1). */
+    repoLocks = new Map();
+    /** An update is installing right now — a second one would fight it. */
+    selfUpdateInFlight = false;
+    constructor(ws, opts) {
+        this.ws = ws;
+        this.opts = opts;
+        this.journals = opts.journals ?? new JournalStore();
+        ws.on('frame', (frame) => {
+            void this.onFrame(frame).catch((error) => log.error('supervisor: frame handler failed', { type: frame.type, error: String(error) }));
+        });
+    }
+    get activeSessionIds() {
+        return [...this.sessions.keys()];
+    }
+    async onFrame(frame) {
+        switch (frame.type) {
+            case 'hello_ack':
+                this.setMaxSessions(frame.maxSessions);
+                await this.reconcile(frame.sessions);
+                break;
+            case 'server_settings':
+                this.setMaxSessions(frame.maxSessions);
+                break;
+            case 'session_start':
+                await this.startSession(frame.session);
+                break;
+            case 'session_message':
+                await this.onUserMessage(frame.sessionId, frame.text, frame.attachments);
+                break;
+            case 'permission_answer': {
+                const running = this.sessions.get(frame.sessionId);
+                running?.session?.answerPermission(frame.requestId, frame.allow, frame.note);
+                break;
+            }
+            case 'session_stop':
+                this.stopSession(frame.sessionId);
+                break;
+            case 'session_interrupt':
+                await this.interruptSession(frame.sessionId);
+                break;
+            case 'session_settings':
+                await this.applySettings(frame.sessionId, frame.model, frame.mode, frame.effort);
+                break;
+            case 'command':
+                await this.runCommand(frame);
+                break;
+            case 'event_ack':
+            case 'event_nack': {
+                if (frame.type === 'event_nack') {
+                    log.warn('supervisor: event nacked, retiring seq', {
+                        sessionId: frame.sessionId,
+                        seq: frame.seq,
+                        reason: frame.reason,
+                    });
+                }
+                const journal = this.journals.open(frame.sessionId);
+                journal.ack(frame.seq); // nack retires the seq too — it is permanent
+                const running = this.sessions.get(frame.sessionId);
+                if (!running && journal.unacked().length === 0) {
+                    this.journals.closeAndDelete(frame.sessionId);
+                }
+                break;
+            }
+            case 'error':
+                log.warn('supervisor: error frame from API', { message: frame.message });
+                break;
+            default:
+                break;
+        }
+    }
+    // ─── Lifecycle ─────────────────────────────────────────────────────
+    async startSession(descriptor) {
+        const existing = this.sessions.get(descriptor.id);
+        if (existing) {
+            // A resume (higher epoch) can land while the previous life is still
+            // winding down — the agent-error FAILED path in particular leaves the
+            // process streaming without `stopRequested`. Queue the relaunch and force
+            // the wind-down instead of silently dropping the new descriptor.
+            if (descriptor.epoch > existing.epoch) {
+                existing.pendingRestart = descriptor;
+                existing.stopRequested = true;
+                existing.session?.stop();
+            }
+            return;
+        }
+        // Up to `maxSessions` agents at once (session 8). Sessions idling after a
+        // finished turn (REVIEW / WAITING_INPUT) don't hold a slot: they are parked
+        // — the provider session survives on disk and relaunches on the next message.
+        if (!this.ensureCapacity(descriptor.id)) {
+            const limit = this.maxSessions;
+            this.reportStatus(descriptor.id, 'FAILED', {
+                errorMessage: limit === 1
+                    ? 'Runner already has an active session'
+                    : `Runner is already running ${limit} active sessions — stop one first`,
+            });
+            return;
+        }
+        if (!this.opts.adapters[descriptor.agent]) {
+            this.reportStatus(descriptor.id, 'FAILED', {
+                errorMessage: `${AGENT_LABELS[descriptor.agent] ?? descriptor.agent} is not installed on this server`,
+            });
+            return;
+        }
+        const running = {
+            descriptor,
+            journal: this.journals.open(descriptor.id),
+            session: null,
+            lastReported: descriptor.status,
+            costUsd: descriptor.costUsd,
+            costBaseUsd: descriptor.costUsd,
+            stopRequested: false,
+            parkRequested: false,
+            pendingMessages: [],
+            activeMs: descriptor.activeMsBase,
+            extraBudgetMinutes: descriptor.extraBudgetMinutes,
+            epoch: descriptor.epoch,
+            mode: descriptor.mode,
+            ...(descriptor.model ? { model: descriptor.model } : {}),
+            ...(descriptor.effort ? { effort: descriptor.effort } : {}),
+            lastPrompt: '',
+        };
+        // Seed the journal counter past whatever the API already stored: a wiped
+        // runner state dir would otherwise restart at seq 1 and every replayed
+        // event would be swallowed as a duplicate (QA-99 MAJOR-3).
+        running.journal.ensureSeqAbove(descriptor.lastSeq);
+        // Messages this session was handed before the daemon last stopped. The API
+        // considers them delivered, so the journal is the only place they still
+        // exist (session 9).
+        running.pendingMessages.push(...running.journal.pending());
+        this.sessions.set(descriptor.id, running);
+        // Messages that arrived for a session this runner did not know yet.
+        const orphaned = this.orphanMessages.get(descriptor.id);
+        if (orphaned) {
+            this.orphanMessages.delete(descriptor.id);
+            for (const message of orphaned) {
+                running.pendingMessages.push(running.journal.appendPending(message.text, message.attachments));
+            }
+        }
+        try {
+            // `worktree add` writes into the shared .git (registration + prune), so
+            // it takes the same repo lock as commit/apply/revert.
+            const { branch, worktreePath } = await this.withRepoLockFor(descriptor.workspace.path, () => ensureSessionWorktree(descriptor.workspace.path, descriptor.id, descriptor.branchHint, {
+                requireExistingBranch: hasWorkToResume(descriptor),
+            }));
+            running.branch = branch;
+            running.worktreePath = worktreePath;
+        }
+        catch (error) {
+            this.reportStatus(descriptor.id, 'FAILED', {
+                errorMessage: `Failed to prepare git worktree: ${maskSecretText(error)}`,
+            });
+            this.sessions.delete(descriptor.id);
+            return;
+        }
+        // A session that is already past STARTING (re-sent because this runner
+        // asked for it) resumes on the next message instead of replaying its
+        // original prompt.
+        if (descriptor.status === 'STARTING') {
+            this.launchAgent(running, composeInitialPrompt(descriptor), null);
+        }
+        else {
+            if (descriptor.epoch > 0) {
+                // The API owns the resume transition; the feed marker has to come from
+                // here because the runner is the only writer of the event seq.
+                this.sendEvent(running, 'system_note', {
+                    text: 'Session resumed — send a message to continue where the agent left off.',
+                });
+            }
+            running.lastReported = descriptor.status === 'REVIEW' ? 'REVIEW' : 'WAITING_INPUT';
+            this.reportStatus(descriptor.id, running.lastReported, {
+                branch: running.branch,
+                worktreePath: running.worktreePath,
+                activeMs: running.activeMs,
+            });
+        }
+        this.flushPendingMessages(running);
+    }
+    /**
+     * Spin the adapter up — for a fresh session, a resume-on-next-message, or a
+     * free CHAT session with no prompt at all (the agent boots, reports its
+     * capabilities and waits for the first message).
+     *
+     * Returns whether an agent process actually started: a caller holding a user
+     * message needs to know, because a refused launch means the message has to
+     * stay queued rather than be marked delivered (session 9).
+     */
+    launchAgent(running, prompt, resumeId) {
+        const { descriptor } = running;
+        const adapter = this.opts.adapters[descriptor.agent];
+        if (!adapter || !running.worktreePath || !running.branch)
+            return false;
+        // An exhausted USD budget must not relaunch $0.01-floor processes (QA-96 F4).
+        // Codex reports no cost at all, so its costUsd never leaves 0 — gating on it
+        // would be a limit that can never fire while the UI shows $0.00. Those
+        // sessions are bounded by budgetMinutes instead.
+        if (reportsCost(descriptor.agent) &&
+            descriptor.workspace.budgetUsd !== null &&
+            descriptor.workspace.budgetUsd - running.costBaseUsd <= 0) {
+            // Not FAILED: nothing went wrong, the session simply spent its allowance.
+            // «Продолжить» raises the workspace budget and picks it back up.
+            running.budgetSpent = true;
+            this.sendEvent(running, 'notice', {
+                level: 'warn',
+                text: `The session has spent its whole $${descriptor.workspace.budgetUsd} budget. Raise the workspace budget to continue.`,
+            });
+            this.reportStatus(descriptor.id, 'STOPPED', {
+                costUsd: running.costUsd,
+                endReason: 'COST_BUDGET',
+                activeMs: running.activeMs,
+                errorMessage: `Session budget ($${descriptor.workspace.budgetUsd}) is exhausted`,
+            });
+            this.sessions.delete(descriptor.id);
+            return false;
+        }
+        // The time budget is already spent: relaunching would burn a process for
+        // nothing and immediately stop again.
+        if (running.budgetSpent) {
+            this.sendEvent(running, 'notice', {
+                level: 'warn',
+                text: 'The time budget is used up — press «Продолжить» to give the agent more time.',
+            });
+            return false;
+        }
+        running.lastPrompt = prompt;
+        running.session = adapter.startSession({
+            sessionId: descriptor.id,
+            cwd: running.worktreePath,
+            ...(prompt ? { prompt } : {}),
+            trustMode: descriptor.workspace.trustMode,
+            mode: running.mode,
+            ...(running.model ? { model: running.model } : {}),
+            ...(running.effort ? { effort: running.effort } : {}),
+            ...(resumeId ? { resumeProviderSessionId: resumeId } : {}),
+            // Descriptor MCP (auto-issued per-workspace key) wins over config.toml.
+            ...((descriptor.mcp ?? this.opts.mcp) ? { mcp: descriptor.mcp ?? this.opts.mcp } : {}),
+            // The SDK budget is per-process; hand the RESIDUAL session budget down.
+            ...(reportsCost(descriptor.agent) && descriptor.workspace.budgetUsd !== null
+                ? { maxBudgetUsd: Math.max(0.01, descriptor.workspace.budgetUsd - running.costBaseUsd) }
+                : {}),
+        });
+        // No prompt → nothing is running yet: the agent is up and waiting for the
+        // user's first message (free CHAT session). reportStatus drives the budget
+        // clock, so this call is also what starts (or does not start) billing.
+        this.reportStatus(descriptor.id, prompt ? 'RUNNING' : 'WAITING_INPUT', {
+            branch: running.branch,
+            worktreePath: running.worktreePath,
+        });
+        void this.pumpEvents(running);
+        return true;
+    }
+    // ─── Time budget (session 7) ───────────────────────────────────────
+    //
+    // The budget measures the AGENT's working time, not the calendar. Everything
+    // below hangs off one predicate and one sync point so there is no way to add
+    // a new waiting state and silently keep billing it.
+    /** Warn the user when this share of the budget is gone. */
+    static BUDGET_WARN_RATIO = 0.8;
+    /** Is the agent actually working right now (i.e. should the clock run)? */
+    static isBillable(running) {
+        return running.lastReported === 'RUNNING' || running.lastReported === 'STARTING';
+    }
+    /**
+     * Start or stop the budget clock to match the session's current state.
+     *
+     * MUST be called from every place that changes `lastReported` — not just
+     * reportStatus. `sendEvent` sets WAITING_PERMISSION directly and the API
+     * infers WAITING_INPUT from a `question` event, and those two states are
+     * exactly where an ask-mode session spends its time waiting for a human.
+     */
+    syncBudgetClock(running) {
+        const billable = Supervisor.isBillable(running) && Boolean(running.session);
+        if (billable) {
+            if (running.activeSince === undefined)
+                running.activeSince = Date.now();
+            this.armBudgetTimers(running);
+            return;
+        }
+        if (running.activeSince !== undefined) {
+            running.activeMs += Date.now() - running.activeSince;
+            delete running.activeSince;
+        }
+        this.clearBudgetTimers(running);
+    }
+    /**
+     * Agent time spent so far, INCLUDING the slice currently in flight. Reading
+     * `activeMs` alone made every RUNNING→RUNNING re-report (a follow-up message,
+     * a reconnect) re-arm the timer from a stale figure, so a busy session could
+     * slide past its limit indefinitely.
+     */
+    static spentMs(running) {
+        return (running.activeMs + (running.activeSince === undefined ? 0 : Date.now() - running.activeSince));
+    }
+    /** Total budget in ms, or null when the workspace has no time limit. */
+    budgetMsFor(running) {
+        const base = running.descriptor.workspace.budgetMinutes;
+        if (base === null)
+            return null;
+        return (base + (running.extraBudgetMinutes ?? 0)) * 60_000;
+    }
+    armBudgetTimers(running) {
+        const budgetMs = this.budgetMsFor(running);
+        if (budgetMs === null)
+            return;
+        this.clearBudgetTimers(running);
+        const remaining = budgetMs - Supervisor.spentMs(running);
+        if (remaining <= 0) {
+            // Deferred, NOT called inline. armBudgetTimers runs inside reportStatus,
+            // and pausing from here would re-enter reportStatus and then let the
+            // outer call send its own (now stale) status after the STOPPED frame.
+            const immediate = setTimeout(() => this.pauseForBudget(running), 0);
+            immediate.unref();
+            running.budgetTimer = immediate;
+            return;
+        }
+        if (!running.budgetWarned) {
+            const warnIn = remaining - budgetMs * (1 - Supervisor.BUDGET_WARN_RATIO);
+            if (warnIn > 0) {
+                running.budgetWarnTimer = setTimeout(() => {
+                    running.budgetWarned = true;
+                    const leftMin = Math.max(1, Math.round((budgetMs - Supervisor.spentMs(running)) / 60_000));
+                    this.sendEvent(running, 'notice', {
+                        level: 'warn',
+                        text: `The agent has used ${Math.round(Supervisor.BUDGET_WARN_RATIO * 100)}% of its ${Math.round(budgetMs / 60_000)} minutes of working time — about ${leftMin} min left.`,
+                    });
+                }, warnIn);
+                running.budgetWarnTimer.unref();
+            }
+            else {
+                running.budgetWarned = true;
+            }
+        }
+        running.budgetTimer = setTimeout(() => this.pauseForBudget(running), remaining);
+        running.budgetTimer.unref();
+    }
+    clearBudgetTimers(running) {
+        if (running.budgetTimer) {
+            clearTimeout(running.budgetTimer);
+            delete running.budgetTimer;
+        }
+        if (running.budgetWarnTimer) {
+            clearTimeout(running.budgetWarnTimer);
+            delete running.budgetWarnTimer;
+        }
+    }
+    /**
+     * The agent has worked for as long as it was allowed. Stop it cleanly and
+     * keep everything needed to pick it back up — this is NOT a failure, and
+     * reporting it as one is what made five of the first twelve prod sessions
+     * look broken.
+     */
+    pauseForBudget(running) {
+        const { descriptor } = running;
+        if (running.budgetSpent || isTerminal(running.lastReported))
+            return;
+        running.budgetSpent = true;
+        this.clearBudgetTimers(running);
+        if (running.activeSince !== undefined) {
+            running.activeMs += Date.now() - running.activeSince;
+            delete running.activeSince;
+        }
+        const minutes = Math.round((this.budgetMsFor(running) ?? 0) / 60_000);
+        log.warn('supervisor: time budget spent', { sessionId: descriptor.id, minutes });
+        // Interrupt so the worktree is left between tool calls rather than mid-edit.
+        // Never awaited: for Codex this is a no-op between turns and a request with
+        // a 60s ceiling during one — neither belongs in a timer callback.
+        void Promise.resolve(running.session?.interrupt()).catch(() => undefined);
+        this.sendEvent(running, 'notice', {
+            level: 'warn',
+            text: `The agent worked for its full ${minutes} minutes and was paused. Press «Продолжить» to give it more time.`,
+        });
+        running.stopRequested = true;
+        this.reportStatus(descriptor.id, 'STOPPED', {
+            costUsd: running.costUsd,
+            endReason: 'TIME_BUDGET',
+            activeMs: running.activeMs,
+            errorMessage: `Time budget (${minutes} min of agent work) reached`,
+        });
+        running.session?.stop();
+    }
+    async pumpEvents(running) {
+        const session = running.session;
+        if (!session)
+            return;
+        const { descriptor } = running;
+        try {
+            for await (const event of session.events) {
+                this.forwardEvent(running, event);
+            }
+        }
+        catch (error) {
+            log.error('supervisor: event stream failed', {
+                sessionId: descriptor.id,
+                error: String(error),
+            });
+        }
+        // Stream ended — the agent process is gone.
+        if (running.session !== session)
+            return; // superseded (shouldn't happen in v0)
+        // The process is down, so nothing is billable any more regardless of the
+        // last status we reported.
+        if (running.activeSince !== undefined) {
+            running.activeMs += Date.now() - running.activeSince;
+            delete running.activeSince;
+        }
+        this.clearBudgetTimers(running);
+        // Stale-resume recovery: relaunch once without a resume id.
+        if (running.freshRetry && !running.stopRequested) {
+            const { prompt } = running.freshRetry;
+            delete running.freshRetry;
+            running.freshRetryDone = true;
+            running.descriptor = { ...running.descriptor, providerSessionId: null };
+            running.costBaseUsd = running.costUsd;
+            this.launchAgent(running, prompt, null);
+            return;
+        }
+        // Auth recovery: one relaunch that KEEPS the provider session, so a
+        // credential hiccup does not cost the agent its whole conversation.
+        if (running.authRetry && !running.stopRequested) {
+            const { prompt } = running.authRetry;
+            delete running.authRetry;
+            running.authRetryDone = true;
+            running.costBaseUsd = running.costUsd;
+            this.launchAgent(running, prompt, running.descriptor.providerSessionId);
+            return;
+        }
+        if (running.stopRequested) {
+            // Report before removing from the map — reportStatus records
+            // lastReported on the live entry, and the journal cleanup below
+            // checks it to drop the file for terminal sessions. Skip the STOPPED
+            // frame when a terminal status (e.g. budget FAILED) was already sent.
+            if (!isTerminal(running.lastReported)) {
+                this.reportStatus(descriptor.id, 'STOPPED', {
+                    costUsd: running.costUsd,
+                    activeMs: running.activeMs,
+                });
+            }
+            this.sessions.delete(descriptor.id);
+        }
+        else if ((running.parkRequested || isSettled(running.lastReported)) &&
+            !isTerminal(running.lastReported) &&
+            running.descriptor.providerSessionId) {
+            // Idle process ended (parked or died between turns) — stay resumable.
+            running.session = null;
+            running.parkRequested = false;
+            running.costBaseUsd = running.costUsd; // next process starts from here
+            // Persist the clock: a parked session can sit for hours and the runner
+            // may be restarted before it ever runs again.
+            this.reportStatus(descriptor.id, statusForReport(running), {
+                costUsd: running.costUsd,
+                activeMs: running.activeMs,
+            });
+            // MUST drain before returning. This is the branch parking uses, i.e. the
+            // ordinary way a slot comes free — an early return here left every held
+            // message waiting forever while the runner sat idle (QA-102 MAJOR-1).
+            this.drainSessionsWaitingForCapacity();
+            return;
+        }
+        else if (!isSettled(running.lastReported)) {
+            this.reportStatus(descriptor.id, 'FAILED', {
+                costUsd: running.costUsd,
+                activeMs: running.activeMs,
+                errorMessage: 'Agent process exited unexpectedly',
+            });
+            this.sessions.delete(descriptor.id);
+        }
+        else {
+            this.sessions.delete(descriptor.id);
+        }
+        // Keep the journal while offline: the recorded terminal status is what
+        // reconcile replays after the next reconnect (QA-96 F1).
+        if (this.ws.connected &&
+            running.journal.unacked().length === 0 &&
+            isTerminal(running.lastReported)) {
+            this.journals.closeAndDelete(descriptor.id);
+        }
+        // A resume arrived while this life was winding down — start it now that the
+        // map entry is gone. One place, after every removal path above.
+        if (running.pendingRestart && !this.sessions.has(descriptor.id)) {
+            const next = running.pendingRestart;
+            delete running.pendingRestart;
+            void this.startSession(next).catch((error) => log.error('supervisor: queued resume failed', {
+                sessionId: descriptor.id,
+                error: String(error),
+            }));
+        }
+        // A slot just came free — hand it to whoever was told to wait for one.
+        this.drainSessionsWaitingForCapacity();
+    }
+    /**
+     * Deliver messages that were held because every slot was taken.
+     *
+     * Called whenever an agent process ends. Without it a message typed into a
+     * parked session while the server was full would sit in the queue until the
+     * next reconnect: the user would see their own bubble in the feed and no
+     * answer, which is the worst possible reading of "the server is busy".
+     */
+    drainSessionsWaitingForCapacity() {
+        for (const waiting of this.sessions.values()) {
+            if (waiting.session || waiting.stopRequested || waiting.budgetSpent)
+                continue;
+            if (waiting.pendingMessages.length === 0 || !waiting.worktreePath)
+                continue;
+            if (this.liveSessionCount(waiting.descriptor.id) >= this.maxSessions)
+                return;
+            this.flushPendingMessages(waiting);
+        }
+    }
+    /** The ceiling actually in force: the API's number, lowered by local config. */
+    get maxSessions() {
+        const local = this.opts.maxSessionsLimit;
+        return local === undefined ? this.serverMaxSessions : Math.min(local, this.serverMaxSessions);
+    }
+    /**
+     * Adopt a ceiling announced by the API.
+     *
+     * `undefined` means "this API does not know about the field" — only then do
+     * we fall back to the historical single slot. A number that is merely out of
+     * range is CLAMPED, never treated as absent: silently collapsing a server to
+     * one agent because of a typo in a config field is a much worse failure than
+     * capping it (QA-102 MINOR-5).
+     */
+    static MAX_SESSIONS_HARD_CAP = 64;
+    setMaxSessions(value) {
+        if (value === undefined)
+            return;
+        const next = Math.min(Supervisor.MAX_SESSIONS_HARD_CAP, Math.max(1, Math.floor(value)));
+        if (next === this.serverMaxSessions)
+            return;
+        const raised = next > this.serverMaxSessions;
+        this.serverMaxSessions = next;
+        log.info('supervisor: parallel session ceiling', {
+            fromApi: next,
+            fromConfig: this.opts.maxSessionsLimit ?? null,
+            effective: this.maxSessions,
+        });
+        // Raising the limit is the natural answer to "the runner is busy" — the
+        // messages that were told to wait must go out now, not at the next
+        // process exit (QA-102 MINOR-4).
+        if (raised)
+            this.drainSessionsWaitingForCapacity();
+    }
+    /**
+     * Sessions holding a slot right now. A session already asked to stop or park
+     * does not count: its process is winding down and its `session` handle stays
+     * set until `pumpEvents` sees the stream end — waiting for that would make
+     * parking look like it freed nothing.
+     */
+    liveSessionCount(exceptSessionId) {
+        let count = 0;
+        for (const existing of this.sessions.values()) {
+            if (existing.descriptor.id === exceptSessionId)
+                continue;
+            if (existing.stopRequested || existing.parkRequested || !existing.session)
+                continue;
+            count++;
+        }
+        return count;
+    }
+    /**
+     * Make room for one more agent process.
+     *
+     * Up to `maxSessions` agents run side by side, each in its own worktree. Over
+     * that, idle-but-resumable sessions (REVIEW / WAITING_INPUT) are parked —
+     * their provider session survives on disk and relaunches on the next message,
+     * so parking costs context nothing. Only mid-turn sessions (RUNNING /
+     * WAITING_PERMISSION) genuinely hold a slot; when they fill the ceiling this
+     * returns false and the caller tells the user rather than thrashing.
+     */
+    ensureCapacity(exceptSessionId) {
+        const limit = this.maxSessions;
+        if (this.liveSessionCount(exceptSessionId) < limit)
+            return true;
+        // Park the least recently useful first: a session waiting for a human is a
+        // better candidate than one that just finished a turn, but both are safe.
+        const parkable = [...this.sessions.values()].filter((existing) => existing.descriptor.id !== exceptSessionId &&
+            !existing.stopRequested &&
+            existing.session &&
+            this.isParkable(existing));
+        for (const candidate of parkable) {
+            if (this.liveSessionCount(exceptSessionId) < limit)
+                break;
+            this.park(candidate);
+        }
+        return this.liveSessionCount(exceptSessionId) < limit;
+    }
+    /** Idle after a finished turn — safe to kill the process and resume later. */
+    isParkable(running) {
+        return ((running.lastReported === 'REVIEW' || running.lastReported === 'WAITING_INPUT') &&
+            Boolean(running.descriptor.providerSessionId));
+    }
+    park(running) {
+        if (!running.session)
+            return;
+        running.parkRequested = true;
+        this.sendEvent(running, 'system_note', {
+            text: 'Session parked — the runner switched to another session. Send a message to resume.',
+        });
+        running.session.stop();
+    }
+    forwardEvent(running, event) {
+        const { descriptor } = running;
+        switch (event.type) {
+            case 'provider_session':
+                running.descriptor = { ...descriptor, providerSessionId: event.providerSessionId };
+                this.reportStatus(descriptor.id, statusForReport(running), {
+                    providerSessionId: event.providerSessionId,
+                });
+                return;
+            case 'cost':
+                // event.costUsd is the live process's running total; the session
+                // total also includes what earlier processes spent (park/restart).
+                running.costUsd = Math.max(running.costUsd, running.costBaseUsd + event.costUsd);
+                this.sendEvent(running, 'cost', {
+                    costUsd: running.costUsd,
+                    numTurns: event.numTurns,
+                    durationMs: event.durationMs,
+                });
+                return;
+            case 'turn_end': {
+                this.sendEvent(running, 'turn_end', { ok: event.ok, errorMessage: event.errorMessage });
+                // Turn end is the natural checkpoint for the budget clock: the slice
+                // just closed, so this is the moment the API can persist it. Without a
+                // report here `agentActiveMs` stayed 0 and every restart or resume
+                // silently handed the session a full fresh budget.
+                if (event.ok) {
+                    const next = descriptor.kind === 'CHAT' ? 'WAITING_INPUT' : 'REVIEW';
+                    this.reportStatus(descriptor.id, next, {
+                        costUsd: running.costUsd,
+                        activeMs: Supervisor.spentMs(running),
+                    });
+                }
+                else {
+                    this.reportStatus(descriptor.id, 'FAILED', {
+                        costUsd: running.costUsd,
+                        activeMs: Supervisor.spentMs(running),
+                        errorMessage: event.errorMessage ?? 'Agent turn failed',
+                    });
+                }
+                return;
+            }
+            case 'error':
+                // A provider session the CLI no longer knows (state wiped, expired
+                // history): don't fail the session — relaunch it fresh once with the
+                // same prompt, the git worktree still holds all the work.
+                if (event.code === 'resume_failed' && !running.freshRetryDone) {
+                    running.freshRetry = { prompt: running.lastPrompt };
+                    this.sendEvent(running, 'notice', {
+                        level: 'warn',
+                        text: 'Previous agent context was lost — starting a fresh conversation in the same branch.',
+                    });
+                    return;
+                }
+                // A credential that went missing under the agent is usually repairable
+                // (the adapter re-asserts its home on start). Give it exactly one go
+                // before telling the user their login is broken — and keep the provider
+                // session, so nothing is lost if the retry works.
+                // No `lastPrompt` guard: a free CHAT session boots with an empty prompt
+                // and is exactly the case that hits an auth failure at startup, so
+                // requiring one excluded the sessions that need the retry most.
+                if (isAuthCode(event.code) && !running.authRetryDone) {
+                    running.authRetry = { prompt: running.lastPrompt };
+                    this.sendEvent(running, 'notice', {
+                        level: 'warn',
+                        text: 'The agent could not use its sign-in — retrying once.',
+                    });
+                    return;
+                }
+                // Forward the code: the API stores the payload as-is, so the dashboard
+                // can offer "Sign in" instead of a dead error card.
+                this.sendEvent(running, 'error', {
+                    message: event.message,
+                    ...(event.code ? { code: event.code } : {}),
+                });
+                this.reportStatus(descriptor.id, 'FAILED', {
+                    costUsd: running.costUsd,
+                    activeMs: Supervisor.spentMs(running),
+                    errorMessage: event.message,
+                });
+                return;
+            case 'permission':
+                this.sendEvent(running, 'permission', {
+                    requestId: event.requestId,
+                    toolName: event.toolName,
+                    title: event.title,
+                    description: event.description,
+                    input: event.input,
+                    // Plan approvals carry the plan itself — the dashboard renders it as
+                    // a plan card instead of a raw tool prompt.
+                    plan: event.plan,
+                });
+                return;
+            case 'permission_resolved':
+                this.sendEvent(running, 'permission_resolved', {
+                    requestId: event.requestId,
+                    allow: event.allow,
+                    source: event.source,
+                    reason: event.reason,
+                });
+                if (event.source === 'user' &&
+                    event.allow &&
+                    running.lastReported === 'WAITING_PERMISSION') {
+                    running.lastReported = 'RUNNING';
+                    this.syncBudgetClock(running); // the human answered — bill again
+                }
+                return;
+            case 'message':
+                this.sendEvent(running, 'message', { role: event.role, text: event.text });
+                return;
+            case 'thinking':
+                this.sendEvent(running, 'thinking', { text: event.text });
+                return;
+            case 'question':
+                // The API maps `question` to WAITING_INPUT and notifies the user. The
+                // runner used to keep believing it was RUNNING — which disagreed with
+                // the API and, worse, kept the time budget running while the agent sat
+                // waiting for an answer.
+                this.sendEvent(running, 'question', { text: event.text, options: event.options });
+                running.lastReported = 'WAITING_INPUT';
+                this.syncBudgetClock(running);
+                return;
+            case 'capabilities':
+                this.sendEvent(running, 'capabilities', {
+                    ...event.capabilities,
+                    currentMode: running.mode,
+                    ...(running.model ? { currentModel: running.model } : {}),
+                });
+                return;
+            case 'settings':
+                if (event.mode)
+                    running.mode = event.mode;
+                if (event.model)
+                    running.model = event.model;
+                // null = the agent dropped the pinned level (model without it) — the
+                // API must clear its column, so the value is forwarded as-is.
+                if (event.effort === null)
+                    delete running.effort;
+                else if (event.effort)
+                    running.effort = event.effort;
+                this.sendEvent(running, 'settings', {
+                    model: event.model,
+                    mode: event.mode,
+                    ...(event.effort === undefined ? {} : { effort: event.effort }),
+                });
+                return;
+            case 'context_usage':
+                this.sendEvent(running, 'context_usage', {
+                    usedTokens: event.usedTokens,
+                    maxTokens: event.maxTokens,
+                });
+                return;
+            case 'notice': {
+                // Only adapter notices are de-duplicated here. The supervisor's own
+                // notices (turn interrupted, session parked, budget warnings) go
+                // through sendEvent directly and are meant to repeat.
+                const key = `${event.level}:${event.text}`;
+                running.seenNotices ??= new Set();
+                if (running.seenNotices.has(key))
+                    return;
+                running.seenNotices.add(key);
+                this.sendEvent(running, 'notice', { level: event.level, text: event.text });
+                return;
+            }
+            case 'tool':
+                this.sendEvent(running, 'tool', {
+                    phase: event.phase,
+                    name: event.name,
+                    toolUseId: event.toolUseId,
+                    detail: event.detail,
+                    text: event.text,
+                });
+                return;
+            default:
+                return;
+        }
+    }
+    async onUserMessage(sessionId, text, attachments) {
+        const running = this.sessions.get(sessionId);
+        if (!running) {
+            // The API believes this session lives here but the runner lost track of
+            // it (restart with a truncated reconnect list, state wipe). Ask for the
+            // descriptor and hold the message until it arrives (QA-99 MINOR-2)
+            // instead of dropping it silently.
+            log.warn('supervisor: message for unknown session — requesting descriptor', { sessionId });
+            const queued = this.orphanMessages.get(sessionId) ?? [];
+            queued.push({ text, ...(attachments?.length ? { attachments } : {}) });
+            this.orphanMessages.set(sessionId, queued.slice(-Supervisor.ORPHAN_MESSAGE_CAP));
+            this.ws.send({ type: 'session_unknown', sessionId });
+            return;
+        }
+        // The feed shows what the USER wrote plus the files they picked — not the
+        // composed prompt with workspace paths, which is an implementation detail.
+        this.sendEvent(running, 'message', {
+            role: 'user',
+            text,
+            ...(attachments?.length ? { attachments } : {}),
+        });
+        if (!running.worktreePath) {
+            // Session is still being prepared — deliver after launch (QA-96 F3).
+            // Attachments travel as metadata and are downloaded at delivery time,
+            // which is the first moment the worktree is guaranteed to exist.
+            running.pendingMessages.push(running.journal.appendPending(text, attachments));
+            return;
+        }
+        this.enqueueDelivery(running, async () => {
+            const composed = await this.materializeAttachments(running, text, attachments);
+            if (this.isStale(running)) {
+                // The session ended while the files downloaded. Park the message on
+                // disk rather than dropping it — «Продолжить» carries it to the agent.
+                running.journal.appendPending(text, attachments);
+                log.warn('supervisor: session ended before the message could be delivered', {
+                    sessionId: running.descriptor.id,
+                });
+                return;
+            }
+            this.deliverMessage(running, composed);
+        });
+    }
+    /**
+     * Run delivery work for one session, strictly after whatever is already
+     * queued for it. Order is the whole point: two messages typed seconds apart
+     * must reach the agent in the order they were typed, however long the first
+     * one's attachments take to download.
+     */
+    enqueueDelivery(running, work) {
+        const previous = running.deliverChain ?? Promise.resolve();
+        running.deliverChain = previous
+            .catch(() => undefined)
+            .then(work)
+            .catch((error) => log.error('supervisor: message delivery failed', {
+            sessionId: running.descriptor.id,
+            error: String(error),
+        }));
+    }
+    /** Did this session go away (stop, teardown, resume) while we were awaiting? */
+    isStale(running) {
+        return running.stopRequested || this.sessions.get(running.descriptor.id) !== running;
+    }
+    /**
+     * Bring the user's files onto this machine and fold their paths into the
+     * prompt. Returns the text unchanged when there is nothing to fetch.
+     *
+     * A failure here never costs the message: the agent still gets what the user
+     * typed, plus a note naming the files that did not make it.
+     */
+    async materializeAttachments(running, text, attachments) {
+        if (!attachments?.length || !running.worktreePath)
+            return text;
+        const { apiUrl, runnerToken } = this.opts;
+        if (!apiUrl || !runnerToken) {
+            this.sendEvent(running, 'notice', {
+                level: 'warn',
+                text: 'This runner cannot fetch attachments — update it to the current version.',
+            });
+            return text;
+        }
+        const { saved, failed } = await saveAttachments({
+            worktreePath: running.worktreePath,
+            apiUrl,
+            token: runnerToken,
+            attachments,
+        });
+        if (failed.length > 0) {
+            this.sendEvent(running, 'notice', {
+                level: 'warn',
+                text: `Could not download ${failed.length === 1 ? 'the attachment' : 'some attachments'}: ${failed.join(', ')}. The message was sent without ${failed.length === 1 ? 'it' : 'them'}.`,
+            });
+        }
+        return composeMessageWithAttachments(text, saved);
+    }
+    /**
+     * Hand a message to the agent, or hold it if there is nowhere to put it yet.
+     *
+     * `held` carries the journal records this text was built from, so a delivery
+     * resolves them and a refusal puts exactly those records back in the queue —
+     * the message is retired from disk only once an agent has it.
+     */
+    deliverMessage(running, text, held = []) {
+        // Older instructions are already waiting: send them together, in order.
+        // Without this a message that CAN go now jumps the queue — and the ones it
+        // jumped are stranded, because the drain only runs when a process exits
+        // (QA-103 MINOR-9). They would then be replayed at the next daemon start,
+        // or lost with the journal if the session ended first.
+        if (held.length === 0 && running.pendingMessages.length > 0) {
+            // Routed through the flush rather than joined here: a queued record may
+            // carry files that still have to be downloaded, and joining raw texts
+            // would deliver the words while silently dropping the screenshot
+            // (QA-104 MAJOR-4). `text` is already composed by the caller, so it
+            // needs no attachments of its own.
+            running.pendingMessages.push(running.journal.appendPending(text));
+            this.flushPendingMessages(running);
+            return;
+        }
+        const settle = () => {
+            for (const record of held)
+                running.journal.resolvePending(record.id);
+        };
+        if (running.session) {
+            running.session.send(text);
+            settle();
+            this.reportStatus(running.descriptor.id, 'RUNNING', {});
+            return;
+        }
+        // Parked session: the follow-up message becomes the resume prompt.
+        if (!this.ensureCapacity(running.descriptor.id)) {
+            this.sendEvent(running, 'system_note', {
+                text: this.maxSessions === 1
+                    ? 'The runner is busy with another session — this one continues as soon as it finishes its turn.'
+                    : `The runner is busy with ${this.maxSessions} other sessions — this one continues as soon as one of them finishes its turn.`,
+            });
+            // The message is already in the feed; keep it so the resume actually
+            // carries it once a slot frees up, instead of the user's instruction
+            // vanishing into a system note. On disk, too — the wait can outlive the
+            // daemon (session 9).
+            running.pendingMessages.push(...(held.length > 0 ? held : [running.journal.appendPending(text)]));
+            return;
+        }
+        if (this.launchAgent(running, text, running.descriptor.providerSessionId)) {
+            settle();
+            return;
+        }
+        // The agent did not start (an exhausted budget is the only way here). The
+        // instruction stays on disk, so «Продолжить» — which is what raises the
+        // budget — carries it to the agent instead of dropping it.
+        running.pendingMessages.push(...(held.length > 0 ? held : [running.journal.appendPending(text)]));
+    }
+    /**
+     * Deliver messages that raced session start (already journaled).
+     *
+     * Async since session 10: a held message may carry files, and this is the
+     * first point at which the worktree they belong in certainly exists. Callers
+     * fire and forget — a failure here is logged, and the records stay on disk.
+     */
+    flushPendingMessages(running) {
+        const pending = running.pendingMessages.splice(0);
+        if (pending.length === 0)
+            return;
+        this.enqueueDelivery(running, async () => {
+            const parts = [];
+            try {
+                for (const record of pending) {
+                    parts.push(await this.materializeAttachments(running, record.text, record.attachments));
+                }
+            }
+            catch (error) {
+                // Back on the queue: the records are still on disk, and the next drain
+                // (or the next restart) retries them.
+                running.pendingMessages.unshift(...pending);
+                throw error;
+            }
+            if (this.isStale(running)) {
+                // Left unresolved in the journal on purpose — a resumed session picks
+                // them back up instead of starting an agent for a session that ended
+                // while the files were downloading (QA-104 MAJOR-3).
+                log.warn('supervisor: session ended before held messages could be delivered', {
+                    sessionId: running.descriptor.id,
+                    held: pending.length,
+                });
+                return;
+            }
+            this.deliverMessage(running, parts.join('\n\n'), pending);
+        });
+    }
+    /** Stop the current turn without ending the session (VS-Code-style Stop). */
+    async interruptSession(sessionId) {
+        const running = this.sessions.get(sessionId);
+        if (!running?.session)
+            return;
+        await running.session.interrupt();
+        this.sendEvent(running, 'notice', { level: 'info', text: 'Turn interrupted by the user' });
+        const next = running.descriptor.kind === 'CHAT' ? 'WAITING_INPUT' : 'REVIEW';
+        this.reportStatus(sessionId, next, {
+            costUsd: running.costUsd,
+            activeMs: Supervisor.spentMs(running),
+        });
+    }
+    /** Live model / interaction-mode switch (persisted for the next relaunch). */
+    async applySettings(sessionId, model, mode, effort) {
+        const running = this.sessions.get(sessionId);
+        if (!running)
+            return;
+        // Remember first: a parked session applies them on its next launch.
+        if (model)
+            running.model = model;
+        if (mode)
+            running.mode = mode;
+        if (effort === null)
+            delete running.effort;
+        else if (effort)
+            running.effort = effort;
+        if (!running.session) {
+            this.sendEvent(running, 'settings', { model, mode, effort });
+            return;
+        }
+        try {
+            // Model first: switching models can invalidate the picked effort, and
+            // the adapter drops it in that case — applying effort after lets an
+            // explicit pick win.
+            if (model)
+                await running.session.setModel(model);
+            if (effort !== undefined)
+                await running.session.setEffort(effort);
+            if (mode)
+                await running.session.setMode(mode);
+        }
+        catch (error) {
+            this.sendEvent(running, 'notice', {
+                level: 'warn',
+                text: `Could not apply the new settings to the running agent: ${maskSecretText(error)}`,
+            });
+        }
+    }
+    stopSession(sessionId) {
+        const running = this.sessions.get(sessionId);
+        if (!running)
+            return;
+        running.stopRequested = true;
+        this.clearBudgetTimers(running);
+        if (running.session) {
+            running.session.stop(); // pumpEvents finishes the cleanup
+        }
+        else {
+            this.reportStatus(sessionId, 'STOPPED', { activeMs: running.activeMs });
+            this.sessions.delete(sessionId);
+            if (this.ws.connected && running.journal.unacked().length === 0) {
+                this.journals.closeAndDelete(sessionId);
+            }
+        }
+    }
+    // ─── Reconciliation (hello_ack) ────────────────────────────────────
+    async reconcile(descriptors) {
+        // Sessions the API no longer considers live (e.g. stopped from the
+        // dashboard while this runner was offline) must not keep an agent process
+        // running and holding the single runner slot (QA-99 MAJOR-2).
+        const known = new Set(descriptors.map((d) => d.id));
+        for (const [sessionId, running] of [...this.sessions]) {
+            if (known.has(sessionId))
+                continue;
+            log.warn('supervisor: session gone server-side — tearing it down', { sessionId });
+            running.stopRequested = true;
+            this.clearBudgetTimers(running);
+            if (running.session) {
+                running.session.stop(); // pumpEvents finishes the cleanup
+            }
+            else {
+                this.sessions.delete(sessionId);
+            }
+        }
+        // Redeliver unacked events for every persisted journal (at-least-once).
+        for (const sessionId of this.journals.persistedSessionIds()) {
+            const journal = this.journals.open(sessionId);
+            for (const event of journal.unacked()) {
+                this.ws.send({
+                    type: 'event',
+                    sessionId,
+                    seq: event.seq,
+                    eventType: event.eventType,
+                    payload: event.payload,
+                });
+            }
+        }
+        for (const descriptor of descriptors) {
+            // Live local session: statuses are fire-and-forget on the wire, so a
+            // status reached while the WS was down is re-reported here (QA-96 F1).
+            const tracked = this.sessions.get(descriptor.id);
+            if (tracked) {
+                // The session was resumed server-side while this runner was offline, and
+                // the local copy is that same work. Adopt the new epoch BEFORE reporting:
+                // the API drops frames stamped with an older one, so keeping ours would
+                // make every status this session ever sends invisible — it would sit in
+                // "waiting" while the agent worked.
+                if (descriptor.epoch > tracked.epoch) {
+                    tracked.epoch = descriptor.epoch;
+                    tracked.descriptor = { ...tracked.descriptor, epoch: descriptor.epoch };
+                }
+                this.reportStatus(descriptor.id, statusForReport(tracked), {
+                    costUsd: tracked.costUsd,
+                    ...(tracked.branch ? { branch: tracked.branch } : {}),
+                    ...(tracked.worktreePath ? { worktreePath: tracked.worktreePath } : {}),
+                    ...(tracked.descriptor.providerSessionId
+                        ? { providerSessionId: tracked.descriptor.providerSessionId }
+                        : {}),
+                });
+                continue;
+            }
+            // Session that went terminal while we were offline: the journal keeps
+            // the last reported status — replay it instead of resurrecting the
+            // session as resumable (QA-96 F1).
+            if (this.journals.exists(descriptor.id)) {
+                const journal = this.journals.open(descriptor.id);
+                const last = journal.lastStatus;
+                // Only replay a terminal status from THIS life of the session. A
+                // resumed session carries a higher epoch, and replaying the FAILED it
+                // was resumed from would kill it again the moment the runner reconnects.
+                if (last &&
+                    isTerminal(last.status) &&
+                    (last.epoch ?? 0) >= descriptor.epoch) {
+                    this.ws.send({
+                        type: 'session_status',
+                        sessionId: descriptor.id,
+                        status: last.status,
+                        ...(last.extra ?? {}),
+                        // Guarded above to be >= the descriptor's epoch, so the API keeps it.
+                        ...(last.epoch === undefined ? {} : { epoch: last.epoch }),
+                    });
+                    if (journal.unacked().length === 0) {
+                        this.journals.closeAndDelete(descriptor.id);
+                    }
+                    continue;
+                }
+            }
+            if (descriptor.status === 'STARTING') {
+                await this.startSession(descriptor);
+            }
+            else if (descriptor.providerSessionId) {
+                // Runner restarted mid-session. The provider session is resumable —
+                // park it until the user sends the next instruction. The map entry is
+                // registered BEFORE the worktree await so a racing message is
+                // buffered instead of dropped (QA-96 F3).
+                const running = {
+                    descriptor,
+                    journal: this.journals.open(descriptor.id),
+                    session: null,
+                    lastReported: descriptor.status === 'REVIEW' ? 'REVIEW' : 'WAITING_INPUT',
+                    costUsd: descriptor.costUsd,
+                    costBaseUsd: descriptor.costUsd,
+                    stopRequested: false,
+                    parkRequested: false,
+                    pendingMessages: [],
+                    // Seed from the API, not 0: a runner restart used to hand the session
+                    // a full fresh budget silently.
+                    activeMs: descriptor.activeMsBase,
+                    extraBudgetMinutes: descriptor.extraBudgetMinutes,
+                    epoch: descriptor.epoch,
+                    mode: descriptor.mode,
+                    ...(descriptor.model ? { model: descriptor.model } : {}),
+                    ...(descriptor.effort ? { effort: descriptor.effort } : {}),
+                    lastPrompt: '',
+                };
+                running.journal.ensureSeqAbove(descriptor.lastSeq);
+                // Anything the API handed us before the daemon stopped (session 9).
+                running.pendingMessages.push(...running.journal.pending());
+                this.sessions.set(descriptor.id, running);
+                try {
+                    const { branch, worktreePath } = await this.withRepoLockFor(descriptor.workspace.path, () => ensureSessionWorktree(descriptor.workspace.path, descriptor.id, descriptor.branchHint, { requireExistingBranch: hasWorkToResume(descriptor) }));
+                    running.branch = branch;
+                    running.worktreePath = worktreePath;
+                }
+                catch (error) {
+                    this.reportStatus(descriptor.id, 'FAILED', {
+                        errorMessage: `Failed to restore session worktree: ${String(error instanceof Error ? error.message : error).slice(0, 500)}`,
+                    });
+                    this.sessions.delete(descriptor.id);
+                    continue;
+                }
+                this.sendEvent(running, 'system_note', {
+                    text: 'Runner reconnected. The session was resumed — send a message to continue.',
+                });
+                // REVIEW stays REVIEW (WAITING_INPUT is not reachable from it);
+                // mid-turn statuses are downgraded to "waiting for the user".
+                if (descriptor.status !== 'REVIEW') {
+                    this.reportStatus(descriptor.id, 'WAITING_INPUT', {});
+                }
+                this.flushPendingMessages(running);
+            }
+            else if (descriptor.status === 'WAITING_INPUT') {
+                // A session that never had a turn (a free session still waiting for
+                // its first message) has nothing to resume — just bring the agent back
+                // up and keep waiting, instead of failing the session.
+                await this.startSession({ ...descriptor, status: 'STARTING', prompt: '' });
+            }
+            else {
+                this.reportStatus(descriptor.id, 'FAILED', {
+                    errorMessage: 'Runner restarted and this session cannot be resumed',
+                });
+            }
+        }
+        // Redelivery is done — anything still on disk from long-finished sessions
+        // is dead weight (QA-99 MINOR-6).
+        this.pruneJournals();
+    }
+    /**
+     * Housekeeping for the journal directory. Safe to call any time: live
+     * sessions are skipped and a journal still holding unacked events survives
+     * until the hard expiry.
+     */
+    pruneJournals() {
+        try {
+            const removed = this.journals.prune({
+                maxAgeMs: Supervisor.JOURNAL_TTL_MS,
+                hardMaxAgeMs: Supervisor.JOURNAL_HARD_TTL_MS,
+                skip: new Set(this.sessions.keys()),
+            });
+            if (removed.length) {
+                log.info('supervisor: pruned stale journals', { count: removed.length });
+            }
+        }
+        catch (error) {
+            log.warn('supervisor: journal prune failed', { error: String(error) });
+        }
+    }
+    // ─── Commands ──────────────────────────────────────────────────────
+    async runCommand(frame) {
+        const reply = (result) => this.ws.send({ type: 'command_result', requestId: frame.requestId, ...result });
+        try {
+            switch (frame.name) {
+                case 'validate_path': {
+                    const path = typeof frame.args?.['path'] === 'string' ? frame.args['path'] : null;
+                    if (!path)
+                        return void reply({ ok: false, error: 'path argument is required' });
+                    const validation = await validateWorkspacePath(path);
+                    return void reply({
+                        ok: validation.ok,
+                        result: validation,
+                        ...(validation.ok ? {} : { error: validation.error }),
+                    });
+                }
+                case 'clean': {
+                    const sessionId = frame.sessionId;
+                    if (!sessionId)
+                        return void reply({ ok: false, error: 'sessionId is required' });
+                    const running = this.sessions.get(sessionId);
+                    if (running)
+                        return void reply({ ok: false, error: 'Session is still active — stop it first' });
+                    // `worktree remove` also mutates the shared .git registration.
+                    await this.withRepoLockFor(sessionWorktreePath(sessionId), () => removeSessionWorktree(sessionId));
+                    return void reply({ ok: true, result: { removed: true } });
+                }
+                case 'purge_session': {
+                    // The session row is already gone from the API. Everything this
+                    // runner still holds for it on disk goes now.
+                    const sessionId = frame.sessionId;
+                    if (!sessionId)
+                        return void reply({ ok: false, error: 'sessionId is required' });
+                    if (this.sessions.get(sessionId)) {
+                        return void reply({ ok: false, error: 'Session is still active — stop it first' });
+                    }
+                    const branch = str(frame.args?.['branch']);
+                    const workspacePath = str(frame.args?.['workspacePath']);
+                    // Only ever true when the API confirmed the work is already applied to
+                    // the base branch — an un-applied branch is the user's only copy of
+                    // what the agent wrote.
+                    const deleteBranch = frame.args?.['deleteBranch'] === true;
+                    const result = await this.withRepoLockFor(workspacePath ?? sessionWorktreePath(sessionId), async () => {
+                        await removeSessionWorktree(sessionId);
+                        if (!deleteBranch || !branch || !workspacePath)
+                            return { branchDeleted: false };
+                        try {
+                            await deleteSessionBranch(workspacePath, branch);
+                            return { branchDeleted: true };
+                        }
+                        catch (error) {
+                            // A branch we could not drop is a leftover, not a failed purge.
+                            return { branchDeleted: false, branchError: maskSecretText(error) };
+                        }
+                    });
+                    this.journals.closeAndDelete(sessionId);
+                    this.orphanMessages.delete(sessionId);
+                    return void reply({ ok: true, result: { removed: true, ...result } });
+                }
+                case 'reset_workspace':
+                    return void reply({
+                        ok: false,
+                        error: 'reset_workspace is not supported by this runner version',
+                    });
+                case 'git_status': {
+                    const paths = gitCommandPaths(frame.args);
+                    if (!paths)
+                        return void reply({
+                            ok: false,
+                            error: 'worktreePath/workspacePath/branch are required',
+                        });
+                    return void reply({
+                        ok: true,
+                        result: await gitStatus(paths.worktreePath, paths.workspacePath, paths.branch),
+                    });
+                }
+                case 'git_diff': {
+                    const paths = gitCommandPaths(frame.args);
+                    const filePath = str(frame.args?.['path']);
+                    if (!paths || !filePath) {
+                        return void reply({
+                            ok: false,
+                            error: 'worktreePath/workspacePath/branch/path are required',
+                        });
+                    }
+                    return void reply({
+                        ok: true,
+                        result: await gitDiff(paths.worktreePath, paths.workspacePath, paths.branch, filePath),
+                    });
+                }
+                // Session 11: history. Read-only, so no repo lock and no busy check —
+                // `git log`/`git show` never touch the index, and refusing to show the
+                // history while the agent happens to be mid-turn would make the panel
+                // useless exactly when it is most interesting.
+                case 'git_log': {
+                    const workspacePath = str(frame.args?.['workspacePath']);
+                    const branch = str(frame.args?.['branch']);
+                    if (!workspacePath || !branch) {
+                        return void reply({ ok: false, error: 'workspacePath and branch are required' });
+                    }
+                    const scope = logScope(frame.args?.['scope']);
+                    const limit = num(frame.args?.['limit']);
+                    const skip = num(frame.args?.['skip']);
+                    return void reply({
+                        ok: true,
+                        result: await gitLog({
+                            workspacePath,
+                            branch,
+                            ...(scope ? { scope } : {}),
+                            ...(limit !== null ? { limit } : {}),
+                            ...(skip !== null ? { skip } : {}),
+                        }),
+                    });
+                }
+                case 'git_show': {
+                    const workspacePath = str(frame.args?.['workspacePath']);
+                    const sha = str(frame.args?.['sha']);
+                    if (!workspacePath || !sha) {
+                        return void reply({ ok: false, error: 'workspacePath and sha are required' });
+                    }
+                    const filePath = str(frame.args?.['path']);
+                    const showBranch = str(frame.args?.['branch']);
+                    return void reply({
+                        ok: true,
+                        result: await gitShow(workspacePath, sha, filePath ?? undefined, showBranch ?? undefined),
+                    });
+                }
+                case 'git_commit': {
+                    const worktreePath = str(frame.args?.['worktreePath']);
+                    const message = str(frame.args?.['message']);
+                    if (!worktreePath || !message) {
+                        return void reply({ ok: false, error: 'worktreePath and message are required' });
+                    }
+                    if (this.isWorktreeBusy(worktreePath)) {
+                        return void reply({
+                            ok: false,
+                            error: 'The agent is still working — wait for the turn to finish',
+                        });
+                    }
+                    return void reply({
+                        ok: true,
+                        result: await this.withRepoLockFor(worktreePath, () => gitCommit(worktreePath, message)),
+                    });
+                }
+                case 'apply_session': {
+                    const paths = gitCommandPaths(frame.args);
+                    const message = str(frame.args?.['message']);
+                    if (!paths || !message) {
+                        return void reply({
+                            ok: false,
+                            error: 'worktreePath/workspacePath/branch/message are required',
+                        });
+                    }
+                    if (this.isWorktreeBusy(paths.worktreePath)) {
+                        return void reply({
+                            ok: false,
+                            error: 'The agent is still working — wait for the turn to finish',
+                        });
+                    }
+                    const applied = await this.withRepoLockFor(paths.workspacePath, () => applySession(paths.workspacePath, paths.worktreePath, paths.branch, message));
+                    return void reply(applied.applied || applied.conflict
+                        ? { ok: true, result: applied }
+                        : { ok: false, error: applied.error ?? 'Apply failed', result: applied });
+                }
+                case 'revert_apply': {
+                    const workspacePath = str(frame.args?.['workspacePath']);
+                    const commitSha = str(frame.args?.['commitSha']);
+                    if (!workspacePath || !commitSha) {
+                        return void reply({ ok: false, error: 'workspacePath and commitSha are required' });
+                    }
+                    const reverted = await this.withRepoLockFor(workspacePath, () => revertApply(workspacePath, commitSha));
+                    return void reply(reverted.reverted || reverted.conflict
+                        ? { ok: true, result: reverted }
+                        : { ok: false, error: reverted.error ?? 'Revert failed', result: reverted });
+                }
+                case 'fs_view': {
+                    const root = str(frame.args?.['root']);
+                    if (!root)
+                        return void reply({ ok: false, error: 'root argument is required' });
+                    return void reply({ ok: true, result: fsView(root, str(frame.args?.['path']) ?? '.') });
+                }
+                case 'self_update': {
+                    // Everything that can refuse this lives in self-update.ts; here we
+                    // only make sure the answer is on the wire BEFORE the process goes
+                    // away, otherwise the dashboard would show a timeout for an update
+                    // that in fact succeeded.
+                    const tarballUrl = str(frame.args?.['tarballUrl']);
+                    if (!tarballUrl)
+                        return void reply({ ok: false, error: 'tarballUrl is required' });
+                    if (!this.opts.apiUrl) {
+                        return void reply({ ok: false, error: 'This runner has no API URL configured' });
+                    }
+                    // Second line of defence behind the API's per-server lock: two
+                    // overlapping `npm install -g` into the same prefix is not something
+                    // to leave to chance on someone else's machine.
+                    if (this.selfUpdateInFlight) {
+                        return void reply({ ok: false, error: 'An update is already running' });
+                    }
+                    this.selfUpdateInFlight = true;
+                    const run = this.opts.selfUpdate ?? selfUpdate;
+                    let outcome;
+                    try {
+                        outcome = await run({ tarballUrl, apiUrl: this.opts.apiUrl });
+                    }
+                    catch (error) {
+                        // A failed update must be retryable without restarting the daemon.
+                        this.selfUpdateInFlight = false;
+                        throw error;
+                    }
+                    // Deliberately NOT cleared on success: the process only exits ~1.5s
+                    // after this reply (the frame has to leave the socket first), and the
+                    // API releases its own lock the moment the reply lands. Clearing here
+                    // left a window in which a second press started an `npm install -g`
+                    // that systemd then killed mid-flight (QA-103 MINOR-8).
+                    this.selfUpdateInFlight = outcome.ok && outcome.restart;
+                    reply({
+                        ok: outcome.ok,
+                        result: outcome,
+                        ...(outcome.ok ? {} : { error: outcome.detail ?? 'Update failed' }),
+                    });
+                    if (outcome.ok && outcome.restart)
+                        this.opts.onRestartRequested?.(outcome);
+                    return;
+                }
+                case 'auth_status':
+                    return void reply({ ok: true, result: await agentAuthStatuses() });
+                case 'login_start': {
+                    const agent = relayAgent(frame.args?.['agent']);
+                    if (!agent)
+                        return void reply({ ok: false, error: 'agent must be claude or codex' });
+                    return void reply({ ok: true, result: await this.authRelay.start(agent) });
+                }
+                case 'login_code': {
+                    const agent = relayAgent(frame.args?.['agent']);
+                    const code = str(frame.args?.['code']);
+                    if (!agent || !code)
+                        return void reply({ ok: false, error: 'agent and code are required' });
+                    const result = await this.authRelay.submitCode(agent, code);
+                    return void reply({
+                        ok: result.ok,
+                        result,
+                        ...(result.ok ? {} : { error: result.detail ?? 'Login failed' }),
+                    });
+                }
+                default:
+                    return void reply({ ok: false, error: `Unknown command` });
+            }
+        }
+        catch (error) {
+            reply({ ok: false, error: maskSecretText(error) });
+        }
+    }
+    /**
+     * Serialise commands that mutate the shared workspace repo. Two sessions of
+     * one workspace can hit «Применить» at the same moment; interleaved
+     * `merge --squash` + `commit` would land both change sets in one commit and
+     * mark the other session failed (QA-99 MAJOR-1).
+     */
+    withRepoLock(repoKey, fn) {
+        const previous = this.repoLocks.get(repoKey) ?? Promise.resolve();
+        const run = previous.catch(() => undefined).then(fn);
+        const tail = run.catch(() => undefined);
+        this.repoLocks.set(repoKey, tail);
+        void tail.then(() => {
+            if (this.repoLocks.get(repoKey) === tail)
+                this.repoLocks.delete(repoKey);
+        });
+        return run;
+    }
+    /**
+     * Same lock, keyed by the shared repository rather than by whichever path the
+     * caller happened to have. A worktree commit and a workspace squash-merge
+     * touch one repo, so they must take one key (see `repoKeyFor`).
+     */
+    async withRepoLockFor(pathInsideRepo, fn) {
+        return this.withRepoLock(await repoKeyFor(pathInsideRepo), fn);
+    }
+    /** A session actively mid-turn in this worktree — git writes must wait. */
+    isWorktreeBusy(worktreePath) {
+        for (const running of this.sessions.values()) {
+            if (running.worktreePath !== worktreePath || !running.session)
+                continue;
+            if (running.lastReported === 'STARTING' ||
+                running.lastReported === 'RUNNING' ||
+                running.lastReported === 'WAITING_PERMISSION') {
+                return true;
+            }
+        }
+        return false;
+    }
+    // ─── Outbound helpers ──────────────────────────────────────────────
+    // Hard cap far below the API's 128KB Zod limit — an oversized payload would
+    // be rejected forever and wedge the journal (QA-96 F2).
+    static EVENT_PAYLOAD_CAP = 100_000;
+    sendEvent(running, eventType, payload) {
+        let compact = Object.fromEntries(Object.entries(maskSecrets(payload)).filter(([, v]) => v !== undefined));
+        if (JSON.stringify(compact).length > Supervisor.EVENT_PAYLOAD_CAP) {
+            log.warn('supervisor: event payload over cap, stubbing', {
+                sessionId: running.descriptor.id,
+                eventType,
+            });
+            compact = { truncated: true, note: 'payload exceeded the event size cap' };
+        }
+        const event = running.journal.append(eventType, compact);
+        this.ws.send({
+            type: 'event',
+            sessionId: running.descriptor.id,
+            seq: event.seq,
+            eventType,
+            payload: event.payload,
+        });
+        if (eventType === 'permission') {
+            // The API infers WAITING_PERMISSION from the event itself, so this never
+            // goes through reportStatus — but the budget clock still has to stop, or
+            // an ask-mode session bills every second the human spends reading the card.
+            running.lastReported = 'WAITING_PERMISSION';
+            this.syncBudgetClock(running);
+        }
+    }
+    reportStatus(sessionId, status, extra) {
+        const running = this.sessions.get(sessionId);
+        if (running) {
+            running.lastReported = status;
+            this.syncBudgetClock(running);
+        }
+        const compact = maskSecrets(Object.fromEntries(Object.entries(extra).filter(([, v]) => v !== undefined)));
+        // Journal the latest status for replay after a reconnect (QA-96 F1) —
+        // only for tracked sessions, so one-shot failure reports don't leave
+        // orphan journal files behind. The epoch stamp keeps a previous life's
+        // terminal status from being replayed over a resumed session.
+        running?.journal.recordStatus(status, compact, running.epoch);
+        // Stamp the life this status belongs to (session 8). The API drops a frame
+        // whose epoch is older than the session's current one, which closes the
+        // «Стоп» ↔ «Продолжить» window: the dying process's STOPPED can no longer
+        // land on the session that was picked back up a moment earlier.
+        this.ws.send({
+            type: 'session_status',
+            sessionId,
+            status,
+            ...compact,
+            ...(running ? { epoch: running.epoch } : {}),
+        });
+    }
+    /** Graceful daemon shutdown: kill agents, keep sessions resumable server-side. */
+    shutdown() {
+        this.authRelay.cancel();
+        for (const running of this.sessions.values()) {
+            this.clearBudgetTimers(running);
+            running.session?.stop();
+        }
+        this.sessions.clear();
+    }
+}
+function str(value) {
+    return typeof value === 'string' && value ? value : null;
+}
+/** Error text safe to hand back to the dashboard (QA-99 MINOR-3). */
+function maskSecretText(error) {
+    return maskString(String(error instanceof Error ? error.message : error)).slice(0, 500);
+}
+function relayAgent(value) {
+    return value === 'claude' || value === 'codex' ? value : null;
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function logScope(value) {
+    return value === 'session' || value === 'branch' || value === 'all' ? value : null;
+}
+function gitCommandPaths(args) {
+    const worktreePath = str(args?.['worktreePath']);
+    const workspacePath = str(args?.['workspacePath']);
+    const branch = str(args?.['branch']);
+    return worktreePath && workspacePath && branch ? { worktreePath, workspacePath, branch } : null;
+}
+function statusForReport(running) {
+    return running.lastReported === 'STARTING'
+        ? 'RUNNING'
+        : running.lastReported;
+}
+const AGENT_LABELS = { CLAUDE: 'Claude Code', CODEX: 'Codex' };
+/** Only Claude reports USD — Codex sessions are bounded by time instead. */
+function reportsCost(agent) {
+    return agent === 'CLAUDE';
+}
+/** Adapter error codes that mean "the sign-in did not work". */
+function isAuthCode(code) {
+    return code === 'auth_expired' || code === 'auth_missing';
+}
+/**
+ * Does this descriptor point at work that already exists on a branch?
+ * If so, silently creating a fresh branch off HEAD would hide the agent's
+ * commits behind an empty worktree — fail loudly instead.
+ */
+function hasWorkToResume(descriptor) {
+    return descriptor.status !== 'STARTING' && Boolean(descriptor.providerSessionId);
+}
+function isTerminal(status) {
+    return status === 'DONE' || status === 'FAILED' || status === 'STOPPED';
+}
+/** Statuses where "process exited" is expected rather than a crash. */
+function isSettled(status) {
+    return isTerminal(status) || status === 'REVIEW';
+}
+export function composeInitialPrompt(descriptor) {
+    if (descriptor.tickets.length === 0)
+        return descriptor.prompt;
+    const ticketLines = descriptor.tickets.map((t) => `- #${t.number}: ${t.title}`).join('\n');
+    return [
+        `You are assigned the following DevBridge ticket(s) in this project:`,
+        ticketLines,
+        '',
+        'Use the DevBridge MCP tools (mcp__devbridge__*) to fetch full ticket details before starting, move the ticket to IN_PROGRESS while you work, and to READY_FOR_REVIEW with a summary comment when done.',
+        '',
+        `Task from the user:`,
+        descriptor.prompt,
+    ].join('\n');
+}
+//# sourceMappingURL=supervisor.js.map