@addai/node 0.11.3 → 0.13.0

package/dist/index.js

@@ -49,11 +49,16 @@ const pairing_1 = require("./pairing");
 const heartbeat_1 = require("./heartbeat");
 const command_runner_1 = require("./command-runner");
 const self_update_1 = require("./self-update");
+const auto_update_1 = require("./auto-update");
+const machine_metrics_1 = require("./machine-metrics");
+const capabilities_1 = require("./capabilities");
 const autostart_1 = require("./autostart");
 const sleep_detector_1 = require("./sleep-detector");
 const claude_config_1 = require("./claude-config");
 const request_pump_1 = require("./request-pump");
 const projects_1 = require("./projects");
+const manager_1 = require("./desktop/manager");
+const relay_client_1 = require("./desktop/relay-client");
 const session_runner_1 = require("./session-runner");
 const diskguard_1 = require("./diskguard");
 const pty_helper_1 = require("./pty-helper");
@@ -143,6 +148,11 @@ async function start(argv = []) {
     // server reports queued install/login commands, the command runner
     // drains them.
     (0, heartbeat_1.setPendingCommandsHook)(command_runner_1.wake);
+    // So each machine sample can say how many runs the box was holding at the
+    // time — "pinned at 90%" and "pinned at 90% running four things" are
+    // different stories. Hooked rather than imported so capabilities.ts needn't
+    // pull in request-pump, and through it session-runner.
+    (0, machine_metrics_1.setRunsInFlightHook)(() => (0, request_pump_1.activeRequestIdList)().length);
     (0, heartbeat_1.start)();
     // If we are the daemon a remote `update_runtime` restarted INTO, close out
     // that command now — with the version we actually came up as. The process
@@ -198,6 +208,10 @@ async function start(argv = []) {
     (0, request_pump_1.start)();
     // …and for pending projects (git clones, future MCP/skill installs).
     (0, projects_1.start)();
+    // …and to keep desktops and the containers behind them in agreement.
+    (0, manager_1.startDesktopManager)();
+    // …and dial out to the relay so a running desktop is watchable from Studio.
+    (0, relay_client_1.startRelayClient)();
     let stopped = false;
     // Outcome of the last drain, so a remote roll can report whether it left
     // work unfinished instead of claiming a clean restart either way.
@@ -209,8 +223,11 @@ async function start(argv = []) {
         // Stop accepting new work first — otherwise the pump would queue
         // another request between drain start and process exit.
         (0, projects_1.stop)();
+        (0, manager_1.stopDesktopManager)();
+        (0, relay_client_1.stopRelayClient)();
         (0, request_pump_1.stop)();
         (0, heartbeat_1.stop)();
+        (0, auto_update_1.stop)();
         sleepMonitor.stop();
         diskGuard.stop();
         // Graceful drain: wait up to drainTimeoutMs for in-flight requests
@@ -254,7 +271,7 @@ async function start(argv = []) {
     // to the same bits (which matters for npx, whose cache dir is per-version)
     // and npm is never called — nothing to fetch, and nothing that can fail
     // offline.
-    (0, command_runner_1.setRestartHook)(async ({ commandId, version, restartOnly }) => {
+    const performRestart = async ({ commandId, version, restartOnly }) => {
         const mode = (0, self_update_1.detectLaunchMode)(process.argv[1] ?? '');
         const plan = (0, self_update_1.planRespawn)(mode, process.argv[1] ?? '', version, process.execPath, process.argv.slice(2));
         const supervised = (0, autostart_1.isSupervised)();
@@ -293,6 +310,21 @@ async function start(argv = []) {
             ? `[restart] standing down for launchd to restart us (${what}); exiting`
             : `[restart] handed over to ${plan.file} (${what}); exiting`);
         setTimeout(() => process.exit(0), 250).unref?.();
+    };
+    (0, command_runner_1.setRestartHook)(performRestart);
+    // Hourly auto-update — the node keeps itself and its harnesses current
+    // without anybody clicking. It rolls through the very same closure the
+    // manual button does, minus the command id, so a hand roll and an auto
+    // roll cannot drift apart.
+    (0, auto_update_1.start)({
+        token: () => (0, store_1.readPairing)()?.daemonToken ?? null,
+        isBusy: () => (0, request_pump_1.activeRequestIdList)().length > 0,
+        breakerOpen: () => (0, supabase_client_1.rpcShouldSkip)(),
+        enabled: heartbeat_1.autoUpdateEnabled,
+        probe: () => (0, capabilities_1.probeCapabilities)(),
+        beat: () => (0, heartbeat_1.beat)(),
+        roll: ({ version }) => performRestart({ version }),
+        version: VERSION,
     });
     process.once('SIGINT', () => { stop().finally(() => process.exit(0)); });
     process.once('SIGTERM', () => { stop().finally(() => process.exit(0)); });
@@ -392,6 +424,16 @@ async function finalizeRestartHandoff() {
     const changed = h.from_version !== VERSION;
     const wanted = h.target_version;
     const missed = wanted !== 'latest' && wanted !== VERSION;
+    // No command id means the hourly auto-update rolled us, not a button. There
+    // is nothing to close; the outcome goes into capabilities instead, which the
+    // next heartbeat (seconds away) carries to the AiNode page.
+    if (!h.command_id) {
+        (0, auto_update_1.recordAutoRoll)({ from: h.from_version, to: VERSION, ...(missed ? { wanted } : {}) });
+        console.log(missed
+            ? `[auto-update] restarted, but came up as ${VERSION} (wanted ${wanted})`
+            : `[auto-update] back up as ${VERSION} (was ${h.from_version})`);
+        return;
+    }
     try {
         await (0, supabase_client_1.rpc)('runtime_command_update', {
             p_token: t,

package/dist/machine-metrics.d.ts

@@ -0,0 +1,72 @@
+import * as os from 'os';
+export interface MachineSample {
+    /** Logical cores. */
+    cpus?: number;
+    /** Physical memory, MB. */
+    mem_total_mb?: number;
+    /** Memory in use, 0-100. */
+    mem_used_pct?: number;
+    /** Processor busy across all cores since the previous sample, 0-100.
+     *  Absent on the first sample of a daemon's life — there is nothing to
+     *  measure against yet, and a made-up first value would be a lie that
+     *  lands in a graph. */
+    cpu_used_pct?: number;
+    /** 1-minute load average per core. Zero on Windows, where the OS has no
+     *  such concept and Node reports [0,0,0]. */
+    load_per_cpu?: number;
+    /** Scratch volume in use, 0-100 — the same signal the health gate refuses
+     *  new runs on at 97%. A filling disk is the failure that has actually
+     *  bitten prod, so it belongs on the same timeline as the rest. */
+    disk_used_pct?: number;
+    /** Agent runs this node was holding at the moment of the sample. Turns
+     *  "the box was pinned at 90%" into "because it was running four things". */
+    runs?: number;
+    /** Seconds since the machine booted. */
+    uptime_s?: number;
+}
+export interface CpuTimes {
+    idle: number;
+    total: number;
+}
+/**
+ * Smallest interval, in summed CPU-milliseconds across all cores, we will
+ * report a busy figure for.
+ *
+ * Without a floor, two readings a millisecond apart can straddle a single
+ * scheduler tick: idle advances by 0, total by ~1, and the honest arithmetic
+ * says 100% busy. That is noise, not measurement, and it lands in the graph as
+ * a spike that never happened — which is exactly how it was found, by a test
+ * that took two samples back to back and got 100 roughly one run in twelve.
+ *
+ * 100ms across all cores is ~12ms of wall time on an 8-core box, far below the
+ * 30s heartbeat this actually runs at, so no real sample is ever refused.
+ */
+export declare const MIN_SAMPLE_MS = 100;
+/** Summed CPU time across every core, in the units Node reports. */
+export declare function readCpuTimes(cpus: os.CpuInfo[]): CpuTimes;
+/**
+ * Busy percentage between two cumulative readings.
+ *
+ * Deliberately delta-based rather than derived from loadavg: load is a queue
+ * length, not a utilisation, it means different things on different kernels,
+ * and on Windows it is always zero. Deltas of the counters Node already
+ * exposes give a real 0-100 on every platform we run on.
+ *
+ * Returns null when the comparison is meaningless — no previous reading, or a
+ * total that did not advance (same tick) or went backwards (core count
+ * changed under us, a VM migrated). A null is "we don't know", which the graph
+ * shows as a gap; inventing 0% would draw an idle machine that wasn't.
+ */
+export declare function cpuUsedPct(prev: CpuTimes | null, now: CpuTimes): number | null;
+/** Memory in use as a percentage. Note this counts the page cache as used on
+ *  Linux, the same way `free` does before you read the -/+ buffers line — it
+ *  is the number every other tool shows, so it is the one to match. */
+export declare function memUsedPct(totalBytes: number, freeBytes: number): number | null;
+export declare function setRunsInFlightHook(fn: () => number): void;
+/** Reset between tests. */
+export declare function resetCpuBaseline(): void;
+/**
+ * One reading of the machine. Never throws: every field is independently
+ * best-effort, and a sample with holes in it beats no heartbeat at all.
+ */
+export declare function sampleMachine(): MachineSample;

package/dist/machine-metrics.js

@@ -0,0 +1,175 @@
+"use strict";
+// What the machine underneath the daemon is actually doing.
+//
+// Entity Studio's AiNode page has read `capabilities.machine` for cores,
+// memory, load and uptime since it was written — but no version of this daemon
+// has ever produced that key, so those readouts have always been dashes and
+// the Memory tile has always silently fallen back to showing the pairing date.
+// This is the producing half.
+//
+// Sampled on the capabilities probe (every heartbeat, ~30s). Everything here
+// is cheap and synchronous: three `os` calls and one statfs. Nothing may throw
+// — a metrics failure must never cost the heartbeat, because the heartbeat is
+// what keeps the node marked online.
+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.MIN_SAMPLE_MS = void 0;
+exports.readCpuTimes = readCpuTimes;
+exports.cpuUsedPct = cpuUsedPct;
+exports.memUsedPct = memUsedPct;
+exports.setRunsInFlightHook = setRunsInFlightHook;
+exports.resetCpuBaseline = resetCpuBaseline;
+exports.sampleMachine = sampleMachine;
+const os = __importStar(require("os"));
+const node_health_1 = require("./node-health");
+const paths_1 = require("./paths");
+/**
+ * Smallest interval, in summed CPU-milliseconds across all cores, we will
+ * report a busy figure for.
+ *
+ * Without a floor, two readings a millisecond apart can straddle a single
+ * scheduler tick: idle advances by 0, total by ~1, and the honest arithmetic
+ * says 100% busy. That is noise, not measurement, and it lands in the graph as
+ * a spike that never happened — which is exactly how it was found, by a test
+ * that took two samples back to back and got 100 roughly one run in twelve.
+ *
+ * 100ms across all cores is ~12ms of wall time on an 8-core box, far below the
+ * 30s heartbeat this actually runs at, so no real sample is ever refused.
+ */
+exports.MIN_SAMPLE_MS = 100;
+/** Summed CPU time across every core, in the units Node reports. */
+function readCpuTimes(cpus) {
+    let idle = 0;
+    let total = 0;
+    for (const c of cpus) {
+        for (const key of Object.keys(c.times)) {
+            total += c.times[key];
+        }
+        idle += c.times.idle;
+    }
+    return { idle, total };
+}
+/**
+ * Busy percentage between two cumulative readings.
+ *
+ * Deliberately delta-based rather than derived from loadavg: load is a queue
+ * length, not a utilisation, it means different things on different kernels,
+ * and on Windows it is always zero. Deltas of the counters Node already
+ * exposes give a real 0-100 on every platform we run on.
+ *
+ * Returns null when the comparison is meaningless — no previous reading, or a
+ * total that did not advance (same tick) or went backwards (core count
+ * changed under us, a VM migrated). A null is "we don't know", which the graph
+ * shows as a gap; inventing 0% would draw an idle machine that wasn't.
+ */
+function cpuUsedPct(prev, now) {
+    if (!prev)
+        return null;
+    const total = now.total - prev.total;
+    const idle = now.idle - prev.idle;
+    if (total < exports.MIN_SAMPLE_MS || idle < 0)
+        return null;
+    const pct = (1 - idle / total) * 100;
+    return Math.max(0, Math.min(100, Math.round(pct * 10) / 10));
+}
+/** Memory in use as a percentage. Note this counts the page cache as used on
+ *  Linux, the same way `free` does before you read the -/+ buffers line — it
+ *  is the number every other tool shows, so it is the one to match. */
+function memUsedPct(totalBytes, freeBytes) {
+    if (!Number.isFinite(totalBytes) || totalBytes <= 0)
+        return null;
+    const pct = (1 - freeBytes / totalBytes) * 100;
+    return Math.max(0, Math.min(100, Math.round(pct * 10) / 10));
+}
+/* ── live sampling ────────────────────────────────────────────────────── */
+let prevCpu = null;
+/** How many runs this node is holding. Wired by index.ts rather than imported,
+ *  so capabilities.ts does not have to pull in request-pump (and through it
+ *  session-runner) just to count them. */
+let runsInFlight = null;
+function setRunsInFlightHook(fn) { runsInFlight = fn; }
+/** Reset between tests. */
+function resetCpuBaseline() { prevCpu = null; }
+/**
+ * One reading of the machine. Never throws: every field is independently
+ * best-effort, and a sample with holes in it beats no heartbeat at all.
+ */
+function sampleMachine() {
+    const s = {};
+    try {
+        const cpus = os.cpus();
+        if (cpus.length > 0) {
+            s.cpus = cpus.length;
+            const now = readCpuTimes(cpus);
+            const pct = cpuUsedPct(prevCpu, now);
+            if (pct !== null)
+                s.cpu_used_pct = pct;
+            prevCpu = now;
+        }
+    }
+    catch { /* no cpu info — the other fields still stand */ }
+    try {
+        const total = os.totalmem();
+        s.mem_total_mb = Math.round(total / (1024 * 1024));
+        const pct = memUsedPct(total, os.freemem());
+        if (pct !== null)
+            s.mem_used_pct = pct;
+    }
+    catch { /* skip */ }
+    try {
+        const [one] = os.loadavg();
+        const cores = s.cpus ?? 0;
+        if (cores > 0 && Number.isFinite(one))
+            s.load_per_cpu = Math.round((one / cores) * 100) / 100;
+    }
+    catch { /* skip */ }
+    try {
+        const disk = (0, node_health_1.readDiskUsedPct)(paths_1.RUNTIME_HOME);
+        if (disk !== null)
+            s.disk_used_pct = Math.round(disk * 10) / 10;
+    }
+    catch { /* skip */ }
+    try {
+        s.runs = runsInFlight?.() ?? 0;
+    }
+    catch {
+        s.runs = 0;
+    }
+    try {
+        s.uptime_s = Math.round(os.uptime());
+    }
+    catch { /* skip */ }
+    return s;
+}

package/dist/self-update.d.ts

@@ -53,6 +53,23 @@ export interface RollPlan {
     /** Non-null = refuse before anything drains, with this explanation. */
     refusal: string | null;
 }
+/**
+ * Is this something we are willing to hand to `npm i -g @addai/node@…`?
+ *
+ * npm accepts far more than a version after the `@`: a tarball URL, a
+ * `github:user/repo`, a `file:` path — each of which installs code of the
+ * caller's choosing, which this daemon then re-execs as its own binary. A
+ * remotely-supplied spec is therefore restricted to a plain semver or a
+ * dist-tag, and everything else is refused before npm is ever invoked.
+ *
+ * This is the second lock. The first is the RLS policy on runtime_commands,
+ * which was found comparing `input ->> 'restart_only'` (text) while this file
+ * compared `=== true` (boolean) — so the string "true" read as a harmless
+ * restart to the database and as a roll-to-anything here, giving anyone a node
+ * was merely SHARED with arbitrary code execution on the owner's machine.
+ * The policy is fixed; this makes the same mistake unexploitable next time.
+ */
+export declare function isSafeVersionSpec(v: string): boolean;
 /**
  * Read an `update_runtime` command's input into what this node should do.
  *
@@ -67,7 +84,12 @@ export declare function planRoll(input: {
     restart_only?: boolean;
 } | null, mode: LaunchMode, currentVersion: string): RollPlan;
 export interface RestartHandoff {
-    command_id: string;
+    /** Absent when the roll was the hourly auto-update rather than a button:
+     *  there is no command to close, so the daemon that comes up records the
+     *  outcome in capabilities instead. The property that matters survives
+     *  either way — it is the NEW process that reports, so a restart that
+     *  never comes back still never reports success. */
+    command_id?: string;
     from_version: string;
     target_version: string;
     mode: LaunchMode;
@@ -87,11 +109,27 @@ export declare function writeHandoff(runtimeDir: string, h: RestartHandoff): voi
 /** Reads and DELETES the handoff — it must never be replayed twice. */
 export declare function takeHandoff(runtimeDir: string): RestartHandoff | null;
 /**
- * `npm i -g <pkg>@<version>`. Returns null on success, else the reason.
+ * `npm i -g <spec>` for any package. Returns null on success, else the reason.
  * Never throws — a failed install must leave the CURRENT daemon running
  * rather than take the node down.
+ *
+ * On a classic Mac with a root-owned /usr/local prefix the first attempt dies
+ * EACCES, so we retry into the daemon's own prefix — the same fallback
+ * command-runner's interactive install uses, and the same one the binary
+ * finders already search. Without it, auto-update would fail silently forever
+ * on exactly the nodes that needed a human least.
  */
+export declare function npmInstallGlobal(spec: string, timeoutMs?: number): Promise<string | null>;
+/** `npm i -g @addai/node@<version>`. Thin wrapper kept for the roll paths. */
 export declare function installGlobal(targetVersion: string, timeoutMs?: number): Promise<string | null>;
+/**
+ * What npm currently calls `latest` for a package, or null if we couldn't ask.
+ *
+ * Null is deliberately NOT treated as "up to date" by callers — it means the
+ * question went unanswered (offline, registry blip), and an unanswered
+ * question must never masquerade as a clean bill of health.
+ */
+export declare function npmLatestVersion(pkg: string, timeoutMs?: number): Promise<string | null>;
 /**
  * Spawn the replacement daemon fully detached, so it survives this process's
  * exit. stdio is redirected to the daemon log (inheriting our stdio would tie

package/dist/self-update.js

@@ -55,16 +55,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PACKAGE_NAME = void 0;
 exports.detectLaunchMode = detectLaunchMode;
 exports.planRespawn = planRespawn;
+exports.isSafeVersionSpec = isSafeVersionSpec;
 exports.planRoll = planRoll;
 exports.handoffPath = handoffPath;
 exports.writeHandoff = writeHandoff;
 exports.takeHandoff = takeHandoff;
+exports.npmInstallGlobal = npmInstallGlobal;
 exports.installGlobal = installGlobal;
+exports.npmLatestVersion = npmLatestVersion;
 exports.spawnReplacement = spawnReplacement;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const win_1 = require("./win");
+const paths_1 = require("./paths");
 exports.PACKAGE_NAME = '@addai/node';
 /**
  * Classify the launch from the running script's path.
@@ -113,6 +117,29 @@ userArgs = []) {
         canChangeVersion: mode === 'global',
     };
 }
+/**
+ * Is this something we are willing to hand to `npm i -g @addai/node@…`?
+ *
+ * npm accepts far more than a version after the `@`: a tarball URL, a
+ * `github:user/repo`, a `file:` path — each of which installs code of the
+ * caller's choosing, which this daemon then re-execs as its own binary. A
+ * remotely-supplied spec is therefore restricted to a plain semver or a
+ * dist-tag, and everything else is refused before npm is ever invoked.
+ *
+ * This is the second lock. The first is the RLS policy on runtime_commands,
+ * which was found comparing `input ->> 'restart_only'` (text) while this file
+ * compared `=== true` (boolean) — so the string "true" read as a harmless
+ * restart to the database and as a roll-to-anything here, giving anyone a node
+ * was merely SHARED with arbitrary code execution on the owner's machine.
+ * The policy is fixed; this makes the same mistake unexploitable next time.
+ */
+function isSafeVersionSpec(v) {
+    // 1.2.3 / 1.2.3-beta.1
+    if (/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(v))
+        return true;
+    // a dist-tag: latest, next, canary…
+    return /^[a-z][a-z0-9-]{0,31}$/.test(v);
+}
 /**
  * Read an `update_runtime` command's input into what this node should do.
  *
@@ -128,9 +155,11 @@ function planRoll(input, mode, currentVersion) {
     // "did we come up as what was asked for?" check meaningful instead of
     // special-cased — and pins npx, whose cache dir is per-version.
     const target = restartOnly ? currentVersion : (input?.version ?? '').trim() || 'latest';
-    const refusal = !restartOnly && mode === 'source' && target !== 'latest'
-        ? 'this node runs from a source checkout — pull and rebuild it there; a remote version bump cannot apply'
-        : null;
+    const refusal = !restartOnly && !isSafeVersionSpec(target)
+        ? `refusing to install "${target}" — a remote roll may name a version or a dist-tag, nothing else`
+        : !restartOnly && mode === 'source' && target !== 'latest'
+            ? 'this node runs from a source checkout — pull and rebuild it there; a remote version bump cannot apply'
+            : null;
     return { target, restartOnly, refusal };
 }
 function handoffPath(runtimeDir) {
@@ -150,22 +179,85 @@ function takeHandoff(runtimeDir) {
         }
         catch { /* already gone */ }
         const parsed = JSON.parse(raw);
-        return parsed && typeof parsed.command_id === 'string' ? parsed : null;
+        // A handoff with no command_id is the auto-update shape, so the id can no
+        // longer be what proves the file is one of ours — from_version is.
+        return parsed && typeof parsed.from_version === 'string' ? parsed : null;
     }
     catch {
         return null;
     }
 }
+/** One `npm i -g` attempt. Resolves the failure reason, or null on success. */
+function npmInstallAttempt(spec, prefix, timeoutMs) {
+    const args = ['i', '-g', ...(prefix ? ['--prefix', prefix] : []), spec];
+    const inv = (0, win_1.resolveCliInvocation)('npm', args);
+    return new Promise((resolve) => {
+        let log = '';
+        let settled = false;
+        const done = (err) => { if (!settled) {
+            settled = true;
+            resolve({ err, log });
+        } };
+        try {
+            const child = (0, child_process_1.spawn)(inv.file, inv.args, { windowsHide: true, env: process.env });
+            const timer = setTimeout(() => { try {
+                child.kill('SIGKILL');
+            }
+            catch { /* gone */ } done(`npm i -g ${spec} timed out`); }, timeoutMs);
+            timer.unref?.();
+            child.stdout?.on('data', b => { log += b.toString('utf8'); });
+            child.stderr?.on('data', b => { log += b.toString('utf8'); });
+            child.on('error', err => { clearTimeout(timer); done(`npm i -g failed to start: ${err.message}`); });
+            child.on('exit', code => {
+                clearTimeout(timer);
+                done(code === 0 ? null : `npm i -g ${spec} exited ${code}: ${log.trim().slice(-400)}`);
+            });
+        }
+        catch (err) {
+            done(`npm i -g failed to start: ${err.message}`);
+        }
+    });
+}
 /**
- * `npm i -g <pkg>@<version>`. Returns null on success, else the reason.
+ * `npm i -g <spec>` for any package. Returns null on success, else the reason.
  * Never throws — a failed install must leave the CURRENT daemon running
  * rather than take the node down.
+ *
+ * On a classic Mac with a root-owned /usr/local prefix the first attempt dies
+ * EACCES, so we retry into the daemon's own prefix — the same fallback
+ * command-runner's interactive install uses, and the same one the binary
+ * finders already search. Without it, auto-update would fail silently forever
+ * on exactly the nodes that needed a human least.
  */
+async function npmInstallGlobal(spec, timeoutMs = 5 * 60_000) {
+    const first = await npmInstallAttempt(spec, null, timeoutMs);
+    if (!first.err)
+        return null;
+    if (!/EACCES/.test(first.log))
+        return first.err;
+    const toolsPrefix = path.join(paths_1.RUNTIME_HOME, 'tools');
+    try {
+        fs.mkdirSync(toolsPrefix, { recursive: true });
+    }
+    catch { /* the spawn will surface it */ }
+    const retry = await npmInstallAttempt(spec, toolsPrefix, timeoutMs);
+    return retry.err;
+}
+/** `npm i -g @addai/node@<version>`. Thin wrapper kept for the roll paths. */
 async function installGlobal(targetVersion, timeoutMs = 5 * 60_000) {
-    const spec = `${exports.PACKAGE_NAME}@${targetVersion || 'latest'}`;
-    const inv = (0, win_1.resolveCliInvocation)('npm', ['i', '-g', spec]);
+    return npmInstallGlobal(`${exports.PACKAGE_NAME}@${targetVersion || 'latest'}`, timeoutMs);
+}
+/**
+ * What npm currently calls `latest` for a package, or null if we couldn't ask.
+ *
+ * Null is deliberately NOT treated as "up to date" by callers — it means the
+ * question went unanswered (offline, registry blip), and an unanswered
+ * question must never masquerade as a clean bill of health.
+ */
+function npmLatestVersion(pkg, timeoutMs = 60_000) {
+    const inv = (0, win_1.resolveCliInvocation)('npm', ['view', pkg, 'version']);
     return new Promise((resolve) => {
-        let stderr = '';
+        let out = '';
         let settled = false;
         const done = (v) => { if (!settled) {
             settled = true;
@@ -176,17 +268,18 @@ async function installGlobal(targetVersion, timeoutMs = 5 * 60_000) {
             const timer = setTimeout(() => { try {
                 child.kill('SIGKILL');
             }
-            catch { /* gone */ } done(`npm i -g ${spec} timed out`); }, timeoutMs);
+            catch { /* gone */ } done(null); }, timeoutMs);
             timer.unref?.();
-            child.stderr?.on('data', b => { stderr += b.toString('utf8'); });
-            child.on('error', err => { clearTimeout(timer); done(`npm i -g failed to start: ${err.message}`); });
+            child.stdout?.on('data', b => { out += b.toString('utf8'); });
+            child.on('error', () => { clearTimeout(timer); done(null); });
             child.on('exit', code => {
                 clearTimeout(timer);
-                done(code === 0 ? null : `npm i -g ${spec} exited ${code}: ${stderr.trim().slice(-400)}`);
+                const v = out.trim();
+                done(code === 0 && /^\d+\.\d+\.\d+/.test(v) ? v : null);
             });
         }
-        catch (err) {
-            done(`npm i -g failed to start: ${err.message}`);
+        catch {
+            done(null);
         }
     });
 }

package/dist/store.d.ts

@@ -1,5 +1,8 @@
 import type { RuntimePairingState } from './types';
 export declare function readPairing(): RuntimePairingState | null;
 export declare function writePairing(state: RuntimePairingState): void;
-export declare function clearPairing(): void;
+export declare function clearPairing(opts?: {
+    stateFile?: string;
+    legacy?: string;
+}): void;
 export declare function isPaired(): boolean;

package/dist/store.js

@@ -43,6 +43,7 @@ exports.writePairing = writePairing;
 exports.clearPairing = clearPairing;
 exports.isPaired = isPaired;
 const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const paths_1 = require("./paths");
 const win_1 = require("./win");
 function ensureHome() {
@@ -71,11 +72,30 @@ function writePairing(state) {
     // rename-over-open-file fails EPERM/EBUSY on Windows — retried there.
     (0, win_1.safeRenameSync)(tmp, paths_1.RUNTIME_STATE_FILE);
 }
-function clearPairing() {
+// `opts` exists so this is testable without touching the real home — same
+// injection migrateLegacyStateDir takes, for the same reason.
+function clearPairing(opts = {}) {
+    const stateFile = opts.stateFile ?? paths_1.RUNTIME_STATE_FILE;
+    const legacy = opts.legacy ?? paths_1.LEGACY_RUNTIME_HOME;
     try {
-        fs.unlinkSync(paths_1.RUNTIME_STATE_FILE);
+        fs.unlinkSync(stateFile);
     }
     catch { /* already gone */ }
+    // The legacy home too. state-migrate COPIES ~/.entities-runtime/state.json
+    // into the new home rather than moving it, so the old file outlives the
+    // rename on purpose — but nothing ever cleaned it up, and the migration
+    // only skips when the new home already has a state.json. Deleting just the
+    // new copy therefore didn't unpair anything: the next start copied the old
+    // token straight back in, the daemon believed it was already paired (so an
+    // explicit `ainode entities <CODE>` never ran the pairing flow at all), the
+    // server rejected the dead token, and it cleared state again. That loop
+    // survived three releases on a real machine before we found it.
+    //
+    // Unpairing means unpaired. Both copies go.
+    try {
+        fs.unlinkSync(path.join(legacy, 'state.json'));
+    }
+    catch { /* no legacy home, or already gone */ }
 }
 function isPaired() {
     return readPairing() !== null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@addai/node",
-  "version": "0.11.3",
+  "version": "0.13.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": [
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "node-pty": "^1.1.0",
-    "ws": "^8.21.1"
+    "ws": "^8.21.3"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",