@bridge4dev/runner 0.46.1 → 0.47.0

package/README.md

@@ -69,16 +69,58 @@ it. If you would rather run it in the foreground, or under your own supervisor,
 
 Both honour `XDG_CONFIG_HOME` / `XDG_STATE_HOME`.
 
+## What the machine's owner can switch off
+
+`config.toml` is read by the runner and cannot be changed from the dashboard — these are
+the owner's vetoes, and they survive re-pairing. A capability switched off here is not
+announced to the server at all, so the dashboard draws no control rather than a control
+that answers «refused».
+
+```toml
+[verify]
+enabled = true          # running the project's own build/test recipe
+
+[checkpoints]
+enabled = true          # restore points (copies of the working tree, on this disk)
+
+[agents]
+install_enabled = true  # installing and updating the agent CLIs (0.47.0)
+```
+
+`[agents] install_enabled = false` covers both routes at once: the **Install** / **Update**
+buttons on the server card and the automatic update a session start would otherwise
+trigger. It is the same download onto the same disk either way.
+
+## Agent CLIs
+
+Since 0.47.0 the runner does not carry a Claude binary and the installer does not install
+agents. Both `claude` and `codex` are ordinary system installs, and the server card shows
+each one with its version:
+
+- **Install / Update** run the vendor's own installer for that agent, at a version the
+  card picked from the registry. Free space is checked first, the new binary is smoke-tested
+  by running it, and a build that will not run is rolled back. **The daemon does not
+  restart** — sessions already running keep the file they opened, and the new version takes
+  effect for the next one.
+- **Auto-update agents** (on by default) does the same thing on its own when a session
+  starts, for that session's agent only, at most once a day per agent.
+
+```bash
+claude --version
+codex --version
+```
+
 ## Updating
 
 From the dashboard: the server card offers **Update runner** once a newer version is
 available, and the runner replaces itself — smoke-testing the new build before it
-restarts, and rolling back to the previous tarball if that test fails.
+restarts, and rolling back to the previous tarball if that test fails. **Updating the
+runner disconnects every session running on this machine**; updating an agent does not.
 
 By hand:
 
 ```bash
-npm install -g @bridge4dev/runner && systemctl --user restart devbridge-runner
+npm install -g --omit=optional @bridge4dev/runner && systemctl --user restart devbridge-runner
 ```
 
 ## License

package/dist/adapters/claude.js

