@bridge4dev/runner 0.13.1 → 0.26.0

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { execFile } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -9,13 +10,27 @@ import { CodexAdapter } from './adapters/codex.js';
 import { ensureCodexHome } from './adapters/codex-home.js';
 import { loadConfig, requireConfig, saveConfig } from './config.js';
 import { log } from './log.js';
-import { isSupervisedProcess, resolveInstalledPackageDir } from './self-update.js';
+import { installIsWritable, isSupervisedProcess, resolveInstalledPackageDir, } from './self-update.js';
 import { Supervisor } from './supervisor.js';
 import { readStatusFile, isPidAlive, writeStatusFile, STATUS_FRESH_MS } from './status-file.js';
 import { RunnerWsClient } from './ws-client.js';
 import { RUNNER_VERSION } from './version.js';
-import { buildUnit, unitExecTarget, unitPath } from './service-unit.js';
+import { buildUnit, cpuQuotaPercent, limitsOverrideIsOutdated, limitsOverridePath, unitExecTarget, unitPath, writeLimitsOverride, LIMITS_VERSION, } from './service-unit.js';
+import { readOomKills, recordCrash, takeLastExit } from './crash-note.js';
+import { agentAuthStatuses } from './auth-relay.js';
+import { addSafeDirectory, agentConfigContour, dockerCheck, ensureAgentPath, firstUnreachableAncestor, hasSafeDirectory, inspectPath, knownWorkspacePaths, lingerEnabled, nodeCheck, otherHomeWithAgents, runnerIdentity, safeDirectoryCommand, systemctlHint, systemdUserBusReachable, systemdUserEnv, } from './environment.js';
+import { mcpConfigDir } from './paths.js';
 const execFileAsync = promisify(execFile);
+/**
+ * Identity of this process, and the note the previous one left.
+ *
+ * Read once at module load, before anything can connect: `takeLastExit()`
+ * CONSUMES the note, so it must happen exactly once per process — reading it
+ * per reconnect would report the same death forever (QA-112).
+ */
+const INSTANCE_ID = crypto.randomUUID();
+const STARTED_AT = new Date().toISOString();
+const LAST_EXIT = takeLastExit();
 function print(line) {
     process.stdout.write(line + '\n');
 }
