@bridge4dev/runner 0.26.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/environment.d.ts

@@ -77,6 +77,20 @@ export interface AgentConfigContour {
     plugins: boolean;
     codexDir: boolean;
     codexConfig: boolean;
+    /**
+     * MCP servers an agent session in this home will actually see, and the ones
+     * that are configured but invisible to it.
+     *
+     * Both numbers, because the difference IS the bug. `claude mcp add` defaults
+     * to LOCAL scope, which stores the server under
+     * `~/.claude.json → projects["<cwd>"].mcpServers` — keyed by the directory it
+     * was added from. Runner sessions work in a per-session git worktree, so that
+     * key never matches and the servers are simply absent. On a live machine this
+     * read as «the agent lost Playwright and Context7», and the only cure was
+     * moving them to user scope (the top-level `mcpServers`).
+     */
+    mcpUserScope: number;
+    mcpProjectScope: number;
 }
 export declare function agentConfigContour(home?: string): AgentConfigContour;
 /**
@@ -116,6 +130,7 @@ export interface ToolCheck {
     /** Set when the tool is there but this user cannot use it. */
     problem?: string;
 }
+export declare function whichExecutable(name: string): string | null;
 /**
  * Node, as THIS user sees it.
  *

package/dist/environment.js

@@ -114,6 +114,27 @@ export async function addSafeDirectory(repoPath) {
         timeout: 10_000,
     });
 }
+/**
+ * Count MCP servers in the CLI's own config file, by scope.
+ *
+ * Reads `~/.claude.json` directly rather than shelling out to `claude mcp
+ * list`: this is a diagnostic that must work when the CLI is missing, and it
+ * must not spend ~300 MB and a second of a doctor run to answer.
+ */
+function countMcpServers(home) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(home, '.claude.json'), 'utf8'));
+        const user = Object.keys(parsed.mcpServers ?? {}).length;
+        let project = 0;
+        for (const entry of Object.values(parsed.projects ?? {})) {
+            project += Object.keys(entry?.mcpServers ?? {}).length;
+        }
+        return { user, project };
+    }
+    catch {
+        return { user: 0, project: 0 };
+    }
+}
 function countAllowRules(file) {
     try {
         const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -152,6 +173,7 @@ export function agentConfigContour(home = os.homedir()) {
     const localSettings = path.join(claudeDir, 'settings.local.json');
     const commandsDir = path.join(claudeDir, 'commands');
     const codexDir = path.join(home, '.codex');
+    const mcp = countMcpServers(home);
     return {
         home,
         claudeDir: fs.existsSync(claudeDir),
@@ -166,6 +188,8 @@ export function agentConfigContour(home = os.homedir()) {
         plugins: fs.existsSync(path.join(claudeDir, 'plugins')),
         codexDir: fs.existsSync(codexDir),
         codexConfig: fs.existsSync(path.join(codexDir, 'config.toml')),
+        mcpUserScope: mcp.user,
+        mcpProjectScope: mcp.project,
     };
 }
 /**
@@ -266,7 +290,7 @@ export function knownWorkspacePaths() {
         return [];
     }
 }
-function whichExecutable(name) {
+export function whichExecutable(name) {
     for (const dir of (process.env['PATH'] ?? '').split(path.delimiter).filter(Boolean)) {
         const candidate = path.join(dir, name);
         try {

package/dist/index.js

@@ -10,7 +10,8 @@ import { CodexAdapter } from './adapters/codex.js';
 import { ensureCodexHome } from './adapters/codex-home.js';
 import { loadConfig, requireConfig, saveConfig } from './config.js';
 import { log } from './log.js';
-import { installIsWritable, isSupervisedProcess, resolveInstalledPackageDir, } from './self-update.js';
+import { installIsWritable, installPrefixFor, isSupervisedProcess, manualUpdateCommand, resolveInstalledPackageDir, } from './self-update.js';
+import { applyStoredClaudeToken } from './agent-auth.js';
 import { Supervisor } from './supervisor.js';
 import { readStatusFile, isPidAlive, writeStatusFile, STATUS_FRESH_MS } from './status-file.js';
 import { RunnerWsClient } from './ws-client.js';
@@ -103,13 +104,20 @@ function hasExecutable(name) {
  * older runner drops a frame it cannot parse without ever replying, so a
  * command it does not know would just hang until the gateway timeout.
  */
-function runnerCapabilities() {
+function runnerCapabilities(apiUrlOverride) {
     const config = loadConfig();
+    // At PAIR time there is no config yet, so the API this runner is about to
+    // belong to has to be passed in — otherwise the very first `hello` (the one
+    // that creates the server record) would omit the update command, and the
+    // dashboard would show a stale one until the daemon reconnected.
+    const apiUrl = apiUrlOverride ?? config?.api.url;
     const localLimit = config?.limits?.max_sessions;
     // Session 14: the machine owner's veto. Default on — the safety of the
     // 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,
@@ -135,6 +143,37 @@ function runnerCapabilities() {
          * is only half the instruction without a name to restart under.
          */
         runnerUser: runnerIdentity().user,
+        /**
+         * Which agent CLIs are actually on this user's PATH (0.27.0).
+         *
+         * Different question from `agents` above, and the difference cost a
+         * support round: `agents` says which agents can RUN sessions (Claude
+         * always can — the SDK bundles its own binary), while signing in needs the
+         * standalone CLI to exist for this user. On a dedicated-user install it
+         * routinely does not, and the sign-in button then failed with an error
+         * about `script`, about a machine whose real problem was that nobody had
+         * installed `claude` for that user at all.
+         */
+        agentClis: {
+            claude: hasExecutable('claude'),
+            codex: hasExecutable('codex'),
+        },
+        /**
+         * Where npm put this package, and the command that updates it here
+         * (0.27.0).
+         *
+         * The dashboard used to assemble the update command itself and then patch
+         * it with string surgery for the dedicated-user case. It cannot: only this
+         * process knows the prefix it was installed into, and `npm install -g`
+         * without that prefix is precisely the EACCES the owner pasted. So the
+         * machine states its own command and the panel just shows it.
+         */
+        ...(installPrefixFor() ? { npmPrefix: installPrefixFor() } : {}),
+        ...(apiUrl
+            ? {
+                updateCommand: manualUpdateCommand(`${apiUrl.replace(/\/$/, '')}/api/v1/dev-setup/runner.tgz`),
+            }
+            : {}),
         /**
          * A stricter ceiling set on the machine itself (layer 1). Reported so the
          * dashboard can explain why raising the number there changed nothing.
@@ -194,6 +233,22 @@ function runnerCapabilities() {
         ...(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
@@ -284,6 +339,17 @@ function runnerCapabilities() {
             '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']
                 : []),
@@ -306,7 +372,7 @@ async function cmdPair(args) {
             name,
             runnerVersion: RUNNER_VERSION,
             osInfo: `${os.type()} ${os.release()} ${os.arch()}`.slice(0, 200),
-            capabilities: runnerCapabilities(),
+            capabilities: runnerCapabilities(apiUrl),
         }),
     });
     const body = (await response.json().catch(() => null));
@@ -429,6 +495,12 @@ async function cmdDaemon() {
     log.info('daemon starting', { version: RUNNER_VERSION, server: config.server.name });
     sweepOrphanedMcpConfigs();
     await repairResourceLimits();
+    // A Claude token this runner captured through the sign-in relay. Applied
+    // BEFORE any adapter exists, because `scrubbedEnv()` copies it out of this
+    // process's environment for every session it starts.
+    if (applyStoredClaudeToken()) {
+        log.info('daemon: using the Claude token stored on this server');
+    }
     const agents = installedAgents();
     const ws = new RunnerWsClient(config.api.ws_url, config.server.token, runnerCapabilities());
     const codex = agents.includes('codex') ? bootstrapCodex(config) : null;
@@ -442,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.
@@ -654,8 +727,16 @@ async function runnerChecks() {
         const state = await systemctlProperty('ActiveState');
         const enabled = await systemctlProperty('UnitFileState');
         const running = state === 'active';
+        // Three separate promises, and the verdict has to fail on any of them.
+        // Until 0.27.0 only the first counted: a service that was running but
+        // would die at the next logout (linger off) or never come back after a
+        // reboot (not enabled) still printed ✔ and still said READY, with the
+        // `loginctl enable-linger` line sitting UNDER the tick as if it were
+        // advice. The whole point of an acceptance sheet is that a green one means
+        // walk away — so a runner that stops when its user logs out is a red line.
+        const durable = running && enabled === 'enabled' && linger !== false;
         checks.push({
-            ok: running,
+            ok: durable,
             name: 'service',
             detail: running
                 ? `running${enabled === 'enabled' ? ', starts on boot' : ' — but NOT enabled: it will not come back after a reboot'}` +
@@ -663,7 +744,7 @@ async function runnerChecks() {
                         ? ', survives logout'
                         : linger === false
                             ? ', but linger is OFF: it stops when this user logs out'
-                            : '')
+                            : ', linger state unknown')
                 : `NOT running (${state ?? 'unknown'})`,
             ...(running
                 ? enabled !== 'enabled'
@@ -725,10 +806,27 @@ async function runnerChecks() {
         ...(canUpdate || packageDir === null
             ? {}
             : {
-                fix: `sudo -iu ${me.user} npm install -g --ignore-scripts --prefix ~/.local ${'@bridge4dev/runner'}`,
-                fixMore: `(reinstalling as ${me.user} is what makes the button work; until then every update is a root command)`,
+                // NOT `--prefix ~/.local`, which is what this line used to say. The
+                // tilde is expanded by the CALLING shell, so run as root it aimed at
+                // /root/.local — a directory the daemon's user cannot write — and
+                // the install died naming a home nobody had chosen. `sudo -iu` hands
+                // the string to the TARGET user's login shell, so `$HOME` is theirs.
+                fix: `sudo -iu ${me.user} sh -lc 'npm config set prefix "$HOME/.local" && npm install -g --ignore-scripts --loglevel=error @bridge4dev/runner'`,
+                fixMore: `(the \`npm config set prefix\` half is what keeps the button working: without it every LATER update aims at the system prefix again and fails with EACCES)`,
             }),
     });
+    // The relay that signs an agent in runs the CLI on a pty, and util-linux
+    // `script` is what allocates it. Missing on minimal images, and its absence
+    // used to surface as «claude login exited before printing a sign-in URL».
+    const hasScript = hasExecutable('script');
+    checks.push({
+        ok: hasScript,
+        name: 'sign-in relay',
+        detail: hasScript
+            ? 'ready (util-linux `script` present)'
+            : '`script` (util-linux) is missing — the dashboard sign-in button cannot run',
+        ...(hasScript ? {} : { fix: 'apt-get install -y bsdextrautils util-linux' }),
+    });
     return checks;
 }
 async function agentChecks() {
@@ -744,12 +842,45 @@ async function agentChecks() {
             process.env['DEVBRIDGE_RUNNER_LOG'] = previousLogLevel;
     });
     const checks = [];
+    // Does the CLI exist for THIS user, before asking whether it is signed in?
+    // «not signed in» over a machine that has no `claude` at all sends the
+    // reader to a login screen for a command that does not exist — and doctor's
+    // own remedy (`sudo -iu <user> claude`) was then `command not found`. That
+    // is the state a dedicated-user install leaves behind by default.
+    const cliPresent = {
+        claude: hasExecutable('claude'),
+        codex: hasExecutable('codex'),
+    };
+    checks.push({
+        ok: cliPresent.claude,
+        name: 'claude cli',
+        detail: cliPresent.claude
+            ? `on ${me.user}'s PATH`
+            : `not installed for ${me.user} — sessions still run (the SDK bundles its own), but signing in needs the CLI`,
+        ...(cliPresent.claude
+            ? {}
+            : {
+                fix: `sudo -iu ${me.user} sh -lc 'curl -fsSL https://claude.ai/install.sh | bash'`,
+            }),
+    });
+    // Codex is optional: plenty of machines only ever run Claude sessions, and a
+    // red line for an agent nobody uses is noise that trains people to ignore
+    // the sheet. Reported, not judged.
+    checks.push({
+        ok: true,
+        name: 'codex cli',
+        detail: cliPresent.codex ? `on ${me.user}'s PATH` : `not installed for ${me.user} (optional)`,
+        ...(cliPresent.codex
+            ? {}
+            : {
+                fix: `sudo -iu ${me.user} sh -lc 'npm install -g @openai/codex'   # only if you use Codex`,
+            }),
+    });
     for (const [agent, info] of [
         ['claude', auth.claude],
         ['codex', auth.codex],
     ]) {
         const signedIn = info.status === 'ok';
-        const command = agent === 'claude' ? 'claude' : 'codex login';
         checks.push({
             ok: signedIn,
             name: `${agent} login`,
@@ -758,12 +889,39 @@ async function agentChecks() {
             ...(signedIn
                 ? {}
                 : {
-                    fix: `${me.isRoot ? command : `sudo -iu ${me.user} ${command}`}${agent === 'claude' ? '   then /login' : ''}`,
+                    // The dashboard button FIRST. It is the product's own path, it
+                    // needs no shell on the server, and an installing agent cannot
+                    // perform an interactive OAuth login anyway — so telling it to
+                    // «run claude and do /login» is telling it to stop. That is
+                    // exactly where the last three installs stopped.
+                    fix: `Dashboard → Development → this server → AGENTS → «Sign in» next to ${agent === 'claude' ? 'Claude Code' : 'Codex'}`,
+                    fixMore: cliPresent[agent]
+                        ? `or on the server: ${me.isRoot ? '' : `sudo -iu ${me.user} `}${agent === 'claude' ? 'claude auth login' : 'codex login'}`
+                        : `(install the CLI first — see the «${agent} cli» line above)`,
                 }),
         });
     }
     const contour = agentConfigContour(me.home);
     const elsewhere = otherHomeWithAgents(me);
+    // MCP servers a session will really see. Only user scope survives a session
+    // worktree, and «configured but in the wrong scope» looks identical to
+    // «working» from anywhere except inside a session.
+    const mcpHidden = contour.mcpUserScope === 0 && contour.mcpProjectScope > 0;
+    checks.push({
+        ok: !mcpHidden,
+        name: 'mcp servers',
+        detail: mcpHidden
+            ? `${contour.mcpProjectScope} configured, but all per-directory — a session works in its own worktree and will see NONE`
+            : contour.mcpUserScope > 0
+                ? `${contour.mcpUserScope} available to every session`
+                : 'none configured (the DevBridge server is injected per session regardless)',
+        ...(mcpHidden
+            ? {
+                fix: `sudo -iu ${me.user} claude mcp add --scope user <name> …   # re-add at user scope`,
+                fixMore: '(`claude mcp add` defaults to the current directory’s scope, which no session shares)',
+            }
+            : {}),
+    });
     checks.push({
         ok: contour.claudeDir,
         name: 'claude config',
@@ -851,7 +1009,15 @@ async function projectChecks(target, fix) {
             name: 'docker',
             detail: docker.problem ?? 'usable by this user',
             ...(docker.problem
-                ? { fix: `usermod -aG docker ${me.user}   (then restart the runner)` }
+                ? {
+                    fix: `usermod -aG docker ${me.user}`,
+                    // Restarting the unit is NOT enough and this cost a diagnosis:
+                    // supplementary groups are fixed when logind creates
+                    // user@<uid>.service, so the daemon keeps the old set until the
+                    // whole user manager restarts. `id ${me.user}` then shows the new
+                    // group while /proc/<pid>/status still shows the old one.
+                    fixMore: `systemctl restart user@${me.uid}.service   # the unit alone keeps the old group set`,
+                }
                 : {}),
         });
     }

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).
  *