@bridge4dev/runner 0.55.1 → 0.56.0

package/dist/adapters/claude-usage.d.ts

@@ -53,13 +53,134 @@ export declare function parseUsageText(text: string, now?: Date): UsageRow[];
  * reworded CLI must never be able to move a wake-up — therefore still holds.
  * `claude-usage.test.ts` pins it.
  */
-export declare function applyUsagePercentages(windows: AgentRateLimitWindow[], rows: UsageRow[]): AgentRateLimitWindow[];
+export declare function applyUsagePercentages(windows: AgentRateLimitWindow[], rows: UsageRow[], options?: {
+    onlyFillGaps?: boolean;
+}): AgentRateLimitWindow[];
+/**
+ * How long the probe may run before it is written off (#390).
+ *
+ * Ninety seconds, and the number is measured rather than chosen. `/usage` was
+ * 3.7s when the old ceiling of 20s was set on 2026-08-15; it is not that
+ * command any more. Since then the CLI prints «What's contributing to your
+ * limits usage?», computed from the machine's OWN session history — 1.4 GB and
+ * ~4900 files on the busiest dev server — so the work grows with the history
+ * and the load rather than with anything we ask for. It is also CPU-bound, not
+ * network-bound: 23.7s wall against 32s of CPU.
+ *
+ * Measured 2026-09-07 on a six-core box under load 4-15:
+ *
+ *   plain, /tmp                 17.7s
+ *   plain, a project checkout   19.0 20.8 22.2 24.0 27.5s
+ *   in the reporter's own runs  15.0 15.3 16.5 17.1 20.8 23.7 28.3s
+ *
+ * So 20s was not a margin, it was the middle of the distribution, and a failed
+ * probe was an ordinary event rather than an exception. The cost of waiting is
+ * nil — the probe is free (0 tokens, 0 turns, 0 dollars, verified 2026-08-15),
+ * runs in the background, and since #390 there is at most ONE of it per
+ * machine. The cost of NOT waiting was the panel losing two of its three rows.
+ */
+export declare const USAGE_PROBE_TIMEOUT_MS = 20000;
+/**
+ * How long a successful reading is believed — the throttle for the whole box.
+ *
+ * Three minutes, unchanged from when this was a per-session throttle. What
+ * changed is the scope: five sessions used to keep five independent clocks and
+ * run five copies of a 20-second process, all of them measuring the same
+ * account. The windows on screen are five hours and a week; three minutes is
+ * already far finer than they move.
+ */
+export declare const USAGE_CACHE_MS: number;
+/**
+ * How long we wait before retrying after a probe that produced nothing.
+ *
+ * Shorter than the success interval, because a machine that has just failed
+ * once is the machine most worth asking again — but not so short that a box
+ * with no subscription at all (own API key, Bedrock, Vertex) spends its life
+ * spawning CLIs. One at a time is guaranteed by the in-flight join below, so
+ * the worst case is a single ~90s process a minute apart, not a pile.
+ */
+export declare const USAGE_FAILURE_COOLDOWN_MS: number;
+export type UsageProbeRunner = (binary: string, cwd: string) => Promise<string | null>;
 /**
  * Run `/usage` in a throwaway process and return what it printed.
  *
  * `--output-format text` rather than the stream: we want the rendering, and the
  * JSON wrapper would only have to be unwrapped again. Never throws — a probe
  * that fails is a percentage we do not show, not a session that breaks.
+ *
+ * Three things about HOW it is run, all of them measured (#390):
+ *
+ *  - `--strict-mcp-config` stops the CLI starting the project's MCP servers,
+ *    which a question about the plan has no use for. Measured in a project
+ *    checkout: 13.8 and 18.5s with the flag against 20.8 and 22.2s without, and
+ *    the output is identical — the same three rows. It narrows the spread; it
+ *    does not remove it, which is why the ceiling above moved as well.
+ *  - the process is niced like every other thing we spawn for an agent. It used
+ *    to be the one child of the runner that was neither caged nor renice'd, and
+ *    at a 90-second ceiling that would have made it a real neighbour on a busy
+ *    box (#387 is the same lesson from the other side).
+ *  - stdin is closed. `-p` does not read it, but `agent-versions.ts` was bitten
+ *    by a CLI that did, and a probe that hangs on an open pipe would now hang
+ *    for a minute and a half. (Not the cause of the slowness here: measured
+ *    with and without, the times overlap.)
+ *
+ * `--bare` was measured too and rejected: it finishes in 2.5s and prints no
+ * usage at all, because it reads neither OAuth nor the keychain — on the
+ * subscription this whole file exists to report, it has nothing to say.
  */
 export declare function probeUsageText(binary: string, cwd: string, timeoutMs?: number): Promise<string | null>;
