Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* "Does the running PM2 daemon still need a `pm2 update`?"
*
* `pm2 update` reloads the daemon in place — it kills the God process and
* resurrects everything from the dump. That refreshes the daemon's cached
* ProcessContainerFork.js path (a stale path from a daemon originally launched
* by another project — e.g. a Yarn PnP zip cache — makes every subsequent
* fork() crash with MODULE_NOT_FOUND), but it also RESTARTS every co-located
* app on the machine. PortOS shares one PM2 daemon with whatever else the user
* runs, so paying that cost on every self-update interrupts unrelated projects
* for a refresh they almost never need.
*
* They need it only when the live daemon is not the one this checkout's
* node_modules would launch: a different install path, or a different pm2
* version. This probe answers that question so update.sh / update.ps1 can run
* `pm2 update` in exactly that case and leave the daemon alone otherwise.
*
* Usage as a CLI (what update.sh and update.ps1 call):
* node scripts/pm2-daemon-refresh.js
*
* Exit 0 → refresh needed, run `pm2 update`.
* Exit 1 → daemon already matches this checkout, skip it.
*
* Fails OPEN: anything unexpected (no report, an RPC error, an unrecognized
* argv shape) exits 0 and restores the unconditional behavior. A needless
* daemon reload is an annoyance; skipping a needed one leaves PortOS unable to
* fork a single app.
*/
import { readFileSync, realpathSync } from 'fs';
import { homedir } from 'os';
import { dirname, join } from 'path';
import { fileURLToPath } from 'url';
import { isDirectlyInvoked } from './lib/directInvocation.js';
const ROOT_DIR = join(dirname(fileURLToPath(import.meta.url)), '..');
// APFS and NTFS are case-insensitive, and the daemon's argv is whatever spelling
// launched it — realpath + case-fold so two spellings of one file compare equal.
const normalizePath = (path) => {
let resolved = path;
try {
resolved = realpathSync(path);
} catch {
// Path no longer exists (node_modules wiped since the daemon launched) —
// compare the literal spelling rather than giving up.
}
return process.platform === 'win32' || process.platform === 'darwin'
? resolved.toLowerCase()
: resolved;
};
/**
* The `lib/Daemon.js` entry out of the daemon's own process.argv.
* @param {string[]|string} argv - `report.argv` (array; string-joined on older daemons)
* @returns {string|null} the Daemon.js path, or null when argv has no recognizable entry
*/
export function daemonEntryFromArgv(argv) {
const parts = Array.isArray(argv) ? argv : typeof argv === 'string' ? argv.split(',') : [];
// Trim before matching AND return the trimmed value — a comma-joined argv leaves
// a leading space on every part after the first, and realpath() rejects ' /path',
// which would compare as a mismatch and force a needless daemon reload.
return parts.map((part) => String(part).trim()).find((part) => /Daemon\.js$/.test(part)) ?? null;
}
/**
* Whether the live daemon has to be reloaded to match this checkout.
* @param {object} options
* @param {object|null} options.report - the daemon's `getReport` payload
* @param {string} options.expectedEntry - path to this checkout's pm2 lib/Daemon.js
* @param {string} options.expectedVersion - this checkout's installed pm2 version
* @param {string|null} [options.expectedNodeVersion] - the Node PortOS is pinned
* to (`PORTOS_NODE_INTERPRETER`), or null to leave the daemon's Node alone
* @returns {{ needed: boolean, reason: string }}
*/
export function daemonNeedsRefresh({ report, expectedEntry, expectedVersion, expectedNodeVersion = null }) {
if (!report) return { needed: true, reason: 'daemon did not report its identity' };
const entry = daemonEntryFromArgv(report.argv);
if (!entry) return { needed: true, reason: 'daemon argv has no Daemon.js entry' };
if (normalizePath(entry) !== normalizePath(expectedEntry)) {
return { needed: true, reason: 'daemon runs from a different pm2 install' };
}
// A version mismatch means node_modules was upgraded under a daemon still
// executing the old code — the CLI would talk to a daemon it no longer matches.
if (report.pm2_version !== expectedVersion) {
return {
needed: true,
reason: `daemon is pm2 ${report.pm2_version}, this checkout has ${expectedVersion}`,
};
}
// Only a pinned install asks for this: an unpinned one never chose a Node, and
// reloading the shared daemon restarts every co-located app.
const daemonNode = report.node_version && report.node_version !== 'N/A' ? String(report.node_version) : null;
if (expectedNodeVersion && daemonNode && daemonNode !== expectedNodeVersion) {
return { needed: true, reason: `daemon runs Node ${daemonNode}, PortOS is pinned to ${expectedNodeVersion}` };
}
return { needed: false, reason: 'daemon already runs this checkout of pm2' };
}
// A wedged daemon must not hang the self-update: update.sh runs this inline with
// no timeout of its own, so an RPC that never answers would stall the whole
// update indefinitely. Bound it and let the caller's catch fail open instead.
const PROBE_TIMEOUT_MS = 15000;
const withTimeout = (promise, ms, label) => {
let timer;
return Promise.race([
promise.finally(() => clearTimeout(timer)),
new Promise((_, reject) => {
timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
}),
]);
};
async function fetchReport(pm2) {
await withTimeout(
new Promise((resolve, reject) => {
pm2.connect((err) => (err ? reject(err) : resolve()));
}),
PROBE_TIMEOUT_MS,
'pm2 connect',
);
try {
return await withTimeout(
new Promise((resolve, reject) => {
pm2.Client.executeRemote('getReport', {}, (err, report) => (err ? reject(err) : resolve(report)));
}),
PROBE_TIMEOUT_MS,
'pm2 getReport',
);
} finally {
pm2.disconnect();
}
}
/**
* Replace this install's own paths in a probe error before it is logged.
*
* A pm2 socket or package-read failure names absolute paths, and update.sh
* appends everything here to data/update.log — which backups sweep up. The
* repo-root and home substitutions keep the message diagnostic (which file,
* which errno) without carrying the OS username off the machine.
* @param {string} message
*/
export function redactPaths(message) {
const home = homedir();
return String(message ?? '')
// Repo root first — it lives under home, so the broader rule would eat it.
.split(ROOT_DIR)
.join('<repo>')
.split(home)
.join('~');
}
async function runCli() {
let verdict = { needed: true, reason: 'could not inspect the running daemon' };
try {
const pm2Dir = join(ROOT_DIR, 'node_modules', 'pm2');
const { default: pm2 } = await import('pm2');
verdict = daemonNeedsRefresh({
report: await fetchReport(pm2),
expectedEntry: join(pm2Dir, 'lib', 'Daemon.js'),
expectedVersion: JSON.parse(readFileSync(join(pm2Dir, 'package.json'), 'utf8')).version,
// launchUpdate exports the pin and puts its bin first on PATH, so this
// process already runs on the pinned Node.
expectedNodeVersion: process.env.PORTOS_NODE_INTERPRETER ? process.versions.node : null,
});
} catch (err) {
verdict = { needed: true, reason: `daemon probe failed: ${redactPaths(err.message)}` };
}
console.log(`${verdict.needed ? '🔄' : '✅'} PM2 daemon refresh ${verdict.needed ? 'needed' : 'skipped'}: ${verdict.reason}`);
return verdict.needed ? 0 : 1;
}
if (isDirectlyInvoked(import.meta.url)) process.exit(await runCli());