@bridge4dev/runner 0.22.1 → 0.27.0

package/dist/index.js

@@ -10,13 +10,16 @@ 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, installPrefixFor, isSupervisedProcess, manualUpdateCommand, resolveInstalledPackageDir, } from './self-update.js';
+import { applyStoredClaudeToken } from './agent-auth.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, 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);
 /**
@@ -60,7 +63,8 @@ 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.
@@ -71,10 +75,15 @@ function selfUpdatable() {
  * only the runner knows how it was started.
  */
 function selfUpdateBlockedReason() {
-    if (resolveInstalledPackageDir() === null)
+    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) {
@@ -95,8 +104,13 @@ function hasExecutable(name) {
  * older runner drops a frame it cannot parse without ever replying, so a
  * command it does not know would just hang until the gateway timeout.
  */
-function runnerCapabilities() {
+function runnerCapabilities(apiUrlOverride) {
     const config = loadConfig();
+    // At PAIR time there is no config yet, so the API this runner is about to
+    // belong to has to be passed in — otherwise the very first `hello` (the one
+    // that creates the server record) would omit the update command, and the
+    // dashboard would show a stale one until the daemon reconnected.
+    const apiUrl = apiUrlOverride ?? config?.api.url;
     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
@@ -119,6 +133,45 @@ function runnerCapabilities() {
         ...(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,
+        /**
+         * Which agent CLIs are actually on this user's PATH (0.27.0).
+         *
+         * Different question from `agents` above, and the difference cost a
+         * support round: `agents` says which agents can RUN sessions (Claude
+         * always can — the SDK bundles its own binary), while signing in needs the
+         * standalone CLI to exist for this user. On a dedicated-user install it
+         * routinely does not, and the sign-in button then failed with an error
+         * about `script`, about a machine whose real problem was that nobody had
+         * installed `claude` for that user at all.
+         */
+        agentClis: {
+            claude: hasExecutable('claude'),
+            codex: hasExecutable('codex'),
+        },
+        /**
+         * Where npm put this package, and the command that updates it here
+         * (0.27.0).
+         *
+         * The dashboard used to assemble the update command itself and then patch
+         * it with string surgery for the dedicated-user case. It cannot: only this
+         * process knows the prefix it was installed into, and `npm install -g`
+         * without that prefix is precisely the EACCES the owner pasted. So the
+         * machine states its own command and the panel just shows it.
+         */
+        ...(installPrefixFor() ? { npmPrefix: installPrefixFor() } : {}),
+        ...(apiUrl
+            ? {
+                updateCommand: manualUpdateCommand(`${apiUrl.replace(/\/$/, '')}/api/v1/dev-setup/runner.tgz`),
+            }
+            : {}),
         /**
          * A stricter ceiling set on the machine itself (layer 1). Reported so the
          * dashboard can explain why raising the number there changed nothing.
@@ -290,7 +343,7 @@ async function cmdPair(args) {
             name,
             runnerVersion: RUNNER_VERSION,
             osInfo: `${os.type()} ${os.release()} ${os.arch()}`.slice(0, 200),
-            capabilities: runnerCapabilities(),
+            capabilities: runnerCapabilities(apiUrl),
         }),
     });
     const body = (await response.json().catch(() => null));
@@ -360,7 +413,10 @@ async function repairResourceLimits() {
             path: limitsOverridePath(),
             version: LIMITS_VERSION,
         });
-        await execFileAsync('systemctl', ['--user', 'daemon-reload'], { timeout: 15_000 });
+        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
@@ -410,6 +466,12 @@ async function cmdDaemon() {
     log.info('daemon starting', { version: RUNNER_VERSION, server: config.server.name });
     sweepOrphanedMcpConfigs();
     await repairResourceLimits();
+    // A Claude token this runner captured through the sign-in relay. Applied
+    // BEFORE any adapter exists, because `scrubbedEnv()` copies it out of this
+    // process's environment for every session it starts.
+    if (applyStoredClaudeToken()) {
+        log.info('daemon: using the Claude token stored on this server');
+    }
     const agents = installedAgents();
     const ws = new RunnerWsClient(config.api.ws_url, config.server.token, runnerCapabilities());
     const codex = agents.includes('codex') ? bootstrapCodex(config) : null;
@@ -576,8 +638,10 @@ async function cmdInstallService() {
         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) {
@@ -593,21 +657,388 @@ async function cmdInstallService() {
     }
     print('Verify with: devbridge-runner status');
 }
-// ─── doctor ──────────────────────────────────────────────────────────
-/**
- * The one command that answers «is this machine set up to run the sessions it
- * says it can run».
- *
- * It exists because of what the 2026-07-30 incident cost to diagnose: the
- * runner's own systemd limits were the cause, they were invisible from
- * DevBridge, and the machine could not be reached. Everything printed here was
- * needed to reach that answer and none of it was available in one place.
- */
+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';
+        // Three separate promises, and the verdict has to fail on any of them.
+        // Until 0.27.0 only the first counted: a service that was running but
+        // would die at the next logout (linger off) or never come back after a
+        // reboot (not enabled) still printed ✔ and still said READY, with the
+        // `loginctl enable-linger` line sitting UNDER the tick as if it were
+        // advice. The whole point of an acceptance sheet is that a green one means
+        // walk away — so a runner that stops when its user logs out is a red line.
+        const durable = running && enabled === 'enabled' && linger !== false;
+        checks.push({
+            ok: durable,
+            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'
+                            : ', linger state unknown')
+                : `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
+            ? {}
+            : {
+                // NOT `--prefix ~/.local`, which is what this line used to say. The
+                // tilde is expanded by the CALLING shell, so run as root it aimed at
+                // /root/.local — a directory the daemon's user cannot write — and
+                // the install died naming a home nobody had chosen. `sudo -iu` hands
+                // the string to the TARGET user's login shell, so `$HOME` is theirs.
+                fix: `sudo -iu ${me.user} sh -lc 'npm config set prefix "$HOME/.local" && npm install -g --ignore-scripts --loglevel=error @bridge4dev/runner'`,
+                fixMore: `(the \`npm config set prefix\` half is what keeps the button working: without it every LATER update aims at the system prefix again and fails with EACCES)`,
+            }),
+    });
+    // The relay that signs an agent in runs the CLI on a pty, and util-linux
+    // `script` is what allocates it. Missing on minimal images, and its absence
+    // used to surface as «claude login exited before printing a sign-in URL».
+    const hasScript = hasExecutable('script');
+    checks.push({
+        ok: hasScript,
+        name: 'sign-in relay',
+        detail: hasScript
+            ? 'ready (util-linux `script` present)'
+            : '`script` (util-linux) is missing — the dashboard sign-in button cannot run',
+        ...(hasScript ? {} : { fix: 'apt-get install -y bsdextrautils util-linux' }),
+    });
+    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 = [];
+    // Does the CLI exist for THIS user, before asking whether it is signed in?
+    // «not signed in» over a machine that has no `claude` at all sends the
+    // reader to a login screen for a command that does not exist — and doctor's
+    // own remedy (`sudo -iu <user> claude`) was then `command not found`. That
+    // is the state a dedicated-user install leaves behind by default.
+    const cliPresent = {
+        claude: hasExecutable('claude'),
+        codex: hasExecutable('codex'),
+    };
+    checks.push({
+        ok: cliPresent.claude,
+        name: 'claude cli',
+        detail: cliPresent.claude
+            ? `on ${me.user}'s PATH`
+            : `not installed for ${me.user} — sessions still run (the SDK bundles its own), but signing in needs the CLI`,
+        ...(cliPresent.claude
+            ? {}
+            : {
+                fix: `sudo -iu ${me.user} sh -lc 'curl -fsSL https://claude.ai/install.sh | bash'`,
+            }),
+    });
+    // Codex is optional: plenty of machines only ever run Claude sessions, and a
+    // red line for an agent nobody uses is noise that trains people to ignore
+    // the sheet. Reported, not judged.
+    checks.push({
+        ok: true,
+        name: 'codex cli',
+        detail: cliPresent.codex ? `on ${me.user}'s PATH` : `not installed for ${me.user} (optional)`,
+        ...(cliPresent.codex
+            ? {}
+            : {
+                fix: `sudo -iu ${me.user} sh -lc 'npm install -g @openai/codex'   # only if you use Codex`,
+            }),
+    });
+    for (const [agent, info] of [
+        ['claude', auth.claude],
+        ['codex', auth.codex],
+    ]) {
+        const signedIn = info.status === 'ok';
+        checks.push({
+            ok: signedIn,
+            name: `${agent} login`,
+            detail: (info.detail ?? info.status) +
+                (info.expiresAt ? ` · until ${info.expiresAt.slice(0, 10)}` : ''),
+            ...(signedIn
+                ? {}
+                : {
+                    // The dashboard button FIRST. It is the product's own path, it
+                    // needs no shell on the server, and an installing agent cannot
+                    // perform an interactive OAuth login anyway — so telling it to
+                    // «run claude and do /login» is telling it to stop. That is
+                    // exactly where the last three installs stopped.
+                    fix: `Dashboard → Development → this server → AGENTS → «Sign in» next to ${agent === 'claude' ? 'Claude Code' : 'Codex'}`,
+                    fixMore: cliPresent[agent]
+                        ? `or on the server: ${me.isRoot ? '' : `sudo -iu ${me.user} `}${agent === 'claude' ? 'claude auth login' : 'codex login'}`
+                        : `(install the CLI first — see the «${agent} cli» line above)`,
+                }),
+        });
+    }
+    const contour = agentConfigContour(me.home);
+    const elsewhere = otherHomeWithAgents(me);
+    // MCP servers a session will really see. Only user scope survives a session
+    // worktree, and «configured but in the wrong scope» looks identical to
+    // «working» from anywhere except inside a session.
+    const mcpHidden = contour.mcpUserScope === 0 && contour.mcpProjectScope > 0;
+    checks.push({
+        ok: !mcpHidden,
+        name: 'mcp servers',
+        detail: mcpHidden
+            ? `${contour.mcpProjectScope} configured, but all per-directory — a session works in its own worktree and will see NONE`
+            : contour.mcpUserScope > 0
+                ? `${contour.mcpUserScope} available to every session`
+                : 'none configured (the DevBridge server is injected per session regardless)',
+        ...(mcpHidden
+            ? {
+                fix: `sudo -iu ${me.user} claude mcp add --scope user <name> …   # re-add at user scope`,
+                fixMore: '(`claude mcp add` defaults to the current directory’s scope, which no session shares)',
+            }
+            : {}),
+    });
+    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}`,
+                    // Restarting the unit is NOT enough and this cost a diagnosis:
+                    // supplementary groups are fixed when logind creates
+                    // user@<uid>.service, so the daemon keeps the old set until the
+                    // whole user manager restarts. `id ${me.user}` then shows the new
+                    // group while /proc/<pid>/status still shows the old one.
+                    fixMore: `systemctl restart user@${me.uid}.service   # the unit alone keeps the old group set`,
+                }
+                : {}),
+        });
+    }
+    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('');
@@ -641,7 +1072,7 @@ async function cmdDoctor(args) {
             'OOMPolicy',
             '-p',
             'NRestarts',
-        ]);
+        ], { env: systemdUserEnv() });
         effective = stdout.trim().split('\n').filter(Boolean);
     }
     catch {
@@ -693,13 +1124,18 @@ async function cmdDoctor(args) {
             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']);
+        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');
     }
@@ -725,10 +1161,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]                                  report (and repair) resource limits
+  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);

