@addai/node 0.18.0 → 0.20.0

package/dist/autostart-linux.d.ts

@@ -0,0 +1,69 @@
+import { AutostartBackend, AutostartEntry } from './autostart';
+export declare const USER_UNIT_DIR: string;
+export declare const UNIT_PATH: string;
+/** systemd records an `enable` as a symlink here; its presence IS "enabled". */
+export declare const WANTS_PATH: string;
+/** Where systemd records that a user may linger. Readable without a subprocess,
+ *  which matters because status() rides every heartbeat. */
+export declare function lingerPath(user?: string): string;
+export declare function currentUser(env?: NodeJS.ProcessEnv): string;
+export interface UnitSpec {
+    entry: AutostartEntry;
+    env: Record<string, string>;
+    logPath: string;
+    workingDirectory: string;
+    /**
+     * `append:` writes straight to our own log file, which is where every other
+     * platform puts it and where the console's Logs screen looks. It needs
+     * systemd 240+; older releases fail to load the unit entirely rather than
+     * ignoring the directive, so anything older is sent to the journal instead.
+     */
+    logMode: 'append' | 'journal';
+}
+/**
+ * The unit file, as a string. Pure — this is what the tests assert on.
+ *
+ * Restart=always mirrors launchd's KeepAlive: the node is meant to be
+ * always-on, and a remote roll depends on it. A supervised `update_runtime`
+ * installs the new version and simply EXITS, and the supervisor starting the
+ * replacement is what makes that safe (see index.ts and isSupervised).
+ *
+ * RestartSec matches macOS's ThrottleInterval so a crash loop is one launch
+ * per 10s on both rather than a spin.
+ */
+export declare function buildUnit(spec: UnitSpec): string;
+/** Pull ExecStart back out of a unit we wrote, for `status`. */
+export declare function parseUnitEntry(unit: string): AutostartEntry | undefined;
+/** systemd's major version, or null when it can't be read. */
+export declare function systemdVersion(probe?: () => string | null): number | null;
+/**
+ * Is this machine actually running systemd?
+ *
+ * `/run/systemd/system` is the documented test for "booted with systemd" —
+ * plenty of containers and a few distros have the binaries present but no
+ * running manager, and there the unit would be written and never run.
+ */
+export declare function systemdAvailable(exists?: (p: string) => boolean): boolean;
+/**
+ * Normalise `systemctl is-active` output.
+ *
+ * It prints one word and exits non-zero for anything but `active`, so the exit
+ * code carries no information the word doesn't.
+ */
+export declare function normaliseActiveState(out: string): string;
+/**
+ * Did the unit actually come up?
+ *
+ * The truth contract this codebase applies to harness logins, applied here:
+ * the exit code is a hint, the probe is the verdict. `systemctl enable --now`
+ * returns 0 for "request accepted", which is not the same as a running node —
+ * a unit can be accepted and then fail its very first ExecStart because a path
+ * is wrong or the runtime is missing, and reporting that as success is the
+ * failure mode that hurts most, because nothing looks wrong until an entity
+ * sits at "Getting ready…" forever.
+ *
+ * `activating` is given a few seconds rather than being called a failure; a
+ * unit that has genuinely failed reports `failed` immediately.
+ */
+export declare function waitUntilActive(probe?: () => string, attempts?: number, sleepMs?: number, sleep?: (ms: number) => void): string;
+export declare const backend: AutostartBackend;

package/dist/autostart-linux.js