@@ -8,7 +8,7 @@ import { evaluateToolUse, maskSecrets, maskString, } from '../policy.js';
 import { availableModes, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, 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 { claudeCliPath } from '../agent-binary.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;
 import { answerSummary, answerValue, discussMessage, invalidationMessage, mirrorOptions, newAskId, MAX_OPTIONS, MAX_QUESTIONS, OPTION_TEXT_LIMIT, QUESTION_TEXT_LIMIT, } from './questions.js';
@@ -501,6 +501,10 @@ class ClaudeSession {
         const options = {
             cwd: spec.cwd,
             env: agentEnv(this.mode),
+            // Empty while `USE_BUNDLED_CLAUDE` — the SDK keeps resolving its own
+            // bundled binary, exactly as before. After C3 this pins the system
+            // `claude`, which is the file the card measures and the button installs.
+            ...claudeExecutableOption(),
             /**
              * Everything the machine's own Claude has (owner's call, 2026-07-30).
              *
@@ -785,7 +789,7 @@ class ClaudeSession {
         if (this.usageProbedAt !== 0 && Date.now() - this.usageProbedAt < USAGE_PROBE_INTERVAL_MS) {
             return;
         }
-        const binary = claudeCliPath();
+        const binary = sessionClaudePath();
         if (!binary)
             return;
         this.usageProbedAt = Date.now();

package/dist/agent-auto-update.d.ts

@@ -0,0 +1,75 @@
+import { type AgentRuntime } from './agent-registry.js';
+import type { MeasuredAgentVersion } from './agent-versions.js';
+/**
+ * Moving an agent CLI forward on its own, when a session on that agent starts
+ * (Р13, §4.8 of the plan).
+ *
+ * Not a scheduler and not our idea of a policy — it is the update path both
+ * vendors already have, reconnected to the way DevBridge actually launches
+ * them. Claude updates itself when a human types `claude` in a terminal; Codex
+ * only prints a banner, and only in its terminal UI. On a dev server nobody
+ * types either: the runner starts `claude` through the SDK and `codex
+ * app-server`, and in that mode NEITHER agent ever moves. Left alone, a machine
+ * stays on whatever version the day of its last manual install left behind.
+ *
+ * Two files' worth of care go into what this must NOT do:
+ *
+ *  - **it must not delay a session.** The person asked for a session, not for
+ *    an update. The install runs behind the start and the current session
+ *    finishes on the file it already opened — a running process keeps its own
+ *    inode, so replacing the binary underneath it is invisible to it;
+ *  - **it must not try again every time.** Once a day per (agent, machine), and
+ *    the mark is written on disk BEFORE the attempt, so a machine with no disk
+ *    space and no network gives up for the day instead of downloading nothing
+ *    over and over at every session start.
+ */
+/** One attempt per agent per day, whatever the outcome. */
+export declare const AUTO_UPDATE_WINDOW_MS: number;
+/**
+ * Take today's single attempt for this agent, or refuse.
+ *
+ * Records the attempt itself rather than trusting the caller to, and records it
+ * **before** the install runs — a download that dies halfway has still used the
+ * day. `auto-resume.ts` claims the same way and for the same reason: a ceiling
+ * that only counts successes is not a ceiling.
+ *
+ * On disk, not in memory: a runner restarted by a crash loop would otherwise
+ * start every session with a fresh allowance.
+ *
+ * The window is measured on the ABSOLUTE distance, which is what makes a clock
+ * that moved matter correctly in both directions. A VM resumed from a snapshot
+ * or an ntp step back an hour must not hand out a second attempt — that is the
+ * common case, and `now - last` alone would let it through. A mark that is a
+ * year in the future is a machine whose clock was simply wrong when it was
+ * written, and freezing auto-update on it until the calendar catches up would
+ * be worse than one extra install.
+ */
+export declare function claimAgentAutoUpdate(wireKey: string, now?: number): boolean;
+/** Test seam — the ledger is a file, and tests need it empty. */
+export declare function forgetAgentAutoUpdates(): void;
+/**
+ * Why we are not updating this agent right now — or `null`, meaning go ahead.
+ *
+ * A string rather than a boolean so the log line says which of the six it was.
+ * Every one of them is «leave the machine exactly as it is», and four of them
+ * are refusals the plan states outright:
+ *
+ *  - **not installed** — installing an absent agent is a person's decision (Р3);
+ *  - **somebody else's package manager** — replacing a Homebrew copy would leave
+ *    two installations fighting over one command name;
+ *  - **the probe failed** — the binary is there and will not say what it is, so
+ *    there is no version to roll back to if the new one is broken;
+ *  - **already current or ahead** — a machine ahead of our snapshot is a machine
+ *    whose owner updated it by hand an hour ago, and walking it back would be a
+ *    downgrade nobody asked for.
+ *
+ * Deliberately pure: no clock, no disk, no processes. The claim and the lock are
+ * the caller's, because only the caller can hold them for the length of an
+ * install.
+ */
+export declare function autoUpdateRefusal(input: {
+    runtime: AgentRuntime;
+    measured: MeasuredAgentVersion;
+    latest: string;
+}): string | null;
+//# sourceMappingURL=agent-auto-update.d.ts.map

package/dist/agent-auto-update.js

@@ -0,0 +1,134 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { compareAgentVersions } from './agent-registry.js';
+import { stateDir } from './paths.js';
+/**
+ * Moving an agent CLI forward on its own, when a session on that agent starts
+ * (Р13, §4.8 of the plan).
+ *
+ * Not a scheduler and not our idea of a policy — it is the update path both
+ * vendors already have, reconnected to the way DevBridge actually launches
+ * them. Claude updates itself when a human types `claude` in a terminal; Codex
+ * only prints a banner, and only in its terminal UI. On a dev server nobody
+ * types either: the runner starts `claude` through the SDK and `codex
+ * app-server`, and in that mode NEITHER agent ever moves. Left alone, a machine
+ * stays on whatever version the day of its last manual install left behind.
+ *
+ * Two files' worth of care go into what this must NOT do:
+ *
+ *  - **it must not delay a session.** The person asked for a session, not for
+ *    an update. The install runs behind the start and the current session
+ *    finishes on the file it already opened — a running process keeps its own
+ *    inode, so replacing the binary underneath it is invisible to it;
+ *  - **it must not try again every time.** Once a day per (agent, machine), and
+ *    the mark is written on disk BEFORE the attempt, so a machine with no disk
+ *    space and no network gives up for the day instead of downloading nothing
+ *    over and over at every session start.
+ */
+/** One attempt per agent per day, whatever the outcome. */
+export const AUTO_UPDATE_WINDOW_MS = 24 * 60 * 60 * 1_000;
+function ledgerPath() {
+    return path.join(stateDir(), 'agent-auto-update.json');
+}
+function read() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(ledgerPath(), 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        // Missing, unreadable or half-written — «nobody has tried today» is the
+        // answer that keeps the feature working rather than the one that is safe,
+        // and the cost of being wrong here is one extra install per day.
+        return {};
+    }
+}
+function write(ledger) {
+    try {
+        const dir = stateDir();
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const tmp = path.join(dir, `.agent-auto-update.json.${process.pid}.tmp`);
+        fs.writeFileSync(tmp, JSON.stringify(ledger), { mode: 0o600 });
+        fs.renameSync(tmp, ledgerPath());
+    }
+    catch {
+        // A machine that cannot write its state directory has bigger problems than
+        // a missed throttle, and failing to record an attempt must never be the
+        // thing that stops a session from starting.
+    }
+}
+/**
+ * Take today's single attempt for this agent, or refuse.
+ *
+ * Records the attempt itself rather than trusting the caller to, and records it
+ * **before** the install runs — a download that dies halfway has still used the
+ * day. `auto-resume.ts` claims the same way and for the same reason: a ceiling
+ * that only counts successes is not a ceiling.
+ *
+ * On disk, not in memory: a runner restarted by a crash loop would otherwise
+ * start every session with a fresh allowance.
+ *
+ * The window is measured on the ABSOLUTE distance, which is what makes a clock
+ * that moved matter correctly in both directions. A VM resumed from a snapshot
+ * or an ntp step back an hour must not hand out a second attempt — that is the
+ * common case, and `now - last` alone would let it through. A mark that is a
+ * year in the future is a machine whose clock was simply wrong when it was
+ * written, and freezing auto-update on it until the calendar catches up would
+ * be worse than one extra install.
+ */
+export function claimAgentAutoUpdate(wireKey, now = Date.now()) {
+    const ledger = read();
+    const last = ledger[wireKey]?.at;
+    if (typeof last === 'number' && Math.abs(now - last) < AUTO_UPDATE_WINDOW_MS)
+        return false;
+    ledger[wireKey] = { at: now };
+    write(ledger);
+    return true;
+}
+/** Test seam — the ledger is a file, and tests need it empty. */
+export function forgetAgentAutoUpdates() {
+    try {
+        fs.rmSync(ledgerPath(), { force: true });
+    }
+    catch {
+        /* nothing to forget */
+    }
+}
+/**
+ * Why we are not updating this agent right now — or `null`, meaning go ahead.
+ *
+ * A string rather than a boolean so the log line says which of the six it was.
+ * Every one of them is «leave the machine exactly as it is», and four of them
+ * are refusals the plan states outright:
+ *
+ *  - **not installed** — installing an absent agent is a person's decision (Р3);
+ *  - **somebody else's package manager** — replacing a Homebrew copy would leave
+ *    two installations fighting over one command name;
+ *  - **the probe failed** — the binary is there and will not say what it is, so
+ *    there is no version to roll back to if the new one is broken;
+ *  - **already current or ahead** — a machine ahead of our snapshot is a machine
+ *    whose owner updated it by hand an hour ago, and walking it back would be a
+ *    downgrade nobody asked for.
+ *
+ * Deliberately pure: no clock, no disk, no processes. The claim and the lock are
+ * the caller's, because only the caller can hold them for the length of an
+ * install.
+ */
+export function autoUpdateRefusal(input) {
+    const { runtime, measured, latest } = input;
+    if (measured.probeFailed)
+        return 'the version probe failed';
+    if (measured.version === null)
+        return 'not installed here';
+    if (measured.managedBy !== runtime.install.managedBy) {
+        return `installed with ${measured.managedBy}`;
+    }
+    const behind = compareAgentVersions(measured.version, latest);
+    if (behind === null)
+        return 'the versions are not comparable';
+    if (behind >= 0)
+        return 'already up to date';
+    return null;
+}
+//# sourceMappingURL=agent-auto-update.js.map

package/dist/agent-binary.d.ts

@@ -25,4 +25,52 @@ export declare function findClaudeCli(packageDir: string): string | null;
  * platform package is reachable from the SDK and from nowhere else.
  */
 export declare function claudeCliPath(): string | null;
+/**
+ * Which Claude the SESSIONS run on.
+ *
+ * `true` — the binary bundled inside this runner's own installation, as an
+ * optional platform package of the SDK. That is how it has always worked, and
+ * it is why «update Claude» has meant «reinstall the runner», which kills every
+ * live session on the machine (гоча #414).
+ *
+ * `false` — the system `claude` on PATH: installed, measured and updated like
+ * any other agent, by the same button, without touching the daemon (Р1, Р10).
+ *
+ * **Flipped to `false` in 0.47.0** (#371, stage C3). It stayed `true` through
+ * the whole implementation on purpose: the API image packs this worktree into
+ * the tarball every dev server updates from, so an early flip would have moved
+ * the fleet onto a system binary half of them did not have — before the button
+ * that installs it existed. That button ships in the same release, the card
+ * says «Install» on any machine that needs it, and Р11 is the owner's decision
+ * that there are no other safety nets: every server is one we can reach.
+ *
+ * The bundled code stays compiled in rather than deleted, so the way back is
+ * this one value rather than a revert. Two things must move with it if it ever
+ * goes back to `true`: the `--omit=optional` in `self-update.ts` (the binary
+ * would stop being installed at all) and the guard test below it.
+ */
+export declare const USE_BUNDLED_CLAUDE = false;
+/**
+ * The Claude executable a session should be started with, or null when there is
+ * none to start.
+ *
+ * The two answers are genuinely different files of different versions on the
+ * same machine — measured seven versions apart on this very dev server — so
+ * every caller must go through here rather than pick one.
+ *
+ * The parameter exists so both branches can be tested without mocking a module
+ * the tests also need the real behaviour of; production always takes the default.
+ */
+export declare function sessionClaudePath(useBundled?: boolean): string | null;
+/**
+ * The SDK option that pins the executable, for both places that build `Options`.
+ *
+ * Empty while the bundled binary is in use: the SDK then resolves its own, which
+ * is exactly today's behaviour and keeps `main` neutral. Empty also when the
+ * system binary is missing — passing a path we know is not there would turn a
+ * clear «Claude is not installed» into an SDK spawn error.
+ */
+export declare function claudeExecutableOption(useBundled?: boolean): {
+    pathToClaudeCodeExecutable?: string;
+};
 //# sourceMappingURL=agent-binary.d.ts.map

package/dist/agent-binary.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { AGENT_RUNTIMES } from './agent-registry.js';
+import { whichExecutable } from './environment.js';
 /**
  * Is the binary this runner would actually launch Claude with present?
  *
@@ -96,4 +98,57 @@ function resolveFromSdkEntry(sdkEntry) {
     }
     return null;
 }
+/**
+ * Which Claude the SESSIONS run on.
+ *
+ * `true` — the binary bundled inside this runner's own installation, as an
+ * optional platform package of the SDK. That is how it has always worked, and
+ * it is why «update Claude» has meant «reinstall the runner», which kills every
+ * live session on the machine (гоча #414).
+ *
+ * `false` — the system `claude` on PATH: installed, measured and updated like
+ * any other agent, by the same button, without touching the daemon (Р1, Р10).
+ *
+ * **Flipped to `false` in 0.47.0** (#371, stage C3). It stayed `true` through
+ * the whole implementation on purpose: the API image packs this worktree into
+ * the tarball every dev server updates from, so an early flip would have moved
+ * the fleet onto a system binary half of them did not have — before the button
+ * that installs it existed. That button ships in the same release, the card
+ * says «Install» on any machine that needs it, and Р11 is the owner's decision
+ * that there are no other safety nets: every server is one we can reach.
+ *
+ * The bundled code stays compiled in rather than deleted, so the way back is
+ * this one value rather than a revert. Two things must move with it if it ever
+ * goes back to `true`: the `--omit=optional` in `self-update.ts` (the binary
+ * would stop being installed at all) and the guard test below it.
+ */
+export const USE_BUNDLED_CLAUDE = false;
+/**
+ * The Claude executable a session should be started with, or null when there is
+ * none to start.
+ *
+ * The two answers are genuinely different files of different versions on the
+ * same machine — measured seven versions apart on this very dev server — so
+ * every caller must go through here rather than pick one.
+ *
+ * The parameter exists so both branches can be tested without mocking a module
+ * the tests also need the real behaviour of; production always takes the default.
+ */
+export function sessionClaudePath(useBundled = USE_BUNDLED_CLAUDE) {
+    return useBundled ? claudeCliPath() : whichExecutable(AGENT_RUNTIMES.claude.bin);
+}
+/**
+ * The SDK option that pins the executable, for both places that build `Options`.
+ *
+ * Empty while the bundled binary is in use: the SDK then resolves its own, which
+ * is exactly today's behaviour and keeps `main` neutral. Empty also when the
+ * system binary is missing — passing a path we know is not there would turn a
+ * clear «Claude is not installed» into an SDK spawn error.
+ */
+export function claudeExecutableOption(useBundled = USE_BUNDLED_CLAUDE) {
+    if (useBundled)
+        return {};
+    const binary = sessionClaudePath(useBundled);
+    return binary ? { pathToClaudeCodeExecutable: binary } : {};
+}
 //# sourceMappingURL=agent-binary.js.map

package/dist/agent-cleanup.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Throwing away the Claude versions nobody will run again (Р12, §4.7).
+ *
+ * Anthropic's native installer keeps **every** version it has ever downloaded
+ * as a separate 200–330 MB executable in `~/.local/share/claude/versions/` and
+ * deletes none of them; the launcher on PATH is a symlink pointing at one. On
+ * this very dev server that was five copies and 1.4 GB with the disk 80 % full
+ * (гоча #414) — and stage D now moves the version forward by itself, so what
+ * used to grow by a file a month grows by a file a day.
+ *
+ * Three files are untouchable, and each is a different way to break a machine:
+ *
+ *  1. **whatever the launcher points at.** Delete it and `claude` on PATH is a
+ *     dangling symlink: no sessions, no sign-in, and nothing on the card
+ *     explaining it — `measureAgent` would report a probe failure, which stage 2
+ *     already knows is a state with no way out from the interface.
+ *  2. **the version a rollback would restore.** A failed install puts the
+ *     previous version back by pointing the launcher at its file, so «keep two»
+ *     is not an arbitrary number: it is current + the one behind it.
+ *  3. **a version some process is still executing.** Claude Code launches its
+ *     own helpers by its own path, and a session that started two updates ago is
+ *     running the third file from the end. Unlinking a mapped executable does
+ *     not kill it on Linux, but it does make every later `exec` of that path
+ *     fail — and the caller's own gate (sweep only when this runner is tracking
+ *     no sessions at all) cannot see a process somebody started by hand.
+ */
+/** Current + the one a rollback would restore. Р12 says two, and two it is. */
+export declare const KEEP_VERSIONS = 2;
+export interface VersionSweepResult {
+    /** Version numbers whose files were unlinked. */
+    removed: string[];
+    /** Freed bytes, as measured before the unlink. */
+    freedBytes: number;
+    /** Versions left alone, with the reason — the log line worth having. */
+    kept: Array<{
+        version: string;
+        reason: string;
+    }>;
+}
+/**
+ * The version the launcher on PATH resolves to, or null.
+ *
+ * Read by resolving the symlink rather than by running `claude --version`: the
+ * question is «which FILE», and this runs on a timer where spawning a 300 MB
+ * binary would be a poor way to ask. `realpath` follows a chain of links, so a
+ * distribution that put its own wrapper in between still answers correctly.
+ */
+export declare function currentNativeVersion(homeDir: string): string | null;
+/**
+ * Version files at least one live process is executing right now, best effort.
+ *
+ * `/proc/<pid>/exe` is a symlink to the executable's real path, so this is an
+ * exact answer for every process this user may look at — and an empty answer on
+ * a platform without `/proc`. Unreadable entries are SKIPPED rather than treated
+ * as a match: another user's process cannot be running a file out of this user's
+ * home, and refusing to sweep whenever `/proc` holds anything opaque would mean
+ * never sweeping on a busy machine.
+ */
+export declare function versionsInUse(homeDir: string): Set<string>;
+export interface VersionSweepOptions {
+    /** The daemon user's home. Only ever this one — never another account's. */
+    homeDir?: string;
+    keep?: number;
+    /** Test seam: which versions a process holds. */
+    inUse?: (homeDir: string) => Set<string>;
+    /** Test seam: which version the launcher points at. */
+    current?: (homeDir: string) => string | null;
+    /** Test seam: actually unlink. */
+    remove?: (file: string) => void;
+}
+/**
+ * Sweep, and say what happened.
+ *
+ * Never throws: this runs on a timer beside live sessions, and a permission
+ * error on one file must cost that file, not the daemon.
+ */
+export declare function pruneNativeClaudeVersions(options?: VersionSweepOptions): VersionSweepResult;
+//# sourceMappingURL=agent-cleanup.d.ts.map