@bridge4dev/runner 0.13.1 → 0.22.1

package/dist/supervisor.js

@@ -1,8 +1,16 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import { log } from './log.js';
-import { maskSecrets, maskString } from './policy.js';
+import { claimAutoResume, clearAutoResume, pruneAutoResume } from './auto-resume.js';
+import { evaluateRecipeCommand, 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 { deleteSessionBranch, ensurePreviewWorktree, ensureSessionWorktree, prepareDirectWorkspace, previewWorktreePath, removePreviewWorktree, removeSessionWorktree, repoKeyFor, sessionWorktreePath, validateWorkspacePath, } from './git.js';
+import { readRecipeProposal } from './recipe.js';
+import { RECIPE_STEP_NAMES, parseProjectRecipe } from './recipe-schema.js';
+import { proposeCommitMessage } from './commit-message.js';
+import { VerifyRunner, runOneOffCommand, } from './verify.js';
+import { VerifyReportQueue } from './verify-queue.js';
+import { applySession, gitBranches, gitCommit, gitDiff, gitLog, gitPush, gitRefs, gitShow, gitStatus, revertApply, gitStage, gitUnstage, gitDiscard, gitPull, gitMergeAbort, updateFromBase, workspaceState, } from './gitops.js';
 import { fsView } from './fsview.js';
 import { agentAuthStatuses, AuthRelay } from './auth-relay.js';
 import { selfUpdate } from './self-update.js';
@@ -30,14 +38,46 @@ export class Supervisor {
     repoLocks = new Map();
     /** An update is installing right now — a second one would fight it. */
     selfUpdateInFlight = false;
+    /** Session 14: one project-recipe run per machine, and its verdict queue. */
+    verify;
+    verifyReports = new VerifyReportQueue();
     constructor(ws, opts) {
         this.ws = ws;
         this.opts = opts;
         this.journals = opts.journals ?? new JournalStore();
+        this.verify = new VerifyRunner({
+            enabled: opts.verifyEnabled !== false,
+            onReport: (report) => {
+                // Queue FIRST, then try the wire. The other order loses the verdict of
+                // every build that finishes while the socket happens to be down — and
+                // a build finishing during a reconnect is not a rare case, it is a
+                // twenty-minute window.
+                this.verifyReports.add(report);
+                this.flushVerifyReports();
+            },
+        });
         ws.on('frame', (frame) => {
             void this.onFrame(frame).catch((error) => log.error('supervisor: frame handler failed', { type: frame.type, error: String(error) }));
         });
     }
+    /**
+     * Push every unacked verdict at the API.
+     *
+     * Called on each reconnect and whenever a run finishes. Sending a report the
+     * API already has is harmless — it is keyed by `runId` and stored idempotently
+     * — while not sending one is a verdict that never existed.
+     */
+    flushVerifyReports() {
+        for (const report of this.verifyReports.pending()) {
+            const sent = this.ws.send({
+                type: 'verify_report',
+                report: report,
+            });
+            if (!sent)
+                break;
+            this.verifyReports.markAttempted(report.runId);
+        }
+    }
     get activeSessionIds() {
         return [...this.sessions.keys()];
     }
@@ -46,10 +86,42 @@ export class Supervisor {
             case 'hello_ack':
                 this.setMaxSessions(frame.maxSessions);
                 await this.reconcile(frame.sessions);
+                // A build that finished while the socket was down has its verdict
+                // sitting on disk. This is the moment it can be delivered.
+                this.flushVerifyReports();
+                break;
+            case 'verify_report_ack':
+                this.verifyReports.ack(frame.runId);
                 break;
             case 'server_settings':
                 this.setMaxSessions(frame.maxSessions);
                 break;
+            /**
+             * Session 15: the project's trust level or auto-commit switch changed
+             * while sessions are running. Applied live — both are read on every tool
+             * call — because the direction that matters is the TIGHTENING one: a
+             * manager switching a project to STRICT and being told it is STRICT while
+             * an agent keeps running under AUTO is the worst version of this control.
+             */
+            case 'workspace_settings': {
+                for (const running of this.sessions.values()) {
+                    if (running.descriptor.workspace.id !== frame.workspaceId)
+                        continue;
+                    if (frame.trustMode !== undefined) {
+                        running.descriptor.workspace.trustMode = frame.trustMode;
+                    }
+                    if (frame.agentAutoCommit !== undefined) {
+                        running.descriptor.workspace.agentAutoCommit = frame.agentAutoCommit;
+                    }
+                    running.session?.setWorkspacePolicy({
+                        ...(frame.trustMode !== undefined ? { trustMode: frame.trustMode } : {}),
+                        ...(frame.agentAutoCommit !== undefined
+                            ? { agentAutoCommit: frame.agentAutoCommit }
+                            : {}),
+                    });
+                }
+                break;
+            }
             case 'session_start':
                 await this.startSession(frame.session);
                 break;
@@ -61,6 +133,9 @@ export class Supervisor {
                 running?.session?.answerPermission(frame.requestId, frame.allow, frame.note);
                 break;
             }
+            case 'question_answer':
+                this.onQuestionAnswer(frame);
+                break;
             case 'session_stop':
                 this.stopSession(frame.sessionId);
                 break;
@@ -108,7 +183,7 @@ export class Supervisor {
             if (descriptor.epoch > existing.epoch) {
                 existing.pendingRestart = descriptor;
                 existing.stopRequested = true;
-                existing.session?.stop();
+                existing.session?.stop('session_stopped');
             }
             return;
         }
@@ -118,9 +193,13 @@ export class Supervisor {
         if (!this.ensureCapacity(descriptor.id)) {
             const limit = this.maxSessions;
             this.reportStatus(descriptor.id, 'FAILED', {
-                errorMessage: limit === 1
+                errorMessage: (limit === 1
                     ? 'Runner already has an active session'
-                    : `Runner is already running ${limit} active sessions — stop one first`,
+                    : `Runner is already running ${limit} active sessions — stop one first`) +
+                    // Since session 12 a session with an open question holds its slot on
+                    // purpose — so "finish the turn" is not something waiting will fix,
+                    // and the message has to say what actually frees it.
+                    this.waitingForAnswerSuffix(descriptor.id),
             });
             return;
         }
@@ -143,6 +222,7 @@ export class Supervisor {
             activeMs: descriptor.activeMsBase,
             extraBudgetMinutes: descriptor.extraBudgetMinutes,
             epoch: descriptor.epoch,
+            openQuestions: new Set(),
             mode: descriptor.mode,
             ...(descriptor.model ? { model: descriptor.model } : {}),
             ...(descriptor.effort ? { effort: descriptor.effort } : {}),
@@ -166,13 +246,15 @@ export class Supervisor {
             }
         }
         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;
+            const prepared = await this.prepareWorkspace(descriptor);
+            running.branch = prepared.branch;
+            running.worktreePath = prepared.worktreePath;
+            // Only when WE created the branch: the fork point is a fact the API can
+            // learn nowhere else, and it pins the first answer it gets.
+            if (prepared.baseSha)
+                running.baseSha = prepared.baseSha;
+            if (prepared.baseBranch)
+                running.baseBranch = prepared.baseBranch;
         }
         catch (error) {
             this.reportStatus(descriptor.id, 'FAILED', {
@@ -204,6 +286,25 @@ export class Supervisor {
         }
         this.flushPendingMessages(running);
     }
+    /**
+     * Where this session is going to work — a worktree of its own, or the project
+     * folder itself (session 16).
+     *
+     * The BRANCH path takes the repo lock because `worktree add` writes into the
+     * shared `.git` (registration + prune), exactly like commit/apply/revert. The
+     * DIRECT path takes none: it only READS which branch a folder is on, and
+     * queueing every session start behind whatever merge happens to be running
+     * would be a lock bought for nothing.
+     */
+    async prepareWorkspace(descriptor) {
+        if (descriptor.workMode === 'DIRECT') {
+            return prepareDirectWorkspace(descriptor.workspace.path);
+        }
+        return this.withRepoLockFor(descriptor.workspace.path, () => ensureSessionWorktree(descriptor.workspace.path, descriptor.id, descriptor.branchHint, {
+            requireExistingBranch: hasWorkToResume(descriptor),
+            ...(descriptor.branchPlan ? { plan: descriptor.branchPlan } : {}),
+        }));
+    }
     /**
      * 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
@@ -246,16 +347,23 @@ export class Supervisor {
         if (running.budgetSpent) {
             this.sendEvent(running, 'notice', {
                 level: 'warn',
-                text: 'The time budget is used up — press «Продолжить» to give the agent more time.',
+                text: 'The time budget is used up — press «Continue» to give the agent more time.',
             });
             return false;
         }
         running.lastPrompt = prompt;
+        // Facts about this session only. The project's own documentation is read by
+        // each agent itself — see `composeWorkspaceContext`.
+        const workspaceContext = composeWorkspaceContext(descriptor);
         running.session = adapter.startSession({
             sessionId: descriptor.id,
             cwd: running.worktreePath,
             ...(prompt ? { prompt } : {}),
+            ...(workspaceContext ? { workspaceContext } : {}),
             trustMode: descriptor.workspace.trustMode,
+            ...(descriptor.workspace.agentAutoCommit === undefined
+                ? {}
+                : { agentAutoCommit: descriptor.workspace.agentAutoCommit }),
             mode: running.mode,
             ...(running.model ? { model: running.model } : {}),
             ...(running.effort ? { effort: running.effort } : {}),
@@ -395,16 +503,17 @@ export class Supervisor {
         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.`,
+            text: `The agent worked for its full ${minutes} minutes and was paused. Press «Continue» to give it more time.`,
         });
         running.stopRequested = true;
+        this.withdrawOpenQuestions(running, 'budget_spent');
         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();
+        running.session?.stop('budget_spent');
     }
     async pumpEvents(running) {
         const session = running.session;
@@ -425,6 +534,21 @@ export class Supervisor {
         // Stream ended — the agent process is gone.
         if (running.session !== session)
             return; // superseded (shouldn't happen in v0)
+        // Backstop for a process that died without going through `stop()` (a crash,
+        // an SDK error, an agent that exited mid-question): the adapter never got
+        // to withdraw its cards, and a card nobody can answer must not stay live.
+        // Guarded like the event loop above — a journal that cannot be written (a
+        // full disk, a daemon already shutting down) must not take the exit path
+        // with it, because everything below it is cleanup.
+        try {
+            this.withdrawOpenQuestions(running, 'session_stopped');
+        }
+        catch (error) {
+            log.warn('supervisor: could not withdraw open questions', {
+                sessionId: descriptor.id,
+                error: String(error),
+            });
+        }
         // The process is down, so nothing is billable any more regardless of the
         // last status we reported.
         if (running.activeSince !== undefined) {
@@ -515,6 +639,46 @@ export class Supervisor {
         // A slot just came free — hand it to whoever was told to wait for one.
         this.drainSessionsWaitingForCapacity();
     }
+    /**
+     * "…and N of them are waiting for an answer from you."
+     *
+     * An open question pins its slot deliberately (`isParkable`), so a message
+     * that blames a running turn sends the user to wait for something that will
+     * never happen. Empty when nothing is waiting.
+     */
+    waitingForAnswerSuffix(exceptSessionId) {
+        let waiting = 0;
+        for (const running of this.sessions.values()) {
+            if (running.descriptor.id === exceptSessionId)
+                continue;
+            if (running.openQuestions.size > 0)
+                waiting++;
+        }
+        if (waiting === 0)
+            return '';
+        return waiting === 1
+            ? ' — one of them is waiting for your answer to a question'
+            : ` — ${waiting} of them are waiting for your answer to a question`;
+    }
+    /**
+     * Close out every ask this session still has open, with a stated cause.
+     *
+     * Idempotent: the adapter reports its own `question_resolved` when it can, and
+     * `forwardEvent` clears the id — so by the time this runs the set is usually
+     * already empty. What it catches is the path where the adapter never got the
+     * chance, and the alternative there is a card that stays clickable forever.
+     */
+    withdrawOpenQuestions(running, reason) {
+        for (const askId of [...running.openQuestions]) {
+            running.openQuestions.delete(askId);
+            this.sendEvent(running, 'question_resolved', {
+                askId,
+                outcome: 'invalidated',
+                source: 'runner',
+                reason,
+            });
+        }
+    }
     /**
      * Deliver messages that were held because every slot was taken.
      *
@@ -612,9 +776,18 @@ export class Supervisor {
         }
         return this.liveSessionCount(exceptSessionId) < limit;
     }
-    /** Idle after a finished turn — safe to kill the process and resume later. */
+    /**
+     * Idle after a finished turn — safe to kill the process and resume later.
+     *
+     * An open question is the exception (session 12): WAITING_INPUT there does
+     * NOT mean "the turn is over", it means the agent's tool call is parked on a
+     * human. Parking such a session killed a live turn — and, worse, killed the
+     * card the user was about to answer — the moment another session wanted a
+     * slot.
+     */
     isParkable(running) {
         return ((running.lastReported === 'REVIEW' || running.lastReported === 'WAITING_INPUT') &&
+            running.openQuestions.size === 0 &&
             Boolean(running.descriptor.providerSessionId));
     }
     park(running) {
@@ -624,7 +797,7 @@ export class Supervisor {
         this.sendEvent(running, 'system_note', {
             text: 'Session parked — the runner switched to another session. Send a message to resume.',
         });
-        running.session.stop();
+        running.session.stop('session_parked');
     }
     forwardEvent(running, event) {
         const { descriptor } = running;
@@ -740,20 +913,66 @@ export class Supervisor {
                 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 });
+                // clock stops with it: since session 12 the agent's tool call is PARKED
+                // on this question, so the agent is genuinely idle — billing the wait
+                // is the bug session 7 removed (five of the first twelve prod sessions
+                // died having spent their budget waiting for a human).
+                running.openQuestions.add(event.askId);
+                this.sendEvent(running, 'question', {
+                    askId: event.askId,
+                    questions: event.questions,
+                    // Mirror fields — an API/dashboard mid-deploy still draws a card.
+                    text: event.text,
+                    options: event.options,
+                });
                 running.lastReported = 'WAITING_INPUT';
                 this.syncBudgetClock(running);
                 return;
-            case 'capabilities':
+            case 'question_resolved':
+                running.openQuestions.delete(event.askId);
+                this.sendEvent(running, 'question_resolved', {
+                    askId: event.askId,
+                    outcome: event.outcome,
+                    source: event.source,
+                    reason: event.reason,
+                    answers: event.answers,
+                    summary: event.summary,
+                });
+                // The human answered — the parked tool call is released and the agent
+                // is working again, so the clock starts. Same shape as the permission
+                // path above, and guarded the same way so a terminal status wins.
+                // `openQuestions.size` matters: both agents can park several asks at
+                // once, and reporting RUNNING while another card is still waiting would
+                // bill a human's thinking time all over again (QA-106 M4).
+                if (event.source === 'user' &&
+                    running.openQuestions.size === 0 &&
+                    running.lastReported === 'WAITING_INPUT') {
+                    running.lastReported = 'RUNNING';
+                    this.reportStatus(descriptor.id, 'RUNNING', {});
+                }
+                return;
+            case 'capabilities': {
+                // The ADAPTER is the authority on which model is selected — it has the
+                // live catalogue and has already resolved the wire id the agent reports
+                // back to the row it belongs to (ticket #111). `running.model` is only
+                // what was asked for at launch, and it is routinely a name no row in
+                // that catalogue carries: sessions whose column was written from an
+                // older capabilities event hold a resolved id like `claude-opus-5[1m]`,
+                // which the dashboard can match to nothing — so it drew the raw id in
+                // the model picker and, because effort levels hang off the selected
+                // row, no effort control at all.
+                const currentModel = event.capabilities.currentModel ?? running.model;
+                // Adopt it, so the next descriptor and the session column carry a name
+                // the picker can find instead of re-poisoning them from the old value.
+                if (currentModel)
+                    running.model = currentModel;
                 this.sendEvent(running, 'capabilities', {
                     ...event.capabilities,
                     currentMode: running.mode,
-                    ...(running.model ? { currentModel: running.model } : {}),
+                    ...(currentModel ? { currentModel } : {}),
                 });
                 return;
+            }
             case 'settings':
                 if (event.mode)
                     running.mode = event.mode;
@@ -777,6 +996,16 @@ export class Supervisor {
                     maxTokens: event.maxTokens,
                 });
                 return;
+            case 'agent_tasks':
+                // Ticket #113. A LEVEL signal: every frame carries the whole live set,
+                // so the dashboard replaces rather than reconciles and a dropped frame
+                // cannot leave a finished subagent spinning in the tray forever.
+                this.sendEvent(running, 'agent_tasks', {
+                    tasks: event.tasks,
+                    done: event.done,
+                    total: event.total,
+                });
+                return;
             case 'notice': {
                 // Only adapter notices are de-duplicated here. The supervisor's own
                 // notices (turn interrupted, session parked, budget warnings) go
@@ -802,6 +1031,59 @@ export class Supervisor {
                 return;
         }
     }
+    /**
+     * The dashboard's answer to a parked question (session 12).
+     *
+     * A miss is reported in the feed rather than swallowed: the three cases that
+     * get here — a card from a previous life of the session, a second click, an
+     * ask the runner already withdrew — all look identical to the user unless
+     * somebody says so.
+     */
+    onQuestionAnswer(frame) {
+        const running = this.sessions.get(frame.sessionId);
+        if (!running) {
+            log.warn('supervisor: question answer for unknown session', { sessionId: frame.sessionId });
+            this.ws.send({ type: 'session_unknown', sessionId: frame.sessionId });
+            return;
+        }
+        const typed = frame.text?.trim();
+        // Asked first, echoed second: the adapter resolves synchronously but its
+        // own events reach the feed a microtask later, so the user's words still
+        // land before the agent's reaction — and on a miss we can hand the text to
+        // the ordinary delivery path, which does the echo itself.
+        const accepted = running.session?.answerQuestion({
+            askId: frame.askId,
+            action: frame.action,
+            ...(frame.answers ? { answers: frame.answers } : {}),
+            ...(frame.text !== undefined ? { text: frame.text } : {}),
+        });
+        if (accepted) {
+            // What the user typed belongs in the conversation, whichever exit they took.
+            if (typed)
+                this.sendEvent(running, 'message', { role: 'user', text: typed });
+            return;
+        }
+        running.openQuestions.delete(frame.askId);
+        this.sendEvent(running, 'system_note', {
+            text: typed
+                ? 'That question is no longer open — sending your reply as an ordinary message instead.'
+                : 'That question is no longer open — the agent has already moved on.',
+        });
+        // The words must not be eaten. This is the ordinary case after a runner
+        // restart: the card in the browser outlived the process that asked, and
+        // showing the user's own message in the feed while nothing receives it is
+        // the exact failure `onUserMessage` was hardened against (QA-106 M2).
+        if (typed) {
+            void this.onUserMessage(frame.sessionId, typed).catch((error) => log.error('supervisor: could not deliver a reply to a closed question', {
+                sessionId: frame.sessionId,
+                error: String(error),
+            }));
+            return;
+        }
+        // Nothing to deliver — but the API optimistically flipped the session to
+        // RUNNING when it relayed the answer, so put the real status back.
+        this.reportStatus(frame.sessionId, statusForReport(running), {});
+    }
     async onUserMessage(sessionId, text, attachments) {
         const running = this.sessions.get(sessionId);
         if (!running) {
@@ -932,9 +1214,10 @@ export class Supervisor {
         // 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
+                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 runner is busy with ${this.maxSessions} other sessions — this one continues as soon as one of them finishes its turn.`) +
+                    this.waitingForAnswerSuffix(running.descriptor.id),
             });
             // 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
@@ -943,6 +1226,9 @@ export class Supervisor {
             running.pendingMessages.push(...(held.length > 0 ? held : [running.journal.appendPending(text)]));
             return;
         }
+        // A person typing into the session is the clearest signal that the work is
+        // back on track, so the automatic-continuation allowance starts over.
+        clearAutoResume(running.descriptor.id);
         if (this.launchAgent(running, text, running.descriptor.providerSessionId)) {
             settle();
             return;
@@ -994,6 +1280,12 @@ export class Supervisor {
         const running = this.sessions.get(sessionId);
         if (!running?.session)
             return;
+        // The turn being interrupted is the turn the question belongs to — leaving
+        // the ask parked would make the user's next message be swallowed as its
+        // answer (QA-106 m7). The adapter reports each withdrawal itself; the local
+        // set is cleared so the session can be parked again.
+        running.session.cancelQuestions('turn_aborted');
+        running.openQuestions.clear();
         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';
@@ -1045,9 +1337,10 @@ export class Supervisor {
         running.stopRequested = true;
         this.clearBudgetTimers(running);
         if (running.session) {
-            running.session.stop(); // pumpEvents finishes the cleanup
+            running.session.stop('session_stopped'); // pumpEvents finishes the cleanup
         }
         else {
+            this.withdrawOpenQuestions(running, 'session_stopped');
             this.reportStatus(sessionId, 'STOPPED', { activeMs: running.activeMs });
             this.sessions.delete(sessionId);
             if (this.ws.connected && running.journal.unacked().length === 0) {
@@ -1068,9 +1361,10 @@ export class Supervisor {
             running.stopRequested = true;
             this.clearBudgetTimers(running);
             if (running.session) {
-                running.session.stop(); // pumpEvents finishes the cleanup
+                running.session.stop('session_stopped'); // pumpEvents finishes the cleanup
             }
             else {
+                this.withdrawOpenQuestions(running, 'session_stopped');
                 this.sessions.delete(sessionId);
             }
         }
@@ -1120,8 +1414,13 @@ export class Supervisor {
                 // 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.
+                // A journal written by a runner from before session 13 could hold a
+                // `DONE` — it is no longer a status this runner may report, and
+                // replaying one would close the session for the user. Drop it and let
+                // the session be picked back up like any other.
                 if (last &&
                     isTerminal(last.status) &&
+                    last.status !== 'DONE' &&
                     (last.epoch ?? 0) >= descriptor.epoch) {
                     this.ws.send({
                         type: 'session_status',
@@ -1160,6 +1459,7 @@ export class Supervisor {
                     activeMs: descriptor.activeMsBase,
                     extraBudgetMinutes: descriptor.extraBudgetMinutes,
                     epoch: descriptor.epoch,
+                    openQuestions: new Set(),
                     mode: descriptor.mode,
                     ...(descriptor.model ? { model: descriptor.model } : {}),
                     ...(descriptor.effort ? { effort: descriptor.effort } : {}),
@@ -1170,9 +1470,16 @@ export class Supervisor {
                 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;
+                    // A session being restored after a runner restart already has its
+                    // branch, so the API sends `CONTINUE` — the NEW guard inside would
+                    // otherwise fire on the runner's own previous work.
+                    const prepared = await this.prepareWorkspace(descriptor);
+                    running.branch = prepared.branch;
+                    running.worktreePath = prepared.worktreePath;
+                    if (prepared.baseSha)
+                        running.baseSha = prepared.baseSha;
+                    if (prepared.baseBranch)
+                        running.baseBranch = prepared.baseBranch;
                 }
                 catch (error) {
                     this.reportStatus(descriptor.id, 'FAILED', {
@@ -1181,9 +1488,43 @@ export class Supervisor {
                     this.sessions.delete(descriptor.id);
                     continue;
                 }
+                /**
+                 * Was a turn actually in flight when the process died?
+                 *
+                 * `RUNNING` and `WAITING_PERMISSION` are the mid-turn statuses; the
+                 * others mean the agent was already waiting for a human, and there is
+                 * nothing to continue. REVIEW is deliberately excluded — the work is
+                 * finished and waiting to be looked at.
+                 */
+                const wasMidTurn = descriptor.status === 'RUNNING' || descriptor.status === 'WAITING_PERMISSION';
+                const resumeId = descriptor.providerSessionId;
+                const willContinue = wasMidTurn && claimAutoResume(descriptor.id);
+                // The note stays either way (owner's call): an interruption is a fact
+                // about the session and must not disappear just because we recovered
+                // from it. Only the instruction at the end changes — telling someone to
+                // send a message while the agent is already working again would be a lie.
                 this.sendEvent(running, 'system_note', {
-                    text: 'Runner reconnected. The session was resumed — send a message to continue.',
+                    text: willContinue
+                        ? 'Runner reconnected. The session was resumed — continuing the interrupted turn.'
+                        : 'Runner reconnected. The session was resumed — send a message to continue.',
                 });
+                if (willContinue) {
+                    // Resumed through the PROVIDER session, so the agent keeps its whole
+                    // conversation; the prompt is only the nudge a human would otherwise
+                    // have to type. Exactly what «продолжай» did by hand — no new class of
+                    // risk, and the same ceiling protects against a crash loop doing it
+                    // forever (see `auto-resume.ts`).
+                    if (this.launchAgent(running, AUTO_RESUME_PROMPT, resumeId)) {
+                        this.reportStatus(descriptor.id, 'RUNNING', {});
+                        this.flushPendingMessages(running);
+                        continue;
+                    }
+                    // Could not start (an exhausted budget is the only way here). Fall
+                    // through to the old behaviour and say so honestly.
+                    this.sendEvent(running, 'system_note', {
+                        text: 'Could not continue automatically — send a message to pick the work back up.',
+                    });
+                }
                 // REVIEW stays REVIEW (WAITING_INPUT is not reachable from it);
                 // mid-turn statuses are downgraded to "waiting for the user".
                 if (descriptor.status !== 'REVIEW') {
@@ -1214,6 +1555,7 @@ export class Supervisor {
      */
     pruneJournals() {
         try {
+            pruneAutoResume(new Set(this.sessions.keys()));
             const removed = this.journals.prune({
                 maxAgeMs: Supervisor.JOURNAL_TTL_MS,
                 hardMaxAgeMs: Supervisor.JOURNAL_HARD_TTL_MS,
@@ -1300,7 +1642,17 @@ export class Supervisor {
                         });
                     return void reply({
                         ok: true,
-                        result: await gitStatus(paths.worktreePath, paths.workspacePath, paths.branch),
+                        result: await gitStatus({
+                            worktreePath: paths.worktreePath,
+                            workspacePath: paths.workspacePath,
+                            sessionBranch: paths.branch,
+                            ...optionalBranch(frame.args?.['baseBranch'], 'baseBranch'),
+                            ...optionalSha(frame.args?.['appliedBranchSha'], 'appliedBranchSha'),
+                            ...optionalSha(frame.args?.['pushedSha'], 'pushedSha'),
+                            // Session 16: a DIRECT session has no base to be measured
+                            // against — the folder's own branch is where the work is.
+                            ...(frame.args?.['direct'] === true ? { direct: true } : {}),
+                        }),
                     });
                 }
                 case 'git_diff': {
@@ -1314,7 +1666,10 @@ export class Supervisor {
                     }
                     return void reply({
                         ok: true,
-                        result: await gitDiff(paths.worktreePath, paths.workspacePath, paths.branch, filePath),
+                        result: await gitDiff(paths.worktreePath, paths.workspacePath, paths.branch, filePath, str(frame.args?.['baseBranch']) ?? undefined, 
+                        // Session 16: the Source Control panel asks for one side of the
+                        // index at a time. Anything else keeps the historical meaning.
+                        diffMode(frame.args?.['mode'])),
                     });
                 }
                 // Session 11: history. Read-only, so no repo lock and no busy check —
@@ -1324,20 +1679,32 @@ export class Supervisor {
                 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 selector = refSelector(frame.args);
+                    // Session 14: the repository graph is reached from the WORKSPACE, so
+                    // a branch is no longer required — but then a ref selector is, or the
+                    // call would have nothing to walk and git would quietly default to
+                    // HEAD.
+                    if (!workspacePath || (!branch && Object.keys(selector).length === 0)) {
+                        return void reply({
+                            ok: false,
+                            error: 'workspacePath and either branch or a ref selection are required',
+                        });
                     }
                     const scope = logScope(frame.args?.['scope']);
                     const limit = num(frame.args?.['limit']);
                     const skip = num(frame.args?.['skip']);
+                    const cursor = str(frame.args?.['cursor']);
                     return void reply({
                         ok: true,
                         result: await gitLog({
                             workspacePath,
-                            branch,
+                            ...(branch ? { branch } : {}),
                             ...(scope ? { scope } : {}),
                             ...(limit !== null ? { limit } : {}),
                             ...(skip !== null ? { skip } : {}),
+                            ...(cursor ? { cursor } : {}),
+                            ...selector,
+                            ...optionalBranch(frame.args?.['baseBranch'], 'baseBranch'),
                         }),
                     });
                 }
@@ -1349,11 +1716,45 @@ export class Supervisor {
                     }
                     const filePath = str(frame.args?.['path']);
                     const showBranch = str(frame.args?.['branch']);
+                    const selector = refSelector(frame.args);
                     return void reply({
                         ok: true,
-                        result: await gitShow(workspacePath, sha, filePath ?? undefined, showBranch ?? undefined),
+                        result: await gitShow(workspacePath, sha, filePath ?? undefined, showBranch ?? undefined, str(frame.args?.['baseBranch']) ?? undefined, 
+                        // The visibility set is widened by exactly the refs the LOG was
+                        // allowed to walk. Passing it only when the caller sent one keeps
+                        // every session read on its original two refs.
+                        Object.keys(selector).length > 0 ? selector : undefined),
                     });
                 }
+                // Session 14: the ref list behind the graph's branch picker. Read-only,
+                // same call as git_log — `for-each-ref` cannot move anything.
+                case 'git_refs': {
+                    const workspacePath = str(frame.args?.['workspacePath']);
+                    if (!workspacePath) {
+                        return void reply({ ok: false, error: 'workspacePath is required' });
+                    }
+                    return void reply({ ok: true, result: await gitRefs(workspacePath) });
+                }
+                // Session 14: what the project folder is ACTUALLY on. The product used
+                // to collect this during path validation and throw it away, which is
+                // why it could never answer «is the running build yours».
+                case 'workspace_state': {
+                    const workspacePath = str(frame.args?.['workspacePath']);
+                    if (!workspacePath) {
+                        return void reply({ ok: false, error: 'workspacePath is required' });
+                    }
+                    return void reply({ ok: true, result: await workspaceState(workspacePath) });
+                }
+                // Session 13: the branch list the «continue an existing branch» picker
+                // reads. Read-only — `for-each-ref` and `worktree list` cannot move a
+                // ref — so no lock and no busy check, same call as git_log above.
+                case 'git_branches': {
+                    const workspacePath = str(frame.args?.['workspacePath']);
+                    if (!workspacePath) {
+                        return void reply({ ok: false, error: 'workspacePath is required' });
+                    }
+                    return void reply({ ok: true, result: await gitBranches(workspacePath) });
+                }
                 case 'git_commit': {
                     const worktreePath = str(frame.args?.['worktreePath']);
                     const message = str(frame.args?.['message']);
@@ -1366,9 +1767,14 @@ export class Supervisor {
                             error: 'The agent is still working — wait for the turn to finish',
                         });
                     }
+                    // Session 16: `all: false` commits the INDEX — what the person
+                    // staged, and nothing else. Absent stays `git add -A` + commit, which
+                    // is what the agent's own auto-commit has always meant and what every
+                    // API older than this release will keep asking for.
+                    const all = frame.args?.['all'] !== false;
                     return void reply({
                         ok: true,
-                        result: await this.withRepoLockFor(worktreePath, () => gitCommit(worktreePath, message)),
+                        result: await this.withRepoLockFor(worktreePath, () => gitCommit(worktreePath, message, { all })),
                     });
                 }
                 case 'apply_session': {
@@ -1386,22 +1792,181 @@ export class Supervisor {
                             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
+                    const applied = await this.withRepoLockFor(paths.workspacePath, () => applySession({
+                        workspacePath: paths.workspacePath,
+                        worktreePath: paths.worktreePath,
+                        sessionBranch: paths.branch,
+                        message,
+                        ...optionalBranch(frame.args?.['expectedBase'], 'expectedBase'),
+                        ...optionalSha(frame.args?.['sinceSha'], 'sinceSha'),
+                    }));
+                    // «Nothing new to apply», «the folder is on another branch» and «the
+                    // folder has uncommitted changes» are answers, not failures: the API
+                    // turns each into a sentence with a way forward, and an `ok: false`
+                    // here would surface as a raw error toast instead.
+                    //
+                    // `workspaceDirty` joining that list is safe for an API older than
+                    // session 15: it does not know the flag, so it falls through to the
+                    // same `AppError.conflict(result.error)` it raises today, with the
+                    // same wording.
+                    return void reply(applied.applied ||
+                        applied.conflict ||
+                        applied.noChanges ||
+                        applied.drifted ||
+                        applied.workspaceDirty
                         ? { ok: true, result: applied }
                         : { ok: false, error: applied.error ?? 'Apply failed', result: applied });
                 }
+                // Session 13: merge the base branch INTO the session branch. Merge and
+                // never rebase — rebase rewrites commits the History tab already showed
+                // a human. Takes the worktree busy check and the repo lock, because it
+                // writes into the session's index just like a commit does.
+                case 'update_from_base': {
+                    const paths = gitCommandPaths(frame.args);
+                    if (!paths) {
+                        return void reply({
+                            ok: false,
+                            error: 'worktreePath/workspacePath/branch 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 updated = await this.withRepoLockFor(paths.worktreePath, () => updateFromBase({
+                        workspacePath: paths.workspacePath,
+                        worktreePath: paths.worktreePath,
+                        sessionBranch: paths.branch,
+                        ...optionalBranch(frame.args?.['baseBranch'], 'baseBranch'),
+                    }));
+                    return void reply(updated.updated || updated.conflict
+                        ? { ok: true, result: updated }
+                        : { ok: false, error: updated.error ?? 'Update failed', result: updated });
+                }
+                // Session 13: the one outgoing write DevBridge performs. Never reached
+                // by an agent — layer 1 denies `git push` outright — only by a human
+                // pressing the button, and only for this session's own branch.
+                case 'git_push': {
+                    const workspacePath = str(frame.args?.['workspacePath']);
+                    const branch = str(frame.args?.['branch']);
+                    const remote = str(frame.args?.['remote']);
+                    if (!workspacePath || !branch || !remote) {
+                        return void reply({
+                            ok: false,
+                            error: 'workspacePath/branch/remote are required',
+                        });
+                    }
+                    const pushed = await this.withRepoLockFor(workspacePath, () => gitPush({ workspacePath, branch, remote }));
+                    return void reply(pushed.pushed
+                        ? { ok: true, result: pushed }
+                        : { ok: false, error: pushed.error ?? 'Push failed', result: pushed });
+                }
                 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
+                    const expected = optionalBranch(frame.args?.['expectedBase'], 'expectedBase');
+                    const reverted = await this.withRepoLockFor(workspacePath, () => revertApply(workspacePath, commitSha, expected.expectedBase));
+                    // Same reasoning as `apply_session`: a dirty project folder is a
+                    // state the API can explain and offer a way out of, not an error.
+                    return void reply(reverted.reverted || reverted.conflict || reverted.workspaceDirty
                         ? { ok: true, result: reverted }
                         : { ok: false, error: reverted.error ?? 'Revert failed', result: reverted });
                 }
+                /**
+                 * Session 16 — the Source Control panel's four verbs.
+                 *
+                 * All of them WRITE into the index or the working tree of the session's
+                 * folder, so all of them take the repo lock and the worktree busy check:
+                 * staging a file underneath an agent that is mid-edit produces a commit
+                 * of half a thought, and «the agent is still working» is a sentence a
+                 * person can act on where a git error is not.
+                 *
+                 * They are deliberately four commands and not one `git` passthrough. A
+                 * passthrough would be a shell on somebody's server behind a web button;
+                 * these take a list of paths, and every one of those paths is checked
+                 * before it reaches an argv slot.
+                 */
+                case 'git_stage':
+                case 'git_unstage':
+                case 'git_discard': {
+                    const worktreePath = str(frame.args?.['worktreePath']);
+                    if (!worktreePath) {
+                        return void reply({ ok: false, error: 'worktreePath is required' });
+                    }
+                    const all = frame.args?.['all'] === true;
+                    const paths = Array.isArray(frame.args?.['paths']) ? frame.args?.['paths'] : null;
+                    if (!all && !paths) {
+                        return void reply({ ok: false, error: 'paths or all is required' });
+                    }
+                    if (this.isWorktreeBusy(worktreePath)) {
+                        return void reply({
+                            ok: false,
+                            error: 'The agent is still working — wait for the turn to finish',
+                        });
+                    }
+                    const request = { worktreePath, ...(all ? { all } : { paths: paths }) };
+                    const run = frame.name === 'git_stage'
+                        ? () => gitStage(request)
+                        : frame.name === 'git_unstage'
+                            ? () => gitUnstage(request)
+                            : () => gitDiscard(request);
+                    try {
+                        const result = await this.withRepoLockFor(worktreePath, run);
+                        return void reply({ ok: true, result });
+                    }
+                    catch (error) {
+                        // A refused path is a sentence the panel shows verbatim («Path must
+                        // be relative to the repository: …»), not a stack trace.
+                        return void reply({ ok: false, error: maskSecretText(error) });
+                    }
+                }
+                /**
+                 * Session 16: `git pull`, and the way back out of one that conflicted.
+                 *
+                 * The only command in this group that reaches the network. It can leave
+                 * a conflicted tree behind on purpose — that is what git does, and the
+                 * panel draws it as «Merge Changes» rather than pretending the pull did
+                 * not happen.
+                 */
+                case 'git_pull': {
+                    const worktreePath = str(frame.args?.['worktreePath']);
+                    if (!worktreePath) {
+                        return void reply({ ok: false, error: 'worktreePath is required' });
+                    }
+                    if (this.isWorktreeBusy(worktreePath)) {
+                        return void reply({
+                            ok: false,
+                            error: 'The agent is still working — wait for the turn to finish',
+                        });
+                    }
+                    const pulled = await this.withRepoLockFor(worktreePath, () => gitPull({ worktreePath }));
+                    // A conflict is an outcome with a state attached, not a failure: the
+                    // API turns it into a sentence and the panel into a file group.
+                    return void reply(pulled.pulled || pulled.conflict
+                        ? { ok: true, result: pulled }
+                        : { ok: false, error: pulled.error ?? 'Pull failed', result: pulled });
+                }
+                case 'git_merge_abort': {
+                    const worktreePath = str(frame.args?.['worktreePath']);
+                    if (!worktreePath) {
+                        return void reply({ ok: false, error: 'worktreePath is required' });
+                    }
+                    if (this.isWorktreeBusy(worktreePath)) {
+                        return void reply({
+                            ok: false,
+                            error: 'The agent is still working — wait for the turn to finish',
+                        });
+                    }
+                    const aborted = await this.withRepoLockFor(worktreePath, () => gitMergeAbort(worktreePath));
+                    return void reply(aborted.aborted
+                        ? { ok: true, result: aborted }
+                        : { ok: false, error: aborted.reason ?? 'Nothing to abort', result: aborted });
+                }
                 case 'fs_view': {
                     const root = str(frame.args?.['root']);
                     if (!root)
@@ -1451,6 +2016,185 @@ export class Supervisor {
                         this.opts.onRestartRequested?.(outcome);
                     return;
                 }
+                // ─── Session 14: the project recipe ──────────────────────────
+                //
+                // Read-only, always available even when verification is switched off:
+                // «this machine will not run it» is a different answer from «this
+                // project has no recipe», and the card has to be able to say both.
+                case 'recipe_state': {
+                    const root = str(frame.args?.['root']) ?? str(frame.args?.['workspacePath']);
+                    if (!root)
+                        return void reply({ ok: false, error: 'workspacePath is required' });
+                    return void reply({
+                        ok: true,
+                        result: { ...readRecipeProposal(root), verifyEnabled: this.verify.enabled },
+                    });
+                }
+                case 'verify_start': {
+                    const parsed = parseVerifyStart(frame.args);
+                    if ('error' in parsed)
+                        return void reply({ ok: false, error: parsed.error });
+                    const started = this.verify.start(parsed.input);
+                    return void reply(started.started
+                        ? { ok: true, result: { started: true, runId: parsed.input.runId } }
+                        : { ok: false, error: started.error ?? 'Could not start the verification' });
+                }
+                case 'verify_status': {
+                    const runId = str(frame.args?.['runId']);
+                    if (!runId)
+                        return void reply({ ok: false, error: 'runId is required' });
+                    const status = this.verify.status(runId, num(frame.args?.['offset']) ?? 0);
+                    return void reply(status
+                        ? { ok: true, result: status }
+                        : { ok: false, error: 'This runner does not know that verification run' });
+                }
+                case 'verify_cancel': {
+                    const runId = str(frame.args?.['runId']);
+                    if (!runId)
+                        return void reply({ ok: false, error: 'runId is required' });
+                    const cancelled = this.verify.cancel(runId);
+                    return void reply(cancelled.cancelled
+                        ? { ok: true, result: cancelled }
+                        : { ok: false, error: cancelled.error ?? 'Could not cancel' });
+                }
+                /**
+                 * Session 14: show a branch WITHOUT touching the project folder.
+                 *
+                 * A second, detached worktree plus the recipe's own `preview` command —
+                 * which has its own docker project and its own ports. Without that
+                 * command there is nothing honest to do: rebuilding in the project
+                 * folder would replace the one copy the machine is running.
+                 */
+                case 'preview_checkout': {
+                    const workspacePath = str(frame.args?.['workspacePath']);
+                    const branch = str(frame.args?.['branch']);
+                    const parsed = parseVerifyStart(frame.args);
+                    if (!workspacePath || !branch) {
+                        return void reply({ ok: false, error: 'workspacePath and branch are required' });
+                    }
+                    if ('error' in parsed)
+                        return void reply({ ok: false, error: parsed.error });
+                    if (!parsed.input.recipe.preview?.run) {
+                        return void reply({
+                            ok: false,
+                            error: 'Previewing this branch would rebuild the only copy this machine is running. Add a `preview` command to the recipe — with its own docker project name and its own ports — and the preview gets its own stack.',
+                        });
+                    }
+                    const checkout = await this.withRepoLockFor(workspacePath, () => ensurePreviewWorktree({
+                        workspacePath,
+                        workspaceKey: frame.workspaceId ?? workspacePath,
+                        branch,
+                    }));
+                    const started = this.verify.start({
+                        ...parsed.input,
+                        target: 'PREVIEW',
+                        preview: true,
+                        cwd: checkout.worktreePath,
+                        branch: checkout.branch,
+                        commitSha: checkout.sha,
+                        dirty: false,
+                    });
+                    return void reply(started.started
+                        ? {
+                            ok: true,
+                            result: {
+                                started: true,
+                                runId: parsed.input.runId,
+                                worktreePath: checkout.worktreePath,
+                                branch: checkout.branch,
+                                sha: checkout.sha,
+                                url: parsed.input.recipe.preview.url ?? null,
+                            },
+                        }
+                        : { ok: false, error: started.error ?? 'Could not start the preview' });
+                }
+                case 'preview_stop': {
+                    const workspacePath = str(frame.args?.['workspacePath']);
+                    if (!workspacePath)
+                        return void reply({ ok: false, error: 'workspacePath is required' });
+                    const key = frame.workspaceId ?? workspacePath;
+                    const stopCommand = str(frame.args?.['stop']);
+                    const dockerProject = str(frame.args?.['project']);
+                    // Cancel the preview's own run FIRST (session 15).
+                    //
+                    // «Stop preview» used to run the stop command and delete the
+                    // worktree while `preview.run` was still executing inside it — so a
+                    // half-built `docker compose up --build` lost its directory mid-flight
+                    // and went on holding the machine's single verification slot until it
+                    // timed out, with the dashboard already showing the preview as
+                    // stopped. Only a PREVIEW run is ours to cancel: a build somebody
+                    // started for a session is a different thing entirely.
+                    if (this.verify.activeTarget === 'PREVIEW') {
+                        const runId = this.verify.activeRunId;
+                        if (runId)
+                            this.verify.cancel(runId);
+                    }
+                    if (stopCommand) {
+                        // The one place layer 1 lifts `docker … down`, and only for the
+                        // compose project the recipe named as its own.
+                        const decision = evaluateRecipeCommand(stopCommand, {
+                            isPreviewStop: true,
+                            ...(dockerProject ? { dockerProject } : {}),
+                        });
+                        if (!decision.allowed) {
+                            return void reply({
+                                ok: false,
+                                error: `The stop command is refused: ${decision.reason}`,
+                            });
+                        }
+                        await runPreviewStop(stopCommand, previewWorktreePath(key));
+                    }
+                    const removed = await this.withRepoLockFor(workspacePath, () => removePreviewWorktree(key));
+                    return void reply({ ok: true, result: { stopped: true, removed } });
+                }
+                /**
+                 * Session 14: a commit message written by an agent, in a one-shot run.
+                 *
+                 * Never `send()` into the live session — that would fill the feed with a
+                 * request nobody made, spend the session's context on the whole diff and
+                 * fight the worktree lock the agent holds mid-turn.
+                 */
+                case 'propose_commit_message': {
+                    const paths = gitCommandPaths(frame.args);
+                    if (!paths) {
+                        return void reply({
+                            ok: false,
+                            error: 'worktreePath/workspacePath/branch are required',
+                        });
+                    }
+                    const ticketsRaw = frame.args?.['tickets'];
+                    const subjectsRaw = frame.args?.['commitSubjects'];
+                    const propose = this.opts.proposeCommitMessage ?? proposeCommitMessage;
+                    const result = await propose({
+                        worktreePath: paths.worktreePath,
+                        workspacePath: paths.workspacePath,
+                        branch: paths.branch,
+                        ...optionalBranch(frame.args?.['baseBranch'], 'baseBranch'),
+                        ...(Array.isArray(ticketsRaw)
+                            ? {
+                                tickets: ticketsRaw
+                                    .filter((n) => typeof n === 'number')
+                                    .slice(0, 20),
+                            }
+                            : {}),
+                        ...(Array.isArray(subjectsRaw)
+                            ? {
+                                commitSubjects: subjectsRaw
+                                    .filter((s) => typeof s === 'string')
+                                    .slice(0, 20),
+                            }
+                            : {}),
+                        ...(str(frame.args?.['language'])
+                            ? { language: str(frame.args?.['language']) }
+                            : {}),
+                        ...(str(frame.args?.['convention'])
+                            ? { convention: str(frame.args?.['convention']) }
+                            : {}),
+                    });
+                    return void reply(result.ok
+                        ? { ok: true, result }
+                        : { ok: false, error: result.error ?? 'Could not write a commit message', result });
+                }
                 case 'auth_status':
                     return void reply({ ok: true, result: await agentAuthStatuses() });
                 case 'login_start': {
@@ -1552,7 +2296,19 @@ export class Supervisor {
             running.lastReported = status;
             this.syncBudgetClock(running);
         }
-        const compact = maskSecrets(Object.fromEntries(Object.entries(extra).filter(([, v]) => v !== undefined)));
+        // The fork point rides along on the first frame after the branch was
+        // created — once, because it never changes and the API pins the first
+        // answer it hears. Sending it on every frame would invite a later, wrong
+        // value to overwrite the right one if the pinning rule were ever relaxed.
+        const base = running && !running.baseReported && (running.baseBranch || running.baseSha)
+            ? {
+                ...(running.baseBranch ? { baseBranch: running.baseBranch } : {}),
+                ...(running.baseSha ? { baseSha: running.baseSha } : {}),
+            }
+            : {};
+        if (running && Object.keys(base).length > 0)
+            running.baseReported = true;
+        const compact = maskSecrets(Object.fromEntries(Object.entries({ ...extra, ...base }).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
@@ -1575,9 +2331,31 @@ export class Supervisor {
         this.authRelay.cancel();
         for (const running of this.sessions.values()) {
             this.clearBudgetTimers(running);
-            running.session?.stop();
+            // BEFORE stop(), and from here rather than from the adapter: the adapter
+            // pushes its `question_resolved` into an async queue that `pumpEvents`
+            // drains a microtask later, and every caller of shutdown() (SIGTERM,
+            // «Update runner», `revoked`) calls `process.exit` in the same tick — so
+            // that event would never be journaled and never reach the wire. This
+            // path writes the journal synchronously, and an unacked event is
+            // redelivered on the next connection (QA-106 M1).
+            try {
+                this.withdrawOpenQuestions(running, 'runner_restarted');
+            }
+            catch (error) {
+                log.warn('supervisor: could not withdraw open questions on shutdown', {
+                    sessionId: running.descriptor.id,
+                    error: String(error),
+                });
+            }
+            // The reason matters here: this path also runs for «Update runner», and a
+            // card that vanishes during an update must say why (session 12).
+            running.session?.stop('runner_restarted');
         }
         this.sessions.clear();
+        // A build that was mid-flight is abandoned, not judged: its row stays
+        // RUNNING until the API's sweep turns it into LOST. A verdict nobody
+        // observed must never become PASSED.
+        this.verify.shutdown();
     }
 }
 function str(value) {
@@ -1596,6 +2374,105 @@ function num(value) {
 function logScope(value) {
     return value === 'session' || value === 'branch' || value === 'all' ? value : null;
 }
+/** Which side of the index a diff request means (session 16). */
+function diffMode(value) {
+    return value === 'staged' || value === 'worktree' ? value : 'base';
+}
+/**
+ * Optional command arguments that become git refs.
+ *
+ * They arrive from the API as `unknown` and end up in an argv slot, so they are
+ * shaped here rather than passed through: a value that is not a ref name (or
+ * not a hash) is dropped, and the callee falls back to what it did before the
+ * argument existed. `exactOptionalPropertyTypes` is why these return a spread
+ * object instead of `T | undefined`.
+ */
+function optionalBranch(value, key) {
+    const raw = str(value);
+    if (!raw || raw.length > 200 || !/^[A-Za-z0-9][A-Za-z0-9._\-/]*$/.test(raw))
+        return {};
+    return { [key]: raw };
+}
+function optionalSha(value, key) {
+    const raw = str(value);
+    if (!raw || !/^[0-9a-f]{7,64}$/i.test(raw))
+        return {};
+    return { [key]: raw };
+}
+/**
+ * Which refs a history request may walk (session 14).
+ *
+ * Present only when the caller actually asked for something: an empty object
+ * means «no selector», which keeps every session-level call on exactly the
+ * two-ref behaviour it had before this release. Names are re-validated inside
+ * `gitLog` too — this is the cheap first gate, not the only one.
+ */
+function refSelector(args) {
+    const raw = args?.['refs'];
+    const refs = Array.isArray(raw)
+        ? raw.filter((value) => typeof value === 'string').slice(0, 64)
+        : null;
+    return {
+        ...(refs && refs.length > 0 ? { refs } : {}),
+        ...(args?.['includeRemotes'] === true ? { includeRemotes: true } : {}),
+        ...(args?.['includeTags'] === true ? { includeTags: true } : {}),
+        ...(args?.['all'] === true ? { all: true } : {}),
+    };
+}
+/**
+ * Everything `verify_start` / `preview_checkout` need, validated as one unit.
+ *
+ * The recipe travels on the frame rather than being read off disk here, and
+ * that is the whole point of the design: the executable copy is the one a human
+ * approved on the DevBridge side, not whatever the working tree says today. The
+ * fingerprint is re-checked inside `VerifyRunner.start`, so a frame that lies
+ * about which recipe it carries gets nowhere.
+ */
+function parseVerifyStart(args) {
+    const runId = str(args?.['runId']);
+    if (!runId || !/^[A-Za-z0-9_-]{8,64}$/.test(runId))
+        return { error: 'A valid runId is required' };
+    const recipeSha = str(args?.['recipeSha']);
+    if (!recipeSha)
+        return { error: 'recipeSha is required' };
+    const cwd = str(args?.['cwd']);
+    if (!cwd || !path.isAbsolute(cwd) || cwd.split('/').includes('..')) {
+        return { error: 'cwd must be an absolute path without ".." segments' };
+    }
+    const parsed = parseProjectRecipe(args?.['recipe']);
+    if (!parsed.ok)
+        return { error: `The approved recipe is not valid: ${parsed.error}` };
+    const targetRaw = args?.['target'];
+    const target = targetRaw === 'BASE' || targetRaw === 'SESSION' || targetRaw === 'PREVIEW'
+        ? targetRaw
+        : 'SESSION';
+    const stepsRaw = args?.['steps'];
+    const steps = Array.isArray(stepsRaw)
+        ? RECIPE_STEP_NAMES.filter((name) => stepsRaw.includes(name))
+        : RECIPE_STEP_NAMES.filter((name) => name !== 'deploy');
+    return {
+        input: {
+            runId,
+            target,
+            recipe: parsed.recipe,
+            recipeSha,
+            cwd,
+            steps: [...steps],
+            branch: str(args?.['branch']),
+            commitSha: str(args?.['commitSha']),
+            dirty: args?.['dirty'] === true,
+        },
+    };
+}
+/** Stop a preview's own stack, inside its own worktree. */
+async function runPreviewStop(command, cwd) {
+    if (!fs.existsSync(cwd))
+        return;
+    const result = await runOneOffCommand(command, cwd);
+    if (!result.ok) {
+        log.warn('preview: the stop command failed', { exitCode: result.exitCode });
+    }
+}
 function gitCommandPaths(args) {
     const worktreePath = str(args?.['worktreePath']);
     const workspacePath = str(args?.['workspacePath']);
@@ -1607,6 +2484,15 @@ function statusForReport(running) {
         ? 'RUNNING'
         : running.lastReported;
 }
+/**
+ * What we say to an agent whose turn a runner restart cut off (session 18).
+ *
+ * Deliberately the same thing a human would type — the provider session is
+ * resumed, so the agent still has the whole conversation and only needs to be
+ * told to carry on. Spelling out WHY matters: without it the agent tends to
+ * summarise what it had done instead of finishing it.
+ */
+const AUTO_RESUME_PROMPT = 'Your previous turn was cut off because the runner process restarted — not by me, and not because anything was wrong with the work. Continue from where you stopped. Re-check the state of anything you were in the middle of before redoing it.';
 const AGENT_LABELS = { CLAUDE: 'Claude Code', CODEX: 'Codex' };
 /** Only Claude reports USD — Codex sessions are bounded by time instead. */
 function reportsCost(agent) {
@@ -1631,18 +2517,86 @@ function isTerminal(status) {
 function isSettled(status) {
     return isTerminal(status) || status === 'REVIEW';
 }
+/**
+ * The first message the agent gets.
+ *
+ * Two shapes, and the difference is whether tickets were handed over
+ * (session 16, owner's decision):
+ *
+ *  - **No tickets** — exactly what the human typed, and an empty prompt stays
+ *    empty. That is how you get a session that boots and waits for you to talk
+ *    first; it is a feature, not an oversight.
+ *  - **Tickets handed to a TICKET session** — the assignment is always sent and
+ *    cannot be removed: «Implement ticket #28.» Handing a ticket over IS the
+ *    instruction, so making the human retype it was ceremony. Anything they
+ *    typed follows underneath.
+ *
+ * What is NOT here any more: eight lines about which MCP tools to call and
+ * which statuses to move through. That is a standing convention of the project,
+ * true on the twentieth turn as much as the first, so it moved to the system
+ * prompt beside `CLAUDE.md` — which is read last and therefore overrides ours.
+ */
 export function composeInitialPrompt(descriptor) {
-    if (descriptor.tickets.length === 0)
+    // A free chat may carry tickets as CONTEXT. Assigning them would put an agent
+    // nobody asked onto somebody else's ticket (session 13).
+    if (descriptor.kind === 'CHAT' || 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');
+    const numbers = descriptor.tickets.map((t) => `#${t.number}`).join(', ');
+    const assignment = descriptor.tickets.length === 1
+        ? `Implement ticket ${numbers}.`
+        : `Implement tickets ${numbers}.`;
+    return descriptor.prompt ? `${assignment}\n\n${descriptor.prompt}` : assignment;
+}
+/**
+ * Extra system-prompt material: where this session is in git, and how tickets
+ * are meant to move (session 13).
+ *
+ * Facts about THIS SESSION, and nothing else. They exist in no file on disk —
+ * which branch the agent is on, that it must not push, where a plan belongs,
+ * what to do with the tickets it was given — so somebody has to say them, and
+ * that somebody is us.
+ *
+ * The project's own documentation is deliberately NOT here. Both agents read
+ * their own file natively, verified live: Claude picks up `CLAUDE.md` through
+ * its memory mechanism (since `settingSources` includes `'project'`), and Codex
+ * picks up `AGENTS.md` even under the runner's isolated `CODEX_HOME`. Pasting a
+ * copy on top of that was work we were doing for no one — and when it was
+ * switched off for Claude alone it briefly left repositories that carry only
+ * `AGENTS.md` with nothing at all, which is precisely the kind of hole a
+ * half-measure digs.
+ *
+ * A repository that wants both agents equipped ships both files, or symlinks
+ * one to the other. That is a repository convention and not something a runner
+ * should paper over.
+ */
+export function composeWorkspaceContext(descriptor) {
+    const sections = [];
+    const plan = descriptor.branchPlan;
+    if (plan) {
+        const forked = plan.baseBranch ? ` It was branched from \`${plan.baseBranch}\`.` : '';
+        sections.push([
+            'Git in this session:',
+            `- You are in a dedicated worktree on branch \`${plan.branch}\`.${forked}`,
+            '- Commit to this branch. Do not switch branches and do not merge into the base branch yourself — a human presses «Apply» in DevBridge, which squash-merges your branch for them.',
+            '- You cannot push: `git push` is refused. A human presses «Push» when they want the branch on the remote.',
+            `- Put a plan or working notes in \`docs/devbridge/${plan.branch.replace(/\//g, '-')}.md\`, unless this repository already has its own convention for where such documents live — if it does, follow that.`,
+        ].join('\n'));
+    }
+    // The ticket convention lives HERE, not in the first chat message (session
+    // 16). It is a standing rule of the project — true on the twentieth turn as
+    // much as the first — and putting it in the visible prompt only trained the
+    // reader to skip past it. `CLAUDE.md` is appended after this section, so a
+    // repository that states its own rule overrides ours by being read last.
+    if (descriptor.kind !== 'CHAT' && descriptor.tickets.length > 0) {
+        sections.push([
+            'DevBridge tickets in this session:',
+            '- Read the full ticket with the DevBridge MCP tools (`mcp__devbridge__*`) before starting — the title alone is never the whole task.',
+            '- Move it to IN_PROGRESS while you work and to READY_FOR_REVIEW with a short summary comment when you are done.',
+        ].join('\n'));
+    }
+    else if (descriptor.tickets.length > 0) {
+        sections.push('DevBridge tickets are attached to this chat for CONTEXT only. Read them with the DevBridge MCP tools; do not change their status — this session is not assigned to them.');
+    }
+    return sections.join('\n\n');
 }
 //# sourceMappingURL=supervisor.js.map