+/** A reading of the machine's plan, with the moment it was taken. */
+export interface UsageReading {
+    rows: UsageRow[];
+    measuredAtMs: number;
+}
+export declare function setUsageProbeRunner(run: UsageProbeRunner | null): void;
+/** Forget everything measured. For tests, and for a re-login that changes account. */
+export declare function invalidateUsageCache(): void;
+/**
+ * What the machine last read, WITHOUT starting a measurement.
+ *
+ * The reason this exists is the defect #390 was actually about. A session's
+ * window map starts empty, and its first `rate_limit_event` arrives 12-28
+ * seconds before any probe of its own could answer. That event describes ONE
+ * window, the snapshot built from it therefore has one row, and the API stores
+ * the newest snapshot as the state of the whole machine — so a session that had
+ * only just started would overwrite three good rows with one, every time, on a
+ * machine with a single session as much as on a busy one.
+ *
+ * Seeding from the box's last reading closes that: a new session publishes what
+ * the machine already knows in its very first snapshot, and the probe that
+ * follows only refreshes it.
+ */
+export declare function lastUsageRows(): UsageReading | null;
+export interface ReadUsageOptions {
+    binary: string;
+    /**
+     * Where to run it. Defaults to {@link probeDir} — a directory of the runner's
+     * own, never a shared one and never a session's working copy. The reading is
+     * identical in every directory (verified), so the choice is made entirely on
+     * safety and tidiness: see `probeDir` for why a shared directory is a hole,
+     * and note that `-p` leaves a transcript behind, which in a checkout would
+     * grow the very local history that makes `/usage` slow.
+     */
+    cwd?: string;
+    /** Fixed clock for tests; both the throttle and the stamp read it. */
+    now?: number;
+}
+/**
+ * The machine's plan percentages — measured at most once per {@link USAGE_CACHE_MS}.
+ *
+ * Two guards, and they answer different questions. The throttle stops us
+ * measuring again too SOON; the in-flight join stops us measuring twice AT
+ * ONCE. Only the second one fixes the pile-up this change is about: five
+ * sessions reaching a turn end together used to start five copies of a
+ * 20-second CPU-bound process, each of which made the others slower — the same
+ * self-sustaining shape `gitops.ts` writes about for `git_status`.
+ *
+ * Always resolves to the best reading we have, never to «nothing» just because
+ * this attempt failed. A stale true number beats an empty panel — and the
+ * reading carries the moment it was TAKEN, so the caller can tell a fresh
+ * measurement from the one it already folded in (see {@link measuredAtMs}).
+ */
+export declare function readUsageRows(options: ReadUsageOptions): Promise<UsageReading | null>;
 //# sourceMappingURL=claude-usage.d.ts.map

package/dist/adapters/claude-usage.js

@@ -1,5 +1,9 @@
 import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 import { log } from '../log.js';
+import { stateDir } from '../paths.js';
+import { lowerPriority } from '../process-priority.js';
 /**
  * How much of the plan is spent — read from the CLI's own `/usage` (#279).
  *
@@ -191,7 +195,7 @@ export function parseUsageText(text, now = new Date()) {
  * reworded CLI must never be able to move a wake-up — therefore still holds.
  * `claude-usage.test.ts` pins it.
  */
