@bridge4dev/runner 0.26.0 → 0.27.0

package/dist/index.js

@@ -10,7 +10,8 @@ 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 { installIsWritable, 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';
@@ -103,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
@@ -135,6 +141,37 @@ function runnerCapabilities() {
          * 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.
@@ -306,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));
@@ -429,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;
@@ -654,8 +697,16 @@ async function runnerChecks() {
         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: running,
+            ok: durable,
             name: 'service',
             detail: running
                 ? `running${enabled === 'enabled' ? ', starts on boot' : ' — but NOT enabled: it will not come back after a reboot'}` +
@@ -663,7 +714,7 @@ async function runnerChecks() {
                         ? ', 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'
@@ -725,10 +776,27 @@ async function runnerChecks() {
         ...(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)`,
+                // 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() {
@@ -744,12 +812,45 @@ async function agentChecks() {
             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';
-        const command = agent === 'claude' ? 'claude' : 'codex login';
         checks.push({
             ok: signedIn,
             name: `${agent} login`,
@@ -758,12 +859,39 @@ async function agentChecks() {
             ...(signedIn
                 ? {}
                 : {
-                    fix: `${me.isRoot ? command : `sudo -iu ${me.user} ${command}`}${agent === 'claude' ? '   then /login' : ''}`,
+                    // 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',
@@ -851,7 +979,15 @@ async function projectChecks(target, fix) {
             name: 'docker',
             detail: docker.problem ?? 'usable by this user',
             ...(docker.problem
-                ? { fix: `usermod -aG docker ${me.user}   (then restart the runner)` }
+                ? {
+                    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`,
+                }
                 : {}),
         });
     }

package/dist/protocol.d.ts

@@ -179,11 +179,11 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         id: string;
         title: string;
     }[];
-    mode?: "ask" | "plan" | "auto" | "full" | undefined;
     mcp?: {
         url: string;
         token: string;
     } | undefined;
+    mode?: "ask" | "plan" | "auto" | "full" | undefined;
     model?: string | null | undefined;
     effort?: string | null | undefined;
     epoch?: number | undefined;
@@ -381,11 +381,11 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             id: string;
             title: string;
         }[];
-        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         mcp?: {
             url: string;
             token: string;
         } | undefined;
+        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;
@@ -469,11 +469,11 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             id: string;
             title: string;
         }[];
-        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         mcp?: {
             url: string;
             token: string;
         } | undefined;
+        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;
@@ -695,11 +695,11 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             id: string;
             title: string;
         }[];
-        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         mcp?: {
             url: string;
             token: string;
         } | undefined;
+        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;
@@ -778,11 +778,11 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             id: string;
             title: string;
         }[];
-        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         mcp?: {
             url: string;
             token: string;
         } | undefined;
+        mode?: "ask" | "plan" | "auto" | "full" | undefined;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;

package/dist/recipe-schema.d.ts