@@ -0,0 +1,390 @@
+"use strict";
+// Linux backend: a `systemd --user` unit.
+//
+// A USER unit, not a system one, for the same reason macOS gets a LaunchAgent
+// and Windows a logon task rather than a service: the daemon needs the user's
+// PATH, their ~/.claude and ~/.codex, and their keyring. A root unit would
+// faithfully boot a node that then fails every single run.
+//
+// The piece with no equivalent on the other two platforms is LINGER. A user
+// manager normally starts at the user's first login and stops when their last
+// session ends, so on a server — where nobody logs in, and where an ssh session
+// ending is the normal case — a user unit without linger is a node that dies
+// the moment you disconnect. `loginctl enable-linger` is what makes the user
+// manager start at BOOT and stay up. On a headless box it is not a nicety;
+// without it this feature does not work at all.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backend = exports.WANTS_PATH = exports.UNIT_PATH = exports.USER_UNIT_DIR = void 0;
+exports.lingerPath = lingerPath;
+exports.currentUser = currentUser;
+exports.buildUnit = buildUnit;
+exports.parseUnitEntry = parseUnitEntry;
+exports.systemdVersion = systemdVersion;
+exports.systemdAvailable = systemdAvailable;
+exports.normaliseActiveState = normaliseActiveState;
+exports.waitUntilActive = waitUntilActive;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const autostart_1 = require("./autostart");
+exports.USER_UNIT_DIR = path.join(os.homedir(), '.config', 'systemd', 'user');
+exports.UNIT_PATH = path.join(exports.USER_UNIT_DIR, autostart_1.SERVICE_NAME);
+/** systemd records an `enable` as a symlink here; its presence IS "enabled". */
+exports.WANTS_PATH = path.join(exports.USER_UNIT_DIR, 'default.target.wants', autostart_1.SERVICE_NAME);
+/** Where systemd records that a user may linger. Readable without a subprocess,
+ *  which matters because status() rides every heartbeat. */
+function lingerPath(user = currentUser()) {
+    return path.join('/var/lib/systemd/linger', user);
+}
+function currentUser(env = process.env) {
+    if (env.USER)
+        return env.USER;
+    if (env.LOGNAME)
+        return env.LOGNAME;
+    try {
+        return os.userInfo().username;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * systemd writes `Environment=` as an ini-ish line, so a value carrying a
+ * space, a `#` or a quote has to be quoted and escaped or the unit silently
+ * parses wrong. A real PATH routinely contains spaces.
+ */
+function envLine(key, value) {
+    const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return `Environment="${key}=${escaped}"`;
+}
+/** ExecStart takes a command line, so each argument is quoted the same way. */
+function execArg(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/**
+ * The unit file, as a string. Pure — this is what the tests assert on.
+ *
+ * Restart=always mirrors launchd's KeepAlive: the node is meant to be
+ * always-on, and a remote roll depends on it. A supervised `update_runtime`
+ * installs the new version and simply EXITS, and the supervisor starting the
+ * replacement is what makes that safe (see index.ts and isSupervised).
+ *
+ * RestartSec matches macOS's ThrottleInterval so a crash loop is one launch
+ * per 10s on both rather than a spin.
+ */
+function buildUnit(spec) {
+    const exec = [spec.entry.file, ...spec.entry.args].map(execArg).join(' ');
+    const env = Object.entries(spec.env).map(([k, v]) => envLine(k, v)).join('\n');
+    const out = spec.logMode === 'append' ? `append:${spec.logPath}` : 'journal';
+    return `[Unit]
+Description=+Ai Node
+Documentation=https://node.add.ai
+# The node's first act is to reach Supabase, so starting before the network is
+# up just means a first heartbeat that fails and retries.
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${exec}
+WorkingDirectory=${spec.workingDirectory}
+Restart=always
+RestartSec=10
+${env}
+StandardOutput=${out}
+StandardError=${out}
+
+[Install]
+WantedBy=default.target
+`;
+}
+/** Pull ExecStart back out of a unit we wrote, for `status`. */
+function parseUnitEntry(unit) {
+    const line = /^ExecStart=(.*)$/m.exec(unit);
+    if (!line)
+        return undefined;
+    const parts = [...line[1].matchAll(/"((?:[^"\\]|\\.)*)"|(\S+)/g)]
+        .map(m => (m[1] !== undefined ? m[1].replace(/\\(.)/g, '$1') : m[2]));
+    if (!parts.length)
+        return undefined;
+    return { file: parts[0], args: parts.slice(1) };
+}
+function run(file, args) {
+    try {
+        const out = (0, child_process_1.execFileSync)(file, args, {
+            encoding: 'utf8', timeout: 20_000, stdio: ['ignore', 'pipe', 'pipe'],
+            // systemctl --user needs to find its user manager. Over ssh with no
+            // seat, or from a daemon started by something that stripped the
+            // environment, XDG_RUNTIME_DIR is missing and every call fails with
+            // "Failed to connect to bus" — which reads like systemd is broken.
+            env: { ...process.env, ...runtimeDirEnv() },
+        });
+        return { ok: true, output: out.toString().trim() };
+    }
+    catch (err) {
+        const e = err;
+        const stderr = e.stderr ? e.stderr.toString().trim() : '';
+        return { ok: false, output: stderr || e.message || `${file} failed` };
+    }
+}
+function runtimeDirEnv() {
+    if (process.env.XDG_RUNTIME_DIR)
+        return {};
+    const uid = typeof process.getuid === 'function' ? process.getuid() : null;
+    if (uid === null)
+        return {};
+    const guess = `/run/user/${uid}`;
+    return fs.existsSync(guess) ? { XDG_RUNTIME_DIR: guess } : {};
+}
+function systemctl(args) {
+    return run('systemctl', ['--user', ...args]);
+}
+/** systemd's major version, or null when it can't be read. */
+function systemdVersion(probe = () => {
+    const r = run('systemctl', ['--version']);
+    return r.ok ? r.output : null;
+}) {
+    const raw = probe();
+    if (!raw)
+        return null;
+    const m = /systemd\s+(\d+)/.exec(raw);
+    return m ? Number(m[1]) : null;
+}
+/**
+ * Is this machine actually running systemd?
+ *
+ * `/run/systemd/system` is the documented test for "booted with systemd" —
+ * plenty of containers and a few distros have the binaries present but no
+ * running manager, and there the unit would be written and never run.
+ */
+function systemdAvailable(exists = p => fs.existsSync(p)) {
+    return exists('/run/systemd/system');
+}
+/**
+ * Normalise `systemctl is-active` output.
+ *
+ * It prints one word and exits non-zero for anything but `active`, so the exit
+ * code carries no information the word doesn't.
+ */
+function normaliseActiveState(out) {
+    const word = (out || '').trim().split(/\s+/)[0] ?? '';
+    return word || 'unknown';
+}
+/** Sleep without going async. `startup enable` is a one-shot CLI command. */
+function nap(ms) {
+    const buf = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(buf, 0, 0, ms);
+}
+/**
+ * Did the unit actually come up?
+ *
+ * The truth contract this codebase applies to harness logins, applied here:
+ * the exit code is a hint, the probe is the verdict. `systemctl enable --now`
+ * returns 0 for "request accepted", which is not the same as a running node —
+ * a unit can be accepted and then fail its very first ExecStart because a path
+ * is wrong or the runtime is missing, and reporting that as success is the
+ * failure mode that hurts most, because nothing looks wrong until an entity
+ * sits at "Getting ready…" forever.
+ *
+ * `activating` is given a few seconds rather than being called a failure; a
+ * unit that has genuinely failed reports `failed` immediately.
+ */
+function waitUntilActive(probe = () => normaliseActiveState(systemctl(['is-active', autostart_1.SERVICE_NAME]).output), attempts = 8, sleepMs = 500, sleep = nap) {
+    let state = 'unknown';
+    for (let i = 0; i < attempts; i++) {
+        state = probe();
+        if (state === 'active' || state === 'failed')
+            return state;
+        sleep(sleepMs);
+    }
+    return state;
+}
+/** The last few log lines, for an error message that can be acted on. */
+function recentLog() {
+    const r = run('journalctl', ['--user', '-u', autostart_1.SERVICE_NAME, '-n', '15', '--no-pager']);
+    return r.ok ? r.output : '';
+}
+function unsupported(reason) {
+    return { supported: false, enabled: false, supervisor: null, issues: [reason] };
+}
+function status() {
+    if (!systemdAvailable()) {
+        return unsupported('this machine is not running systemd, so there is nothing to start the node at boot');
+    }
+    if (!fs.existsSync(exports.UNIT_PATH)) {
+        return { supported: true, enabled: false, supervisor: 'systemd' };
+    }
+    // Deliberately no `systemctl` call here: status() rides every heartbeat, and
+    // the two files on disk are the whole answer. The unit says what to run; the
+    // default.target.wants symlink is how systemd records `enable`.
+    const unit = fs.readFileSync(exports.UNIT_PATH, 'utf8');
+    const entry = parseUnitEntry(unit);
+    const enabled = fs.existsSync(exports.WANTS_PATH);
+    const issues = [];
+    const program = entry?.args[0] ?? entry?.file;
+    if (program && !fs.existsSync(program)) {
+        issues.push(`the pinned program is gone (${program}) — re-run \`ainode startup enable\``);
+    }
+    // The one that actually bites on a server, and it is invisible until the
+    // first logout takes the node down with it.
+    if (enabled && !fs.existsSync(lingerPath())) {
+        issues.push('lingering is off, so this node stops when you log out — '
+            + `run \`sudo loginctl enable-linger ${currentUser()}\``);
+    }
+    return {
+        supported: true,
+        enabled,
+        supervisor: 'systemd',
+        entry,
+        path: exports.UNIT_PATH,
+        ...(issues.length ? { issues } : {}),
+    };
+}
+function enable(entry, env, logPath) {
+    const warnings = [];
+    if (!systemdAvailable()) {
+        return {
+            ok: false,
+            warnings,
+            error: 'this machine is not running systemd (no /run/systemd/system), so there is nothing to register with',
+        };
+    }
+    const version = systemdVersion();
+    // Unknown version is treated as old. Guessing "new" and being wrong means a
+    // unit systemd refuses to load at all, which is a worse failure than logs
+    // landing in the journal.
+    const logMode = version !== null && version >= 240 ? 'append' : 'journal';
+    if (logMode === 'journal') {
+        warnings.push(`systemd ${version ?? 'of unknown version'} is older than 240, so output goes to the journal `
+            + `instead of ${logPath} — read it with \`journalctl --user -u ${autostart_1.SERVICE_NAME} -f\``);
+    }
+    fs.mkdirSync(exports.USER_UNIT_DIR, { recursive: true });
+    fs.writeFileSync(exports.UNIT_PATH, buildUnit({
+        entry,
+        env,
+        logPath,
+        workingDirectory: os.homedir(),
+        logMode,
+    }), { mode: 0o644 });
+    const reload = systemctl(['daemon-reload']);
+    if (!reload.ok) {
+        return {
+            ok: false,
+            path: exports.UNIT_PATH,
+            warnings,
+            error: `systemctl --user could not be reached: ${reload.output}\n`
+                + 'If this is an ssh session on a server, the user manager may not be running — '
+                + `try \`sudo loginctl enable-linger ${currentUser()}\` and run this again.`,
+        };
+    }
+    // Linger BEFORE starting, so a node armed over ssh survives the disconnect
+    // that usually follows within the minute. Not fatal if it fails: the unit is
+    // still correct and still starts at the next login, so say what is missing
+    // rather than refusing the whole operation.
+    if (!fs.existsSync(lingerPath())) {
+        const linger = run('loginctl', ['enable-linger', currentUser()]);
+        if (!linger.ok) {
+            warnings.push('could not enable lingering, so this node will stop when you log out — '
+                + `run \`sudo loginctl enable-linger ${currentUser()}\` to fix that`);
+        }
+    }
+    const handover = (0, autostart_1.stopRunningDaemon)();
+    if (handover.kind === 'stuck') {
+        return {
+            ok: false,
+            path: exports.UNIT_PATH,
+            warnings,
+            error: `a node is already running here (pid ${handover.pid}) and did not stop within 40s — quit it, then run \`ainode startup enable\` again`,
+        };
+    }
+    if (handover.kind === 'self') {
+        // Deliberately `enable` without `--now`: starting the unit would spawn a
+        // second daemon, which cannot take the lockfile and would be restarted
+        // every 10s for as long as this one lives.
+        const armed = systemctl(['enable', autostart_1.SERVICE_NAME]);
+        if (!armed.ok) {
+            return { ok: false, path: exports.UNIT_PATH, warnings, error: `systemctl --user enable failed: ${armed.output}` };
+        }
+        warnings.push('this node is running right now, so systemd takes over when it next restarts');
+        return { ok: true, path: exports.UNIT_PATH, warnings };
+    }
+    if (handover.kind === 'stopped') {
+        warnings.push('stopped the node that was already running; systemd owns it now');
+    }
+    const armed = systemctl(['enable', '--now', autostart_1.SERVICE_NAME]);
+    if (!armed.ok) {
+        return { ok: false, path: exports.UNIT_PATH, warnings, error: `systemctl --user enable --now failed: ${armed.output}` };
+    }
+    // The verdict, not the hint. Everything above this line has only established
+    // that systemd accepted the unit.
+    const state = waitUntilActive();
+    if (state !== 'active') {
+        const log = recentLog();
+        return {
+            ok: false,
+            path: exports.UNIT_PATH,
+            warnings,
+            error: [
+                `the unit was registered but did not start (systemd reports it "${state}").`,
+                `Its definition is at ${exports.UNIT_PATH} and has been left in place so you can look.`,
+                '',
+                `  systemctl --user status ${autostart_1.SERVICE_NAME}`,
+                `  journalctl --user -u ${autostart_1.SERVICE_NAME} -n 50`,
+                ...(log ? ['', log] : []),
+            ].join('\n'),
+        };
+    }
+    return { ok: true, path: exports.UNIT_PATH, warnings };
+}
+function disable() {
+    if (!systemdAvailable())
+        return { ok: true }; // nothing was ever registered
+    // `disable --now` both stops the running unit and removes the symlink. This
+    // takes the node offline, which is what "stop starting at login" has to mean
+    // when the thing is running right now — same as the launchd backend.
+    systemctl(['disable', '--now', autostart_1.SERVICE_NAME]);
+    try {
+        fs.unlinkSync(exports.UNIT_PATH);
+    }
+    catch { /* already gone */ }
+    systemctl(['daemon-reload']);
+    // Linger is deliberately LEFT ON. It is a property of the user account, not
+    // of this node, and a user may well have other lingering units; turning it
+    // off here would reach outside what this feature owns.
+    return { ok: true };
+}
+exports.backend = { supervisor: 'systemd', status, enable, disable };

package/dist/autostart-mac.d.ts

@@ -25,38 +25,4 @@ export declare function parsePlistEntry(xml: string): AutostartEntry | undefined
 /** Directories macOS gates behind user consent no background agent can give. */
 export declare function protectedPathReason(scriptPath: string, home?: string): string | null;
 export declare function protectedPathError(label: string, scriptPath: string): string;
-/**
- * Hand the node over to launchd.
- *
- * A daemon started by hand holds the lockfile, and `acquireLockfile()` throws
- * for anyone else. Bootstrapping the agent underneath it would therefore mean
- * launchd relaunching a job that exits 1 every ten seconds until the human
- * closes their terminal. So we ask the incumbent to stand down first — SIGTERM
- * runs its normal drain, so live entity turns finish rather than being cut.
- *
- * Except when the incumbent is US. `ainode startup enable` can be pressed from
- * inside the console of the very daemon it is arming, and signalling ourselves
- * there would kill the node the user is looking at. That case writes the plist
- * and stops: ~/Library/LaunchAgents is read at every login, so the change
- * lands at the next one without anybody being killed for it.
- */
-export type Handover = 
-/** Nothing was running — safe to start the agent immediately. */
-{
-    kind: 'none';
-}
-/** The running daemon is this very process. Write only, don't bootstrap. */
- | {
-    kind: 'self';
-}
-/** Someone else's daemon stood down; the agent can take over now. */
- | {
-    kind: 'stopped';
-}
-/** It was asked to stop and didn't. */
- | {
-    kind: 'stuck';
-    pid: number;
-};
-export declare function stopRunningDaemon(timeoutMs?: number, selfPid?: number): Handover;
 export declare const backend: AutostartBackend;

package/dist/autostart-mac.js

@@ -43,13 +43,11 @@ exports.buildPlist = buildPlist;
 exports.parsePlistEntry = parsePlistEntry;
 exports.protectedPathReason = protectedPathReason;
 exports.protectedPathError = protectedPathError;
-exports.stopRunningDaemon = stopRunningDaemon;
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const autostart_1 = require("./autostart");
-const lockfile_1 = require("./lockfile");
 exports.PLIST_PATH = path.join(os.homedir(), 'Library', 'LaunchAgents', `${autostart_1.LABEL}.plist`);
 /** `<string>` bodies are the only place user data lands in the plist, and a
  *  PATH entry with an `&` in it would otherwise produce invalid XML that
@@ -186,29 +184,6 @@ function launchctl(args) {
         return { ok: false, output: stderr || e.message || 'launchctl failed' };
     }
 }
-function stopRunningDaemon(timeoutMs = 40_000, selfPid = process.pid) {
-    const lock = (0, lockfile_1.readLockfile)();
-    if (!lock || !(0, lockfile_1.lockfileAlive)(lock))
-        return { kind: 'none' };
-    if (lock.pid === selfPid)
-        return { kind: 'self' };
-    try {
-        process.kill(lock.pid, 'SIGTERM');
-    }
-    catch {
-        return { kind: 'stopped' };
-    }
-    // Synchronous poll: `startup enable` is a one-shot CLI command, and making
-    // the whole backend async to sleep 250ms would buy nothing.
-    const deadline = Date.now() + timeoutMs;
-    const nap = new Int32Array(new SharedArrayBuffer(4));
-    while (Date.now() < deadline) {
-        Atomics.wait(nap, 0, 0, 250);
-        if (!(0, lockfile_1.lockfileAlive)((0, lockfile_1.readLockfile)()))
-            return { kind: 'stopped' };
-    }
-    return { kind: 'stuck', pid: lock.pid };
-}
 function enable(entry, env, logPath, opts = {}) {
     const warnings = [];
     const script = entry.args[0] ?? entry.file;
@@ -232,7 +207,7 @@ function enable(entry, env, logPath, opts = {}) {
     // handover would sit there watching a lockfile that keeps coming back and
     // conclude the node is stuck. Booting out first makes the stop stick.
     launchctl(['bootout', `${domain()}/${autostart_1.LABEL}`]);
-    const handover = stopRunningDaemon();
+    const handover = (0, autostart_1.stopRunningDaemon)();
     if (handover.kind === 'stuck') {
         return {
             ok: false,

package/dist/autostart.d.ts

@@ -1,4 +1,4 @@
-export type Supervisor = 'launchd' | 'schtasks';
+export type Supervisor = 'launchd' | 'schtasks' | 'systemd';
 /** The exact command a supervisor is told to run. */
 export interface AutostartEntry {
     file: string;
@@ -43,6 +43,27 @@ export declare const LABEL = "ai.add.node";
 /** Task Scheduler's name for the same thing. Space-free: `schtasks` quoting
  *  through cmd.exe is a known source of Windows breakage in this codebase. */
 export declare const TASK_NAME = "AiNode";
+/** systemd's name for the same thing — a per-user unit, never a system one. */
+export declare const SERVICE_NAME = "ainode.service";
+export type Handover = 
+/** Nothing was running — safe to start the supervised job immediately. */
+{
+    kind: 'none';
+}
+/** The running daemon is this very process. Write only, don't start. */
+ | {
+    kind: 'self';
+}
+/** Someone else's daemon stood down; the supervisor can take over now. */
+ | {
+    kind: 'stopped';
+}
+/** It was asked to stop and didn't. */
+ | {
+    kind: 'stuck';
+    pid: number;
+};
+export declare function stopRunningDaemon(timeoutMs?: number, selfPid?: number): Handover;
 export interface ResolvedEntry {
     entry?: AutostartEntry;
     error?: string;

package/dist/autostart.js

@@ -50,7 +50,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TASK_NAME = exports.LABEL = void 0;
+exports.SERVICE_NAME = exports.TASK_NAME = exports.LABEL = void 0;
+exports.stopRunningDaemon = stopRunningDaemon;
 exports.resolveEntry = resolveEntry;
 exports.buildEnv = buildEnv;
 exports.status = status;
@@ -67,6 +68,31 @@ exports.LABEL = 'ai.add.node';
 /** Task Scheduler's name for the same thing. Space-free: `schtasks` quoting
  *  through cmd.exe is a known source of Windows breakage in this codebase. */
 exports.TASK_NAME = 'AiNode';
+/** systemd's name for the same thing — a per-user unit, never a system one. */
+exports.SERVICE_NAME = 'ainode.service';
+function stopRunningDaemon(timeoutMs = 40_000, selfPid = process.pid) {
+    const lock = (0, lockfile_1.readLockfile)();
+    if (!lock || !(0, lockfile_1.lockfileAlive)(lock))
+        return { kind: 'none' };
+    if (lock.pid === selfPid)
+        return { kind: 'self' };
+    try {
+        process.kill(lock.pid, 'SIGTERM');
+    }
+    catch {
+        return { kind: 'stopped' };
+    }
+    // Synchronous poll: `startup enable` is a one-shot CLI command, and making
+    // the whole backend async to sleep 250ms would buy nothing.
+    const deadline = Date.now() + timeoutMs;
+    const nap = new Int32Array(new SharedArrayBuffer(4));
+    while (Date.now() < deadline) {
+        Atomics.wait(nap, 0, 0, 250);
+        if (!(0, lockfile_1.lockfileAlive)((0, lockfile_1.readLockfile)()))
+            return { kind: 'stopped' };
+    }
+    return { kind: 'stuck', pid: lock.pid };
+}
 /**
  * The command to write into the supervisor's definition.
  *
@@ -154,6 +180,10 @@ function backend(platform = process.platform) {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
         return require('./autostart-win').backend;
     }
+    if (platform === 'linux') {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require('./autostart-linux').backend;
+    }
     return null;
 }
 const UNSUPPORTED = { supported: false, enabled: false, supervisor: null };
@@ -199,13 +229,17 @@ function disable() {
 /** Is a supervisor going to restart us if we exit? Decides whether a remote
  *  roll self-respawns or simply stands down and lets the supervisor act. */
 function isSupervised(state = status(), env = process.env) {
-    // launchd is a live supervisor: KeepAlive brings the job straight back.
-    // Task Scheduler is not — its logon trigger has already fired, and the
-    // 5-minute repeat is a backstop measured in minutes, not a restart path.
-    // So only launchd earns exit-and-be-restarted.
-    if (env.AINODE_SUPERVISOR === 'launchd')
+    // launchd (KeepAlive) and systemd (Restart=always) are live supervisors:
+    // they bring the job straight back, which is what makes a remote roll safe
+    // to perform by simply exiting.
+    //
+    // Task Scheduler is not one. Its logon trigger has already fired, and the
+    // 5-minute repeat is a backstop measured in minutes, not a restart path — so
+    // a Windows roll self-respawns instead (see index.ts).
+    const live = ['launchd', 'systemd'];
+    if (env.AINODE_SUPERVISOR && live.includes(env.AINODE_SUPERVISOR))
         return true;
-    return state.supervisor === 'launchd' && state.enabled;
+    return live.includes(state.supervisor) && state.enabled;
 }
 /* ── human-readable state, shared by the CLI and the TUI ──────────────── */
 function describeStatus(s) {

package/dist/claude-binary.d.ts

@@ -1,3 +1,22 @@
+/**
+ * The daemon's own npm prefix — `~/.ainode/tools`.
+ *
+ * Two ways a harness ends up in there rather than on the machine's global
+ * PATH. npmInstallGlobal falls back to it when the real global prefix is
+ * root-owned (the classic `/usr/local` Mac), and a node installed by
+ * node.add.ai points npm's builtin prefix at it deliberately, so the node
+ * carries its own runtime and its own CLIs and touches nothing else.
+ *
+ * win.ts's shared findCliBinary has searched here for a while, which is why
+ * codex/gemini/grok/kimi find their installs. This file predates that helper
+ * and keeps its own resolution on purpose — its POSIX probe runs an
+ * *interactive login* shell so a `claude` shell alias resolves — so it needs
+ * the same candidates added by hand rather than a refactor onto the helper.
+ *
+ * The legacy home is searched too: a box whose state dir was never migrated
+ * can still hold harnesses installed before the rename.
+ */
+export declare function toolsPrefixCandidates(name: string, isWindows?: boolean, roots?: string[]): string[];
 /**
  * Find the Claude Code CLI binary. Mirrors the resolution strategy
  * the desktop app uses, so the runtime spawns the same Claude the

package/dist/claude-binary.js

@@ -33,12 +33,40 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolsPrefixCandidates = toolsPrefixCandidates;
 exports.findClaudeBinary = findClaudeBinary;
 exports.encodeProjectPath = encodeProjectPath;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
+const paths_1 = require("./paths");
 const IS_WINDOWS = process.platform === 'win32';
+/**
+ * The daemon's own npm prefix — `~/.ainode/tools`.
+ *
+ * Two ways a harness ends up in there rather than on the machine's global
+ * PATH. npmInstallGlobal falls back to it when the real global prefix is
+ * root-owned (the classic `/usr/local` Mac), and a node installed by
+ * node.add.ai points npm's builtin prefix at it deliberately, so the node
+ * carries its own runtime and its own CLIs and touches nothing else.
+ *
+ * win.ts's shared findCliBinary has searched here for a while, which is why
+ * codex/gemini/grok/kimi find their installs. This file predates that helper
+ * and keeps its own resolution on purpose — its POSIX probe runs an
+ * *interactive login* shell so a `claude` shell alias resolves — so it needs
+ * the same candidates added by hand rather than a refactor onto the helper.
+ *
+ * The legacy home is searched too: a box whose state dir was never migrated
+ * can still hold harnesses installed before the rename.
+ */
+function toolsPrefixCandidates(name, isWindows = IS_WINDOWS, roots = [paths_1.RUNTIME_HOME, paths_1.LEGACY_RUNTIME_HOME]) {
+    return roots.flatMap(root => isWindows
+        ? [
+            path.join(root, 'tools', `${name}.exe`),
+            path.join(root, 'tools', `${name}.cmd`),
+        ]
+        : [path.join(root, 'tools', 'bin', name)]);
+}
 /**
  * Find the Claude Code CLI binary. Mirrors the resolution strategy
  * the desktop app uses, so the runtime spawns the same Claude the
@@ -78,6 +106,7 @@ function findClaudeBinary() {
             path.join(localAppData, 'npm', 'claude.cmd'),
             path.join(userProfile, '.npm-global', 'claude.cmd'),
             path.join(userProfile, 'AppData', 'Roaming', 'npm', 'claude.cmd'),
+            ...toolsPrefixCandidates('claude'),
         ];
         for (const p of candidates) {
             try {
@@ -123,6 +152,7 @@ function findClaudeBinary() {
             `${home}/.bun/bin/claude`,
             `${home}/.volta/bin/claude`,
             `${home}/.nvm/current/bin/claude`,
+            ...toolsPrefixCandidates('claude'),
         ];
         for (const p of candidates) {
             try {

package/dist/command-runner.js

@@ -55,6 +55,7 @@ const store_1 = require("./store");
 const capabilities_1 = require("./capabilities");
 const heartbeat_1 = require("./heartbeat");
 const win_1 = require("./win");
+const start_engine_1 = require("./desktop/start-engine");
 const harness_registry_1 = require("./harness-registry");
 const self_update_1 = require("./self-update");
 const autostart_1 = require("./autostart");
@@ -64,6 +65,7 @@ const docker_1 = require("./desktop/docker");
 const manager_1 = require("./desktop/manager");
 const creds_1 = require("./desktop/creds");
 const install_engine_1 = require("./desktop/install-engine");
+const engine_1 = require("./desktop/engine");
 const COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
 /** Own version, read the same way index.ts does. Resolved here rather than
  *  imported from index.ts, which already imports this module. */
@@ -684,6 +686,63 @@ async function runDesktopCommand(cmd) {
  *  the verdict, not the installer's exit code - Docker Desktop on macOS
  *  installs the app but the daemon is not up until someone launches it, so a
  *  clean exit does not mean a usable engine. */
+/**
+ * Wake an engine that is installed but asleep.
+ *
+ * Distinct from runInstallEngine on purpose: there is nothing to install, so
+ * there is nothing to reboot for and — on macOS and Windows — no password to
+ * ask for. Only the Linux path needs the sudo round trip, and only when this
+ * daemon is not already root, so most machines see a button that just works.
+ */
+async function runStartEngine(cmd) {
+    let log = '';
+    const onLog = (chunk) => {
+        log = (log + chunk).slice(-LOG_TAIL_CHARS);
+        void update(cmd.id, null, { log });
+    };
+    await update(cmd.id, 'running', { log });
+    try {
+        const engine = await (0, start_engine_1.startEngine)(onLog, async () => {
+            // Same parking pattern as the install: Studio collects the password the
+            // way it collects a harness login code.
+            await update(cmd.id, 'awaiting_input', { needs: 'sudo_password', log });
+            const deadline = Date.now() + INPUT_WAIT_MS;
+            while (Date.now() < deadline) {
+                const row = await pollRow(cmd.id);
+                if (!row)
+                    break;
+                if (row.status === 'canceled')
+                    return null;
+                const pw = row.input?.sudo_password;
+                if (pw) {
+                    // Wipe it from the row the moment we hold it.
+                    const t = token();
+                    if (t) {
+                        try {
+                            await (0, supabase_client_1.rpc)('runtime_command_clear_input', { p_token: t, p_id: cmd.id });
+                        }
+                        catch { /* best effort — it still must not reach the log */ }
+                    }
+                    await update(cmd.id, 'running', { needs: null, log });
+                    return pw;
+                }
+                await new Promise(r => setTimeout(r, INPUT_POLL_MS));
+            }
+            return null;
+        });
+        // The provider caches "no engine"; without this the next desktop command
+        // would still believe the machine cannot host anything.
+        (0, docker_1.resetProviderCache)();
+        if (!engine) {
+            await update(cmd.id, 'failed', { log }, 'The engine did not start. It may still be booting — this machine reports in every 30 seconds.');
+            return;
+        }
+        await update(cmd.id, 'completed', { log });
+    }
+    catch (e) {
+        await update(cmd.id, 'failed', { log }, e instanceof Error ? e.message : String(e));
+    }
+}
 async function runInstallEngine(cmd) {
     let log = '';
     const onLog = (chunk) => {
@@ -692,7 +751,11 @@ async function runInstallEngine(cmd) {
     };
     await update(cmd.id, 'running', { log });
     try {
-        await (0, install_engine_1.installEngine)(onLog, async () => {
+        // Installed but unreachable is a permissions problem, not a missing one -
+        // the same button must repair rather than reinstall.
+        const before = await (0, engine_1.detectEngine)();
+        const blocked = !!before && !before.running;
+        const outcome = await (0, install_engine_1.installEngine)(onLog, async () => {
             // Park the command and let Studio collect it, exactly as a harness
             // login collects a paste-back code.
             await update(cmd.id, 'awaiting_input', { needs: 'sudo_password', log });
@@ -720,8 +783,19 @@ async function runInstallEngine(cmd) {
                 await new Promise(r => setTimeout(r, INPUT_POLL_MS));
             }
             return null;
-        });
+        }, blocked);
         (0, docker_1.resetProviderCache)();
+        if (outcome.needsRestart) {
+            // Group membership only applies to new processes, so this daemon still
+            // cannot reach the socket. Say so plainly and bounce it.
+            onLog('\nPermissions fixed. Restarting this machine\'s node so it picks up the new group…\n');
+            await update(cmd.id, 'completed', { log, restarting: true });
+            await (0, heartbeat_1.beat)();
+            if (restartHook) {
+                await restartHook({ commandId: cmd.id, version: VERSION, restartOnly: true });
+            }
+            return;
+        }
         const engine = await (0, docker_1.getProvider)(true);
         if (!engine) {
             await update(cmd.id, 'failed', { log }, 'Installed, but no engine is answering yet. On macOS, Docker Desktop has to be opened once before its daemon runs.');
@@ -753,6 +827,10 @@ async function execute(cmd) {
         await runInstallEngine(cmd);
         return;
     }
+    if (cmd.kind === 'start_engine') {
+        await runStartEngine(cmd);
+        return;
+    }
     if (DESKTOP_KINDS.includes(cmd.kind)) {
         await runDesktopCommand(cmd);
         return;

package/dist/desktop/install-engine.d.ts

@@ -8,6 +8,16 @@ export interface InstallPlan {
 }
 /** Pure, so the choice is testable on any machine. */
 export declare function installPlan(platform: NodeJS.Platform, isRoot: boolean): InstallPlan;
+/** Docker is there but this user cannot reach its socket. The fix is group
+ *  membership, not another install — and it needs root, so it takes the same
+ *  password round trip. */
+export declare function repairPlan(user: string): {
+    inner: string;
+    manual: string;
+};
+/** Group membership is fixed for FUTURE processes only, so the daemon that
+ *  asked for the fix still cannot reach the socket until it restarts. */
+export declare const REPAIR_NEEDS_RESTART = true;
 export declare function runningAsRoot(): boolean;
 /** Build the argv for a privileged install. The password NEVER goes in argv —
  *  argv is world-readable through /proc on Linux, so anyone with a shell on
@@ -17,4 +27,9 @@ export declare function sudoArgv(inner: string): {
     file: string;
     args: string[];
 };
-export declare function installEngine(onLog: (s: string) => void, askPassword?: () => Promise<string | null>): Promise<void>;
+/** Install if it is missing; fix permissions if it is merely unreachable.
+ *  One button, because from the outside they are the same complaint: this
+ *  machine cannot host desktops. Returns whether a restart is now needed. */
+export declare function installEngine(onLog: (s: string) => void, askPassword?: () => Promise<string | null>, alreadyInstalledButBlocked?: boolean): Promise<{
+    needsRestart: boolean;
+}>;

package/dist/desktop/install-engine.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPAIR_NEEDS_RESTART = void 0;
 exports.installPlan = installPlan;
+exports.repairPlan = repairPlan;
 exports.runningAsRoot = runningAsRoot;
 exports.sudoArgv = sudoArgv;
 exports.installEngine = installEngine;
@@ -37,6 +39,19 @@ function installPlan(platform, isRoot) {
         manual: 'curl -fsSL https://get.docker.com | sudo sh', needsRoot: true,
     };
 }
+/** Docker is there but this user cannot reach its socket. The fix is group
+ *  membership, not another install — and it needs root, so it takes the same
+ *  password round trip. */
+function repairPlan(user) {
+    const u = user.replace(/[^A-Za-z0-9._-]/g, '');
+    return {
+        inner: `usermod -aG docker ${u}`,
+        manual: `sudo usermod -aG docker ${u}`,
+    };
+}
+/** Group membership is fixed for FUTURE processes only, so the daemon that
+ *  asked for the fix still cannot reach the socket until it restarts. */
+exports.REPAIR_NEEDS_RESTART = true;
 function runningAsRoot() {
     return typeof process.getuid === 'function' && process.getuid() === 0;
 }
@@ -47,11 +62,37 @@ function runningAsRoot() {
 function sudoArgv(inner) {
     return { file: 'sudo', args: ['-S', '-p', '', 'sh', '-c', inner] };
 }
-async function installEngine(onLog, askPassword) {
+/** Install if it is missing; fix permissions if it is merely unreachable.
+ *  One button, because from the outside they are the same complaint: this
+ *  machine cannot host desktops. Returns whether a restart is now needed. */
+async function installEngine(onLog, askPassword, alreadyInstalledButBlocked) {
     const plan = installPlan(process.platform, runningAsRoot());
     let file = plan.file;
     let args = plan.args;
     let password = null;
+    // Docker present but the socket is refused: repair, do not reinstall.
+    const repair = alreadyInstalledButBlocked
+        ? repairPlan(process.env.USER || process.env.LOGNAME || 'root')
+        : null;
+    if (repair) {
+        if (runningAsRoot()) {
+            onLog(`fixing permissions\n  ${repair.inner}\n\n`);
+            file = 'sh';
+            args = ['-c', repair.inner];
+        }
+        else if (askPassword) {
+            onLog(`This machine needs a sudo password to fix Docker permissions.\n  ${repair.manual}\n\n`);
+            password = await askPassword();
+            if (!password)
+                throw new Error(`No password given. Run it on the machine instead:\n  ${repair.manual}`);
+            const sudo = sudoArgv(repair.inner);
+            file = sudo.file;
+            args = sudo.args;
+        }
+        else {
+            throw new Error(`Needs root. Run this on the machine:\n  ${repair.manual}`);
+        }
+    }
     if (!file && plan.needsRoot && askPassword) {
         onLog('This machine needs a sudo password to install Docker.\n');
         password = await askPassword();
@@ -86,6 +127,7 @@ async function installEngine(onLog, askPassword) {
         child.on('error', err => reject(new Error(`${file} is not available here. Install it by hand:\n  ${plan.manual}\n(${err.message})`)));
         child.on('exit', code => code === 0
             ? resolve()
-            : reject(new Error(`install failed (exit ${code}). Try by hand:\n  ${plan.manual}\n${tail.slice(-400)}`)));
+            : reject(new Error(`${repair ? 'permission fix' : 'install'} failed (exit ${code}). Try by hand:\n  ${repair ? repair.manual : plan.manual}\n${tail.slice(-400)}`)));
     });
+    return { needsRestart: !!repair && exports.REPAIR_NEEDS_RESTART };
 }

package/dist/desktop/start-engine.d.ts

@@ -0,0 +1,44 @@
+import { EngineInfo } from './provider';
+export interface StartPlan {
+    /** Null when this platform has no way we can drive without a password. */
+    file: string | null;
+    args: string[];
+    /** What a human would run, shown when we cannot do it ourselves. */
+    manual: string;
+    needsRoot: boolean;
+    /** Launch and walk away — Docker Desktop is a GUI app that outlives us. */
+    detached: boolean;
+}
+/**
+ * Pure, so the choice is testable on any machine.
+ *
+ * @param programFiles  %ProgramFiles% on Windows. Passed in rather than read
+ *                      from the environment so the Windows path is testable
+ *                      from a Mac, which is where it is usually written.
+ */
+export declare function startPlan(platform: NodeJS.Platform, isRoot: boolean, programFiles?: string): StartPlan;
+/** Build the argv for a privileged start. Password on stdin, never argv —
+ *  argv is world-readable through /proc. */
+export declare function sudoStartArgv(): {
+    file: string;
+    args: string[];
+};
+export declare function runningAsRoot(): boolean;
+/**
+ * How long to wait for the daemon after the launch command returns.
+ *
+ * Docker Desktop is not "started" when its process exists — it boots a VM.
+ * On a cold Windows machine that is routinely a minute or more, so a short
+ * timeout would report failure on a machine that was about to work.
+ */
+export declare const START_TIMEOUT_MS = 150000;
+/** Poll until the engine actually answers, or we run out of patience. */
+export declare function waitForEngine(onLog: (s: string) => void, timeoutMs?: number, probe?: () => Promise<EngineInfo | null>): Promise<EngineInfo | null>;
+/**
+ * Ask this machine's engine to start.
+ *
+ * Returns the engine once it answers, or null with the reason logged. The
+ * password callback is only ever invoked on Linux, and only when this process
+ * is not already root.
+ */
+export declare function startEngine(onLog: (chunk: string) => void, askPassword: () => Promise<string | null>): Promise<EngineInfo | null>;

package/dist/desktop/start-engine.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.START_TIMEOUT_MS = void 0;
+exports.startPlan = startPlan;
+exports.sudoStartArgv = sudoStartArgv;
+exports.runningAsRoot = runningAsRoot;
+exports.waitForEngine = waitForEngine;
+exports.startEngine = startEngine;
+// Start a container engine that is installed but asleep.
+//
+// A machine with Docker installed and closed is the single most common reason
+// the Desktops tab is dark, and it is the one case where the fix is genuinely
+// one command. Reinstalling would be wrong (it is already there), and telling
+// someone to walk to the machine is only honest while nothing here can do it.
+//
+// Deliberately separate from install-engine: installing is a slow, privileged,
+// possibly-rebooting operation, and starting is a fast unprivileged one on the
+// two desktop platforms. Sharing a code path would have meant the start button
+// inheriting the install button's sudo round trip on machines that never need
+// it.
+const child_process_1 = require("child_process");
+const win_1 = require("../win");
+const engine_1 = require("./engine");
+/**
+ * Pure, so the choice is testable on any machine.
+ *
+ * @param programFiles  %ProgramFiles% on Windows. Passed in rather than read
+ *                      from the environment so the Windows path is testable
+ *                      from a Mac, which is where it is usually written.
+ */
+function startPlan(platform, isRoot, programFiles) {
+    if (platform === 'darwin') {
+        // `open -a` returns as soon as the app is launching; the daemon comes up
+        // a while later, which is why the caller polls rather than trusting exit 0.
+        return {
+            file: 'open', args: ['-a', 'Docker'],
+            manual: 'open -a Docker', needsRoot: false, detached: false,
+        };
+    }
+    if (platform === 'win32') {
+        // Spawned directly rather than through `cmd /c start`: quoting a path with
+        // spaces through cmd is the kind of thing that works until someone's
+        // Windows is installed on a different drive.
+        const base = programFiles || 'C:\\Program Files';
+        return {
+            file: `${base}\\Docker\\Docker\\Docker Desktop.exe`, args: [],
+            manual: 'Start Docker Desktop from the Start menu',
+            needsRoot: false, detached: true,
+        };
+    }
+    // Linux: the daemon is a system service, so this needs root the same way
+    // installing does — and takes the same password round trip.
+    return {
+        file: isRoot ? 'sh' : null,
+        args: ['-c', 'systemctl start docker'],
+        manual: 'sudo systemctl start docker',
+        needsRoot: true, detached: false,
+    };
+}
+/** Build the argv for a privileged start. Password on stdin, never argv —
+ *  argv is world-readable through /proc. */
+function sudoStartArgv() {
+    return { file: 'sudo', args: ['-S', '-p', '', 'sh', '-c', 'systemctl start docker'] };
+}
+function runningAsRoot() {
+    return typeof process.getuid === 'function' && process.getuid() === 0;
+}
+/**
+ * How long to wait for the daemon after the launch command returns.
+ *
+ * Docker Desktop is not "started" when its process exists — it boots a VM.
+ * On a cold Windows machine that is routinely a minute or more, so a short
+ * timeout would report failure on a machine that was about to work.
+ */
+exports.START_TIMEOUT_MS = 150_000;
+const POLL_MS = 3_000;
+/** Poll until the engine actually answers, or we run out of patience. */
+async function waitForEngine(onLog, timeoutMs = exports.START_TIMEOUT_MS, probe = engine_1.detectEngine) {
+    const deadline = Date.now() + timeoutMs;
+    let dots = 0;
+    while (Date.now() < deadline) {
+        const e = await probe();
+        if (e && e.running)
+            return e;
+        // A line every few seconds, so the log looks alive during a long VM boot
+        // rather than looking like it hung.
+        if (dots++ % 4 === 0) {
+            onLog(`  still waiting for the engine… ${Math.round((Date.now() - (deadline - timeoutMs)) / 1000)}s\n`);
+        }
+        await new Promise(r => setTimeout(r, POLL_MS));
+    }
+    return null;
+}
+/**
+ * Ask this machine's engine to start.
+ *
+ * Returns the engine once it answers, or null with the reason logged. The
+ * password callback is only ever invoked on Linux, and only when this process
+ * is not already root.
+ */
+async function startEngine(onLog, askPassword) {
+    const plan = startPlan(process.platform, runningAsRoot(), process.env.ProgramFiles);
+    if (!plan.file) {
+        // Linux, not root. Ask for the password and go through sudo.
+        const pw = await askPassword();
+        if (!pw) {
+            onLog(`\nNo password given. Start it on the machine instead:\n  ${plan.manual}\n`);
+            return null;
+        }
+        const { file, args } = sudoStartArgv();
+        const code = await run(file, args, onLog, false, pw);
+        if (code !== 0) {
+            onLog(`\nThat did not work. On the machine:\n  ${plan.manual}\n`);
+            return null;
+        }
+    }
+    else {
+        onLog(`Starting ${plan.file}…\n`);
+        const code = await run(plan.file, plan.args, onLog, plan.detached);
+        // A detached GUI launch has no meaningful exit code, and on Windows the
+        // exe returns immediately. Only a hard spawn failure is worth reporting,
+        // and that surfaces as -1 below.
+        if (code === -1) {
+            onLog(`\nCould not launch it. On the machine:\n  ${plan.manual}\n`);
+            return null;
+        }
+    }
+    onLog('Waiting for the engine to answer…\n');
+    const engine = await waitForEngine(onLog);
+    if (!engine) {
+        onLog(`\nIt did not come up in time. It may still be starting — this page turns on by itself when it does.\n`);
+        return null;
+    }
+    onLog(`\n${engine.id} is ready.\n`);
+    return engine;
+}
+function run(binary, args, onLog, detached, stdin) {
+    return new Promise(resolve => {
+        try {
+            const inv = (0, win_1.resolveCliInvocation)(binary, args);
+            const child = (0, child_process_1.spawn)(inv.file, inv.args, {
+                env: process.env,
+                windowsHide: true,
+                detached,
+                stdio: stdin ? ['pipe', 'pipe', 'pipe'] : undefined,
+            });
+            if (stdin && child.stdin) {
+                child.stdin.write(`${stdin}\n`);
+                child.stdin.end();
+            }
+            child.stdout?.on('data', b => onLog(b.toString('utf8')));
+            child.stderr?.on('data', b => onLog(b.toString('utf8')));
+            child.on('error', () => resolve(-1));
+            if (detached) {
+                // Let it outlive this process; Docker Desktop must not die with the
+                // daemon that launched it.
+                child.unref();
+                resolve(0);
+                return;
+            }
+            child.on('exit', code => resolve(code ?? -1));
+        }
+        catch {
+            resolve(-1);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@addai/node",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Daemon that pairs a machine with your +Ai account and runs Claude / Codex / Kimi / Gemini agents on its behalf. Reachable via Supabase from Vault, Entity Studio, or any other +Ai surface.",
   "license": "MIT",
   "keywords": [