@bridge4dev/runner 0.55.1 → 0.57.0

package/dist/adapters/questions.js

@@ -52,6 +52,38 @@ export function answerValue(answer) {
 export function answerSummary(answers) {
     return clip(answers.map(answerValue).filter(Boolean).join(' · '), OPTION_TEXT_LIMIT);
 }
+/**
+ * The same answer as something to SAY, when the card that asked is gone (#401).
+ *
+ * Not `answerSummary`: that one is a label for a resolved card, so it is
+ * clipped to an option's width and drops the notes. This is the person's reply
+ * being handed to the agent as an ordinary message, and nothing they typed may
+ * be shortened away on the path. The questions themselves cannot be named —
+ * their text lived in the process that asked and is gone with it — so the
+ * answer is given as the words it was made of, which is what the person
+ * actually chose.
+ *
+ * Empty when there is nothing in it: the caller uses that to tell «the reply
+ * was lost» from «there was no reply to lose».
+ */
+export function answersAsMessage(answers) {
+    return clip(answers
+        .map((answer) => {
+        const value = answerValue(answer);
+        const notes = answer.notes?.trim();
+        if (value && notes)
+            return `${value} (${notes})`;
+        return value || notes || '';
+    })
+        .filter(Boolean)
+        .join('\n'), 
+    // The same ceiling `discussMessage` uses, and for a harder reason: this text
+    // becomes a feed event, and an event over the API's size limit is replaced
+    // wholesale by a truncation marker. The frame this is built from allows four
+    // answers of sixteen 2 000-char values plus a 10 000-char custom field —
+    // ~176 KB — and the runner takes that frame straight off the socket.
+    8_000);
+}
 /**
  * The «discuss instead» exit.
  *

package/dist/auth-relay.js

@@ -7,6 +7,7 @@ import { log } from './log.js';
 import { maskString } from './policy.js';
 import { runnerIdentity, whichExecutable } from './environment.js';
 import { applyStoredClaudeToken, clearStoredClaudeToken, extractOauthToken, storeClaudeToken, storedClaudeToken, } from './agent-auth.js';
+import { invalidateUsageCache } from './adapters/claude-usage.js';
 import { adoptLoginResult, discardStagingHome, prepareStagingHome, repairCodexAuth, stagingCodexHomePath, } from './adapters/codex-home.js';
 const execFileAsync = promisify(execFile);
 /* eslint-disable no-control-regex -- this module parses raw pty output, so
@@ -48,6 +49,22 @@ export function extractLoginUrl(agent, raw) {
         return null;
     return candidate.replace(/[.,)\]}>'"]+$/, '');
 }
+/**
+ * A new login means the plan figures belong to somebody else (#390, #380).
+ *
+ * The `/usage` reading is cached for the whole MACHINE, so after a re-login the
+ * panel would keep showing the previous account's percentages — and since #380
+ * it shows them next to the NEW account's address, which turns a stale number
+ * into a wrong statement about a named person. The reading is thrown away here
+ * for the same reason `invalidateAgentVersions()` is thrown away after an
+ * install: the fact it described is no longer the fact.
+ *
+ * Does not cover a login performed by hand on the server (`claude auth login`
+ * outside DevBridge) — that one corrects itself within the cache interval.
+ */
+function forgetClaudeUsage() {
+    invalidateUsageCache();
+}
 export function extractDeviceCode(raw) {
     // Device-auth user codes look like XXXX-XXXX (letters/digits).
     return stripControl(raw).match(/\b[A-Z0-9]{4,8}-[A-Z0-9]{4,8}\b/)?.[0] ?? null;
@@ -334,6 +351,7 @@ export class AuthRelay {
             }
             log.info('auth-relay: stored a long-lived Claude token for this runner');
             clearAgentAuthFailure('claude');
+            forgetClaudeUsage();
             return { ok: true, detail: 'signed in with a long-lived token stored on this server' };
         }
         // `claude auth login` writes the credential just before it exits; give the
@@ -343,6 +361,7 @@ export class AuthRelay {
             const status = await probe();
             if (status.status === 'ok') {
                 clearAgentAuthFailure('claude');
+                forgetClaudeUsage();
                 return { ok: true };
             }
             await sleep(300);

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/supervisor.d.ts

@@ -6,6 +6,7 @@ import { pruneNativeClaudeVersions } from './agent-cleanup.js';
 import { type AgentVersionsMeasurement } from './agent-versions.js';
 import { type HostLoadFrame } from './host-load.js';
 import { type ScopeMemoryStatus } from './session-cage.js';
+import { createCheckpoint } from './checkpoints.js';
 import type { RunnerWsClient } from './ws-client.js';
 import type { SessionDescriptor } from './protocol.js';
 import type { AgentAdapter } from './adapters/types.js';
@@ -50,6 +51,17 @@ export interface SupervisorOptions {
     verifyEnabled?: boolean;
     /** Test seam for the one-shot commit-message run. */
     proposeCommitMessage?: typeof proposeCommitMessage;
+    /**
+     * Test seam for taking a restore point — #401.
+     *
+     * A seam and not a detail: the opening restore point is the whole window this
+     * ticket is about. It runs between «the working folder is ready» and «the
+     * first process exists», it takes SECONDS on a dirty tree, and a message that
+     * arrives inside it used to open a second door to `launchAgent`. Timing that
+     * window from the outside is guesswork; holding it open from a test is the
+     * only way the race is reproducible on demand.
+     */
+    createCheckpoint?: typeof createCheckpoint;
     /**
      * `[checkpoints] enabled` from the runner's own config (ticket #126), by the
      * same rule as `[verify] enabled`: restore points are copies of the working
@@ -227,6 +239,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 +904,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;
     /**