-export function applyUsagePercentages(windows, rows) {
+export function applyUsagePercentages(windows, rows, options = {}) {
     // Keyed by window AND label: a per-model weekly row is its own line, not an
     // overwrite of the plan-wide one.
     const id = (window) => `${window.key}:${window.label ?? ''}`;
@@ -202,7 +206,19 @@ export function applyUsagePercentages(windows, rows) {
         merged.set(key, {
             key: row.key,
             windowMinutes: existing?.windowMinutes ?? (row.key === 'five_hour' ? 300 : 10_080),
-            usedPercent: row.percent,
+            // `onlyFillGaps` is what a STALE reading gets (#390, QA MAJOR). The
+            // reading belongs to the machine and is handed to a session at the end of
+            // every turn; meanwhile a `rate_limit_event` may have put a newer
+            // percentage into this very window. Overwriting it rolled 95% back to the
+            // 60% measured three minutes earlier, once per turn, in both directions
+            // (too low inside a window, too high just after it resets). A fresh
+            // measurement still wins outright — it is the authority for percentages,
+            // which is the whole premise of #279.
+            usedPercent: options.onlyFillGaps &&
+                existing?.usedPercent !== null &&
+                existing?.usedPercent !== undefined
+                ? existing.usedPercent
+                : row.percent,
             // Event first, text second, nothing third. See the docblock above for why
             // this ordering is the whole safety argument.
             resetsAt: existing?.resetsAt ?? row.resetsAt ?? null,
@@ -213,23 +229,310 @@ export function applyUsagePercentages(windows, rows) {
     return [...merged.values()].sort((a, b) => (a.windowMinutes ?? Number.MAX_SAFE_INTEGER) - (b.windowMinutes ?? Number.MAX_SAFE_INTEGER) ||
         (a.label ?? '').localeCompare(b.label ?? ''));
 }
+/**
+ * How long the probe may run before it is written off (#390).
+ *
+ * Ninety seconds, and the number is measured rather than chosen. `/usage` was
+ * 3.7s when the old ceiling of 20s was set on 2026-08-15; it is not that
+ * command any more. Since then the CLI prints «What's contributing to your
+ * limits usage?», computed from the machine's OWN session history — 1.4 GB and
+ * ~4900 files on the busiest dev server — so the work grows with the history
+ * and the load rather than with anything we ask for. It is also CPU-bound, not
+ * network-bound: 23.7s wall against 32s of CPU.
+ *
+ * Measured 2026-09-07 on a six-core box under load 4-15:
+ *
+ *   plain, /tmp                 17.7s
+ *   plain, a project checkout   19.0 20.8 22.2 24.0 27.5s
+ *   in the reporter's own runs  15.0 15.3 16.5 17.1 20.8 23.7 28.3s
+ *
+ * So 20s was not a margin, it was the middle of the distribution, and a failed
+ * probe was an ordinary event rather than an exception. The cost of waiting is
+ * nil — the probe is free (0 tokens, 0 turns, 0 dollars, verified 2026-08-15),
+ * runs in the background, and since #390 there is at most ONE of it per
+ * machine. The cost of NOT waiting was the panel losing two of its three rows.
+ */
+export const USAGE_PROBE_TIMEOUT_MS = 20_000;
+/**
+ * How long a successful reading is believed — the throttle for the whole box.
+ *
+ * Three minutes, unchanged from when this was a per-session throttle. What
+ * changed is the scope: five sessions used to keep five independent clocks and
+ * run five copies of a 20-second process, all of them measuring the same
+ * account. The windows on screen are five hours and a week; three minutes is
+ * already far finer than they move.
+ */
+export const USAGE_CACHE_MS = 3 * 60 * 1_000;
+/**
+ * How long we wait before retrying after a probe that produced nothing.
+ *
+ * Shorter than the success interval, because a machine that has just failed
+ * once is the machine most worth asking again — but not so short that a box
+ * with no subscription at all (own API key, Bedrock, Vertex) spends its life
+ * spawning CLIs. One at a time is guaranteed by the in-flight join below, so
+ * the worst case is a single ~90s process a minute apart, not a pile.
+ */
+export const USAGE_FAILURE_COOLDOWN_MS = 60 * 1_000;
+/** At most one line per reason per this long. See `warnProbeFailure`. */
+const WARN_THROTTLE_MS = 15 * 60 * 1_000;
+/**
+ * A probe that failed is worth SAYING (#390).
+ *
+ * It used to be `log.debug` while the runner logs at `info`, so the one thing
+ * that explains a panel losing two of its three rows was invisible from
+ * outside: the percentages simply stopped, and every other signal said the
+ * machine was healthy.
+ *
+ * Throttled per reason rather than said every time, because the failure that
+ * repeats forever is the boring one — a machine with no subscription probes,
+ * fails, and would otherwise write a line into journald every minute until the
+ * log is useless. The first line of a new failure is the one that carries the
+ * information; the hundredth only buries it.
+ */
+const warnedAtMs = new Map();
+function warnProbeFailure(error, timeoutMs, now) {
+    const killed = typeof error === 'object' &&
+        error !== null &&
+        'killed' in error &&
+        error.killed === true;
+    const reason = killed ? 'timeout' : 'error';
+    const last = warnedAtMs.get(reason);
+    if (last !== undefined && now - last < WARN_THROTTLE_MS) {
+        log.debug('claude: /usage probe failed again', { reason, error: String(error) });
+        return;
+    }
+    warnedAtMs.set(reason, now);
+    log.warn(killed
+        ? 'claude: /usage did not finish in time — plan percentages will go stale'
+        : 'claude: /usage could not be read — plan percentages will go stale', { reason, timeoutMs, error: String(error) });
+}
 /**
  * Run `/usage` in a throwaway process and return what it printed.
  *
  * `--output-format text` rather than the stream: we want the rendering, and the
  * JSON wrapper would only have to be unwrapped again. Never throws — a probe
  * that fails is a percentage we do not show, not a session that breaks.
+ *
+ * Three things about HOW it is run, all of them measured (#390):
+ *
+ *  - `--strict-mcp-config` stops the CLI starting the project's MCP servers,
+ *    which a question about the plan has no use for. Measured in a project
+ *    checkout: 13.8 and 18.5s with the flag against 20.8 and 22.2s without, and
+ *    the output is identical — the same three rows. It narrows the spread; it
+ *    does not remove it, which is why the ceiling above moved as well.
+ *  - the process is niced like every other thing we spawn for an agent. It used
+ *    to be the one child of the runner that was neither caged nor renice'd, and
+ *    at a 90-second ceiling that would have made it a real neighbour on a busy
+ *    box (#387 is the same lesson from the other side).
+ *  - stdin is closed. `-p` does not read it, but `agent-versions.ts` was bitten
+ *    by a CLI that did, and a probe that hangs on an open pipe would now hang
+ *    for a minute and a half. (Not the cause of the slowness here: measured
+ *    with and without, the times overlap.)
+ *
+ * `--bare` was measured too and rejected: it finishes in 2.5s and prints no
+ * usage at all, because it reads neither OAuth nor the keychain — on the
+ * subscription this whole file exists to report, it has nothing to say.
  */
-export function probeUsageText(binary, cwd, timeoutMs = 20_000) {
+export function probeUsageText(binary, cwd, timeoutMs = USAGE_PROBE_TIMEOUT_MS) {
     return new Promise((resolve) => {
-        execFile(binary, ['-p', '/usage', '--output-format', 'text'], { cwd, timeout: timeoutMs, maxBuffer: 1024 * 1024 }, (error, stdout) => {
+        let settled = false;
+        const finish = (text) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(watchdog);
+            resolve(text);
+        };
+        const child = execFile(binary, ['--strict-mcp-config', '-p', '/usage', '--output-format', 'text'], {
+            cwd,
+            timeout: timeoutMs,
+            maxBuffer: 1024 * 1024,
+            // SIGTERM can be trapped, SIGKILL cannot. A probe that ignored the
+            // polite signal would never call this callback, and since the cache
+            // above clears its in-flight slot only when the callback runs, ONE such
+            // process would stop the machine ever measuring again (QA-390 MINOR).
+            // Nothing here needs a graceful exit: it reads and prints.
+            killSignal: 'SIGKILL',
+        }, (error, stdout) => {
             if (error) {
-                log.debug('claude: /usage probe failed', { error: String(error) });
-                resolve(null);
+                warnProbeFailure(error, timeoutMs, Date.now());
+                finish(null);
                 return;
             }
-            resolve(stdout);
+            finish(stdout);
         });
+        // Belt as well as braces: the callback also waits for the output streams to
+        // close, and a grandchild holding the pipe can keep them open after the CLI
+        // itself is gone. This promise must settle no matter what, because the
+        // in-flight slot is released from it.
+        const watchdog = setTimeout(() => {
+            log.warn('claude: /usage probe left its pipes open — giving up on it', { timeoutMs });
+            finish(null);
+        }, timeoutMs + 15_000);
+        watchdog.unref?.();
+        child.stdin?.end();
+        lowerPriority(child.pid);
+    });
+}
+/**
+ * Where the probe runs — a directory only this runner can write to.
+ *
+ * NOT a shared directory, and this is a security property rather than a
+ * preference (QA-390 BLOCKER). For Claude Code the working directory is the
+ * root of a project's SETTINGS: it reads `<cwd>/.claude/settings.json`, and
+ * that file may define hooks — commands the CLI then runs. `-p` asks for no
+ * trust confirmation at all, verified live. The runner is root by default
+ * (`--user <name>` is opt-in), so a world-writable `cwd` means any local user
+ * can drop `/tmp/.claude/settings.json` and have it executed as root within
+ * three minutes. Demonstrated end to end during review: a non-root user's hook
+ * wrote `uid=0(root)`.
+ *
+ * Before this ticket the probe inherited the session's own working copy, which
+ * is inside the project's trust boundary; `os.tmpdir()` was the accident that
+ * this comment exists to prevent someone re-introducing.
+ *
+ * Second, smaller reason for a directory of our own: with `cwd` on a busy
+ * `/tmp` the CLI walks it (`rg --files --hidden`) — 162,595 files and 1.16s on
+ * this machine, spent for nothing.
+ */
+function probeDir() {
+    const dir = path.join(stateDir(), 'usage-probe');
+    try {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        return dir;
+    }
+    catch (error) {
+        // No private directory, no probe. Falling back to a shared one is exactly
+        // the hole above, and a missing percentage is a far smaller loss.
+        log.warn('claude: no private directory for the /usage probe — skipping it', {
+            dir,
+            error: String(error),
+        });
+        return null;
+    }
+}
+/**
+ * The last reading that SUCCEEDED. A failed probe never clears it.
+ *
+ * This is the whole difference between «we could not measure just now» and «we
+ * know nothing»: the first must keep showing the last true numbers, and only
+ * the second is allowed to leave the panel empty.
+ */
+let lastRows = null;
+/**
+ * When {@link lastRows} was MEASURED — not when it was last handed out.
+ *
+ * Load-bearing rather than diagnostic (QA-390 MAJOR). A reading may be up to
+ * {@link USAGE_CACHE_MS} old, and it is handed to a session at the end of every
+ * turn. Meanwhile a `rate_limit_event` can have put a NEWER percentage into
+ * that session's window, and `applyUsagePercentages` overwrites percentages
+ * without asking how old they are — so an unqualified reading rolled 95% back
+ * to the 60% the machine measured three minutes ago, on every turn. The stamp
+ * is what lets the adapter tell «this is news» from «this is what you already
+ * folded in».
+ */
+let measuredAtMs = 0;
+/** When the last attempt FINISHED, successful or not — the throttle's clock. */
+let attemptedAtMs = 0;
+/** Did that attempt produce rows? Decides which of the two intervals applies. */
+let lastAttemptOk = false;
+/** The probe currently running, so overlapping callers share it. */
+let inFlight = null;
+/**
+ * The probe the cache runs. Replaced only by tests.
+ *
+ * A module-level seat rather than an argument, because the caller that needs it
+ * is a session buried inside the adapter and threading a test-only parameter
+ * through 126 constructions of `ClaudeAdapter` would put it on the product's
+ * own seam. It has to exist at all for a sharper reason than tidiness: until
+ * #390 the only thing keeping the adapter's own test file from spawning a real
+ * `claude` on this machine — which also hosts production — was that its fake
+ * `cwd` did not exist, and this change stopped the probe using the session's
+ * `cwd` at all.
+ */
+let probeRunner = (binary, cwd) => probeUsageText(binary, cwd);
+export function setUsageProbeRunner(run) {
+    probeRunner = run ?? ((binary, cwd) => probeUsageText(binary, cwd));
+}
+/** Forget everything measured. For tests, and for a re-login that changes account. */
+export function invalidateUsageCache() {
+    lastRows = null;
+    measuredAtMs = 0;
+    attemptedAtMs = 0;
+    lastAttemptOk = false;
+    inFlight = null;
+    warnedAtMs.clear();
+}
+/**
+ * What the machine last read, WITHOUT starting a measurement.
+ *
+ * The reason this exists is the defect #390 was actually about. A session's
+ * window map starts empty, and its first `rate_limit_event` arrives 12-28
+ * seconds before any probe of its own could answer. That event describes ONE
+ * window, the snapshot built from it therefore has one row, and the API stores
+ * the newest snapshot as the state of the whole machine — so a session that had
+ * only just started would overwrite three good rows with one, every time, on a
+ * machine with a single session as much as on a busy one.
+ *
+ * Seeding from the box's last reading closes that: a new session publishes what
+ * the machine already knows in its very first snapshot, and the probe that
+ * follows only refreshes it.
+ */
+export function lastUsageRows() {
+    return lastRows ? { rows: lastRows, measuredAtMs } : null;
+}
+/**
+ * The machine's plan percentages — measured at most once per {@link USAGE_CACHE_MS}.
+ *
+ * Two guards, and they answer different questions. The throttle stops us
+ * measuring again too SOON; the in-flight join stops us measuring twice AT
+ * ONCE. Only the second one fixes the pile-up this change is about: five
+ * sessions reaching a turn end together used to start five copies of a
+ * 20-second CPU-bound process, each of which made the others slower — the same
+ * self-sustaining shape `gitops.ts` writes about for `git_status`.
+ *
+ * Always resolves to the best reading we have, never to «nothing» just because
+ * this attempt failed. A stale true number beats an empty panel — and the
+ * reading carries the moment it was TAKEN, so the caller can tell a fresh
+ * measurement from the one it already folded in (see {@link measuredAtMs}).
+ */
+export function readUsageRows(options) {
+    const now = options.now ?? Date.now();
+    const interval = lastAttemptOk ? USAGE_CACHE_MS : USAGE_FAILURE_COOLDOWN_MS;
+    if (attemptedAtMs !== 0 && now - attemptedAtMs < interval) {
+        return Promise.resolve(lastUsageRows());
+    }
+    if (inFlight)
+        return inFlight;
+    const cwd = options.cwd ?? probeDir();
+    if (cwd === null)
+        return Promise.resolve(lastUsageRows());
+    const pending = probeRunner(options.binary, cwd)
+        .then((text) => {
+        const rows = text ? parseUsageText(text) : [];
+        attemptedAtMs = options.now ?? Date.now();
+        lastAttemptOk = rows.length > 0;
+        // Zero rows is not an answer worth keeping: it means the wording moved or
+        // the CLI said nothing, and the previous true reading is still the best
+        // thing we have to show.
+        if (rows.length > 0) {
+            lastRows = rows;
+            measuredAtMs = attemptedAtMs;
+        }
+        return lastUsageRows();
+    })
+        .catch((error) => {
+        // `probeUsageText` resolves rather than rejects, so this is a seat that
+        // threw or a parser that did — either way the reading is unchanged.
+        log.debug('claude: /usage probe threw', { error: String(error) });
+        attemptedAtMs = options.now ?? Date.now();
+        lastAttemptOk = false;
+        return lastUsageRows();
+    })
+        .finally(() => {
+        inFlight = null;
     });
+    inFlight = pending;
+    return pending;
 }
 //# sourceMappingURL=claude-usage.js.map

package/dist/adapters/claude.js

@@ -10,10 +10,8 @@ import { cageSpawn, memoryDeathSentence, releaseSessionScope } from '../session-
 import { evaluateToolUse, maskSecrets, maskString, } from '../policy.js';
 import { availableModes, cardDescription, DIRECT_BRANCH_RULE, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
 import { percentFromUtilization, RATE_WINDOW_MINUTES, rateWindowKey } from './rate-limits.js';
-import { applyUsagePercentages, parseUsageText, probeUsageText } from './claude-usage.js';
+import { applyUsagePercentages, lastUsageRows, readUsageRows } from './claude-usage.js';
 import { claudeExecutableOption, sessionClaudePath } from '../agent-binary.js';
-/** How often `/usage` may be read. Free, but still a process. */
-const USAGE_PROBE_INTERVAL_MS = 3 * 60 * 1000;
 /** Same 2KB the SDK keeps: enough for the CLI's last words, not a log sink. */
 const STDERR_TAIL_LIMIT = 2048;
 import { answerSummary, answerValue, discussMessage, invalidationMessage, mirrorOptions, newAskId, MAX_OPTIONS, MAX_QUESTIONS, OPTION_TEXT_LIMIT, QUESTION_TEXT_LIMIT, } from './questions.js';
@@ -832,8 +830,6 @@ class ClaudeSession {
     rateLimitsAvailable = false;
     /** A refusal seen since the last turn ended, waiting to be reported with it. */
     limitBlockPending = false;
-    /** When `/usage` was last read, so a busy session does not spawn a process a second. */
-    usageProbedAt = 0;
     /**
      * The one key the window map is written under, from every source.
      *
@@ -870,41 +866,85 @@ class ClaudeSession {
         return providerName === 'five_hour' || providerName === 'seven_day';
     }
     /**
-     * Read the percentages out of the CLI's own `/usage` (#279).
+     * Read the percentages out of the CLI's own `/usage` (#279, #390).
      *
-     * Fire-and-forget, throttled, and free — a local command, not a request
-     * (probe 2026-08-15: zero tokens, zero turns, zero dollars). The live event
-     * gives us the clock and almost never the number; this gives the number and
-     * never touches the clock.
+     * Fire-and-forget and free — a local command, not a request (probe
+     * 2026-08-15: zero tokens, zero turns, zero dollars). The live event gives us
+     * the clock and almost never the number; this gives the number and never
+     * touches the clock.
+     *
+     * Two steps, and the FIRST one is the fix for #390. The reading belongs to
+     * the machine, not to this session — one account, one set of numbers — so
+     * before anything is measured we take what the box already knows. Without it
+     * a session that started thirty seconds ago publishes a snapshot built from
+     * its single `rate_limit_event`, and because the API stores the newest
+     * snapshot as the state of the whole server, that one row replaced three good
+     * ones. Seeding costs nothing, needs no binary, and is why raising the
+     * timeout alone would not have fixed the report.
+     *
+     * The second step refreshes it. The throttle, the ceiling and the guarantee
+     * that only one probe runs per machine all live in `readUsageRows`.
      */
     refreshUsage() {
         if (this.stopped)
             return;
-        if (this.usageProbedAt !== 0 && Date.now() - this.usageProbedAt < USAGE_PROBE_INTERVAL_MS) {
-            return;
-        }
+        if (this.absorbUsageReading(lastUsageRows()))
+            this.emitRateLimits();
         const binary = sessionClaudePath();
         if (!binary)
             return;
-        this.usageProbedAt = Date.now();
-        void probeUsageText(binary, this.spec.cwd)
-            .then((text) => {
-            if (!text || this.stopped)
+        void readUsageRows({ binary })
+            .then((reading) => {
+            if (this.stopped)
                 return;
-            const rows = parseUsageText(text);
-            if (rows.length === 0)
-                return;
-            // A percentage proves a plan as surely as the event does.
-            this.rateLimitsAvailable = true;
-            const merged = applyUsagePercentages([...this.rateLimitWindows.values()], rows);
-            this.rateLimitWindows.clear();
-            for (const window of merged) {
-                this.rateLimitWindows.set(ClaudeSession.windowKey(window.key, window.label), window);
-            }
-            this.emitRateLimits();
+            if (this.absorbUsageReading(reading))
+                this.emitRateLimits();
         })
             .catch((error) => log.debug('claude: usage probe failed', { error: String(error) }));
     }
+    /** The measurement already folded in, so an older one cannot undo a newer event. */
+    usageAppliedAtMs = 0;
+    /**
+     * Fold a `/usage` reading into this session's window map.
+     *
+     * The reading belongs to the MACHINE and arrives at both ends of every turn,
+     * so most of the time it is something this session has already applied. That
+     * distinction is load-bearing rather than an optimisation (found by review):
+     * between two turns a `rate_limit_event` can put a NEWER percentage into a
+     * window, and re-applying a three-minute-old measurement over it rolled 95%
+     * back to 60% — every turn, and in both directions, because usage only climbs
+     * inside a window and drops to nothing when it resets. The warning badge is
+     * driven off that number.
+     *
+     * So a reading we have not seen before is applied outright — it is the
+     * authority for percentages, which is #279's whole premise — and one we have
+     * only FILLS what is still missing.
+     *
+     * Returns whether anything actually moved, so a repeat costs no frame. The
+     * supervisor's level gate would drop the duplicate anyway, but the cheapest
+     * frame is the one never built.
+     */
+    absorbUsageReading(reading) {
+        if (!reading || reading.rows.length === 0)
+            return false;
+        const fresh = reading.measuredAtMs > this.usageAppliedAtMs;
+        const before = this.rateLimitsFingerprint();
+        // A percentage proves a plan as surely as the event does.
+        this.rateLimitsAvailable = true;
+        const merged = applyUsagePercentages([...this.rateLimitWindows.values()], reading.rows, {
+            onlyFillGaps: !fresh,
+        });
+        this.rateLimitWindows.clear();
+        for (const window of merged) {
+            this.rateLimitWindows.set(ClaudeSession.windowKey(window.key, window.label), window);
+        }
+        if (fresh)
+            this.usageAppliedAtMs = reading.measuredAtMs;
+        return this.rateLimitsFingerprint() !== before;
+    }
+    rateLimitsFingerprint() {
+        return JSON.stringify([this.rateLimitsAvailable, [...this.rateLimitWindows.values()]]);
+    }
     /** Read the flag and clear it: one refusal marks exactly one turn end. */
     consumeLimitBlock() {
         const blocked = this.limitBlockPending;

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

@@ -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;
     /**

package/dist/supervisor.js

@@ -144,6 +144,8 @@ export class Supervisor {
      * which of the two is running.
      */
     installInFlight = null;
+    /** A restore-point collection is running; a second reconnect must not start another (#388). */
+    checkpointGcInFlight = false;
     /** Session 14: one project-recipe run per machine, and its verdict queue. */
     verify;
     verifyReports = new VerifyReportQueue();
@@ -3401,9 +3403,20 @@ export 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.
      */
     async captureCheckpoint(running, kind, messageSeq) {
         const worktreePath = running.worktreePath;
@@ -3421,7 +3434,13 @@ export class Supervisor {
             return;
         }
         if (kind === 'TURN' && this.isSessionMidTurn(running)) {
-            this.noticeOncePerTurn(running, 'checkpoint-self-busy', 'No restore point was taken for this step: this session was still answering when it was due.');
+            // Silent in the feed, on purpose (#384) — see the note above. The `return`
+            // is not cosmetic and does not go: reading a tree the agent is writing
+            // produces a restore point that restores half a file (gotcha 438).
+            log.info('supervisor: no restore point — the session was mid-turn', {
+                sessionId: running.descriptor.id,
+                ...(messageSeq === undefined ? {} : { messageSeq }),
+            });
             return;
         }
         if (await this.isRepoLocked(worktreePath)) {
@@ -3487,16 +3506,18 @@ export class Supervisor {
     /**
      * 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).
      */
     noticeOncePerTurn(running, key, text) {
         running.noticesThisTurn ??= new Set();
@@ -4275,14 +4296,26 @@ export class Supervisor {
         // switched off leaves restore points — a full copy of a working tree —
         // with no row anywhere pointing at them, and nothing else on this machine
         // would ever collect them.
-        void pruneCheckpoints({ liveSessionIds: known }).then((result) => {
-            if (result.droppedRefs > 0) {
-                log.info('supervisor: collected orphaned restore points', {
-                    sessions: result.droppedSessions.length,
-                    refs: result.droppedRefs,
-                });
-            }
-        }, (error) => log.warn('supervisor: restore-point GC failed', { error: String(error) }));
+        //
+        // One at a time (#388): reconnects come in runs, and since the collection
+        // holds the store while it collects, a second one started on top of the
+        // first would only queue — in front of the restore points of whoever is
+        // working. The next reconnect collects whatever this pass leaves.
+        if (!this.checkpointGcInFlight) {
+            this.checkpointGcInFlight = true;
+            void pruneCheckpoints({ liveSessionIds: known })
+                .then((result) => {
+                if (result.droppedRefs > 0) {
+                    log.info('supervisor: collected orphaned restore points', {
+                        sessions: result.droppedSessions.length,
+                        refs: result.droppedRefs,
+                    });
+                }
+            }, (error) => log.warn('supervisor: restore-point GC failed', { error: String(error) }))
+                .finally(() => {
+                this.checkpointGcInFlight = false;
+            });
+        }
         for (const [sessionId, running] of [...this.sessions]) {
             if (known.has(sessionId))
                 continue;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.55.1";
+export declare const RUNNER_VERSION = "0.56.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in sync with package.json by the release script (manual for now).
-export const RUNNER_VERSION = '0.55.1';
+export const RUNNER_VERSION = '0.56.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge4dev/runner",
-  "version": "0.55.1",
+  "version": "0.56.0",
   "description": "DevBridge dev runner — connects a dev server to DevBridge and runs agent sessions (Claude Code / Codex)",
   "homepage": "https://bridge4.dev",
   "license": "MIT",