@bridge4dev/runner 0.26.0 → 0.29.0

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;
@@ -179,11 +179,11 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         id: string;
         title: string;
     }[];
-    mode?: "ask" | "plan" | "auto" | "full" | undefined;
     mcp?: {
         url: string;
         token: string;
     } | undefined;
+    mode?: "ask" | "plan" | "auto" | "full" | undefined;
     model?: string | null | undefined;
     effort?: string | null | undefined;
     epoch?: number | undefined;
@@ -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;
@@ -381,11 +381,11 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             id: string;
             title: string;
         }[];
-        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         mcp?: {
             url: string;
             token: string;
         } | undefined;
+        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;
@@ -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;
@@ -469,11 +469,11 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             id: string;
             title: string;
         }[];
-        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         mcp?: {
             url: string;
             token: string;
         } | undefined;
+        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;
@@ -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;
@@ -695,11 +695,11 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             id: string;
             title: string;
         }[];
-        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         mcp?: {
             url: string;
             token: string;
         } | undefined;
+        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;
@@ -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;
@@ -778,11 +778,11 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             id: string;
             title: string;
         }[];
-        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         mcp?: {
             url: string;
             token: string;
         } | undefined;
+        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;

package/dist/recipe-schema.d.ts

@@ -253,6 +253,7 @@ export declare const ProjectRecipeSchema: z.ZodObject<{
         shaPath?: string | undefined;
     } | undefined;
 }, {
+    version?: 1 | undefined;
     preview?: {
         run: string;
         url?: string | undefined;
@@ -260,7 +261,6 @@ export declare const ProjectRecipeSchema: z.ZodObject<{
         timeoutSec?: number | undefined;
         stop?: string | undefined;
     } | undefined;
-    version?: 1 | undefined;
     notes?: string | undefined;
     steps?: {
         verify?: {

package/dist/self-update.d.ts

@@ -62,6 +62,28 @@ export interface SelfUpdateOptions {
  * has one above `packages/runner`.
  */
 export declare function resolveInstalledPackageDir(entry?: string): string | null;
+/**
+ * The npm prefix the RUNNING package was installed into.
+ *
+ * This is the whole fix for the dedicated-user layout. `npm install -g` obeys
+ * npm's *configured* prefix, and `--prefix` is a per-invocation flag that npm
+ * persists nowhere — so the install the instructions prescribed for a dedicated
+ * user (`npm install -g --prefix ~/.local …`) produced a runner in
+ * `~/.local/lib/node_modules` while every later `npm install -g` aimed at
+ * `/usr`. Measured on a live server: `npm prefix -g` → `/usr`,
+ * `installIsWritable` → true (both checked directories really are the user's),
+ * and then npm dies with EACCES *inside* the update — the exact
+ * «the permissions to access this file as the current user» the owner pasted.
+ *
+ * Deriving the prefix from where we physically are is the truthful answer: it
+ * cannot disagree with reality, and it costs no subprocess. Returns null for a
+ * layout that is not a global npm install (a source checkout, a vendored copy),
+ * where the caller should fall back to `npm prefix -g`.
+ *
+ * `<prefix>/lib/node_modules/@scope/pkg` → `<prefix>`
+ * `<prefix>/lib/node_modules/pkg`        → `<prefix>`
+ */
+export declare function installPrefixFor(packageDir?: string | null): string | null;
 /**
  * Can this user actually replace the installed package?
  *
@@ -72,8 +94,11 @@ export declare function resolveInstalledPackageDir(entry?: string): string | nul
  * current user» — a dashboard button that cannot work, and an error in npm's
  * words rather than ours.
  *
- * Both directories matter: npm rewrites the package AND the `bin` symlink, and
- * either one being root-owned is enough to fail.
+ * Three directories matter, because npm rewrites all three: the package itself,
+ * the `node_modules` above it, and `<prefix>/bin`, where the command symlink
+ * lives. `bin` was missing here and is not hypothetical — a prefix whose
+ * `lib/node_modules` was handed over with chown while `bin` stayed root-owned
+ * passes the first two and still fails.
  */
 export declare function installIsWritable(packageDir?: string | null): boolean;
 /**
@@ -92,5 +117,21 @@ export declare function isSupervisedProcess(env?: NodeJS.ProcessEnv): boolean;
  * never be talked into fetching its own replacement over http.
  */
 export declare function isTrustedTarballUrl(tarballUrl: string, apiUrl: string): boolean;
+/**
+ * The command a person can paste on the server to update this exact machine.
+ *
+ * Built by the runner rather than by the dashboard because only the runner
+ * knows the three things that make it correct: which prefix it lives in, which
+ * user it runs as, and that user's uid for `XDG_RUNTIME_DIR`. The dashboard
+ * used to assemble a generic `npm install -g <url> && systemctl --user restart`
+ * and then patch it with string surgery — which produced a command that could
+ * not work on precisely the machines that needed it.
+ */
+export declare function manualUpdateCommand(tarballUrl: string, options?: {
+    prefix?: string | null;
+    user?: string;
+    uid?: number;
+    packageDir?: string | null;
+}): string;
 export declare function selfUpdate(options: SelfUpdateOptions): Promise<SelfUpdateOutcome>;
 //# sourceMappingURL=self-update.d.ts.map

package/dist/self-update.js

@@ -55,6 +55,51 @@ export function resolveInstalledPackageDir(entry = process.argv[1] ?? '') {
     }
     return null;
 }
+/**
+ * The npm prefix the RUNNING package was installed into.
+ *
+ * This is the whole fix for the dedicated-user layout. `npm install -g` obeys
+ * npm's *configured* prefix, and `--prefix` is a per-invocation flag that npm
+ * persists nowhere — so the install the instructions prescribed for a dedicated
+ * user (`npm install -g --prefix ~/.local …`) produced a runner in
+ * `~/.local/lib/node_modules` while every later `npm install -g` aimed at
+ * `/usr`. Measured on a live server: `npm prefix -g` → `/usr`,
+ * `installIsWritable` → true (both checked directories really are the user's),
+ * and then npm dies with EACCES *inside* the update — the exact
+ * «the permissions to access this file as the current user» the owner pasted.
+ *
+ * Deriving the prefix from where we physically are is the truthful answer: it
+ * cannot disagree with reality, and it costs no subprocess. Returns null for a
+ * layout that is not a global npm install (a source checkout, a vendored copy),
+ * where the caller should fall back to `npm prefix -g`.
+ *
+ * `<prefix>/lib/node_modules/@scope/pkg` → `<prefix>`
+ * `<prefix>/lib/node_modules/pkg`        → `<prefix>`
+ */
+export function installPrefixFor(packageDir = resolveInstalledPackageDir()) {
+    if (!packageDir)
+        return null;
+    const marker = `${path.sep}node_modules${path.sep}`;
+    const at = packageDir.lastIndexOf(marker);
+    if (at < 0)
+        return null;
+    const nodeModules = packageDir.slice(0, at + marker.length - 1);
+    const lib = path.dirname(nodeModules);
+    // Anything else is not the layout `npm install -g --prefix` produces, and
+    // guessing a prefix that npm would not use is worse than not guessing.
+    if (path.basename(lib) !== 'lib')
+        return null;
+    return path.dirname(lib);
+}
+function isWritable(target) {
+    try {
+        fs.accessSync(target, fs.constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Can this user actually replace the installed package?
  *
@@ -65,24 +110,29 @@ export function resolveInstalledPackageDir(entry = process.argv[1] ?? '') {
  * current user» — a dashboard button that cannot work, and an error in npm's
  * words rather than ours.
  *
- * Both directories matter: npm rewrites the package AND the `bin` symlink, and
- * either one being root-owned is enough to fail.
+ * Three directories matter, because npm rewrites all three: the package itself,
+ * the `node_modules` above it, and `<prefix>/bin`, where the command symlink
+ * lives. `bin` was missing here and is not hypothetical — a prefix whose
+ * `lib/node_modules` was handed over with chown while `bin` stayed root-owned
+ * passes the first two and still fails.
  */
 export function installIsWritable(packageDir = resolveInstalledPackageDir()) {
     if (!packageDir)
         return false;
-    const writable = (target) => {
-        try {
-            fs.accessSync(target, fs.constants.W_OK);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    };
+    const marker = `${path.sep}node_modules${path.sep}`;
+    const at = packageDir.lastIndexOf(marker);
     // `<prefix>/lib/node_modules/@scope/pkg` → `<prefix>/lib/node_modules`
-    const nodeModules = path.dirname(packageDir.includes(`${path.sep}@`) ? path.dirname(packageDir) : packageDir);
-    return writable(packageDir) && writable(nodeModules);
+    const nodeModules = at >= 0 ? packageDir.slice(0, at + marker.length - 1) : path.dirname(packageDir);
+    if (!isWritable(packageDir) || !isWritable(nodeModules))
+        return false;
+    const prefix = installPrefixFor(packageDir);
+    // No `bin` yet is fine — npm creates it. An existing one we cannot write is not.
+    if (prefix) {
+        const bin = path.join(prefix, 'bin');
+        if (fs.existsSync(bin) && !isWritable(bin))
+            return false;
+    }
+    return true;
 }
 /**
  * Is something going to restart us?
@@ -140,17 +190,23 @@ const COMMAND_NAME = 'devbridge-runner';
  * command — the stable thing, referenced by a unit file we do not control —
  * points at the new one. So we follow the command.
  */
-async function commandOwner(exec) {
-    let prefix;
-    try {
-        const result = await exec('npm', ['prefix', '-g'], {
-            timeout: VERIFY_TIMEOUT_MS,
-            env: npmEnv(),
-        });
-        prefix = result.stdout.trim();
-    }
-    catch {
-        return null;
+async function commandOwner(exec, installPrefix = null) {
+    // Where we actually live outranks what npm is configured to think. Under the
+    // dedicated-user layout `npm prefix -g` answers `/usr` — a directory that on
+    // such a host holds no runner at all — so asking npm first returned null and
+    // took the EEXIST rename-recovery and the unit repair down with it.
+    let prefix = installPrefix;
+    if (!prefix) {
+        try {
+            const result = await exec('npm', ['prefix', '-g'], {
+                timeout: VERIFY_TIMEOUT_MS,
+                env: npmEnv(),
+            });
+            prefix = result.stdout.trim();
+        }
+        catch {
+            return null;
+        }
     }
     if (!prefix)
         return null;
@@ -167,13 +223,55 @@ async function commandOwner(exec) {
         return null;
     }
 }
-function installArgs(source) {
+function installArgs(source, prefix) {
     // `--ignore-scripts` matches the documented install: this package and its whole
     // tree have no install/postinstall scripts, so nothing legitimate is skipped —
     // and an update pulled over the network gets no chance to run anything at
     // install time. `--loglevel=error` because npm's ERESOLVE warning about zod is
     // expected, harmless and long enough to bury the line that matters.
-    return ['install', '-g', '--ignore-scripts', '--loglevel=error', source];
+    //
+    // `--prefix` names the prefix the runner is ALREADY installed in. Without it
+    // npm uses its configured global prefix, which on a dedicated-user install is
+    // a directory the daemon cannot write — and, on the rarer host where it can,
+    // npm cheerfully installs a SECOND copy somewhere the service does not exec,
+    // reports success, and the runner restarts on the old version forever.
+    return [
+        'install',
+        '-g',
+        '--ignore-scripts',
+        '--loglevel=error',
+        ...(prefix ? ['--prefix', prefix] : []),
+        source,
+    ];
+}
+/**
+ * The command a person can paste on the server to update this exact machine.
+ *
+ * Built by the runner rather than by the dashboard because only the runner
+ * knows the three things that make it correct: which prefix it lives in, which
+ * user it runs as, and that user's uid for `XDG_RUNTIME_DIR`. The dashboard
+ * used to assemble a generic `npm install -g <url> && systemctl --user restart`
+ * and then patch it with string surgery — which produced a command that could
+ * not work on precisely the machines that needed it.
+ */
+export function manualUpdateCommand(tarballUrl, options = {}) {
+    const packageDir = options.packageDir === undefined ? resolveInstalledPackageDir() : options.packageDir;
+    const prefix = options.prefix === undefined ? installPrefixFor(packageDir) : options.prefix;
+    const user = options.user ?? os.userInfo().username;
+    const uid = options.uid ?? (typeof process.getuid === 'function' ? process.getuid() : -1);
+    const install = ['npm install -g --ignore-scripts --loglevel=error']
+        .concat(prefix ? [`--prefix ${prefix}`] : [])
+        .concat([tarballUrl])
+        .join(' ');
+    const restart = 'systemctl --user restart devbridge-runner';
+    // Writable by us → one line, run as ourselves. Not writable → the install
+    // half needs root and the restart half needs the daemon's own user, and
+    // «run it as root» alone is how people ended up with a new package and an
+    // old process still running.
+    if (installIsWritable(packageDir))
+        return `${install} && ${restart}`;
+    const runtime = uid >= 0 ? `/run/user/${uid}` : `/run/user/$(id -u ${user})`;
+    return `sudo ${install} && sudo -iu ${user} env XDG_RUNTIME_DIR=${runtime} ${restart}`;
 }
 /**
  * Install a global package, clearing the way if a DIFFERENTLY-NAMED build of this
@@ -186,25 +284,22 @@ function installArgs(source) {
  * one owner instead of two, which is also the only state the NEXT update can
  * work from.
  */
-async function installGlobal(exec, source) {
+async function installGlobal(exec, source, prefix) {
     try {
-        await exec('npm', installArgs(source), { timeout: NPM_TIMEOUT_MS, env: npmEnv() });
+        await exec('npm', installArgs(source, prefix), { timeout: NPM_TIMEOUT_MS, env: npmEnv() });
         return;
     }
     catch (error) {
         if (!/EEXIST/i.test(describe(error)))
             throw error;
-        const owner = await commandOwner(exec);
+        const owner = await commandOwner(exec, prefix);
         if (!owner)
             throw error;
         log.warn('self-update: the command belongs to another package — retiring it', {
             package: owner.name,
         });
-        await exec('npm', ['uninstall', '-g', '--loglevel=error', owner.name], {
-            timeout: NPM_TIMEOUT_MS,
-            env: npmEnv(),
-        });
-        await exec('npm', installArgs(source), { timeout: NPM_TIMEOUT_MS, env: npmEnv() });
+        await exec('npm', ['uninstall', '-g', '--loglevel=error', ...(prefix ? ['--prefix', prefix] : []), owner.name], { timeout: NPM_TIMEOUT_MS, env: npmEnv() });
+        await exec('npm', installArgs(source, prefix), { timeout: NPM_TIMEOUT_MS, env: npmEnv() });
     }
 }
 /**
@@ -256,13 +351,12 @@ export async function selfUpdate(options) {
     // runner's own user.
     if (!installIsWritable(packageDir)) {
         const user = os.userInfo().username;
-        const uid = typeof process.getuid === 'function' ? process.getuid() : -1;
         return fail(`The runner package in ${packageDir} belongs to another user, and this daemon runs as ${user}, ` +
-            'so it cannot replace itself. Update it on the server in two steps — install as root:\n' +
-            `  npm install -g --ignore-scripts --loglevel=error ${options.tarballUrl}\n` +
-            'then restart the service as the runner’s own user:\n' +
-            `  sudo -iu ${user} env XDG_RUNTIME_DIR=/run/user/${uid >= 0 ? uid : '$(id -u ' + user + ')'} systemctl --user restart devbridge-runner`);
+            'so it cannot replace itself. Run this on the server instead:\n  ' +
+            manualUpdateCommand(options.tarballUrl, { packageDir }));
     }
+    // Derived once and threaded through every npm call below.
+    const prefix = installPrefixFor(packageDir);
     // Pack the current version FIRST: without a rollback artefact there is no
     // honest way back if the new build turns out to be broken.
     const rollbackDir = path.join(stateDir(), 'rollback');
@@ -287,7 +381,7 @@ export async function selfUpdate(options) {
         return fail('Could not prepare a rollback copy of the current version — update aborted');
     }
     try {
-        await installGlobal(exec, options.tarballUrl);
+        await installGlobal(exec, options.tarballUrl, prefix);
     }
     catch (error) {
         return fail(`Install failed: ${describe(error)}`, { rollbackTarball });
@@ -295,7 +389,7 @@ export async function selfUpdate(options) {
     // Where the new build actually landed. After a rename `packageDir` is the
     // directory we just retired, so its manifest would report the OLD version —
     // and the smoke test below would run code that no longer exists.
-    const installed = await commandOwner(exec);
+    const installed = await commandOwner(exec, prefix);
     const newPackageDir = installed?.dir ?? packageDir;
     const toVersion = readVersion(newPackageDir) ?? undefined;
     // The real test: does the newly installed build start? `--version` loads the
@@ -318,12 +412,12 @@ export async function selfUpdate(options) {
             // Through the same door as the install above: if the failed update renamed
             // the package, the command now belongs to the new name and putting the old
             // one back hits the very same EEXIST.
-            await installGlobal(exec, rollbackTarball);
+            await installGlobal(exec, rollbackTarball, prefix);
             return fail(`The new version did not start (${detail}). The previous version was restored and the runner keeps working.`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
         }
         catch (rollbackError) {
             return fail(`The new version did not start (${detail}) and the rollback failed too (${describe(rollbackError)}). ` +
-                `Restore it on the server with: npm install -g ${rollbackTarball}`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
+                `Restore it on the server with: npm install -g${prefix ? ` --prefix ${prefix}` : ''} ${rollbackTarball}`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
         }
     }
     // The service unit may be pinned to a file inside the directory this update

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