@bridge4dev/runner 0.27.0 → 0.29.0

package/dist/config.d.ts

@@ -64,6 +64,25 @@ declare const ConfigSchema: z.ZodObject<{
     }, {
         enabled?: boolean | undefined;
     }>>;
+    /**
+     * Ticket #126: the machine owner's veto over restore points.
+     *
+     * A restore point is a copy of the working tree, kept on this machine, in an
+     * object store of the runner's own. That is disk this server's owner pays
+     * for and content they may not want duplicated at all — so the same rule as
+     * `[verify]` applies: `enabled = false` means the capability is not
+     * announced, the dashboard draws no rewind action, and no snapshot is ever
+     * taken. Secrets are excluded from a checkpoint in any case (`policy.ts`
+     * decides what counts), but "excluded" is a promise, and switching the whole
+     * thing off is a fact.
+     */
+    checkpoints: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+    }, {
+        enabled?: boolean | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     api: {
         url: string;
@@ -74,6 +93,9 @@ declare const ConfigSchema: z.ZodObject<{
         name: string;
         token: string;
     };
+    checkpoints?: {
+        enabled: boolean;
+    } | undefined;
     mcp?: {
         url: string;
         token: string;
@@ -97,6 +119,9 @@ declare const ConfigSchema: z.ZodObject<{
         name: string;
         token: string;
     };
+    checkpoints?: {
+        enabled?: boolean | undefined;
+    } | undefined;
     mcp?: {
         url: string;
         token: string;

package/dist/config.js

@@ -59,6 +59,23 @@ const ConfigSchema = z.object({
         enabled: z.boolean().default(true),
     })
         .optional(),
+    /**
+     * Ticket #126: the machine owner's veto over restore points.
+     *
+     * A restore point is a copy of the working tree, kept on this machine, in an
+     * object store of the runner's own. That is disk this server's owner pays
+     * for and content they may not want duplicated at all — so the same rule as
+     * `[verify]` applies: `enabled = false` means the capability is not
+     * announced, the dashboard draws no rewind action, and no snapshot is ever
+     * taken. Secrets are excluded from a checkpoint in any case (`policy.ts`
+     * decides what counts), but "excluded" is a promise, and switching the whole
+     * thing off is a fact.
+     */
+    checkpoints: z
+        .object({
+        enabled: z.boolean().default(true),
+    })
+        .optional(),
 });
 export function loadConfig() {
     const file = configFilePath();

package/dist/index.js

@@ -116,6 +116,8 @@ function runnerCapabilities(apiUrlOverride) {
     // feature is that a DevBridge manager approves every command first — but the
     // person who owns the server gets the last word on whether it exists here.
     const verifyEnabled = config?.verify?.enabled !== false;
+    // Ticket #126: the same veto, for restore points. Default on.
+    const checkpointsEnabled = config?.checkpoints?.enabled !== false;
     return {
         agents: installedAgents(),
         git: true,
@@ -231,6 +233,22 @@ function runnerCapabilities(apiUrlOverride) {
         ...(verifyEnabled ? { previewWorktrees: true } : {}),
         /** Session 14: one-shot agent-written commit messages. */
         commitMessages: true,
+        /**
+         * Ticket #126: restore points for the working tree, and the rewind that
+         * uses them. Withheld — not reported as false — when the machine's owner
+         * switched them off, by the same rule as `verifyRuns`.
+         */
+        ...(checkpointsEnabled
+            ? { sessionCheckpoints: true }
+            : { checkpointsBlocked: 'disabled-by-config' }),
+        /**
+         * Ticket #126: rewinding what the AGENT remembers, and `/compact` on
+         * demand. Both agents can do both — Claude through `resumeSessionAt` +
+         * `forkSession`, Codex through the stable `thread/fork { lastTurnId }` and
+         * `thread/compact/start` of app-server 0.145.0.
+         */
+        contextRewind: true,
+        contextCompaction: true,
         /**
          * Session 15: `git_status` reports whether the PROJECT FOLDER is clean, so
          * the panel can say what is blocking an Apply instead of offering a button
@@ -321,6 +339,17 @@ function runnerCapabilities(apiUrlOverride) {
             'git_merge_abort',
             'recipe_state',
             'propose_commit_message',
+            'recall_message',
+            'compact_context',
+            ...(checkpointsEnabled
+                ? [
+                    'session_checkpoint',
+                    'session_checkpoints',
+                    'session_rewind_preview',
+                    'session_rewind_files',
+                    'context_rewind',
+                ]
+                : []),
             ...(verifyEnabled
                 ? ['verify_start', 'verify_status', 'verify_cancel', 'preview_checkout', 'preview_stop']
                 : []),
@@ -485,6 +514,7 @@ async function cmdDaemon() {
         // The same veto the capability list honours — announced AND enforced, so a
         // frame from an API that has not noticed still cannot start a run.
         verifyEnabled: config.verify?.enabled !== false,
+        checkpointsEnabled: config.checkpoints?.enabled !== false,
         apiUrl: config.api.url,
         // Used to fetch the files a user attaches to a message (session 10) — the
         // same token the WS connection authenticates with, never passed onwards.

package/dist/journal.d.ts

@@ -20,6 +20,16 @@ export interface PendingMessage {
      * session worktree is guaranteed to exist.
      */
     attachments?: PendingAttachment[];
+    /**
+     * Feed seq of the `message` event this text was echoed under (ticket #125).
+     *
+     * The only identifier the queue and the browser share: the API never sees
+     * `id` (it is minted here), and the `session_message` frame carries no id of
+     * its own — so the seq of the bubble the user is looking at is what a recall
+     * has to name. Absent on records written by a runner older than 0.28.0:
+     * those cannot be recalled, which is correct — they predate the feature.
+     */
+    seq?: number;
 }
 export interface PendingAttachment {
     id: string;
@@ -43,6 +53,11 @@ export declare class SessionJournal {
         extra?: Record<string, unknown>;
         epoch?: number;
     } | null;
+    /** The agent's conversation tip, and the provider session it lives in. */
+    lastAnchor: {
+        anchor: string;
+        providerSessionId: string;
+    } | null;
     constructor(sessionId: string, dir?: string);
     private replay;
     private write;
@@ -60,6 +75,14 @@ export declare class SessionJournal {
      * Statuses are fire-and-forget on the wire; journaling the latest one lets
      * the supervisor re-report it after a reconnect (QA-96 F1).
      */
+    /**
+     * Remember the conversation tip across a process gap (ticket #126).
+     *
+     * Written only when it actually moves: an agent that says nothing writes
+     * nothing, and the same line repeated every turn would grow the file for no
+     * reason.
+     */
+    recordAnchor(anchor: string, providerSessionId: string): void;
     recordStatus(status: string, extra?: Record<string, unknown>, epoch?: number): void;
     /** Assign the next seq and persist the event before it is sent. */
     append(eventType: string, payload: Record<string, unknown>): JournalEvent;
@@ -77,9 +100,19 @@ export declare class SessionJournal {
      * it is queued in memory, so the ordering is "on disk, then held" — a crash
      * between the two costs a duplicate delivery at worst, never a lost message.
      */
-    appendPending(text: string, attachments?: PendingAttachment[]): PendingMessage;
+    appendPending(text: string, attachments?: PendingAttachment[], seq?: number): PendingMessage;
     /** The message reached an agent — stop replaying it after a restart. */
     resolvePending(id: string): void;
+    /**
+     * The user recalled the message before any agent saw it (ticket #125).
+     *
+     * Returns false when the record is already gone — which is the answer to
+     * "did I win the race", and the only safe way to ask it: the caller must
+     * report `already_delivered` rather than a success it cannot back up.
+     */
+    cancelPending(id: string): boolean;
+    /** The queued record echoed under this feed seq, if it is still queued. */
+    findPendingBySeq(seq: number): PendingMessage | undefined;
     /** Messages still waiting, oldest first (ids are minted in order). */
     pending(): PendingMessage[];
     get lastAssignedSeq(): number;

package/dist/journal.js

@@ -19,6 +19,8 @@ export class SessionJournal {
     bytesOnDisk = 0;
     /** Last status reported for this session — replayed after a reconnect. */
     lastStatus = null;
+    /** The agent's conversation tip, and the provider session it lives in. */
+    lastAnchor = null;
     constructor(sessionId, dir = journalDir()) {
         this.sessionId = sessionId;
         fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -52,6 +54,9 @@ export class SessionJournal {
             else if (parsed.kind === 'ack') {
                 this.unackedBySeq.delete(parsed.seq);
             }
+            else if (parsed.kind === 'anchor') {
+                this.lastAnchor = { anchor: parsed.anchor, providerSessionId: parsed.providerSessionId };
+            }
             else if (parsed.kind === 'status') {
                 this.lastStatus = {
                     status: parsed.status,
@@ -64,6 +69,7 @@ export class SessionJournal {
                     id: parsed.id,
                     text: parsed.text,
                     ...(parsed.attachments?.length ? { attachments: parsed.attachments } : {}),
+                    ...(typeof parsed.seq === 'number' ? { seq: parsed.seq } : {}),
                 });
                 // Ids are `p<n>`; keep the counter above whatever the file holds so a
                 // restarted runner cannot mint an id that is already in flight.
@@ -71,7 +77,7 @@ export class SessionJournal {
                 if (Number.isFinite(n) && n >= this.pendingCounter)
                     this.pendingCounter = n + 1;
             }
-            else if (parsed.kind === 'pending_done') {
+            else if (parsed.kind === 'pending_done' || parsed.kind === 'pending_cancelled') {
                 this.pendingById.delete(parsed.id);
             }
             else if (parsed.kind === 'seq') {
@@ -98,6 +104,9 @@ export class SessionJournal {
         for (const event of this.unacked()) {
             lines.push({ kind: 'event', ...event, ts: new Date().toISOString() });
         }
+        if (this.lastAnchor) {
+            lines.push({ kind: 'anchor', ...this.lastAnchor });
+        }
         if (this.lastStatus) {
             lines.push({
                 kind: 'status',
@@ -115,6 +124,7 @@ export class SessionJournal {
                 id: record.id,
                 text: record.text,
                 ...(record.attachments?.length ? { attachments: record.attachments } : {}),
+                ...(record.seq === undefined ? {} : { seq: record.seq }),
                 ts: new Date().toISOString(),
             });
         }
@@ -138,6 +148,21 @@ export class SessionJournal {
      * Statuses are fire-and-forget on the wire; journaling the latest one lets
      * the supervisor re-report it after a reconnect (QA-96 F1).
      */
+    /**
+     * Remember the conversation tip across a process gap (ticket #126).
+     *
+     * Written only when it actually moves: an agent that says nothing writes
+     * nothing, and the same line repeated every turn would grow the file for no
+     * reason.
+     */
+    recordAnchor(anchor, providerSessionId) {
+        if (this.lastAnchor?.anchor === anchor &&
+            this.lastAnchor.providerSessionId === providerSessionId) {
+            return;
+        }
+        this.lastAnchor = { anchor, providerSessionId };
+        this.write({ kind: 'anchor', anchor, providerSessionId });
+    }
     recordStatus(status, extra, epoch) {
         this.lastStatus = {
             status,
@@ -187,18 +212,20 @@ export class SessionJournal {
      * it is queued in memory, so the ordering is "on disk, then held" — a crash
      * between the two costs a duplicate delivery at worst, never a lost message.
      */
-    appendPending(text, attachments) {
+    appendPending(text, attachments, seq) {
         const id = `p${this.pendingCounter++}`;
         const record = {
             id,
             text,
             ...(attachments?.length ? { attachments } : {}),
+            ...(seq === undefined ? {} : { seq }),
         };
         this.write({
             kind: 'pending',
             id,
             text,
             ...(attachments?.length ? { attachments } : {}),
+            ...(seq === undefined ? {} : { seq }),
             ts: new Date().toISOString(),
         });
         this.pendingById.set(id, record);
@@ -211,6 +238,28 @@ export class SessionJournal {
         this.pendingById.delete(id);
         this.write({ kind: 'pending_done', id });
     }
+    /**
+     * The user recalled the message before any agent saw it (ticket #125).
+     *
+     * Returns false when the record is already gone — which is the answer to
+     * "did I win the race", and the only safe way to ask it: the caller must
+     * report `already_delivered` rather than a success it cannot back up.
+     */
+    cancelPending(id) {
+        if (!this.pendingById.has(id))
+            return false;
+        this.pendingById.delete(id);
+        this.write({ kind: 'pending_cancelled', id });
+        return true;
+    }
+    /** The queued record echoed under this feed seq, if it is still queued. */
+    findPendingBySeq(seq) {
+        for (const record of this.pendingById.values()) {
+            if (record.seq === seq)
+                return record;
+        }
+        return undefined;
+    }
     /** Messages still waiting, oldest first (ids are minted in order). */
     pending() {
         return [...this.pendingById.values()];

package/dist/paths.d.ts

@@ -22,6 +22,16 @@ export declare function worktreesDir(): string;
 export declare function knownWorkspacesPath(): string;
 /** Session 14: the single preview checkout per repository. */
 export declare function previewsDir(): string;
+/**
+ * Ticket #126: git object stores holding the sessions' restore points.
+ *
+ * Deliberately under `devbridge-runner/`, and deliberately NOT under
+ * `worktrees/` or `previews/` — those two are excluded from the runner-tree
+ * rule in `SECRET_PATH_PATTERNS` (the agent has to be able to read its own
+ * workspace), so anything that must stay unreadable to the agent belongs
+ * exactly here.
+ */
+export declare function checkpointsDir(): string;
 /**
  * Per-session MCP config files (ticket #119).
  *

package/dist/paths.js

@@ -54,6 +54,18 @@ export function knownWorkspacesPath() {
 export function previewsDir() {
     return path.join(stateDir(), 'previews');
 }
+/**
+ * Ticket #126: git object stores holding the sessions' restore points.
+ *
+ * Deliberately under `devbridge-runner/`, and deliberately NOT under
+ * `worktrees/` or `previews/` — those two are excluded from the runner-tree
+ * rule in `SECRET_PATH_PATTERNS` (the agent has to be able to read its own
+ * workspace), so anything that must stay unreadable to the agent belongs
+ * exactly here.
+ */
+export function checkpointsDir() {
+    return path.join(stateDir(), 'checkpoints');
+}
 /**
  * Per-session MCP config files (ticket #119).
  *

package/dist/policy.js

@@ -97,6 +97,16 @@ const SECRET_PATH_PATTERNS = [
     // its own workspace — caught by the existing suite the moment it was tried.
     /(^|\/)devbridge-mcp\.[^/]*\.json$/,
     /(^|\/)devbridge-runner(\/(?!worktrees(\/|$)|previews(\/|$))|$)/,
+    // Ticket #126: the object store holding this session's restore points — a
+    // full copy of the working tree as it was at every turn.
+    //
+    // The runner-directory rule above already covers it on an ordinary install.
+    // This one is for the case that rule cannot see: under a
+    // `DEVBRIDGE_RUNNER_HOME` override the path carries no `devbridge-runner`
+    // segment at all, which is exactly the gap the MCP-config entry was added
+    // for. Matching the distinctive `checkpoints/<hash>.git` shape closes it
+    // wherever the state directory ends up.
+    /(^|\/)checkpoints\/[0-9a-f]{8,}\.git(\/|$)/,
     /(^|\/)(shadow|passwd|sudoers)$/,
     /(^|\/)\.netrc$/,
     /(^|\/)\.git-credentials$/,
@@ -440,6 +450,11 @@ const SECRET_COMMAND_PATTERNS = [
     // never contains the suffix.
     /devbridge-mcp/,
     /devbridge-runner\/(?!worktrees|previews)/,
+    // Ticket #126 — the command form of the restore-point entry above. Written
+    // as its own rule for the same reason gotcha #110 exists: a path in one
+    // secret table and not the other is theatre, and `git --git-dir=…` /
+    // `cat …/checkpoints/<hash>.git/…` walks past a Read-tool guard entirely.
+    /checkpoints\/[0-9a-f]{8,}\.git/,
     /devbridge-runner(?=\s|$|['"])/,
     /\/etc\/(shadow|passwd|sudoers)/,
     /\.git-credentials/,

package/dist/protocol.d.ts

@@ -126,8 +126,8 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     model: string | null;
     effort: string | null;
     prompt: string;
-    epoch: number;
     providerSessionId: string | null;
+    epoch: number;
     lastSeq: number;
     costUsd: number;
     activeMsBase: number;
@@ -328,8 +328,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         model: string | null;
         effort: string | null;
         prompt: string;
-        epoch: number;
         providerSessionId: string | null;
+        epoch: number;
         lastSeq: number;
         costUsd: number;
         activeMsBase: number;
@@ -410,8 +410,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         model: string | null;
         effort: string | null;
         prompt: string;
-        epoch: number;
         providerSessionId: string | null;
+        epoch: number;
         lastSeq: number;
         costUsd: number;
         activeMsBase: number;
@@ -642,8 +642,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         model: string | null;
         effort: string | null;
         prompt: string;
-        epoch: number;
         providerSessionId: string | null;
+        epoch: number;
         lastSeq: number;
         costUsd: number;
         activeMsBase: number;
@@ -722,8 +722,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         model: string | null;
         effort: string | null;
         prompt: string;
-        epoch: number;
         providerSessionId: string | null;
+        epoch: number;
         lastSeq: number;
         costUsd: number;
         activeMsBase: number;

package/dist/supervisor.d.ts

@@ -39,6 +39,14 @@ export interface SupervisorOptions {
     verifyEnabled?: boolean;
     /** Test seam for the one-shot commit-message run. */
     proposeCommitMessage?: typeof proposeCommitMessage;
+    /**
+     * `[checkpoints] enabled` from the runner's own config (ticket #126), by the
+     * same rule as `[verify] enabled`: restore points are copies of the working
+     * tree kept on this machine, so the machine's owner has the last word on
+     * whether they are taken at all. `false` means the capability is not
+     * announced and no rewind can be started.
+     */
+    checkpointsEnabled?: boolean;
 }
 export declare class Supervisor {
     private readonly ws;
@@ -61,6 +69,17 @@ export declare class Supervisor {
     private readonly authRelay;
     /** Serialises repo-mutating git commands per workspace repo (QA-99 MAJOR-1). */
     private readonly repoLocks;
+    /**
+     * 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.
+     */
+    private readonly repoLockDepth;
     /** An update is installing right now — a second one would fight it. */
     private selfUpdateInFlight;
     /** Session 14: one project-recipe run per machine, and its verdict queue. */
@@ -198,6 +217,14 @@ export declare class Supervisor {
      * slot.
      */
     private isParkable;
+    /**
+     * 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).
+     */
     private park;
     private forwardEvent;
     /**
@@ -210,6 +237,16 @@ export declare class Supervisor {
      */
     private onQuestionAnswer;
     private onUserMessage;
+    /**
+     * 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.
+     */
+    private queueMessage;
     /**
      * Run delivery work for one session, strictly after whatever is already
      * queued for it. Order is the whole point: two messages typed seconds apart
@@ -235,6 +272,39 @@ export declare class Supervisor {
      * the message is retired from disk only once an agent has it.
      */
     private deliverMessage;
+    /**
+     * 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.
+     */
+    private requeue;
+    /**
+     * 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.
+     */
+    private currentAnchor;
+    /**
+     * 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.
+     */
+    private captureCheckpoint;
     /**
      * Deliver messages that raced session start (already journaled).
      *
@@ -263,15 +333,31 @@ export declare class Supervisor {
      * mark the other session failed (QA-99 MAJOR-1).
      */
     private withRepoLock;
+    /** Is a repo-mutating command queued or running for this path right now? */
+    private isRepoLocked;
     /**
      * Same lock, keyed by the shared repository rather than by whichever path the
      * caller happened to have. A worktree commit and a workspace squash-merge
      * touch one repo, so they must take one key (see `repoKeyFor`).
      */
     private withRepoLockFor;
+    /**
+     * 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.
+     */
+    private requireSession;
     /** A session actively mid-turn in this worktree — git writes must wait. */
     private isWorktreeBusy;
     private static readonly EVENT_PAYLOAD_CAP;
+    /**
+     * 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.
+     */
     private sendEvent;
     private reportStatus;
     /** Graceful daemon shutdown: kill agents, keep sessions resumable server-side. */