@bridge4dev/runner 0.27.0 → 0.29.0

package/dist/supervisor.js

@@ -16,6 +16,10 @@ import { agentAuthStatuses, AuthRelay, clearAgentAuthFailure, noteAgentAuthFailu
 import { selfUpdate } from './self-update.js';
 import { rememberWorkspacePath } from './environment.js';
 import { composeMessageWithAttachments, saveAttachments, } from './attachments.js';
+import { applyRewind, createCheckpoint, dropCheckpoints, listCheckpoints, previewRewind, pruneCheckpoints, } from './checkpoints.js';
+/** Refusals shared by every checkpoint command (ticket #126). */
+const CHECKPOINTS_OFF = 'Restore points are switched off on this server ([checkpoints] enabled = false)';
+const AGENT_BUSY = 'The agent is still working — stop the turn first';
 export class Supervisor {
     ws;
     opts;
@@ -37,6 +41,17 @@ export class Supervisor {
     authRelay = new AuthRelay();
     /** Serialises repo-mutating git commands per workspace repo (QA-99 MAJOR-1). */
     repoLocks = new Map();
+    /**
+     * Repo keys with work in flight right now (ticket #126).
+     *
+     * A checkpoint deliberately does NOT take the repo lock — it only reads the
+     * worktree, and queueing a user's message behind a 150-second push would be
+     * a plain regression. What it does instead is decline to run while a
+     * mutating command holds the repo: a snapshot taken halfway through an apply
+     * would be a state that never existed, and offering to restore it is worse
+     * than having no restore point for that one message.
+     */
+    repoLockDepth = 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. */
@@ -268,6 +283,13 @@ export class Supervisor {
         // asked for it) resumes on the next message instead of replaying its
         // original prompt.
         if (descriptor.status === 'STARTING') {
+            // Ticket #126: the point before the agent has touched anything. It is
+            // anchored to seq 0 — the synthetic opening bubble the dashboard puts in
+            // front of every feed — so "put it all back" is reachable from the very
+            // first thing on the page.
+            await this.captureCheckpoint(running, 'TURN', 0);
+            if (this.isStale(running))
+                return;
             this.launchAgent(running, composeInitialPrompt(descriptor), null);
         }
         else {
@@ -360,6 +382,14 @@ export class Supervisor {
         // Facts about this session only. The project's own documentation is read by
         // each agent itself — see `composeWorkspaceContext`.
         const workspaceContext = composeWorkspaceContext(descriptor);
+        const rewind = running.rewindAnchor;
+        delete running.rewindAnchor;
+        // A rewind resumes the conversation the POINT names, which is not always
+        // the one this session is on now: rewinding twice, or rewinding the first
+        // message after a rewind, both reach back into the thread the fork came
+        // from. Its transcript is still on disk — that is what makes the point
+        // usable at all.
+        const resumeTarget = rewind ? rewind.agentSession : resumeId;
         running.session = adapter.startSession({
             sessionId: descriptor.id,
             cwd: running.worktreePath,
@@ -372,7 +402,12 @@ export class Supervisor {
             mode: running.mode,
             ...(running.model ? { model: running.model } : {}),
             ...(running.effort ? { effort: running.effort } : {}),
-            ...(resumeId ? { resumeProviderSessionId: resumeId } : {}),
+            ...(resumeTarget ? { resumeProviderSessionId: resumeTarget } : {}),
+            // Ticket #126: a conversation rewind takes effect exactly here, on the
+            // next process this session starts. Consumed rather than kept — a rewind
+            // is one event, not a standing setting, and re-applying it on a later
+            // relaunch would silently throw away everything said since.
+            ...(rewind ? { resumeAtAnchor: rewind.anchor } : {}),
             // 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.
@@ -571,6 +606,16 @@ export class Supervisor {
             this.launchAgent(running, prompt, null);
             return;
         }
+        // The way back when the CLI refuses the rewind anchor: one relaunch WITHOUT
+        // it, keeping the conversation. Nothing was rewound, so nothing is cut.
+        if (running.rewindRetry && !running.stopRequested) {
+            const { prompt } = running.rewindRetry;
+            delete running.rewindRetry;
+            running.rewindRetryDone = true;
+            running.costBaseUsd = running.costUsd;
+            this.launchAgent(running, prompt, running.descriptor.providerSessionId);
+            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) {
@@ -795,29 +840,48 @@ export class Supervisor {
             running.openQuestions.size === 0 &&
             Boolean(running.descriptor.providerSessionId));
     }
-    park(running) {
+    /**
+     * Stop the agent process but keep the session resumable.
+     *
+     * `quiet` is for the callers that say it better themselves: a conversation
+     * rewind parks the session too, and announcing «the runner switched to
+     * another session» there is simply untrue — nothing switched, the user
+     * rewound (ticket #126).
+     */
+    park(running, options = {}) {
         if (!running.session)
             return;
+        // Ask the process where the conversation stands while it is still there to
+        // ask (ticket #126) — a restore point taken after this would otherwise
+        // have no way to rewind the agent's memory.
+        this.currentAnchor(running);
         running.parkRequested = true;
         // `code` is what the dashboard reads to tell «parked» from «your turn»
         // (#124). The prose stays for runners older than 0.23.0, which the
         // dashboard still matches on; delete that fallback once the fleet has
         // moved, not before.
-        this.sendEvent(running, 'system_note', {
-            code: 'session_parked',
-            text: 'Session parked — the runner switched to another session. Send a message to resume.',
-        });
+        if (!options.quiet) {
+            this.sendEvent(running, 'system_note', {
+                code: 'session_parked',
+                text: 'Session parked — the runner switched to another session. Send a message to resume.',
+            });
+        }
         running.session.stop('session_parked');
     }
     forwardEvent(running, event) {
         const { descriptor } = running;
         switch (event.type) {
-            case 'provider_session':
+            case 'provider_session': {
                 running.descriptor = { ...descriptor, providerSessionId: event.providerSessionId };
                 this.reportStatus(descriptor.id, statusForReport(running), {
                     providerSessionId: event.providerSessionId,
                 });
+                // The CLI resumed at the anchor and forked, so the cut announced when
+                // the rewind was asked for stands. Nothing to send — it is already in
+                // the feed; this only retires the promise to take it back.
+                delete running.pendingRewind;
                 return;
+            }
             case 'cost':
                 // event.costUsd is the live process's running total; the session
                 // total also includes what earlier processes spent (park/restart).
@@ -829,7 +893,22 @@ export class Supervisor {
                 });
                 return;
             case 'turn_end': {
-                this.sendEvent(running, 'turn_end', { ok: event.ok, errorMessage: event.errorMessage });
+                this.sendEvent(running, 'turn_end', {
+                    ok: event.ok,
+                    errorMessage: event.errorMessage,
+                    ...(event.aborted ? { aborted: true } : {}),
+                });
+                // The session is already on its way out with a status that MEANS
+                // something — a spent budget, a Stop, a teardown. A turn ending inside
+                // that window is a consequence of it, and letting the line below
+                // overwrite `STOPPED / TIME_BUDGET` with `FAILED` (or with a cheerful
+                // WAITING_INPUT) replaces a true, actionable ending with a wrong one.
+                if (running.stopRequested || running.budgetSpent)
+                    return;
+                // A finished turn is the last instant this conversation is BOTH
+                // complete and readable: the process can be parked or lose its slot at
+                // any point after it, and `conversationAnchor()` needs a live one.
+                this.currentAnchor(running);
                 // 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
@@ -854,6 +933,31 @@ export class Supervisor {
                 // 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.
+                // The CLI does not know the point we asked it to resume at. The
+                // conversation is intact — only the rewind did not happen — so the
+                // session must survive, the feed must NOT be cut (nothing was rewound),
+                // and the person must be told plainly rather than left believing the
+                // agent has forgotten something it still remembers.
+                if (event.code === 'rewind_failed') {
+                    // Put the conversation back on the page: the agent still has every
+                    // word of it, and a transcript that shows less than the agent knows
+                    // is the one outcome this feature must never produce.
+                    const cutToUndo = running.pendingRewind;
+                    delete running.pendingRewind;
+                    if (cutToUndo) {
+                        this.sendEvent(running, 'session_rewind_undone', {
+                            rewoundSeq: cutToUndo.rewoundSeq,
+                        });
+                    }
+                    if (!event.recovered && !running.rewindRetryDone) {
+                        running.rewindRetry = { prompt: running.lastPrompt };
+                        this.sendEvent(running, 'notice', {
+                            level: 'warn',
+                            text: 'The conversation could not be rewound to that point — the agent still remembers everything after it. Its files were not affected.',
+                        });
+                    }
+                    return;
+                }
                 if (event.code === 'resume_failed' && !running.freshRetryDone) {
                     running.freshRetry = { prompt: running.lastPrompt };
                     this.sendEvent(running, 'notice', {
@@ -1126,16 +1230,19 @@ export class Supervisor {
         }
         // 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', {
+        // Its seq is the name this message answers to for the rest of its life
+        // (ticket #125): recall, checkpoint anchor and rewind all quote it.
+        const echoed = this.sendEvent(running, 'message', {
             role: 'user',
             text,
             ...(attachments?.length ? { attachments } : {}),
         });
+        const originSeq = echoed.seq;
         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));
+            this.queueMessage(running, running.journal.appendPending(text, attachments, originSeq));
             return;
         }
         this.enqueueDelivery(running, async () => {
@@ -1143,15 +1250,40 @@ export class Supervisor {
             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);
+                // Announced like every other queueing decision: a bubble that is
+                // waiting must say so, whichever door it came through.
+                const parked = running.journal.appendPending(text, attachments, originSeq);
+                if (parked.seq !== undefined) {
+                    this.sendEvent(running, 'message_queued', { targetSeq: parked.seq });
+                }
                 log.warn('supervisor: session ended before the message could be delivered', {
                     sessionId: running.descriptor.id,
                 });
                 return;
             }
-            this.deliverMessage(running, composed);
+            // Ticket #126: the restore point belongs in FRONT of this message, and
+            // this is the last moment the tree is still as the user left it.
+            await this.captureCheckpoint(running, 'TURN', originSeq);
+            if (this.isStale(running))
+                return;
+            this.deliverMessage(running, composed, [], originSeq);
         });
     }
+    /**
+     * Queue a message that no agent can take yet, and say so in the feed
+     * (ticket #125).
+     *
+     * Every queueing decision goes through here so the browser's idea of "this
+     * one can still be taken back" cannot drift from the runner's. Records with
+     * no seq — orphans, and anything written by a runner older than 0.28.0 —
+     * stay silent: they have no name the browser could quote back.
+     */
+    queueMessage(running, record) {
+        running.pendingMessages.push(record);
+        if (record.seq !== undefined) {
+            this.sendEvent(running, 'message_queued', { targetSeq: record.seq });
+        }
+    }
     /**
      * Run delivery work for one session, strictly after whatever is already
      * queued for it. Order is the whole point: two messages typed seconds apart
@@ -1211,7 +1343,7 @@ export class Supervisor {
      * 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 = []) {
+    deliverMessage(running, text, held = [], originSeq) {
         // 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
@@ -1223,13 +1355,23 @@ export class Supervisor {
             // 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.queueMessage(running, running.journal.appendPending(text, undefined, originSeq));
             this.flushPendingMessages(running);
             return;
         }
         const settle = () => {
-            for (const record of held)
+            const delivered = [];
+            for (const record of held) {
                 running.journal.resolvePending(record.id);
+                if (record.seq !== undefined)
+                    delivered.push(record.seq);
+            }
+            // Ticket #125: the queue is now empty of these, so the browser must stop
+            // offering to take them back. Only for messages that were ever announced
+            // as queued — the ordinary path never queues and needs no frame.
+            if (delivered.length > 0) {
+                this.sendEvent(running, 'message_delivered', { targetSeqs: delivered });
+            }
         };
         if (running.session) {
             running.session.send(text);
@@ -1250,7 +1392,7 @@ export class Supervisor {
             // 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)]));
+            this.requeue(running, held, text, originSeq);
             return;
         }
         // A person typing into the session is the clearest signal that the work is
@@ -1263,7 +1405,105 @@ export class Supervisor {
         // 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)]));
+        this.requeue(running, held, text, originSeq);
+    }
+    /**
+     * Nothing could take the message: put it back where it came from.
+     *
+     * Records that were already held keep their identity (and their queued
+     * announcement); a first-time refusal mints one and announces it.
+     */
+    requeue(running, held, text, originSeq) {
+        if (held.length > 0) {
+            // Already announced as queued when they first went in — re-announcing
+            // would be a second frame saying what the feed already knows.
+            running.pendingMessages.push(...held);
+            return;
+        }
+        this.queueMessage(running, running.journal.appendPending(text, undefined, originSeq));
+    }
+    /**
+     * Where this session's conversation stands, live process or not (ticket #126).
+     *
+     * Reads the running agent when there is one and remembers what it said;
+     * falls back to that memory when there is not. The provider session id is
+     * checked on the way out rather than on the way in: an anchor minted before
+     * a fork is not wrong, it simply belongs to a conversation this session no
+     * longer has.
+     */
+    currentAnchor(running) {
+        const providerSessionId = running.descriptor.providerSessionId;
+        const live = providerSessionId ? (running.session?.conversationAnchor() ?? null) : null;
+        if (live && providerSessionId) {
+            running.journal.recordAnchor(live, providerSessionId);
+            return { anchor: live, agentSession: providerSessionId };
+        }
+        // No live process to ask — and that is the COMMON case at the moment a
+        // restore point is taken: a parked session, a runner that just
+        // reconnected, the message right after a rewind. The journal keeps the
+        // tip, together with the conversation it belongs to.
+        const remembered = running.journal.lastAnchor;
+        return remembered
+            ? { anchor: remembered.anchor, agentSession: remembered.providerSessionId }
+            : null;
+    }
+    /**
+     * Take a restore point in front of the work that is about to start
+     * (ticket #126).
+     *
+     * Called from the delivery chain — which is already asynchronous because of
+     * attachments — rather than from `deliverMessage`, which is synchronous and
+     * has five exits. Never throws and never blocks delivery: a message must
+     * reach the agent whether or not a restore point could be taken.
+     *
+     * Three reasons it declines, and each of them is a state in which a snapshot
+     * would be a lie rather than a restore point:
+     *  - the machine's owner switched checkpoints off;
+     *  - the agent is mid-turn, so the tree is being written to as we read it;
+     *  - a repo-mutating command holds the repository.
+     */
+    async captureCheckpoint(running, kind, messageSeq) {
+        const worktreePath = running.worktreePath;
+        if (!worktreePath || this.opts.checkpointsEnabled === false)
+            return;
+        if (kind === 'TURN' && this.isWorktreeBusy(worktreePath))
+            return;
+        if (await this.isRepoLocked(worktreePath))
+            return;
+        // The anchor and the conversation it names travel TOGETHER: a point
+        // recorded against an older provider session stays usable, because the
+        // rewind resumes the session the point names rather than whichever one the
+        // session happens to be on now.
+        const anchor = this.currentAnchor(running);
+        const result = await createCheckpoint({
+            worktreePath,
+            sessionId: running.descriptor.id,
+            kind,
+            ...(messageSeq === undefined ? {} : { messageSeq }),
+            ...(anchor ? { agentAnchor: anchor.anchor, agentSession: anchor.agentSession } : {}),
+        });
+        if (this.isStale(running))
+            return;
+        if (!result.created) {
+            if (result.reason === 'too-large') {
+                // Loud, because the alternative is a session that quietly has no way
+                // back and a button that quietly is not there.
+                this.sendEvent(running, 'notice', {
+                    level: 'warn',
+                    text: 'This working tree is too large to take a restore point — rewind is unavailable for this step. Check that build output is in .gitignore.',
+                });
+            }
+            return;
+        }
+        this.sendEvent(running, 'checkpoint', {
+            ordinal: result.record.ordinal,
+            kind: result.record.kind,
+            createdAt: result.record.createdAt,
+            fileCount: result.record.fileCount,
+            canRewindContext: Boolean(result.record.agentAnchor),
+            ...(messageSeq === undefined ? {} : { messageSeq }),
+            ...(result.skippedFiles.length ? { skippedFiles: result.skippedFiles.slice(0, 20) } : {}),
+        });
     }
     /**
      * Deliver messages that raced session start (already journaled).
@@ -1299,6 +1539,13 @@ export class Supervisor {
                 });
                 return;
             }
+            // Anchored to the FIRST of the joined messages: that bubble is the one a
+            // person means by "put it back to before I said this".
+            await this.captureCheckpoint(running, 'TURN', pending[0]?.seq);
+            if (this.isStale(running)) {
+                running.pendingMessages.unshift(...pending);
+                return;
+            }
             this.deliverMessage(running, parts.join('\n\n'), pending);
         });
     }
@@ -1381,6 +1628,19 @@ export class Supervisor {
         // 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));
+        // Ticket #126: this list is the only moment the runner learns which
+        // sessions still exist. Deleting a session while its dev server is
+        // switched off leaves restore points — a full copy of a working tree —
+        // with no row anywhere pointing at them, and nothing else on this machine
+        // would ever collect them.
+        void pruneCheckpoints({ liveSessionIds: known }).then((result) => {
+            if (result.droppedRefs > 0) {
+                log.info('supervisor: collected orphaned restore points', {
+                    sessions: result.droppedSessions.length,
+                    refs: result.droppedRefs,
+                });
+            }
+        }, (error) => log.warn('supervisor: restore-point GC failed', { error: String(error) }));
         for (const [sessionId, running] of [...this.sessions]) {
             if (known.has(sessionId))
                 continue;
@@ -1657,6 +1917,11 @@ export class Supervisor {
                     });
                     this.journals.closeAndDelete(sessionId);
                     this.orphanMessages.delete(sessionId);
+                    // Ticket #126: the restore points are copies of this session's
+                    // working tree. The session is gone from the API, so they are the
+                    // last thing on this machine that still holds its content.
+                    if (workspacePath)
+                        await dropCheckpoints(workspacePath, sessionId);
                     return void reply({ ok: true, result: { removed: true, ...result } });
                 }
                 case 'reset_workspace':
@@ -1664,6 +1929,245 @@ export class Supervisor {
                         ok: false,
                         error: 'reset_workspace is not supported by this runner version',
                     });
+                case 'recall_message': {
+                    // Ticket #125: take a queued message back before any agent sees it.
+                    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: 'Unknown session' });
+                    const targetSeq = num(frame.args?.['targetSeq']);
+                    if (targetSeq === null)
+                        return void reply({ ok: false, error: 'targetSeq is required' });
+                    // NOT A SINGLE `await` FROM HERE TO THE REPLY. Frames are handled
+                    // concurrently (`void this.onFrame(frame)`, gotcha #68), so a yield
+                    // in this window would let the delivery chain hand the agent the
+                    // very message we are removing — and both sides would report success.
+                    const record = running.journal.findPendingBySeq(targetSeq);
+                    const index = record
+                        ? running.pendingMessages.findIndex((held) => held.id === record.id)
+                        : -1;
+                    if (!record || index < 0) {
+                        // Never queued, or a flush already took it out of the queue and is
+                        // downloading its files. Both read the same from where the user
+                        // stands: the agent has it. Answering `not_found` here would be a
+                        // lie about a session we know, and answering success would be a
+                        // promise we cannot keep — this is the only safe direction.
+                        return void reply({
+                            ok: true,
+                            result: { recalled: false, reason: 'already_delivered' },
+                        });
+                    }
+                    running.pendingMessages.splice(index, 1);
+                    running.journal.cancelPending(record.id);
+                    this.sendEvent(running, 'message_recalled', { targetSeq });
+                    return void reply({ ok: true, result: { recalled: true } });
+                }
+                // ─── Ticket #126: restore points ────────────────────────────────
+                case 'session_checkpoint': {
+                    const running = this.requireSession(frame.sessionId);
+                    if (typeof running === 'string')
+                        return void reply({ ok: false, error: running });
+                    if (this.opts.checkpointsEnabled === false) {
+                        return void reply({ ok: false, error: CHECKPOINTS_OFF });
+                    }
+                    if (!running.worktreePath) {
+                        return void reply({ ok: false, error: 'The session has no working folder yet' });
+                    }
+                    if (this.isWorktreeBusy(running.worktreePath)) {
+                        return void reply({ ok: false, error: AGENT_BUSY });
+                    }
+                    const before = (await listCheckpoints(running.worktreePath, running.descriptor.id))
+                        .length;
+                    await this.captureCheckpoint(running, 'MANUAL', num(frame.args?.['messageSeq']) ?? undefined);
+                    const after = await listCheckpoints(running.worktreePath, running.descriptor.id);
+                    if (after.length === before) {
+                        return void reply({ ok: false, error: 'A restore point could not be taken right now' });
+                    }
+                    return void reply({ ok: true, result: { ordinal: after.at(-1)?.ordinal } });
+                }
+                case 'session_checkpoints': {
+                    const running = this.requireSession(frame.sessionId);
+                    if (typeof running === 'string')
+                        return void reply({ ok: false, error: running });
+                    if (!running.worktreePath)
+                        return void reply({ ok: true, result: { items: [] } });
+                    const items = await listCheckpoints(running.worktreePath, running.descriptor.id);
+                    return void reply({
+                        ok: true,
+                        result: {
+                            items: items.map((item) => ({
+                                ordinal: item.ordinal,
+                                kind: item.kind,
+                                createdAt: item.createdAt,
+                                fileCount: item.fileCount,
+                                // An anchor is enough: it names its own conversation, and that
+                                // conversation is still on disk.
+                                canRewindContext: Boolean(item.agentAnchor),
+                                ...(item.messageSeq === undefined ? {} : { messageSeq: item.messageSeq }),
+                            })),
+                        },
+                    });
+                }
+                case 'session_rewind_preview': {
+                    const running = this.requireSession(frame.sessionId);
+                    if (typeof running === 'string')
+                        return void reply({ ok: false, error: running });
+                    const ordinal = num(frame.args?.['ordinal']);
+                    if (ordinal === null || !running.worktreePath) {
+                        return void reply({ ok: false, error: 'ordinal is required' });
+                    }
+                    const preview = await previewRewind({
+                        worktreePath: running.worktreePath,
+                        sessionId: running.descriptor.id,
+                        ordinal,
+                    });
+                    return void reply({ ok: true, result: preview });
+                }
+                case 'session_rewind_files': {
+                    const running = this.requireSession(frame.sessionId);
+                    if (typeof running === 'string')
+                        return void reply({ ok: false, error: running });
+                    if (this.opts.checkpointsEnabled === false) {
+                        return void reply({ ok: false, error: CHECKPOINTS_OFF });
+                    }
+                    const ordinal = num(frame.args?.['ordinal']);
+                    if (ordinal === null || !running.worktreePath) {
+                        return void reply({ ok: false, error: 'ordinal is required' });
+                    }
+                    if (this.isWorktreeBusy(running.worktreePath)) {
+                        return void reply({ ok: false, error: AGENT_BUSY });
+                    }
+                    const confirmRaw = frame.args?.['confirmDeletes'];
+                    const confirmDeletes = Array.isArray(confirmRaw)
+                        ? confirmRaw.filter((p) => typeof p === 'string')
+                        : [];
+                    const expectedTreeOid = frame.args?.['expectedTreeOid'];
+                    // The repo lock, unlike the read-only checkpoint, IS taken here: this
+                    // writes the working tree, exactly like commit, apply and revert.
+                    const result = await this.withRepoLockFor(running.worktreePath, () => applyRewind({
+                        worktreePath: running.worktreePath,
+                        sessionId: running.descriptor.id,
+                        ordinal,
+                        confirmDeletes,
+                        ...(typeof expectedTreeOid === 'string' && expectedTreeOid
+                            ? { expectedTreeOid }
+                            : {}),
+                    }));
+                    this.sendEvent(running, 'checkpoint', {
+                        ordinal: result.safety.ordinal,
+                        kind: result.safety.kind,
+                        createdAt: result.safety.createdAt,
+                        fileCount: result.safety.fileCount,
+                        canRewindContext: Boolean(result.safety.agentAnchor),
+                        // This frame IS the browser's offer of «Undo rewind» — the point it
+                        // names belongs to no message, so there is nowhere else the offer
+                        // could come from. Withheld when the rewind was itself an undo:
+                        // going back again is a redo, and a button that quietly changes
+                        // meaning after one press is worse than no button.
+                        undoable: result.rewoundToKind !== 'SAFETY',
+                    });
+                    this.sendEvent(running, 'system_note', {
+                        code: 'files_rewound',
+                        text: `Working tree put back to an earlier point: ${result.restored} file(s) restored, ${result.recreated} brought back, ${result.deleted} removed. This is undoable — the state you just left was saved first.`,
+                    });
+                    return void reply({ ok: true, result });
+                }
+                case 'context_rewind': {
+                    const running = this.requireSession(frame.sessionId);
+                    if (typeof running === 'string')
+                        return void reply({ ok: false, error: running });
+                    const ordinal = num(frame.args?.['ordinal']);
+                    if (ordinal === null || !running.worktreePath) {
+                        return void reply({ ok: false, error: 'ordinal is required' });
+                    }
+                    if (this.isWorktreeBusy(running.worktreePath)) {
+                        return void reply({ ok: false, error: AGENT_BUSY });
+                    }
+                    const items = await listCheckpoints(running.worktreePath, running.descriptor.id);
+                    const point = items.find((item) => item.ordinal === ordinal);
+                    // No equality check against the CURRENT provider session any more.
+                    // The point names the conversation its anchor lives in, and that
+                    // conversation is still on disk — which is what makes rewinding
+                    // twice, or rewinding the first message after a rewind, work at all.
+                    // Requiring the ids to match refused both, on the grounds that the
+                    // point «predates a conversation rewind» — true, and beside the
+                    // point.
+                    const agentSession = point?.agentSession ?? running.descriptor.providerSessionId;
+                    if (!point?.agentAnchor || !agentSession) {
+                        return void reply({
+                            ok: false,
+                            error: 'The agent had not answered yet at this point, so there is no conversation to rewind to. Its files can still be restored.',
+                        });
+                    }
+                    // What an agent remembers is fixed when its process starts, so the
+                    // rewind is applied by replacing that process. Park the live one and
+                    // bring it straight back — the CLI's own rewind happens when you
+                    // press it, and so does this one. Waiting for the user's next message
+                    // would leave them staring at a page where nothing had changed.
+                    running.rewindAnchor = { anchor: point.agentAnchor, agentSession };
+                    // Parked, not relaunched. A launch with no prompt does not resume
+                    // the conversation at all — the CLI reads the anchor only when the
+                    // first input arrives — so spawning a process here would idle in a
+                    // runner slot and change nothing. The anchor is consumed by the
+                    // launch the user's next message triggers, which is the same moment
+                    // the CLI validates it either way.
+                    if (running.session)
+                        this.park(running, { quiet: true });
+                    // The conversation tip is now THIS point — that is what a rewind
+                    // means — so the next restore point must record it, not the message
+                    // the user just rewound away from (which `park()` above would
+                    // otherwise have left behind, QA-120 M3). Writing it here is also
+                    // what lets the very next message be rewound in turn: it inherits a
+                    // tip that names a conversation still on disk.
+                    running.journal.recordAnchor(point.agentAnchor, agentSession);
+                    // The cut is announced NOW, and taken back if the CLI turns out not
+                    // to know the anchor.
+                    //
+                    // Waiting for confirmation was tried and is not possible: a launch
+                    // with no prompt does not resume at all until the first input, so
+                    // `system:init` — and with it any proof the fork happened — never
+                    // arrives on its own (measured: 20s, no init). Holding the cut until
+                    // then meant the page did not change when the button was pressed,
+                    // and the late cut then swallowed the message the user had sent in
+                    // the meantime.
+                    //
+                    // So the feed is cut optimistically and CORRECTED if the resume is
+                    // refused — an amendment, exactly like every other removal here.
+                    if (point?.messageSeq !== undefined) {
+                        const cut = this.sendEvent(running, 'session_rewound', {
+                            targetSeq: point.messageSeq,
+                        });
+                        running.pendingRewind = { rewoundSeq: cut.seq };
+                    }
+                    this.sendEvent(running, 'system_note', {
+                        code: 'context_rewound',
+                        text: (point?.messageSeq ?? 0) > 0
+                            ? 'Rewound to an earlier point — the agent no longer remembers anything after it, and your message is back in the composer.'
+                            : 'Rewound to an earlier point — the agent no longer remembers anything after it.',
+                    });
+                    return void reply({ ok: true, result: { rewound: true } });
+                }
+                case 'compact_context': {
+                    const running = this.requireSession(frame.sessionId);
+                    if (typeof running === 'string')
+                        return void reply({ ok: false, error: running });
+                    if (!running.session) {
+                        return void reply({
+                            ok: false,
+                            error: 'The agent is not running — send a message first, then compact',
+                        });
+                    }
+                    const done = await running.session.compact();
+                    if (!done) {
+                        return void reply({
+                            ok: false,
+                            error: 'The agent could not compact right now — wait for the current turn to finish',
+                        });
+                    }
+                    return void reply({ ok: true, result: { started: true } });
+                }
                 case 'git_status': {
                     const paths = gitCommandPaths(frame.args);
                     if (!paths)
@@ -2265,15 +2769,30 @@ export class Supervisor {
      */
     withRepoLock(repoKey, fn) {
         const previous = this.repoLocks.get(repoKey) ?? Promise.resolve();
+        this.repoLockDepth.set(repoKey, (this.repoLockDepth.get(repoKey) ?? 0) + 1);
         const run = previous.catch(() => undefined).then(fn);
         const tail = run.catch(() => undefined);
         this.repoLocks.set(repoKey, tail);
         void tail.then(() => {
+            const depth = (this.repoLockDepth.get(repoKey) ?? 1) - 1;
+            if (depth <= 0)
+                this.repoLockDepth.delete(repoKey);
+            else
+                this.repoLockDepth.set(repoKey, depth);
             if (this.repoLocks.get(repoKey) === tail)
                 this.repoLocks.delete(repoKey);
         });
         return run;
     }
+    /** Is a repo-mutating command queued or running for this path right now? */
+    async isRepoLocked(pathInsideRepo) {
+        try {
+            return (this.repoLockDepth.get(await repoKeyFor(pathInsideRepo)) ?? 0) > 0;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * 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
@@ -2282,6 +2801,17 @@ export class Supervisor {
     async withRepoLockFor(pathInsideRepo, fn) {
         return this.withRepoLock(await repoKeyFor(pathInsideRepo), fn);
     }
+    /**
+     * The live session this command names, or the sentence to refuse it with.
+     *
+     * A string return is deliberately unmistakable for a session: every caller
+     * has to branch on the type, so "I did not check" cannot compile.
+     */
+    requireSession(sessionId) {
+        if (!sessionId)
+            return 'sessionId is required';
+        return this.sessions.get(sessionId) ?? 'Unknown session';
+    }
     /** A session actively mid-turn in this worktree — git writes must wait. */
     isWorktreeBusy(worktreePath) {
         for (const running of this.sessions.values()) {
@@ -2299,6 +2829,13 @@ export class Supervisor {
     // 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;
+    /**
+     * Journal an event, put it on the wire, and return it.
+     *
+     * The return value matters since ticket #125: the seq assigned here is the
+     * only name the browser and the runner share for one message, so the caller
+     * that echoes a user bubble has to be able to read it back.
+     */
     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) {
@@ -2323,6 +2860,7 @@ export class Supervisor {
             running.lastReported = 'WAITING_PERMISSION';
             this.syncBudgetClock(running);
         }
+        return event;
     }
     reportStatus(sessionId, status, extra) {
         const running = this.sessions.get(sessionId);