@bridge4dev/runner 0.55.0 → 0.56.0

package/dist/checkpoints.d.ts

@@ -144,6 +144,11 @@ export interface RewindPreview {
  *
  * Never throws for an ordinary failure: a checkpoint that could not be taken
  * must not stop the message it was taken for from reaching the agent.
+ *
+ * The store is held for the whole of it (#388): until the closing `update-ref`
+ * nothing names the objects being written, and a collection running in the
+ * same store would take them for garbage — which is what they are, right up
+ * until they are not.
  */
 export declare function createCheckpoint(input: CreateCheckpointInput): Promise<CreateCheckpointResult>;
 export declare function listCheckpoints(worktreePath: string, sessionId: string): Promise<CheckpointRecord[]>;
@@ -156,7 +161,13 @@ export declare function listCheckpoints(worktreePath: string, sessionId: string)
  * a cap on a courtesy must degrade, never reject.
  */
 export declare const MAX_BUSY_SESSIONS = 10;
-/** What a rewind to this checkpoint would do, without doing any of it. */
+/**
+ * What a rewind to this checkpoint would do, without doing any of it.
+ *
+ * Holds the store (#388): building the preview writes a tree of «where we are
+ * now», and that tree is named by no ref ever — a collection running beside it
+ * takes it, and `diff-tree` then fails on the oid it was just handed.
+ */
 export declare function previewRewind(input: {
     worktreePath: string;
     sessionId: string;

package/dist/checkpoints.js

@@ -149,9 +149,154 @@ async function ensureStore(worktreePath) {
     }
     return store;
 }
+/**
+ * One store, one thing at a time: snapshots OR collection (#388).
+ *
+ * The store is keyed by REPOSITORY, so every session working in one folder
+ * writes into the same objects directory — and `pruneCheckpoints` collects in
+ * it. Between the first `update-index --add` and the closing `update-ref` the
+ * objects of a snapshot are named by nothing, and `gc --prune=now` collects
+ * exactly what nothing names. Measured on production 07.09.2026: a reconnect
+ * fired the collection while a turn was taking its point, and `write-tree`
+ * died on its own blobs («invalid object … error building trees»). A rewind
+ * preview is the same shape — its tree is never named by a ref at all.
+ *
+ * Shared for the writers, exclusive for the collection. Three properties are
+ * load-bearing:
+ *
+ *  1. Writers do not exclude each other. Two sessions in one folder take their
+ *     points at the same time, as they always did — `tempIndexFile` is what
+ *     keeps them apart, and this gate must not quietly serialise them.
+ *  2. The queue is fair: a later writer never overtakes a waiting collection.
+ *     A busy folder takes a point every few seconds, and a collection that can
+ *     be overtaken is a collection that never runs — i.e. the disk it exists to
+ *     give back is never given back.
+ *  3. A collection WAITS; it never gives up and runs anyway. Waiting costs it
+ *     nothing (nobody awaits it — `reconcile` fires it and moves on), while
+ *     running anyway is precisely the defect this closes.
+ *
+ * In-process, deliberately. The directory is shared per MACHINE, but the runner
+ * daemon is the only process that ever opens it — this module has exactly one
+ * importer — so ordering inside this process is ordering, full stop. A second
+ * runner started by hand beside the service would need a lock in the
+ * filesystem; that is not a shape this product has.
+ */
+class StoreGate {
+    /** Snapshots and previews in flight. */
+    writing = 0;
+    /** A collection has the store to itself. */
+    collecting = false;
+    queue = [];
+    async enter(exclusive) {
+        // The empty-queue test is the fairness rule: with somebody already waiting,
+        // even a writer that could go now takes its place at the back.
+        if (this.queue.length === 0 && this.free(exclusive)) {
+            this.take(exclusive);
+            return;
+        }
+        await new Promise((admit) => {
+            this.queue.push({ exclusive, admit });
+        });
+    }
+    leave(exclusive) {
+        if (exclusive)
+            this.collecting = false;
+        else
+            this.writing -= 1;
+        while (this.queue.length > 0) {
+            const next = this.queue[0];
+            if (!next || !this.free(next.exclusive))
+                return;
+            this.queue.shift();
+            this.take(next.exclusive);
+            next.admit();
+            // A collection is alone in there; the writers behind it wait for its turn
+            // to end.
+            if (next.exclusive)
+                return;
+        }
+    }
+    /** Nobody holds it and nobody is waiting — the entry can be forgotten. */
+    idle() {
+        return this.writing === 0 && !this.collecting && this.queue.length === 0;
+    }
+    free(exclusive) {
+        return exclusive ? !this.collecting && this.writing === 0 : !this.collecting;
+    }
+    take(exclusive) {
+        if (exclusive)
+            this.collecting = true;
+        else
+            this.writing += 1;
+    }
+}
+const storeGates = new Map();
+/**
+ * Hold this store while `fn` runs.
+ *
+ * `writing` for anything that puts objects in the store OR reads objects a
+ * collection could take; `collecting` for the collection itself.
+ *
+ * ONE lease per operation, taken at the entry point and never inside it. The
+ * rewind is why: it previews, takes a safety point and reads the checkpoint's
+ * tree, and if each of those took its own lease, a collection queuing between
+ * two of them would be waiting for a lease the rewind cannot release until the
+ * collection lets it continue. That is a deadlock, and the fair queue in the
+ * point above is exactly what makes it possible — so the fairness and the
+ * single lease are one decision, not two.
+ */
+async function withStore(store, mode, fn) {
+    // Resolved, because the two sides name the store from different ends: the
+    // writers build it out of `storeFor`, the collection out of a directory
+    // listing.
+    const key = path.resolve(store);
+    const exclusive = mode === 'collecting';
+    const gate = storeGates.get(key) ?? new StoreGate();
+    storeGates.set(key, gate);
+    // No `await` between the lookup and the claim — `enter` takes its place
+    // synchronously, so the entry cannot be swept out from under it below.
+    const askedAt = Date.now();
+    await gate.enter(exclusive);
+    const waitedMs = Date.now() - askedAt;
+    if (waitedMs > 1_000) {
+        // The one thing this gate can do that is felt from outside: a restore point
+        // — and with it the message in front of it — waiting for a collection to
+        // finish. Unlogged, that is a delay nobody can explain afterwards.
+        log.info('checkpoints: waited for the store to be free', {
+            store: path.basename(key),
+            mode,
+            waitedMs,
+        });
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        gate.leave(exclusive);
+        if (gate.idle() && storeGates.get(key) === gate)
+            storeGates.delete(key);
+    }
+}
 function indexFileFor(sessionId) {
     return path.join(checkpointsDir(), 'index', `${sessionId}.idx`);
 }
+/**
+ * Drop a temporary index, and never fail because of it.
+ *
+ * These calls sit in `finally` blocks, and a throw from there escapes PAST the
+ * catch that classifies failures — which would turn «could not take a restore
+ * point» into a rejected promise, and `createCheckpoint` promises never to
+ * throw. The file is scratch; losing the ability to delete it is not worth a
+ * message that never reaches the agent.
+ */
+function removeIndex(indexFile) {
+    try {
+        fs.rmSync(indexFile, { force: true });
+    }
+    catch (error) {
+        log.warn('checkpoints: could not remove a temporary index', { error: String(error) });
+    }
+}
 /**
  * A private index file for ONE operation.
  *
@@ -383,17 +528,42 @@ function decodeMeta(message) {
  *
  * Never throws for an ordinary failure: a checkpoint that could not be taken
  * must not stop the message it was taken for from reaching the agent.
+ *
+ * The store is held for the whole of it (#388): until the closing `update-ref`
+ * nothing names the objects being written, and a collection running in the
+ * same store would take them for garbage — which is what they are, right up
+ * until they are not.
  */
 export async function createCheckpoint(input) {
+    let store;
+    try {
+        store = await ensureStore(input.worktreePath);
+    }
+    catch (error) {
+        // Almost always «this folder is not a git repository» — the store is built
+        // from the repo's own common dir, so there is nothing to open.
+        return checkpointRefusal(input.sessionId, error);
+    }
+    return withStore(store, 'writing', () => takeCheckpoint(store, input));
+}
+/** An error on the way to a restore point, read as a reason to report. */
+function checkpointRefusal(sessionId, error) {
+    const detail = String(error instanceof Error ? error.message : error).slice(0, 300);
+    if (/not a git repository|ambiguous argument 'HEAD'|unknown revision/i.test(detail)) {
+        return { created: false, reason: 'not-a-repo', detail };
+    }
+    log.warn('checkpoints: could not create a restore point', { sessionId, error: detail });
+    return { created: false, reason: 'failed', detail };
+}
+/** The point itself. The caller holds the store; this never takes it (#388). */
+async function takeCheckpoint(store, input) {
     const { worktreePath, sessionId, kind } = input;
+    const indexFile = tempIndexFile(sessionId, 'create');
     try {
-        const store = await ensureStore(worktreePath);
-        const indexFile = tempIndexFile(sessionId, 'create');
         // Both ends of the shutter — see `CreateCheckpointInput.busySessions`.
         const busyBefore = input.busySessions?.() ?? [];
         const built = await buildIndex(store, worktreePath, indexFile);
         if (built.tooLarge) {
-            fs.rmSync(indexFile, { force: true });
             return { created: false, reason: 'too-large' };
         }
         const { headSha, included, excluded: skippedFiles, byteCount } = built;
@@ -417,7 +587,6 @@ export async function createCheckpoint(input) {
         const commit = await gitStore(store, worktreePath, indexFile, 'commit-tree', tree, '-m', encodeMeta(meta));
         const ordinal = await nextOrdinal(store, worktreePath, sessionId);
         await gitStore(store, worktreePath, indexFile, 'update-ref', refFor(sessionId, ordinal), commit);
-        fs.rmSync(indexFile, { force: true });
         return {
             created: true,
             record: { ordinal, commit, ...meta },
@@ -426,12 +595,12 @@ export async function createCheckpoint(input) {
         };
     }
     catch (error) {
-        const detail = String(error instanceof Error ? error.message : error).slice(0, 300);
-        if (/not a git repository|ambiguous argument 'HEAD'|unknown revision/i.test(detail)) {
-            return { created: false, reason: 'not-a-repo', detail };
-        }
-        log.warn('checkpoints: could not create a restore point', { sessionId, error: detail });
-        return { created: false, reason: 'failed', detail };
+        return checkpointRefusal(sessionId, error);
+    }
+    finally {
+        // In `finally` rather than on the way out: every refusal above used to
+        // leave its index file behind, and `checkpoints/index/` only ever grew.
+        removeIndex(indexFile);
     }
 }
 async function readCheckpoint(store, worktreePath, sessionId, ordinal) {
@@ -492,11 +661,28 @@ async function currentTree(store, worktreePath, indexFile) {
  */
 export const MAX_BUSY_SESSIONS = 10;
 const MAX_PREVIEW_ENTRIES = 5_000;
-/** What a rewind to this checkpoint would do, without doing any of it. */
+/**
+ * What a rewind to this checkpoint would do, without doing any of it.
+ *
+ * Holds the store (#388): building the preview writes a tree of «where we are
+ * now», and that tree is named by no ref ever — a collection running beside it
+ * takes it, and `diff-tree` then fails on the oid it was just handed.
+ */
 export async function previewRewind(input) {
+    const store = await ensureStore(input.worktreePath);
+    const indexFile = tempIndexFile(input.sessionId, 'preview');
+    try {
+        return await withStore(store, 'writing', () => buildPreview(store, indexFile, input));
+    }
+    finally {
+        // Named out here so that every way out of the preview — including the two
+        // that used to walk past the cleanup — leaves the index behind it.
+        removeIndex(indexFile);
+    }
+}
+/** The preview itself. The caller holds the store; this never takes it (#388). */
+async function buildPreview(store, indexFile, input) {
     const { worktreePath, sessionId, ordinal } = input;
-    const store = await ensureStore(worktreePath);
-    const indexFile = tempIndexFile(sessionId, 'preview');
     const record = await readCheckpoint(store, worktreePath, sessionId, ordinal);
     const { tree, headSha } = await currentTree(store, worktreePath, indexFile);
     if (!record) {
@@ -511,7 +697,6 @@ export async function previewRewind(input) {
         };
     }
     const raw = await gitStore(store, worktreePath, indexFile, 'diff-tree', '-r', '--no-renames', '--name-status', '-z', `${record.commit}^{tree}`, tree);
-    fs.rmSync(indexFile, { force: true });
     const restore = [];
     const remove = [];
     const recreate = [];
@@ -597,12 +782,53 @@ async function mergeInProgress(worktreePath) {
  * by list, and a rule is exactly what nobody confirmed.
  */
 export async function applyRewind(input) {
-    const { worktreePath, sessionId, ordinal, confirmDeletes, expectedTreeOid } = input;
+    const { worktreePath } = input;
     const store = await ensureStore(worktreePath);
+    // ONE lease over the whole of it (#388), and it covers the READS as much as
+    // the writes: the collection unlinks refs and then collects, so a checkpoint
+    // whose ref ages out mid-rewind would lose its tree between the safety point
+    // and the `read-tree` that restores it — a rewind that fails after it has
+    // already promised. Nesting a second lease inside this one would deadlock
+    // against a waiting collection, which is why `buildPreview` and
+    // `takeCheckpoint` are called here rather than their exported wrappers.
+    const { record, preview, safety } = await withStore(store, 'writing', () => rewindToPoint(store, input));
+    // Outside the lease from here on: this is the worktree and the PROJECT's
+    // index, and nothing in the checkpoint store depends on it.
+    //
+    // `read-tree --reset -u` removes the files that are in the seeded index and
+    // not in the checkpoint — which is the same set the user just confirmed,
+    // because both come from the same tree diff. This pass is the belt to that
+    // brace: it names each path explicitly, re-checks it against the worktree
+    // root, and reports what is actually gone. Nothing here deletes by rule, and
+    // there is no `git clean` anywhere in this file.
+    await deletePaths(worktreePath, preview.delete);
+    const deleted = preview.delete.filter((rel) => !fs.existsSync(path.join(worktreePath, rel))).length;
+    await reconcileIndex(worktreePath, preview, record.stagedPaths);
+    return {
+        restored: preview.restore.length,
+        deleted,
+        recreated: preview.recreate.length,
+        safety,
+        rewoundToKind: record.kind,
+    };
+}
+/**
+ * Everything the rewind does INSIDE the store: check, take the safety point,
+ * put the tree back. The caller holds the lease; nothing here takes one (#388).
+ */
+async function rewindToPoint(store, input) {
+    const { worktreePath, sessionId, ordinal, confirmDeletes, expectedTreeOid } = input;
     const record = await readCheckpoint(store, worktreePath, sessionId, ordinal);
     if (!record)
         throw new Error('This restore point is no longer available');
-    const preview = await previewRewind({ worktreePath, sessionId, ordinal });
+    const previewIndex = tempIndexFile(sessionId, 'preview');
+    let preview;
+    try {
+        preview = await buildPreview(store, previewIndex, { worktreePath, sessionId, ordinal });
+    }
+    finally {
+        removeIndex(previewIndex);
+    }
     if (preview.blockedReason) {
         throw new Error(rewindBlockMessage(preview.blockedReason));
     }
@@ -624,7 +850,7 @@ export async function applyRewind(input) {
     if (expected.length !== echoed.length || expected.some((p, i) => p !== echoed[i])) {
         throw new Error(MOVED);
     }
-    const safetyResult = await createCheckpoint({
+    const safetyResult = await takeCheckpoint(store, {
         worktreePath,
         sessionId,
         kind: 'SAFETY',
@@ -636,29 +862,18 @@ export async function applyRewind(input) {
             : 'Could not take a safety point before the rewind — nothing was changed');
     }
     const indexFile = tempIndexFile(sessionId, 'rewind');
-    // Seed the index with the CURRENT state so `read-tree --reset -u` only
-    // touches files that actually differ. Against an empty index git rewrites
-    // every file in the repository, and an mtime bump on a whole tree is a full
-    // rebuild for every watcher on the machine.
-    await currentTree(store, worktreePath, indexFile);
-    await gitStore(store, worktreePath, indexFile, 'read-tree', '--reset', '-u', `${record.commit}^{tree}`);
-    fs.rmSync(indexFile, { force: true });
-    // `read-tree --reset -u` removes the files that are in the seeded index and
-    // not in the checkpoint — which is the same set the user just confirmed,
-    // because both come from the same tree diff. This pass is the belt to that
-    // brace: it names each path explicitly, re-checks it against the worktree
-    // root, and reports what is actually gone. Nothing here deletes by rule, and
-    // there is no `git clean` anywhere in this file.
-    await deletePaths(worktreePath, preview.delete);
-    const deleted = preview.delete.filter((rel) => !fs.existsSync(path.join(worktreePath, rel))).length;
-    await reconcileIndex(worktreePath, preview, record.stagedPaths);
-    return {
-        restored: preview.restore.length,
-        deleted,
-        recreated: preview.recreate.length,
-        safety: safetyResult.record,
-        rewoundToKind: record.kind,
-    };
+    try {
+        // Seed the index with the CURRENT state so `read-tree --reset -u` only
+        // touches files that actually differ. Against an empty index git rewrites
+        // every file in the repository, and an mtime bump on a whole tree is a full
+        // rebuild for every watcher on the machine.
+        await currentTree(store, worktreePath, indexFile);
+        await gitStore(store, worktreePath, indexFile, 'read-tree', '--reset', '-u', `${record.commit}^{tree}`);
+    }
+    finally {
+        removeIndex(indexFile);
+    }
+    return { record, preview, safety: safetyResult.record };
 }
 /**
  * Said when the files of a restore point cannot be trusted (#310). Its own
@@ -852,8 +1067,23 @@ export async function pruneCheckpoints(input) {
                 // Dropping a ref only unlinks it; the trees and blobs it named stay on
                 // disk until they are collected. Skipping this would make "retention"
                 // mean nothing at all for the thing that actually takes the space.
-                await gitRefs(store, 'reflog', 'expire', '--expire=now', '--all');
-                await gitRefs(store, 'gc', '--prune=now', '--quiet');
+                //
+                // Under the store's lease, and taken HERE rather than around the walk
+                // above (#388): `--prune=now` deletes everything no ref names, and a
+                // snapshot being written in this same store is a set of objects no ref
+                // names YET. The lease is claimed per store and only around these two
+                // commands, so the ref walk of every other store stays outside it —
+                // though the loop itself is sequential, so a folder that keeps this one
+                // waiting does postpone the stores after it. That is acceptable and
+                // was already true of `gc` itself: collection is best-effort and comes
+                // round again on the next reconnect.
+                //
+                // It WAITS rather than skipping: a collection that runs anyway is the
+                // whole defect.
+                await withStore(store, 'collecting', async () => {
+                    await gitRefs(store, 'reflog', 'expire', '--expire=now', '--all');
+                    await gitRefs(store, 'gc', '--prune=now', '--quiet');
+                });
             }
         }
         catch (error) {

package/dist/index.js

@@ -1443,10 +1443,10 @@ async function cmdDoctor(args) {
     print(`                  ${devbridgeSliceOverridePath()}`);
     if (cage.mode === 'scope') {
         const mb = (bytes) => bytes === null ? 'infinity' : `${Math.round(bytes / 1024 / 1024)} MB`;
-        print(`  per session     MemoryHigh ${mb(cage.memoryHighBytes)} (brake: slows, never kills), MemoryMax ${mb(cage.memoryMaxBytes)} (wall), MemorySwapMax ${mb(cage.swapMaxBytes)}, TasksMax ${SESSION_TASKS_MAX}`);
-        print(`  at the wall     ${cage.oomContinue
-            ? 'OOMPolicy=continue — the kernel kills the hungriest process, the session stays up'
-            : 'this systemd does not take OOMPolicy on a scope (it is newer than the rest of the cage), so what happens at the wall is its own default — on systemd 253+ that is «stop the whole session»'}`);
+        print(`  per session     share ${mb(cage.memoryHighBytes)} (MemoryHigh — allocations are throttled above it), ceiling ${mb(cage.memoryMaxBytes)} (MemoryMax), swap ${mb(cage.swapMaxBytes)} (MemorySwapMax), TasksMax ${SESSION_TASKS_MAX}`);
+        print(`  at the ceiling  ${cage.oomContinue
+            ? 'OOMPolicy=continue — the kernel stops the largest process in the session'
+            : 'this systemd does not take OOMPolicy on a scope, so its own default applies — on systemd 253+ that stops the whole session'}`);
         // What systemd has IN FORCE on the slice, beside the paths of the files
         // that were supposed to put it there. «В файле 7680M, действует 6.0G» is the
         // lesson of §5.5, and the drop-in of a slice can fail to land in exactly the
@@ -1457,7 +1457,7 @@ async function cmdDoctor(args) {
             print('                  NOT CAPPED — the drop-in above has not been applied.');
             print(`                  Apply with: ${systemctlHint('daemon-reload')}`);
         }
-        print(`  service ceiling ${mb(cage.serviceMemoryMaxBytes)} (the per-session brake is half of the containing ceiling, capped at 2.5 GiB; the wall IS the containing ceiling)`);
+        print(`  service ceiling ${mb(cage.serviceMemoryMaxBytes)} (a session's share is a third of the containing ceiling, its own ceiling is that minus one share)`);
         print(`  expand-env flag ${cage.expandEnvironmentFlag ? 'passed (systemd ≥ 254)' : 'not passed — this systemd does not know it, and --scope does not expand anyway'}`);
     }
     else {

package/dist/session-cage.d.ts

@@ -433,6 +433,12 @@ export declare function parseScopeMemoryStatus(files: {
  */
 export declare function readScopeMemoryStatus(unit: string, readFile?: (p: string) => string): ScopeMemoryStatus | null;
 export declare function markScopeOomKillsSeen(id: string, oomKills: number): void;
+/**
+ * «a process in it was stopped» / «3 processes in it were stopped», so the verb
+ * agrees. Shared with the supervisor's feed notices, which count the same
+ * thing and must not word it differently.
+ */
+export declare function stoppedProcesses(count: number, where?: 'it' | 'this one'): string;
 /**
  * Snapshot the cgroup's verdict before systemd can take it away.
  *

package/dist/session-cage.js

@@ -891,6 +891,16 @@ const oomKillsSeen = new Map();
 export function markScopeOomKillsSeen(id, oomKills) {
     oomKillsSeen.set(id, oomKills);
 }
+/**
+ * «a process in it was stopped» / «3 processes in it were stopped», so the verb
+ * agrees. Shared with the supervisor's feed notices, which count the same
+ * thing and must not word it differently.
+ */
+export function stoppedProcesses(count, where = 'it') {
+    return count === 1
+        ? `a process in ${where} was stopped`
+        : `${count} processes in ${where} were stopped`;
+}
 const deaths = new Map();
 /**
  * Snapshot the cgroup's verdict before systemd can take it away.
@@ -909,7 +919,7 @@ export function rememberDeath(id, unit, readStatus = readScopeMemoryStatus) {
         maxBytes: status.maxBytes,
         // `oom` moves only where the limit that was hit belongs. A kill with our
         // own counter still at zero came from an ancestor — the pool.
-        ownWall: status.ownLimitOom > 0,
+        reached: status.ownLimitOom > 0 ? 'own-ceiling' : 'shared-pool',
     });
 }
 /**
@@ -928,9 +938,9 @@ function rememberDeathFromResult(id) {
     deaths.set(id, {
         oomKills: 1,
         maxBytes: sessionCage().memoryMaxBytes,
-        // systemd stopped the unit for an OOM inside it; which limit was hit is not
-        // in `Result`, and «your own wall» is the claim that must not be guessed.
-        ownWall: false,
+        // systemd stopped the unit for an OOM inside it; which limit was reached is
+        // not in `Result`, and neither claim may be guessed.
+        reached: 'unknown',
     });
 }
 /**
@@ -947,16 +957,21 @@ export function explainMemoryDeath(id) {
     if (!death)
         return null;
     deaths.delete(id);
-    const killed = death.oomKills === 1 ? 'a process' : `${death.oomKills} processes`;
-    const wall = death.maxBytes === null ? '' : ` of ${Math.round(death.maxBytes / MIB)} MB`;
-    if (death.ownWall) {
-        return (`The session ran out of memory: it went over its own memory ceiling${wall} and the kernel killed ` +
-            `${killed} inside it. ` +
-            'Resume it and avoid re-running the command that was in flight, or give the machine more memory or swap.');
+    const stopped = stoppedProcesses(death.oomKills);
+    const ceiling = death.maxBytes === null ? '' : ` of ${Math.round(death.maxBytes / MIB)} MB`;
+    if (death.reached === 'own-ceiling') {
+        return (`This session reached its memory ceiling${ceiling} and ${stopped} — ` +
+            'send a message to carry on; if it keeps happening, the machine needs more memory.');
+    }
+    if (death.reached === 'shared-pool') {
+        return (`The machine ran out of memory for agent sessions and ${stoppedProcesses(death.oomKills, 'this one')} — ` +
+            'send a message to carry on; if it keeps happening, run fewer sessions at once or give the machine more memory.');
     }
-    return (`The machine ran out of memory for agent sessions — all sessions on it share one ceiling — and the kernel killed ` +
-        `${killed} in this one. This session was not necessarily the greedy one. ` +
-        'Resume it; if it keeps happening, run fewer sessions at once or give the machine more memory or swap.');
+    // Which ceiling was reached is unknowable here, so the sentence names no
+    // culprit: it has to be true whether this session was the greedy one or a
+    // bystander.
+    return (`There was not enough memory for this session and ${stopped} — ` +
+        'send a message to carry on; if it keeps happening, run fewer sessions at once or give the machine more memory.');
 }
 const realSystemctl = async (args) => {
     const { stdout, stderr } = await execFileAsync('systemctl', ['--user', ...args], {

package/dist/supervisor.d.ts

@@ -227,6 +227,8 @@ export declare class Supervisor {
      * which of the two is running.
      */
     private installInFlight;
+    /** A restore-point collection is running; a second reconnect must not start another (#388). */
+    private checkpointGcInFlight;
     /** Session 14: one project-recipe run per machine, and its verdict queue. */
     private readonly verify;
     private readonly verifyReports;
@@ -890,24 +892,37 @@ export declare class Supervisor {
      * a second session opened. The neighbours are recorded on the point instead —
      * the conversation can always be rewound to it, the files cannot.
      *
-     * Every refusal is now audible. A restore point that was never taken is
-     * invisible until the day somebody reaches for it, and «the button is not
-     * there» is not a sentence anybody can act on.
+     * A refusal is audible when it is a refusal — when the person can do
+     * something about it, or when a way back they might reach for is not there.
+     * A restore point that was never taken is invisible until the day somebody
+     * reaches for it, and «the button is not there» is not a sentence anybody can
+     * act on.
+     *
+     * «This session was still answering» is the exception, and it is the only one
+     * (#384). It is not a fault and not a state to act on: it is what a follow-up
+     * note to a working agent looks like from in here, thirty times in a day on
+     * one machine, and it costs almost nothing — the point in front of the turn
+     * already stands, and rewinding to it takes back the files AND the
+     * conversation, including the note. So it goes to the runner's own log, where
+     * support can answer «why is there no point for that step», and not into the
+     * feed, where it read as breakage.
      */
     private captureCheckpoint;
     /**
      * Say something once per BUSY PERIOD, not once per message (#310).
      *
-     * A folder held by a neighbour stays held for minutes, and a session mid-turn
-     * can be sent three follow-up notes inside one answer. Keying this on the
-     * message seq would have counted each of those as its own turn and said the
-     * same sentence three times — the noise the frequency policy exists to
-     * prevent. The set is cleared when the session next comes to rest
-     * (`reportStatus`), which is exactly when the reason stops being true.
+     * A repository held by another git command stays held for as long as that
+     * command runs, and three follow-up notes can arrive inside one answer.
+     * Keying this on the message seq would have counted each of those as its own
+     * turn and said the same sentence three times — the noise the frequency
+     * policy exists to prevent. The set is cleared when the session next comes to
+     * rest (`reportStatus`), which is exactly when the reason stops being true.
      *
      * A SET of keys, not the last one said: two different reasons can both come
      * up inside one period, and remembering only the most recent would let them
-     * take turns re-announcing each other.
+     * take turns re-announcing each other. One key uses this today — «another git
+     * command holds this repository» — and the set stays a set for that reason,
+     * not out of habit: the mid-turn key left when it stopped being said (#384).
      */
     private noticeOncePerTurn;
     /**