package/dist/paths.d.ts

@@ -11,6 +11,15 @@ export declare function configFilePath(): string;
 export declare function statusFilePath(): string;
 export declare function journalDir(): string;
 export declare function worktreesDir(): string;
+/**
+ * Project directories this runner has been pointed at.
+ *
+ * Kept so `devbridge-runner doctor` can check the permissions that actually
+ * matter on this machine without being told the paths — the runner learns them
+ * from the API (binding a project, starting a session) and the person running
+ * doctor may have no idea which directories are bound.
+ */
+export declare function knownWorkspacesPath(): string;
 /** Session 14: the single preview checkout per repository. */
 export declare function previewsDir(): string;
 /**

package/dist/paths.js

@@ -39,6 +39,17 @@ export function journalDir() {
 export function worktreesDir() {
     return path.join(stateDir(), 'worktrees');
 }
+/**
+ * Project directories this runner has been pointed at.
+ *
+ * Kept so `devbridge-runner doctor` can check the permissions that actually
+ * matter on this machine without being told the paths — the runner learns them
+ * from the API (binding a project, starting a session) and the person running
+ * doctor may have no idea which directories are bound.
+ */
+export function knownWorkspacesPath() {
+    return path.join(stateDir(), 'workspaces.json');
+}
 /** Session 14: the single preview checkout per repository. */
 export function previewsDir() {
     return path.join(stateDir(), 'previews');