@@ -47,7 +62,28 @@ function installedAgents() {
  * instead of a button that would fail on tap.
  */
 function selfUpdatable() {
-    return resolveInstalledPackageDir() !== null && isSupervisedProcess();
+    const packageDir = resolveInstalledPackageDir();
+    return packageDir !== null && isSupervisedProcess() && installIsWritable(packageDir);
+}
+/**
+ * Why this runner cannot replace itself — so the card can SAY it.
+ *
+ * Both halves look identical from the dashboard (no button), and "why does this
+ * machine have a button and that one doesn't" is exactly the question the page
+ * should not leave hanging. Reported as a string rather than inferred, because
+ * only the runner knows how it was started.
+ */
+function selfUpdateBlockedReason() {
+    const packageDir = resolveInstalledPackageDir();
+    if (packageDir === null)
+        return 'source-checkout';
+    if (!isSupervisedProcess())
+        return 'unsupervised';
+    // Installed by one user, run by another: npm would fail halfway through with
+    // EACCES. Reported so the card shows the command instead of a button.
+    if (!installIsWritable(packageDir))
+        return 'not-writable';
+    return null;
 }
 function hasExecutable(name) {
     const dirs = (process.env['PATH'] ?? '').split(path.delimiter).filter(Boolean);
@@ -68,7 +104,12 @@ function hasExecutable(name) {
  * command it does not know would just hang until the gateway timeout.
  */
 function runnerCapabilities() {
-    const localLimit = loadConfig()?.limits?.max_sessions;
+    const config = loadConfig();
+    const localLimit = config?.limits?.max_sessions;
+    // Session 14: the machine owner's veto. Default on — the safety of the
+    // feature is that a DevBridge manager approves every command first — but the
+    // person who owns the server gets the last word on whether it exists here.
+    const verifyEnabled = config?.verify?.enabled !== false;
     return {
         agents: installedAgents(),
         git: true,
@@ -83,7 +124,17 @@ function runnerCapabilities() {
          * installed package under a supervisor — a source checkout or a hand-started
          * daemon says so here, so the button never appears where it cannot work.
          */
-        ...(selfUpdatable() ? { selfUpdate: true } : {}),
+        ...(selfUpdatable()
+            ? { selfUpdate: true }
+            : { selfUpdateBlocked: selfUpdateBlockedReason() ?? 'unsupervised' }),
+        /**
+         * Which OS user this daemon runs as (0.24.0).
+         *
+         * The card needs it to write a command that will actually work: an update
+         * installed by root has to be restarted as THIS user, and «run it as root»
+         * is only half the instruction without a name to restart under.
+         */
+        runnerUser: runnerIdentity().user,
         /**
          * A stricter ceiling set on the machine itself (layer 1). Reported so the
          * dashboard can explain why raising the number there changed nothing.
@@ -99,8 +150,144 @@ function runnerCapabilities() {
          * History tab rather than showing a tab that answers "unknown command".
          */
         gitHistory: true,
+        /**
+         * Session 12: parks `AskUserQuestion` and understands the `question_answer`
+         * frame. The API refuses to accept an answer without it — otherwise the
+         * frame would leave, the socket would report success, and the runner would
+         * drop it: the silent failure this whole session exists to remove.
+         */
+        questionCards: true,
+        /**
+         * Session 13: git is a workplace, not a one-way door.
+         *
+         * Understands `branchPlan` (create vs continue, with a pinned fork point),
+         * answers `git_branches` / `update_from_base` / `git_push`, and reports
+         * ahead/behind/drift in `git_status`. One flag rather than four: they ship
+         * together and the panel needs all of them to say anything true.
+         */
+        gitWorkspace: true,
+        /**
+         * Session 14: the graph became a repository viewer.
+         *
+         * `git_refs`, a `git_log` that takes an explicit ref set, typed
+         * decorations, the committer in both formats, and `workspace_state`. One
+         * flag rather than five: the graph needs all of them at once to draw
+         * anything the previous version could not.
+         */
+        gitRefs: true,
+        /**
+         * Session 14: reads `.devbridge/project.json`. Announced even when
+         * verification is switched off — «this machine will not run recipes» and
+         * «this project has no recipe» are different sentences and the card has to
+         * be able to say both.
+         */
+        projectRecipe: true,
+        /**
+         * Session 14: can execute an APPROVED recipe and report a verdict.
+         *
+         * Withheld when the machine's owner set `[verify] enabled = false`, and
+         * withheld means the dashboard draws no card at all — a control that is
+         * switched off must not look like a control that is broken.
+         */
+        ...(verifyEnabled ? { verifyRuns: true } : { verifyBlocked: 'disabled-by-config' }),
+        /** Session 14: a second, detached worktree driven only by `preview`. */
+        ...(verifyEnabled ? { previewWorktrees: true } : {}),
+        /** Session 14: one-shot agent-written commit messages. */
+        commitMessages: true,
+        /**
+         * Session 15: `git_status` reports whether the PROJECT FOLDER is clean, so
+         * the panel can say what is blocking an Apply instead of offering a button
+         * that the runner will refuse.
+         */
+        workspaceDirtyReporting: true,
+        /**
+         * Session 15: reads `agentAutoCommit` off the workspace and honours it on
+         * every tool call rather than at launch.
+         *
+         * Its own flag now. It used to ride on `workspaceStash`, which was fine
+         * while the two shipped together and wrong the moment one of them was
+         * deleted — the settings card would have started calling every up-to-date
+         * runner incapable of the setting it honours.
+         */
+        agentAutoCommit: true,
+        /**
+         * Session 16: git is git.
+         *
+         * `git_stage` / `git_unstage` / `git_discard` / `git_pull` /
+         * `git_merge_abort`, a `git_status` that reports the working tree the way
+         * `git status` does (both columns, upstream, ahead/behind, merge in
+         * progress), a `git_diff` that can show either side of the index, a
+         * `git_commit` that can commit just what was staged, and `workMode:
+         * DIRECT` — a session that works in the project folder itself.
+         *
+         * One flag for all of it because the Source Control panel needs all of it:
+         * a stage button next to a status that cannot say what is staged would be a
+         * control with nothing to control.
+         */
+        sourceControl: true,
+        /**
+         * Session 17 (#113): `agent_tasks` — the live set of subagents, background
+         * shells and dynamic workflows the agent is running beside the
+         * conversation, published as a level signal with REPLACE semantics.
+         *
+         * Nothing gates on it yet — the tray simply stays empty on a runner that
+         * sends no `agent_tasks`, which is the right behaviour either way. It is
+         * advertised now because a capability has to be on the wire BEFORE anything
+         * can gate on it: the runner ships to machines on its own schedule, and a
+         * flag added at the same time as its first reader is a flag that reads
+         * `false` on every server that has not been updated yet.
+         */
+        agentTasks: true,
+        /**
+         * Session 18 (QA-112): the facts DevBridge needs to stop guessing.
+         *
+         * `maxSessions` was a number out of thin air (default 3) while this machine
+         * silently decided whether three agents fit. Three measured `claude`
+         * processes are ~1.7 GB and one workspace typecheck peaks at 1.5 GB, so on a
+         * small box the answer is no — and the only symptom used to be a dead runner.
+         * Reported so the dashboard can recommend a ceiling and explain a refusal.
+         */
+        machine: {
+            cpuCount: os.cpus().length,
+            memTotalBytes: os.totalmem(),
+            memAvailableBytes: os.freemem(),
+            limitsVersion: LIMITS_VERSION,
+            limitsCurrent: !limitsOverrideIsOutdated(),
+        },
+        /**
+         * Identity of THIS process, so the API can tell a network blink from a
+         * restart. Without it `dev-runner: connected activeSessions: 3` reads the
+         * same either way, which is why the incident's six drops could not be
+         * classified (QA-112 MAJOR-4).
+         */
+        instanceId: INSTANCE_ID,
+        startedAt: STARTED_AT,
+        /**
+         * How the PREVIOUS process died, consumed once. Absent on a clean start.
+         * `kind: 'oom'` is inferred from the cgroup counter — see `crash-note.ts`.
+         */
+        ...(LAST_EXIT ? { lastExit: LAST_EXIT } : {}),
         /** Commands beyond the stage-A/B set. */
-        commands: ['purge_session', 'git_log', 'git_show'],
+        commands: [
+            'purge_session',
+            'git_log',
+            'git_show',
+            'git_branches',
+            'update_from_base',
+            'git_push',
+            'git_refs',
+            'workspace_state',
+            'git_stage',
+            'git_unstage',
+            'git_discard',
+            'git_pull',
+            'git_merge_abort',
+            'recipe_state',
+            'propose_commit_message',
+            ...(verifyEnabled
+                ? ['verify_start', 'verify_status', 'verify_cancel', 'preview_checkout', 'preview_stop']
+                : []),
+        ],
     };
 }
 // ─── pair ────────────────────────────────────────────────────────────
@@ -165,9 +352,83 @@ function bootstrapCodex(config) {
 }
 /** Long enough for the `command_result` frame to leave the socket. */
 const RESTART_DELAY_MS = 1_500;
+/**
+ * Bring this machine's resource policy up to date, on every daemon start.
+ *
+ * `self-update` also does this, and that is NOT enough: the update is executed by
+ * the process being replaced, so the code that writes the drop-in only exists in
+ * the build being INSTALLED. Updating 0.20.1 → 0.21.0 therefore left the bad
+ * `MemoryMax=2G` in place and the runner reported `limitsCurrent: false` on its
+ * first hello — caught live on vmi3328440, 2026-07-30 03:35 UTC.
+ *
+ * A migration that only runs during an update can never fix the version that
+ * introduces it. Startup is the place that always belongs to the new build.
+ *
+ * Idempotent by version marker, so a normal restart writes nothing. Never fatal:
+ * a runner that refuses to start because it could not improve its own limits is
+ * strictly worse than one that starts without the improvement.
+ */
+async function repairResourceLimits() {
+    try {
+        if (!writeLimitsOverride())
+            return;
+        log.warn('daemon: resource limits drop-in written — reloading systemd', {
+            path: limitsOverridePath(),
+            version: LIMITS_VERSION,
+        });
+        await execFileAsync('systemctl', ['--user', 'daemon-reload'], {
+            timeout: 15_000,
+            env: systemdUserEnv(),
+        });
+        // Deliberately no restart: `daemon-reload` alone is enough for these
+        // directives (verified live — OOMPolicy went stop→continue and MemoryMax
+        // 2G→infinity with the PID unchanged), and restarting here would park every
+        // live session to apply a setting that is already in force.
+        log.info('daemon: resource limits applied without a restart');
+    }
+    catch (error) {
+        log.error('daemon: could not apply the resource limits drop-in', {
+            error: String(error instanceof Error ? error.message : error),
+            hint: 'run `devbridge-runner doctor --fix`',
+        });
+    }
+}
+/**
+ * Ticket #119. `ClaudeAdapter.stop()` removes each session's MCP config file,
+ * but a kill -9, an OOM or a machine reboot leaves it behind — a live project
+ * key sitting on disk with nothing left that will ever clean it up. Nothing is
+ * running yet at this point in the boot, so every file here is by definition an
+ * orphan of a previous process.
+ */
+function sweepOrphanedMcpConfigs() {
+    const dir = mcpConfigDir();
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return; // never created — the normal case on a fresh install
+    }
+    let removed = 0;
+    for (const name of entries) {
+        if (!name.startsWith('devbridge-mcp.') || !name.endsWith('.json'))
+            continue;
+        try {
+            fs.unlinkSync(path.join(dir, name));
+            removed += 1;
+        }
+        catch {
+            // Leave it; a warning per file would be noise.
+        }
+    }
+    if (removed > 0)
+        log.warn('daemon: removed orphaned MCP config files', { count: removed });
+}
 async function cmdDaemon() {
     const config = requireConfig();
     log.info('daemon starting', { version: RUNNER_VERSION, server: config.server.name });
+    sweepOrphanedMcpConfigs();
+    await repairResourceLimits();
     const agents = installedAgents();
     const ws = new RunnerWsClient(config.api.ws_url, config.server.token, runnerCapabilities());
     const codex = agents.includes('codex') ? bootstrapCodex(config) : null;
@@ -178,6 +439,9 @@ async function cmdDaemon() {
         },
         ...(config.mcp ? { mcp: { url: config.mcp.url, token: config.mcp.token } } : {}),
         ...(config.limits?.max_sessions ? { maxSessionsLimit: config.limits.max_sessions } : {}),
+        // The same veto the capability list honours — announced AND enforced, so a
+        // frame from an API that has not noticed still cannot start a run.
+        verifyEnabled: config.verify?.enabled !== false,
         apiUrl: config.api.url,
         // Used to fetch the files a user attaches to a message (session 10) — the
         // same token the WS connection authenticates with, never passed onwards.
@@ -231,6 +495,37 @@ async function cmdDaemon() {
     };
     process.on('SIGINT', () => shutdown('SIGINT'));
     process.on('SIGTERM', () => shutdown('SIGTERM'));
+    /**
+     * A death must leave a note. Until 0.21.0 the only handlers here were the two
+     * signals above, so an unhandled error exited the process silently and the
+     * only trace anywhere was systemd's `Scheduled restart job` — which is why the
+     * 2026-07-30 incident could not be classified as OOM-vs-crash after the fact
+     * (QA-112 MAJOR-4).
+     *
+     * `crashFile` is read by the next process and reported in `hello`, so the
+     * cause survives the restart and reaches the dashboard.
+     */
+    const noteFatal = (kind, error) => {
+        const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
+        log.error(`daemon: ${kind} — exiting for a restart`, { detail: detail.slice(0, 2000) });
+        try {
+            recordCrash({
+                kind,
+                detail: detail.slice(0, 2000),
+                at: new Date().toISOString(),
+                version: RUNNER_VERSION,
+                activeSessionIds: supervisor.activeSessionIds,
+            });
+        }
+        catch {
+            /* the log line above is already on disk via journald */
+        }
+        // Not a graceful supervisor.shutdown(): the process state is by definition
+        // untrustworthy here, and systemd `Restart=always` is the recovery path.
+        process.exit(1);
+    };
+    process.on('uncaughtException', (error) => noteFatal('uncaughtException', error));
+    process.on('unhandledRejection', (reason) => noteFatal('unhandledRejection', reason));
     ws.start();
     updateStatus();
     // Keep the process alive forever; ws timers drive everything.
@@ -289,14 +584,21 @@ async function cmdInstallService() {
     const exec = unitExecTarget();
     fs.writeFileSync(target, buildUnit(exec.execStart));
     print(`Wrote ${target}`);
+    // Resource policy is a versioned drop-in, not part of the unit — see
+    // `buildLimitsOverride`. Forced here: a fresh install must have it even if a
+    // file from an older runner is already sitting there.
+    writeLimitsOverride(true);
+    print(`Wrote ${limitsOverridePath()}`);
     if (!exec.viaCommand) {
         // Worth saying out loud: a unit pinned to a file inside the package directory
         // breaks if that directory ever moves (which a package rename does).
         print(`note: the service runs ${exec.execStart} directly — re-run install-service after reinstalling the package.`);
     }
     try {
-        await execFileAsync('systemctl', ['--user', 'daemon-reload']);
-        await execFileAsync('systemctl', ['--user', 'enable', '--now', 'devbridge-runner']);
+        await execFileAsync('systemctl', ['--user', 'daemon-reload'], { env: systemdUserEnv() });
+        await execFileAsync('systemctl', ['--user', 'enable', '--now', 'devbridge-runner'], {
+            env: systemdUserEnv(),
+        });
         print('Service enabled and started (systemctl --user).');
     }
     catch (error) {
@@ -312,6 +614,399 @@ async function cmdInstallService() {
     }
     print('Verify with: devbridge-runner status');
 }
+function printCheck(check) {
+    print(`  ${check.ok ? '✔' : '✘'} ${check.name.padEnd(15)} ${check.detail}`);
+    if (check.fix)
+        print(`      → ${check.fix}`);
+    if (check.fixMore)
+        print(`        ${check.fixMore}`);
+}
+/** One property of the user service, or null when systemd cannot answer. */
+async function systemctlProperty(name) {
+    try {
+        const { stdout } = await execFileAsync('systemctl', ['--user', 'show', 'devbridge-runner', '-p', name, '--value'], { timeout: 10_000, env: systemdUserEnv() });
+        const value = stdout.trim();
+        return value.length > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function runnerChecks() {
+    const me = runnerIdentity();
+    const checks = [];
+    const busReachable = await systemdUserBusReachable();
+    const linger = await lingerEnabled();
+    if (!busReachable) {
+        checks.push({
+            ok: false,
+            name: 'service',
+            detail: 'systemd user session NOT reachable',
+            // `systemctl --user` prints «Failed to connect to bus» and exits 0, so a
+            // health check reads that as success. Give the form that works.
+            fix: systemctlHint('status devbridge-runner'),
+        });
+    }
+    else {
+        // The bus answering says nothing about the service. Reporting READY over a
+        // stopped daemon is worse than having no acceptance at all — an acceptance
+        // that lies is what sends somebody away from a server that does not work.
+        const state = await systemctlProperty('ActiveState');
+        const enabled = await systemctlProperty('UnitFileState');
+        const running = state === 'active';
+        checks.push({
+            ok: running,
+            name: 'service',
+            detail: running
+                ? `running${enabled === 'enabled' ? ', starts on boot' : ' — but NOT enabled: it will not come back after a reboot'}` +
+                    (linger === true
+                        ? ', survives logout'
+                        : linger === false
+                            ? ', but linger is OFF: it stops when this user logs out'
+                            : '')
+                : `NOT running (${state ?? 'unknown'})`,
+            ...(running
+                ? enabled !== 'enabled'
+                    ? { fix: systemctlHint('enable devbridge-runner') }
+                    : linger === false
+                        ? { fix: `loginctl enable-linger ${me.user}` }
+                        : {}
+                : {
+                    fix: systemctlHint('start devbridge-runner'),
+                    fixMore: systemctlHint('status devbridge-runner  # why it stopped'),
+                }),
+        });
+        // …and whether it actually reached DevBridge. The same file `status` reads.
+        const status = readStatusFile();
+        const live = status !== null &&
+            isPidAlive(status.pid) &&
+            Date.now() - new Date(status.updatedAt).getTime() < STATUS_FRESH_MS;
+        checks.push({
+            ok: Boolean(live && status?.connected),
+            name: 'connected',
+            detail: !live
+                ? 'the daemon has not reported in — it is not running, or it just started'
+                : status?.connected
+                    ? `talking to ${status.apiUrl ?? 'DevBridge'}`
+                    : 'running but NOT connected to DevBridge',
+            ...(live && status?.connected
+                ? {}
+                : {
+                    fix: systemctlHint('status devbridge-runner'),
+                    fixMore: 'and check the token: devbridge-runner status',
+                }),
+        });
+    }
+    const node = await nodeCheck();
+    checks.push({
+        ok: node.path !== null && !node.problem,
+        name: 'node',
+        detail: node.path
+            ? `${node.version ?? 'installed'}${node.problem ? ` — ${node.problem}` : ''}`
+            : 'not on this user’s PATH',
+        ...(node.path && !node.problem
+            ? {}
+            : {
+                fix: `install Node 22 for ${me.user} (a Node installed for another user is not inherited)`,
+            }),
+    });
+    const packageDir = resolveInstalledPackageDir();
+    const canUpdate = packageDir !== null && installIsWritable(packageDir);
+    checks.push({
+        // A source checkout is a legitimate setup with a different update channel,
+        // not a fault — calling it «not ready» would cry wolf on the dogfood box.
+        ok: canUpdate || packageDir === null,
+        name: 'updates',
+        detail: canUpdate
+            ? 'the «Update runner» button in the dashboard will work'
+            : packageDir === null
+                ? 'started from a source checkout — updated with git, not from the dashboard'
+                : `the package in ${packageDir} belongs to another user, so the dashboard button cannot update it`,
+        ...(canUpdate || packageDir === null
+            ? {}
+            : {
+                fix: `sudo -iu ${me.user} npm install -g --ignore-scripts --prefix ~/.local ${'@bridge4dev/runner'}`,
+                fixMore: `(reinstalling as ${me.user} is what makes the button work; until then every update is a root command)`,
+            }),
+    });
+    return checks;
+}
+async function agentChecks() {
+    const me = runnerIdentity();
+    // The probes log a verdict line each, which belongs in the journal, not in
+    // the middle of a sheet a person is reading.
+    const previousLogLevel = process.env['DEVBRIDGE_RUNNER_LOG'];
+    process.env['DEVBRIDGE_RUNNER_LOG'] = 'error';
+    const auth = await agentAuthStatuses().finally(() => {
+        if (previousLogLevel === undefined)
+            delete process.env['DEVBRIDGE_RUNNER_LOG'];
+        else
+            process.env['DEVBRIDGE_RUNNER_LOG'] = previousLogLevel;
+    });
+    const checks = [];
+    for (const [agent, info] of [
+        ['claude', auth.claude],
+        ['codex', auth.codex],
+    ]) {
+        const signedIn = info.status === 'ok';
+        const command = agent === 'claude' ? 'claude' : 'codex login';
+        checks.push({
+            ok: signedIn,
+            name: `${agent} login`,
+            detail: (info.detail ?? info.status) +
+                (info.expiresAt ? ` · until ${info.expiresAt.slice(0, 10)}` : ''),
+            ...(signedIn
+                ? {}
+                : {
+                    fix: `${me.isRoot ? command : `sudo -iu ${me.user} ${command}`}${agent === 'claude' ? '   then /login' : ''}`,
+                }),
+        });
+    }
+    const contour = agentConfigContour(me.home);
+    const elsewhere = otherHomeWithAgents(me);
+    checks.push({
+        ok: contour.claudeDir,
+        name: 'claude config',
+        detail: contour.claudeDir
+            ? `${contour.allowRules === null ? 'settings unreadable' : `${contour.allowRules} allow rules`} · ${contour.commands} commands · plugins: ${contour.plugins ? 'yes' : 'no'}`
+            : `nothing in ${me.home} — the agent starts with defaults and NO permission allowlist`,
+        ...(contour.claudeDir
+            ? {}
+            : {
+                fix: elsewhere
+                    ? `set it up as ${me.user}, or copy ${elsewhere}/.claude and ${elsewhere}/.codex into ${me.home}`
+                    : `run the agent once as ${me.user} and set its permissions there`,
+                ...(elsewhere
+                    ? {
+                        fixMore: '(a copied login means both accounts share ONE refresh token — a renewal in either signs the other out)',
+                    }
+                    : {}),
+            }),
+    });
+    return checks;
+}
+async function projectChecks(target, fix) {
+    const me = runnerIdentity();
+    const checks = [];
+    const access = inspectPath(target);
+    if (access.unreachable) {
+        const blocked = firstUnreachableAncestor(target) ?? target;
+        return [
+            {
+                ok: false,
+                name: 'access',
+                detail: `${me.user} is not allowed into ${blocked}`,
+                fix: `chmod o+x ${blocked}   (or setfacl -m u:${me.user}:x ${blocked})`,
+            },
+        ];
+    }
+    if (!access.exists) {
+        return [{ ok: false, name: 'access', detail: 'missing on this machine' }];
+    }
+    const usable = access.readable && access.writable;
+    checks.push({
+        ok: usable,
+        name: 'access',
+        detail: usable
+            ? `readable and writable${access.ownedByUs ? '' : ` (owner uid ${access.ownerUid})`}`
+            : `${access.readable ? 'read-only' : 'not readable'} for ${me.user}`,
+        ...(usable
+            ? {}
+            : { fix: `chown -R ${me.user} ${target}   (or setfacl -R -m u:${me.user}:rwX ${target})` }),
+    });
+    const excused = await hasSafeDirectory(target);
+    const gitRefuses = !access.ownedByUs && !excused;
+    if (gitRefuses && fix) {
+        try {
+            await addSafeDirectory(target);
+            checks.push({ ok: true, name: 'git', detail: `fixed: ${safeDirectoryCommand(target)}` });
+        }
+        catch (error) {
+            checks.push({
+                ok: false,
+                name: 'git',
+                detail: `could not fix: ${String(error instanceof Error ? error.message : error)}`,
+            });
+        }
+    }
+    else {
+        checks.push({
+            ok: !gitRefuses,
+            name: 'git',
+            detail: gitRefuses
+                ? `refuses this repository — it belongs to uid ${access.ownerUid}, not to ${me.user}`
+                : 'ok',
+            ...(gitRefuses
+                ? {
+                    fix: safeDirectoryCommand(target),
+                    fixMore: '(if you hand the directory over with chown instead, add the same line for its previous owner — otherwise THEY lose git here)',
+                }
+                : {}),
+        });
+    }
+    const docker = await dockerCheck();
+    if (docker.path) {
+        checks.push({
+            ok: !docker.problem,
+            name: 'docker',
+            detail: docker.problem ?? 'usable by this user',
+            ...(docker.problem
+                ? { fix: `usermod -aG docker ${me.user}   (then restart the runner)` }
+                : {}),
+        });
+    }
+    return checks;
+}
+async function reportAgentReadiness(paths, fix) {
+    const me = runnerIdentity();
+    print('');
+    print(`Runs as ${me.user} (uid ${me.uid}), home ${me.home}`);
+    if (me.isRoot) {
+        // Not a warning — the owner's call. But layer 1 is then the ONLY
+        // containment, and saying it once is cheaper than assuming they know.
+        print('  running as root: the layer-1 policy is the only containment');
+    }
+    const sections = [
+        ['Runner', await runnerChecks()],
+        ['Agent', await agentChecks()],
+    ];
+    for (const target of paths) {
+        sections.push([`Project ${target}`, await projectChecks(target, fix)]);
+    }
+    const failed = sections.flatMap(([, checks]) => checks).filter((check) => !check.ok);
+    print('');
+    print(failed.length === 0
+        ? 'READY — an agent will work on this machine'
+        : `NOT READY — ${failed.length} thing${failed.length === 1 ? '' : 's'} to fix (each one has its command below)`);
+    for (const [title, checks] of sections) {
+        print('');
+        print(title);
+        for (const check of checks)
+            printCheck(check);
+    }
+    if (paths.length === 0) {
+        print('');
+        print('Projects');
+        // Silence here would read as «all good» rather than «nothing to check yet».
+        print('  no project bound yet — this fills in when one is bound in the dashboard.');
+        print('  To check one now: devbridge-runner doctor /path/to/project');
+    }
+    return failed.length === 0;
+}
+async function cmdDoctor(args) {
+    const fix = args.includes('--fix');
+    const config = loadConfig();
+    print(`devbridge-runner ${RUNNER_VERSION}`);
+    print(config ? `Paired with: ${config.server.name} (${config.api.url})` : 'Not paired');
+    // Paths given on the command line win; otherwise check what this runner has
+    // actually been pointed at, because the person running doctor may not know.
+    const givenPaths = args.filter((arg) => arg.startsWith('/'));
+    const projectPaths = givenPaths.length > 0 ? givenPaths : knownWorkspacePaths();
+    const ready = await reportAgentReadiness(projectPaths, fix);
+    const cpuCount = os.cpus().length;
+    const quota = cpuQuotaPercent(cpuCount);
+    print('');
+    print('Machine');
+    print(`  cpus            ${cpuCount}`);
+    print(`  memory total    ${Math.round(os.totalmem() / 1024 / 1024)} MB`);
+    print(`  memory free     ${Math.round(os.freemem() / 1024 / 1024)} MB`);
+    // The number that matters: sessions cost ~1.5 GB each once an agent starts a
+    // build, so this is the honest ceiling regardless of what the dashboard says.
+    const advised = Math.max(1, Math.floor(os.totalmem() / 1024 / 1024 / 1536));
+    print(`  fits sessions   ~${advised} (at ~1.5 GB per session under load)`);
+    print('');
+    print('Service limits');
+    const outdated = limitsOverrideIsOutdated();
+    print(`  drop-in         ${limitsOverridePath()}`);
+    print(`  version         ${outdated ? `MISSING or OLD (want ${LIMITS_VERSION})` : LIMITS_VERSION}`);
+    print(`  cpu quota       ${quota === null ? 'none (fewer than 4 cpus)' : `${quota}%`}`);
+    let effective;
+    try {
+        const { stdout } = await execFileAsync('systemctl', [
+            '--user',
+            'show',
+            'devbridge-runner',
+            '-p',
+            'CPUQuotaPerSecUSec',
+            '-p',
+            'MemoryMax',
+            '-p',
+            'MemoryHigh',
+            '-p',
+            'OOMPolicy',
+            '-p',
+            'NRestarts',
+        ], { env: systemdUserEnv() });
+        effective = stdout.trim().split('\n').filter(Boolean);
+    }
+    catch {
+        effective = ['(systemctl --user unavailable — is this a source checkout?)'];
+    }
+    print('');
+    print('Effective (systemd)');
+    for (const line of effective)
+        print(`  ${line}`);
+    // The two settings that turned one agent's OOM into a dead server.
+    const bad = effective.filter((l) => (l.startsWith('OOMPolicy=') && !l.endsWith('=continue')) ||
+        (l.startsWith('MemoryMax=') && !l.endsWith('=infinity')) ||
+        (l.startsWith('CPUQuotaPerSecUSec=') && l.endsWith('=800ms')));
+    if (bad.length > 0) {
+        print('');
+        print('PROBLEM — these limits kill every session on this machine when one agent runs out of memory:');
+        for (const line of bad)
+            print(`  ${line}`);
+    }
+    // `systemctl set-property` (the zero-downtime emergency fix) persists into
+    // `~/.config/systemd/user.control/`, which OUTRANKS the drop-in we ship. Left
+    // in place it silently pins the numbers from whatever the emergency was, on a
+    // machine whose core count may since have changed — so say so.
+    const controlDir = path.join(os.homedir(), '.config', 'systemd', 'user.control', 'devbridge-runner.service.d');
+    try {
+        const files = fs.readdirSync(controlDir).filter((f) => f.endsWith('.conf'));
+        if (files.length > 0) {
+            print('');
+            print(`Emergency overrides present (these WIN over the shipped policy): ${controlDir}`);
+            for (const file of files)
+                print(`  ${file}`);
+            print('  Remove with: systemctl --user revert devbridge-runner');
+        }
+    }
+    catch {
+        /* no emergency overrides — the normal case */
+    }
+    const oomKills = readOomKills();
+    if (oomKills !== null) {
+        print('');
+        print(`OOM kills in this service's cgroup (cumulative): ${oomKills}`);
+    }
+    if (LAST_EXIT) {
+        print(`Previous process exit: ${LAST_EXIT.kind}${LAST_EXIT.at ? ` at ${LAST_EXIT.at}` : ''}`);
+    }
+    if (!fix) {
+        if (outdated || bad.length > 0) {
+            print('');
+            print('Run `devbridge-runner doctor --fix` to write the drop-in, then restart the service.');
+            process.exit(1);
+        }
+        // A readiness problem is a real finding too: exiting 0 over «the agent has
+        // no login here» is how the installing agent reports success on a server
+        // where nothing will run.
+        if (!ready)
+            process.exit(1);
+        return;
+    }
+    writeLimitsOverride(true);
+    print('');
+    print(`Wrote ${limitsOverridePath()}`);
+    try {
+        await execFileAsync('systemctl', ['--user', 'daemon-reload'], { env: systemdUserEnv() });
+        print('systemctl --user daemon-reload — done.');
+        print('Restart when sessions are idle: systemctl --user restart devbridge-runner');
+    }
+    catch (error) {
+        fail(`daemon-reload failed: ${String(error instanceof Error ? error.message : error)}`);
+    }
+}
 // ─── set-token ───────────────────────────────────────────────────────
 function cmdSetToken(args) {
     const token = args[0];
@@ -330,9 +1025,19 @@ Usage:
   devbridge-runner install-service                                 install + start systemd user service
   devbridge-runner status                                          connection status (exit 0 = connected)
   devbridge-runner set-token <dbr_token>                           store a rotated runner token
+  devbridge-runner doctor [--fix] [path...]                        will an agent work here? logins, settings,
+                                                                   project permissions, resource limits
 `;
 async function main() {
+    // Before anything looks for an agent CLI. Append-only, so a service that can
+    // already find its tools keeps finding them (see ensureAgentPath).
+    const addedToPath = ensureAgentPath();
     const [command, ...args] = process.argv.slice(2);
+    // Said once, and only when it actually changed something: on a machine where
+    // the agent CLIs were already findable this is silent.
+    if (addedToPath.length > 0 && command === 'daemon') {
+        log.info('runner: extended PATH so the agent CLIs are findable', { added: addedToPath });
+    }
     switch (command) {
         case 'pair':
             return cmdPair(args);
@@ -344,6 +1049,8 @@ async function main() {
             return cmdInstallService();
         case 'set-token':
             return cmdSetToken(args);
+        case 'doctor':
+            return cmdDoctor(args);
         case '--version':
         case 'version':
             print(RUNNER_VERSION);