@@ -253,6 +253,7 @@ export declare const ProjectRecipeSchema: z.ZodObject<{
         shaPath?: string | undefined;
     } | undefined;
 }, {
+    version?: 1 | undefined;
     preview?: {
         run: string;
         url?: string | undefined;
@@ -260,7 +261,6 @@ export declare const ProjectRecipeSchema: z.ZodObject<{
         timeoutSec?: number | undefined;
         stop?: string | undefined;
     } | undefined;
-    version?: 1 | undefined;
     notes?: string | undefined;
     steps?: {
         verify?: {

package/dist/self-update.d.ts

@@ -62,6 +62,28 @@ export interface SelfUpdateOptions {
  * has one above `packages/runner`.
  */
 export declare function resolveInstalledPackageDir(entry?: string): string | null;
+/**
+ * The npm prefix the RUNNING package was installed into.
+ *
+ * This is the whole fix for the dedicated-user layout. `npm install -g` obeys
+ * npm's *configured* prefix, and `--prefix` is a per-invocation flag that npm
+ * persists nowhere — so the install the instructions prescribed for a dedicated
+ * user (`npm install -g --prefix ~/.local …`) produced a runner in
+ * `~/.local/lib/node_modules` while every later `npm install -g` aimed at
+ * `/usr`. Measured on a live server: `npm prefix -g` → `/usr`,
+ * `installIsWritable` → true (both checked directories really are the user's),
+ * and then npm dies with EACCES *inside* the update — the exact
+ * «the permissions to access this file as the current user» the owner pasted.
+ *
+ * Deriving the prefix from where we physically are is the truthful answer: it
+ * cannot disagree with reality, and it costs no subprocess. Returns null for a
+ * layout that is not a global npm install (a source checkout, a vendored copy),
+ * where the caller should fall back to `npm prefix -g`.
+ *
+ * `<prefix>/lib/node_modules/@scope/pkg` → `<prefix>`
+ * `<prefix>/lib/node_modules/pkg`        → `<prefix>`
+ */
+export declare function installPrefixFor(packageDir?: string | null): string | null;
 /**
  * Can this user actually replace the installed package?
  *
@@ -72,8 +94,11 @@ export declare function resolveInstalledPackageDir(entry?: string): string | nul
  * current user» — a dashboard button that cannot work, and an error in npm's
  * words rather than ours.
  *
- * Both directories matter: npm rewrites the package AND the `bin` symlink, and
- * either one being root-owned is enough to fail.
+ * Three directories matter, because npm rewrites all three: the package itself,
+ * the `node_modules` above it, and `<prefix>/bin`, where the command symlink
+ * lives. `bin` was missing here and is not hypothetical — a prefix whose
+ * `lib/node_modules` was handed over with chown while `bin` stayed root-owned
+ * passes the first two and still fails.
  */
 export declare function installIsWritable(packageDir?: string | null): boolean;
 /**
@@ -92,5 +117,21 @@ export declare function isSupervisedProcess(env?: NodeJS.ProcessEnv): boolean;
  * never be talked into fetching its own replacement over http.
  */
 export declare function isTrustedTarballUrl(tarballUrl: string, apiUrl: string): boolean;
+/**
+ * The command a person can paste on the server to update this exact machine.
+ *
+ * Built by the runner rather than by the dashboard because only the runner
+ * knows the three things that make it correct: which prefix it lives in, which
+ * user it runs as, and that user's uid for `XDG_RUNTIME_DIR`. The dashboard
+ * used to assemble a generic `npm install -g <url> && systemctl --user restart`
+ * and then patch it with string surgery — which produced a command that could
+ * not work on precisely the machines that needed it.
+ */
+export declare function manualUpdateCommand(tarballUrl: string, options?: {
+    prefix?: string | null;
+    user?: string;
+    uid?: number;
+    packageDir?: string | null;
+}): string;
 export declare function selfUpdate(options: SelfUpdateOptions): Promise<SelfUpdateOutcome>;
 //# sourceMappingURL=self-update.d.ts.map

package/dist/self-update.js

@@ -55,6 +55,51 @@ export function resolveInstalledPackageDir(entry = process.argv[1] ?? '') {
     }
     return null;
 }
+/**
+ * The npm prefix the RUNNING package was installed into.
+ *
+ * This is the whole fix for the dedicated-user layout. `npm install -g` obeys
+ * npm's *configured* prefix, and `--prefix` is a per-invocation flag that npm
+ * persists nowhere — so the install the instructions prescribed for a dedicated
+ * user (`npm install -g --prefix ~/.local …`) produced a runner in
+ * `~/.local/lib/node_modules` while every later `npm install -g` aimed at
+ * `/usr`. Measured on a live server: `npm prefix -g` → `/usr`,
+ * `installIsWritable` → true (both checked directories really are the user's),
+ * and then npm dies with EACCES *inside* the update — the exact
+ * «the permissions to access this file as the current user» the owner pasted.
+ *
+ * Deriving the prefix from where we physically are is the truthful answer: it
+ * cannot disagree with reality, and it costs no subprocess. Returns null for a
+ * layout that is not a global npm install (a source checkout, a vendored copy),
+ * where the caller should fall back to `npm prefix -g`.
+ *
+ * `<prefix>/lib/node_modules/@scope/pkg` → `<prefix>`
+ * `<prefix>/lib/node_modules/pkg`        → `<prefix>`
+ */
+export function installPrefixFor(packageDir = resolveInstalledPackageDir()) {
+    if (!packageDir)
+        return null;
+    const marker = `${path.sep}node_modules${path.sep}`;
+    const at = packageDir.lastIndexOf(marker);
+    if (at < 0)
+        return null;
+    const nodeModules = packageDir.slice(0, at + marker.length - 1);
+    const lib = path.dirname(nodeModules);
+    // Anything else is not the layout `npm install -g --prefix` produces, and
+    // guessing a prefix that npm would not use is worse than not guessing.
+    if (path.basename(lib) !== 'lib')
+        return null;
+    return path.dirname(lib);
+}
+function isWritable(target) {
+    try {
+        fs.accessSync(target, fs.constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Can this user actually replace the installed package?
  *
@@ -65,24 +110,29 @@ export function resolveInstalledPackageDir(entry = process.argv[1] ?? '') {
  * current user» — a dashboard button that cannot work, and an error in npm's
  * words rather than ours.
  *
- * Both directories matter: npm rewrites the package AND the `bin` symlink, and
- * either one being root-owned is enough to fail.
+ * Three directories matter, because npm rewrites all three: the package itself,
+ * the `node_modules` above it, and `<prefix>/bin`, where the command symlink
+ * lives. `bin` was missing here and is not hypothetical — a prefix whose
+ * `lib/node_modules` was handed over with chown while `bin` stayed root-owned
+ * passes the first two and still fails.
  */
 export function installIsWritable(packageDir = resolveInstalledPackageDir()) {
     if (!packageDir)
         return false;
-    const writable = (target) => {
-        try {
-            fs.accessSync(target, fs.constants.W_OK);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    };
+    const marker = `${path.sep}node_modules${path.sep}`;
+    const at = packageDir.lastIndexOf(marker);
     // `<prefix>/lib/node_modules/@scope/pkg` → `<prefix>/lib/node_modules`
-    const nodeModules = path.dirname(packageDir.includes(`${path.sep}@`) ? path.dirname(packageDir) : packageDir);
-    return writable(packageDir) && writable(nodeModules);
+    const nodeModules = at >= 0 ? packageDir.slice(0, at + marker.length - 1) : path.dirname(packageDir);
+    if (!isWritable(packageDir) || !isWritable(nodeModules))
+        return false;
+    const prefix = installPrefixFor(packageDir);
+    // No `bin` yet is fine — npm creates it. An existing one we cannot write is not.
+    if (prefix) {
+        const bin = path.join(prefix, 'bin');
+        if (fs.existsSync(bin) && !isWritable(bin))
+            return false;
+    }
+    return true;
 }
 /**
  * Is something going to restart us?
@@ -140,17 +190,23 @@ const COMMAND_NAME = 'devbridge-runner';
  * command — the stable thing, referenced by a unit file we do not control —
  * points at the new one. So we follow the command.
  */
-async function commandOwner(exec) {
-    let prefix;
-    try {
-        const result = await exec('npm', ['prefix', '-g'], {
-            timeout: VERIFY_TIMEOUT_MS,
-            env: npmEnv(),
-        });
-        prefix = result.stdout.trim();
-    }
-    catch {
-        return null;
+async function commandOwner(exec, installPrefix = null) {
+    // Where we actually live outranks what npm is configured to think. Under the
+    // dedicated-user layout `npm prefix -g` answers `/usr` — a directory that on
+    // such a host holds no runner at all — so asking npm first returned null and
+    // took the EEXIST rename-recovery and the unit repair down with it.
+    let prefix = installPrefix;
+    if (!prefix) {
+        try {
+            const result = await exec('npm', ['prefix', '-g'], {
+                timeout: VERIFY_TIMEOUT_MS,
+                env: npmEnv(),
+            });
+            prefix = result.stdout.trim();
+        }
+        catch {
+            return null;
+        }
     }
     if (!prefix)
         return null;
@@ -167,13 +223,55 @@ async function commandOwner(exec) {
         return null;
     }
 }
-function installArgs(source) {
+function installArgs(source, prefix) {
     // `--ignore-scripts` matches the documented install: this package and its whole
     // tree have no install/postinstall scripts, so nothing legitimate is skipped —
     // and an update pulled over the network gets no chance to run anything at
     // install time. `--loglevel=error` because npm's ERESOLVE warning about zod is
     // expected, harmless and long enough to bury the line that matters.
-    return ['install', '-g', '--ignore-scripts', '--loglevel=error', source];
+    //
+    // `--prefix` names the prefix the runner is ALREADY installed in. Without it
+    // npm uses its configured global prefix, which on a dedicated-user install is
+    // a directory the daemon cannot write — and, on the rarer host where it can,
+    // npm cheerfully installs a SECOND copy somewhere the service does not exec,
+    // reports success, and the runner restarts on the old version forever.
+    return [
+        'install',
+        '-g',
+        '--ignore-scripts',
+        '--loglevel=error',
+        ...(prefix ? ['--prefix', prefix] : []),
+        source,
+    ];
+}
+/**
+ * The command a person can paste on the server to update this exact machine.
+ *
+ * Built by the runner rather than by the dashboard because only the runner
+ * knows the three things that make it correct: which prefix it lives in, which
+ * user it runs as, and that user's uid for `XDG_RUNTIME_DIR`. The dashboard
+ * used to assemble a generic `npm install -g <url> && systemctl --user restart`
+ * and then patch it with string surgery — which produced a command that could
+ * not work on precisely the machines that needed it.
+ */
+export function manualUpdateCommand(tarballUrl, options = {}) {
+    const packageDir = options.packageDir === undefined ? resolveInstalledPackageDir() : options.packageDir;
+    const prefix = options.prefix === undefined ? installPrefixFor(packageDir) : options.prefix;
+    const user = options.user ?? os.userInfo().username;
+    const uid = options.uid ?? (typeof process.getuid === 'function' ? process.getuid() : -1);
+    const install = ['npm install -g --ignore-scripts --loglevel=error']
+        .concat(prefix ? [`--prefix ${prefix}`] : [])
+        .concat([tarballUrl])
+        .join(' ');
+    const restart = 'systemctl --user restart devbridge-runner';
+    // Writable by us → one line, run as ourselves. Not writable → the install
+    // half needs root and the restart half needs the daemon's own user, and
+    // «run it as root» alone is how people ended up with a new package and an
+    // old process still running.
+    if (installIsWritable(packageDir))
+        return `${install} && ${restart}`;
+    const runtime = uid >= 0 ? `/run/user/${uid}` : `/run/user/$(id -u ${user})`;
+    return `sudo ${install} && sudo -iu ${user} env XDG_RUNTIME_DIR=${runtime} ${restart}`;
 }
 /**
  * Install a global package, clearing the way if a DIFFERENTLY-NAMED build of this
@@ -186,25 +284,22 @@ function installArgs(source) {
  * one owner instead of two, which is also the only state the NEXT update can
  * work from.
  */
-async function installGlobal(exec, source) {
+async function installGlobal(exec, source, prefix) {
     try {
-        await exec('npm', installArgs(source), { timeout: NPM_TIMEOUT_MS, env: npmEnv() });
+        await exec('npm', installArgs(source, prefix), { timeout: NPM_TIMEOUT_MS, env: npmEnv() });
         return;
     }
     catch (error) {
         if (!/EEXIST/i.test(describe(error)))
             throw error;
-        const owner = await commandOwner(exec);
+        const owner = await commandOwner(exec, prefix);
         if (!owner)
             throw error;
         log.warn('self-update: the command belongs to another package — retiring it', {
             package: owner.name,
         });
-        await exec('npm', ['uninstall', '-g', '--loglevel=error', owner.name], {
-            timeout: NPM_TIMEOUT_MS,
-            env: npmEnv(),
-        });
-        await exec('npm', installArgs(source), { timeout: NPM_TIMEOUT_MS, env: npmEnv() });
+        await exec('npm', ['uninstall', '-g', '--loglevel=error', ...(prefix ? ['--prefix', prefix] : []), owner.name], { timeout: NPM_TIMEOUT_MS, env: npmEnv() });
+        await exec('npm', installArgs(source, prefix), { timeout: NPM_TIMEOUT_MS, env: npmEnv() });
     }
 }
 /**
@@ -256,13 +351,12 @@ export async function selfUpdate(options) {
     // runner's own user.
     if (!installIsWritable(packageDir)) {
         const user = os.userInfo().username;
-        const uid = typeof process.getuid === 'function' ? process.getuid() : -1;
         return fail(`The runner package in ${packageDir} belongs to another user, and this daemon runs as ${user}, ` +
-            'so it cannot replace itself. Update it on the server in two steps — install as root:\n' +
-            `  npm install -g --ignore-scripts --loglevel=error ${options.tarballUrl}\n` +
-            'then restart the service as the runner’s own user:\n' +
-            `  sudo -iu ${user} env XDG_RUNTIME_DIR=/run/user/${uid >= 0 ? uid : '$(id -u ' + user + ')'} systemctl --user restart devbridge-runner`);
+            'so it cannot replace itself. Run this on the server instead:\n  ' +
+            manualUpdateCommand(options.tarballUrl, { packageDir }));
     }
+    // Derived once and threaded through every npm call below.
+    const prefix = installPrefixFor(packageDir);
     // Pack the current version FIRST: without a rollback artefact there is no
     // honest way back if the new build turns out to be broken.
     const rollbackDir = path.join(stateDir(), 'rollback');
@@ -287,7 +381,7 @@ export async function selfUpdate(options) {
         return fail('Could not prepare a rollback copy of the current version — update aborted');
     }
     try {
-        await installGlobal(exec, options.tarballUrl);
+        await installGlobal(exec, options.tarballUrl, prefix);
     }
     catch (error) {
         return fail(`Install failed: ${describe(error)}`, { rollbackTarball });
@@ -295,7 +389,7 @@ export async function selfUpdate(options) {
     // Where the new build actually landed. After a rename `packageDir` is the
     // directory we just retired, so its manifest would report the OLD version —
     // and the smoke test below would run code that no longer exists.
-    const installed = await commandOwner(exec);
+    const installed = await commandOwner(exec, prefix);
     const newPackageDir = installed?.dir ?? packageDir;
     const toVersion = readVersion(newPackageDir) ?? undefined;
     // The real test: does the newly installed build start? `--version` loads the
@@ -318,12 +412,12 @@ export async function selfUpdate(options) {
             // Through the same door as the install above: if the failed update renamed
             // the package, the command now belongs to the new name and putting the old
             // one back hits the very same EEXIST.
-            await installGlobal(exec, rollbackTarball);
+            await installGlobal(exec, rollbackTarball, prefix);
             return fail(`The new version did not start (${detail}). The previous version was restored and the runner keeps working.`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
         }
         catch (rollbackError) {
             return fail(`The new version did not start (${detail}) and the rollback failed too (${describe(rollbackError)}). ` +
-                `Restore it on the server with: npm install -g ${rollbackTarball}`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
+                `Restore it on the server with: npm install -g${prefix ? ` --prefix ${prefix}` : ''} ${rollbackTarball}`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
         }
     }
     // The service unit may be pinned to a file inside the directory this update

package/dist/version.d.ts

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