@selvajs/cli 4.8.0-beta.10 → 4.8.0-beta.11

package/src/commands/doctor.js

@@ -2,8 +2,8 @@
 // Node engine, boot persistence. Yellow warnings don't fail, red failures exit 1.
 //
 // Read-only by default. `--fix` applies the repairs attached to individual
-// checks, each behind its own confirmation — and only those needing no root and
-// no runtime restart. See `applyFixes`.
+// checks, each behind its own confirmation — only fixes needing no root and
+// no runtime restart exist. See applyFixes.
 
 import {
 	existsSync,
@@ -23,6 +23,7 @@ import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 import { satisfiesNodeRange } from '../node-range.js';
 import { green, yellow, red, fixable } from '../checks/result.js';
 import { checkBootPersistence } from '../checks/boot.js';
+import { checkRuntimeEnvironment } from '../checks/runtime.js';
 import {
 	checkDeprecatedEnv,
 	checkOrigin,
@@ -73,6 +74,7 @@ export async function runDoctor(argv = []) {
 	checks.push(checkPackage(dir, '@selvajs/selva'));
 	checks.push(checkNodeEngine(dir));
 	checks.push(checkCliRuntimeAlignment(dir));
+	checks.push(...checkRuntimeEnvironment(dir));
 	checks.push(...checkBootPersistence(dir));
 	checks.push(checkOrigin(env));
 	checks.push(...checkDeprecatedEnv(env));
@@ -105,15 +107,9 @@ export async function runDoctor(argv = []) {
 	}
 }
 
-/**
- * Apply the repairs attached to failing checks, each behind its own
- * confirmation. Returns the updated failure count.
- *
- * Nothing here needs root: anything privileged (the systemd unit) or that would
- * restart this process (a Node upgrade) stays a printed instruction, because a
- * fixer that dies halfway through its own runtime leaves the operator with no
- * obvious path back.
- */
+// Anything privileged (the systemd unit) or that would restart this process
+// (a Node upgrade) stays a printed instruction instead of a fixer — one that
+// dies halfway through its own runtime leaves the operator with no way back.
 async function applyFixes(resolved, failures) {
 	const repairs = resolved.filter((c) => c.fix && c.severity !== 'green');
 	if (repairs.length === 0) {
@@ -183,8 +179,7 @@ async function checkSupabase(env) {
 		return red(`SUPABASE_URL="${env.SUPABASE_URL}" is not a valid URL`);
 	}
 
-	// Ping the Supabase health endpoint. Soft-fail to yellow on network
-	// errors — operators may be offline at install time.
+	// Network errors go yellow, not red — operators may be offline at install time.
 	try {
 		const controller = new AbortController();
 		const timer = setTimeout(() => controller.abort(), 4000);
@@ -199,11 +194,10 @@ async function checkSupabase(env) {
 	}
 }
 
-// App↔DB schema handshake (audit O3). Expected head = newest migration shipped
-// by the installed @selvajs/supabase-provider; actual = what the database
-// reports via the selva.migration_head() RPC. Red on skew — the app degrades
-// /api/health to 503 at boot in the same state, so catching it here saves a
-// confusing deploy.
+// Compares the newest migration shipped by @selvajs/supabase-provider against
+// what the database reports via selva.migration_head(). Red on skew — the app
+// degrades /api/health to 503 at boot in the same state, so catching it here
+// saves a confusing deploy.
 async function checkSupabaseMigrations(dir, env) {
 	if (!env.SUPABASE_URL || !env.SUPABASE_SERVICE_ROLE_KEY) {
 		return yellow('Migration-head check skipped — Supabase env incomplete');
@@ -264,6 +258,7 @@ async function checkSupabaseMigrations(dir, env) {
 				`Database reports no applied migrations (expected head ${expected}). Sync + run: npx supabase db push`
 			);
 		}
+		// String comparison — relies on both heads being fixed-width, zero-padded timestamps.
 		if (actual < expected) {
 			return red(
 				`Database migration head ${actual} is behind the installed provider (${expected}). Sync + run: npx supabase db push`
@@ -271,7 +266,6 @@ async function checkSupabaseMigrations(dir, env) {
 		}
 		return green(`Database migration head ${actual} matches the installed provider`);
 	} catch (err) {
-		// Soft-fail on network errors, same as checkSupabase.
 		return yellow(`Migration-head check skipped (${err.message ?? err})`);
 	}
 }
@@ -295,7 +289,7 @@ function majorOf(version) {
 	return m ? Number(m[1]) : null;
 }
 
-// CLI and runtime release together (fixed group); major skew = stale CLI pin.
+// CLI and runtime release as a fixed group; major-version skew means a stale CLI pin.
 function checkCliRuntimeAlignment(dir) {
 	const here = dirname(fileURLToPath(import.meta.url));
 	const cliVersion = readPackageVersion(join(here, '..', '..', 'package.json'));
@@ -303,7 +297,7 @@ function checkCliRuntimeAlignment(dir) {
 		join(dir, 'node_modules', '@selvajs', 'selva', 'package.json')
 	);
 
-	// Runtime missing is already reported red by checkPackage; stay quiet here.
+	// checkPackage already reports missing runtime as red; stay quiet here.
 	if (!runtimeVersion) return yellow('CLI/runtime version check skipped (runtime not installed)');
 	if (!cliVersion) return yellow('CLI/runtime version check skipped (could not read CLI version)');
 
@@ -324,16 +318,10 @@ function checkCliRuntimeAlignment(dir) {
 	);
 }
 
-// Verify VM reboot will resurrect app: dump.pm2 saved, systemd unit installed, no stray global pm2.
-/**
- * Does this host's Node satisfy the installed runtime's `engines.node`?
- *
- * npm only enforces engines under `engine-strict=true`, which no deployment
- * sets, so a mismatched install succeeds silently and `/api/health` still
- * returns 200 — routes using newer APIs throw only under real traffic
- * (issue #176). Deliberately NOT auto-fixable: upgrading Node is
- * distro-specific and would restart the process running this check.
- */
+// npm only enforces engines.node under engine-strict=true, which no deployment
+// sets, so a mismatched install succeeds silently and /api/health still returns
+// 200 — routes using newer APIs throw only under real traffic. Not auto-fixable:
+// upgrading Node is distro-specific and would restart the process running this check.
 function checkNodeEngine(dir) {
 	let required;
 	try {
@@ -363,12 +351,10 @@ function checkNodeEngine(dir) {
 	);
 }
 
-/**
- * `selva migrate` parks the old node_modules aside so a failed install can be
- * rolled back, and removes it on either outcome. One surviving here means the
- * migration was killed mid-flight — worth saying, because it is a full copy of
- * the dependency tree and the deployment may be running on the wrong one.
- */
+// `selva migrate` parks the old node_modules aside so a failed install can be
+// rolled back, and removes it on either outcome. One surviving here means the
+// migration was killed mid-flight — worth flagging since it's a full copy of
+// the dependency tree and the deployment may be running on the wrong one.
 function checkMigrationLeftovers(dir) {
 	const stash = join(dir, NODE_MODULES_STASH);
 	if (!existsSync(stash)) return green('no interrupted migration left behind');
@@ -403,19 +389,18 @@ function checkLayoutDrift(dir) {
 	);
 }
 
-// Must match HeaderAuthProvider.DEFAULT_HEADERS (duplicated to avoid loading runtime).
-// Smoke test in providers/header-auth pins them; divergence surfaces in CI.
+// Duplicated from HeaderAuthProvider.DEFAULT_HEADERS to avoid loading the runtime here.
+// A test in providers/header-auth pins both sides, so drift surfaces in CI.
 const DEFAULT_HEADER_NAMES = {
 	upn: 'SELVA-UserPrincipalName',
 	email: 'SELVA-Email',
 	displayName: 'SELVA-DisplayName'
 };
 
-// Header-auth checks (read-only; runtime invariants like spoofing can't be verified).
+// Static config only — runtime invariants like spoofing protection can't be checked from here.
 function checkHeaderAuth(dir, env, dataProvider) {
 	const out = [];
 
-	// Allowlist file location.
 	const allowlistDir = env.HEADER_AUTH_DATA_DIR ?? env.DATA_PATH;
 	if (!allowlistDir) {
 		out.push(red('HEADER_AUTH_DATA_DIR (or DATA_PATH) unset — provider will fail to start'));
@@ -425,21 +410,21 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		if (existsSync(allowlistPath)) {
 			out.push(green(`header-allowlist.json present (${allowlistDir}/header-allowlist.json)`));
 		} else {
-			// Provider creates lazily, but missing file locks everyone out.
+			// The provider creates this file lazily, but a missing file locks everyone out
+			// until one exists — worth a warning even though nothing is technically broken.
 			out.push(
 				yellow(
 					`header-allowlist.json not found at ${allowlistDir}/ — no users will be allowed in until one is added`
 				)
 			);
 
-			// Check writability only if explicitly set (DATA_PATH checked separately).
+			// DATA_PATH's own writability is checked separately (checkDataPath).
 			if (env.HEADER_AUTH_DATA_DIR) {
 				out.push(checkDirWritable(allowlistAbsDir, `HEADER_AUTH_DATA_DIR=${allowlistDir}`));
 			}
 		}
 	}
 
-	// HOST binding (loopback recommended for header-auth).
 	const host = env.HOST ?? '0.0.0.0';
 	if (host === '127.0.0.1' || host === 'localhost') {
 		out.push(green(`HOST=${host} (loopback-only)`));
@@ -452,12 +437,11 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		);
 	}
 
-	// 3. ORIGIN — header-auth implies a reverse proxy, so ORIGIN is required.
+	// header-auth always sits behind a reverse proxy, so ORIGIN is required.
 	if (!env.ORIGIN) {
 		out.push(red('ORIGIN unset — required for header-auth (always behind a proxy)'));
 	}
 
-	// Non-local data provider: HEADER_AUTH_DATA_DIR must be explicit (no DATA_PATH fallback).
 	if (dataProvider !== 'local' && !env.HEADER_AUTH_DATA_DIR) {
 		out.push(
 			red(
@@ -467,10 +451,10 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		);
 	}
 
-	// 5. Bootstrap admin email. Without it, the first proxy-authenticated
-	// visitor's UPN is rejected (not in allowlist) and the operator has to
-	// hand-write JSON to claim admin. With it, the first matching visit is
-	// auto-allowlisted and granted instance_admin in one step.
+	// Without this, the first proxy-authenticated visitor's UPN is rejected
+	// (not in the allowlist) and the operator has to hand-write JSON to claim
+	// admin. With it, the first matching visit auto-allowlists and grants
+	// instance_admin in one step.
 	if (!env.BOOTSTRAP_INSTANCE_ADMIN_EMAIL) {
 		out.push(
 			red(
@@ -482,7 +466,6 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		out.push(green(`BOOTSTRAP_INSTANCE_ADMIN_EMAIL=${env.BOOTSTRAP_INSTANCE_ADMIN_EMAIL}`));
 	}
 
-	// Resolved header names (print for diffing against proxy config; partial override = typo risk).
 	const resolved = {
 		upn: env.HEADER_AUTH_UPN_HEADER || DEFAULT_HEADER_NAMES.upn,
 		email: env.HEADER_AUTH_EMAIL_HEADER || DEFAULT_HEADER_NAMES.email,

package/src/commands/init.js

@@ -1,11 +1,6 @@
-// `selva init` — reconfigure an existing deployment.
-//
-// Differences from `create`:
-//   • Reads current .env values; uses them as prompt defaults.
-//   • Never regenerates SELVA_HMAC_KEY / SELVA_AT_REST_KEY if they're set.
-//     Rotating those invalidates sessions and at-rest encryption — that's
-//     `selva keys rotate`'s job, not init's.
-//   • Doesn't touch package.json or run npm install.
+// `selva init` — reconfigures an existing deployment. Unlike `create`, it reads
+// the current .env as prompt defaults and never touches package.json or runs
+// npm install.
 
 import { join } from 'node:path';
 import * as p from '@clack/prompts';
@@ -23,10 +18,10 @@ export async function runInit() {
 	const current = readEnvFile(envPath);
 	const values = await collectConfig({ defaults: current, mode: 'init' });
 
-	// Preserve secrets. The only safe time to generate them is at install
-	// time (no sessions to invalidate, no encrypted data to lose). If the
-	// existing .env doesn't have them — which can happen if a previous
-	// scaffold bailed mid-flight — generate now and warn.
+	// Never regenerate an existing key: rotating SELVA_HMAC_KEY or
+	// SELVA_AT_REST_KEY invalidates sessions and at-rest encryption — that's
+	// `selva keys rotate`'s job, not init's. Missing keys (a scaffold that
+	// bailed mid-flight) are the one case it's safe to generate here.
 	if (
 		current.SELVA_HMAC_KEY &&
 		current.SELVA_HMAC_KEY !== 'replace-this-with-a-random-32-byte-hex-key'

package/src/commands/migrate.js

@@ -1,5 +1,5 @@
-// Migrate deployment to current layout: rewrite package.json (drop legacy
-// provider packages), remove stale selva.config.js, update ecosystem.config.cjs.
+// Migrates a deployment to the current layout: rewrites package.json (drops legacy
+// provider packages), removes stale selva.config.js, updates ecosystem.config.cjs.
 // Idempotent; mirrors update's lifecycle (stop/mutate/start with rollback on failure).
 
 import { existsSync, readFileSync, writeFileSync, copyFileSync, rmSync, renameSync } from 'node:fs';
@@ -13,29 +13,25 @@ import {
 	buildDeploymentPackageJson,
 	CANONICAL_FIELDS,
 	DEPENDENCIES,
-	LEGACY_DEPENDENCIES
+	LEGACY_DEPENDENCIES,
+	OVERRIDES
 } from '../deployment-package.js';
 import { APP_NAME, runPm2 } from './pm2.js';
 
-/**
- * Where `migrate` parks the old node_modules while npm installs the new one.
- * Left behind only if the process is killed mid-migration — `detectDrift`
- * reports it, because a stray copy of the dependency tree is both confusing and
- * large enough to matter on a small VM.
- */
+// Where migrate parks the old node_modules while npm installs the new one.
+// Left behind only if the process is killed mid-migration; `selva doctor`
+// flags a surviving stash as an interrupted migration.
 export const NODE_MODULES_STASH = 'node_modules.selva-migrate-bak';
 
-/**
- * @param {object} [deps] Seams for tests. The rollback path destroys and
- *   restores a real dependency tree, so it has to be exercised against a real
- *   directory — but not against a real npm or a real pm2 daemon.
- */
+// `deps` are seams for tests: the rollback path destroys and restores a real
+// dependency tree, so it has to run against a real directory — but not against
+// a real npm or pm2 daemon.
 export async function runMigrate(
 	_argv,
 	{
 		dir: injectedDir,
-		// --prefer-online bypasses the stale-packument trap: npm can otherwise
-		// resolve a cached packument that predates the release being migrated to.
+		// --prefer-online: npm can otherwise resolve a cached packument that
+		// predates the release being migrated to.
 		install = (cwd) => execSync('npm install --prefer-online', { cwd, stdio: 'pipe' }),
 		confirm = (message) => p.confirm({ message, initialValue: true }),
 		pm2 = runPm2
@@ -56,8 +52,6 @@ export async function runMigrate(
 	const target = buildTargetPackageJson(before);
 	const pkgDiff = diffPackageJson(before, target);
 
-	// Side-files: selva.config.js (now unused) and ecosystem.config.cjs
-	// (must point at @selvajs/selva, not @selvajs/runtime).
 	const configPath = join(dir, 'selva.config.js');
 	const hasStaleConfig = existsSync(configPath);
 
@@ -65,9 +59,9 @@ export async function runMigrate(
 	const ecoHasStaleRuntime =
 		existsSync(ecoPath) && readFileSync(ecoPath, 'utf8').includes('@selvajs/runtime');
 
-	// Deprecated env keys. The server reads the old names for one more minor
-	// version, so this is a warning today and a silent fallback to defaults once
-	// that shim goes — rewriting now is what keeps a tuned value tuned.
+	// The server drops its read-old-name shim after one minor version, so
+	// rewriting now is what keeps a tuned value tuned instead of silently
+	// reverting to defaults later.
 	const envPath = join(dir, '.env');
 	const envBefore = existsSync(envPath) ? readFileSync(envPath, 'utf8') : null;
 	const envRename = envBefore
@@ -106,9 +100,10 @@ export async function runMigrate(
 		return;
 	}
 
-	// Stop pm2 before npm rewrites (SvelteKit lazy-loads chunks; see update command).
+	// Stop pm2 before npm rewrites — SvelteKit lazy-loads chunks, so a rewrite
+	// under a running server serves a broken page (same reason `update` stops first).
 	// A legacy deployment may predate the local-pm2 layout, so a missing binary
-	// is not fatal here — there is nothing running for us to stop.
+	// isn't fatal here: there's nothing running for us to stop.
 	try {
 		const stopStatus = pm2(dir, ['stop', APP_NAME], { inherit: false });
 		if (stopStatus !== 0) {
@@ -118,7 +113,6 @@ export async function runMigrate(
 		p.log.warn('No deployment-local pm2 to stop — continuing.');
 	}
 
-	// Back up for rollback on npm-install failure.
 	const bakPath = pkgPath + '.bak';
 	copyFileSync(pkgPath, bakPath);
 	writeFileSync(pkgPath, JSON.stringify(target, null, 2) + '\n', 'utf8');
@@ -130,7 +124,7 @@ export async function runMigrate(
 
 	if (ecoHasStaleRuntime) {
 		copyFileSync(ecoPath, ecoPath + '.bak');
-		// Rewrite @selvajs/runtime → @selvajs/selva only (preserve customizations).
+		// Text substitution, not regeneration, so any operator customizations to the file survive.
 		const ecoContent = readFileSync(ecoPath, 'utf8').replace(
 			/@selvajs\/runtime/g,
 			'@selvajs/selva'
@@ -143,11 +137,11 @@ export async function runMigrate(
 		writeFileSync(envPath, envRename.text, 'utf8');
 	}
 
-	// A clean install is required — a legacy lockfile pins the old package set
-	// across a major bump. But node_modules is also where pm2 lives, and the
-	// rollback below has to restart the app, so deleting it outright leaves a
-	// failed migration with no way back up. Rename instead: atomic, keeps the
-	// .bin symlinks intact, and restorable until the install succeeds.
+	// A legacy lockfile pins the old package set across a major bump, so this needs
+	// a clean install. But node_modules is also where pm2 lives, and rollback has to
+	// restart the app — deleting it outright would leave a failed migration with no
+	// way back up. Rename instead: atomic, keeps .bin symlinks intact, restorable
+	// until the install succeeds.
 	const nodeModules = join(dir, 'node_modules');
 	const nodeModulesBak = join(dir, NODE_MODULES_STASH);
 	const lockPath = join(dir, 'package-lock.json');
@@ -176,8 +170,8 @@ export async function runMigrate(
 			copyFileSync(envPath + '.bak', envPath);
 		}
 
-		// Restore the dependency tree the app was running on. A half-installed
-		// node_modules from the failed attempt is worse than the old one.
+		// A half-installed node_modules from the failed attempt is worse than the old
+		// one, so clear it before restoring the stash.
 		rmSync(nodeModules, { recursive: true, force: true });
 		if (existsSync(nodeModulesBak)) renameSync(nodeModulesBak, nodeModules);
 		if (lockBak !== null) writeFileSync(lockPath, lockBak, 'utf8');
@@ -187,6 +181,10 @@ export async function runMigrate(
 		process.exit(1);
 	}
 
+	// Migration itself already succeeded at this point, so a failed pm2 start is reported
+	// but doesn't exit non-zero or trigger rollback — the on-disk state is fine, only the
+	// running process isn't. Contrast restartAfterRollback, which does exit 1: that path
+	// runs after a rollback, where a failed restart leaves nothing serving traffic at all.
 	let status;
 	try {
 		status = pm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
@@ -194,6 +192,16 @@ export async function runMigrate(
 		status = 1;
 		p.log.error(`Could not invoke pm2: ${err instanceof Error ? err.message : err}`);
 	}
+	// A pin change means the just-installed pm2 CLI and the still-running
+	// daemon are now different versions. That's the repairable skew direction
+	// (daemon older), but it stays skewed until the operator acts — say so
+	// here, once, instead of letting doctor nag forever. Deliberately NOT
+	// automated: `pm2 update` recycles the daemon, and doing that unattended
+	// inside a migration converts a mid-flight failure into an outage (see
+	// plans/fixes/host-prerequisites-and-pm2-audit.md).
+	const pm2Notice = buildPm2UpgradeNotice(before.dependencies?.pm2, target.dependencies.pm2);
+	if (pm2Notice) p.log.warn(pm2Notice);
+
 	const backupHints = ['package.json.bak'];
 	if (hasStaleConfig) backupHints.push('selva.config.js.bak');
 	if (ecoHasStaleRuntime) backupHints.push('ecosystem.config.cjs.bak');
@@ -212,14 +220,9 @@ export async function runMigrate(
 	}
 }
 
-/**
- * Bring the app back up after a failed migration.
- *
- * Never throws: the migration is already aborting, and an exception here would
- * replace the rollback's diagnosis with a stack trace. A failure to restart is
- * the operator's problem to act on, so it must be stated, not swallowed — the
- * old code returned a bare 1 and printed nothing.
- */
+// Never throws: the migration is already aborting, and an exception here would
+// replace the rollback's diagnosis with a stack trace. A failure to restart is
+// the operator's problem to act on, so it gets logged, not swallowed.
 function restartAfterRollback(dir, pm2 = runPm2) {
 	try {
 		const status = pm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
@@ -263,6 +266,19 @@ function diffPackageJson(before, after) {
 		else if (a !== b) lines.push(`${pc.yellow('~')} ${name} ${pc.dim(a + ' → ' + b)}`);
 	}
 
+	// Without this section, an overrides-only change reads as "already on the
+	// current layout" and the security shim never reaches existing deployments.
+	const beforeOverrides = before.overrides ?? {};
+	const afterOverrides = after.overrides ?? {};
+	const allOverrides = new Set([...Object.keys(beforeOverrides), ...Object.keys(afterOverrides)]);
+	for (const name of [...allOverrides].sort()) {
+		const a = beforeOverrides[name];
+		const b = afterOverrides[name];
+		if (a && !b) lines.push(`${pc.red('-')} overrides.${name} ${pc.dim(a)}`);
+		else if (!a && b) lines.push(`${pc.green('+')} overrides.${name} ${pc.dim(b)}`);
+		else if (a !== b) lines.push(`${pc.yellow('~')} overrides.${name} ${pc.dim(a + ' → ' + b)}`);
+	}
+
 	const beforeScripts = before.scripts ?? {};
 	const afterScripts = after.scripts ?? {};
 	const allScripts = new Set([...Object.keys(beforeScripts), ...Object.keys(afterScripts)]);
@@ -276,9 +292,9 @@ function diffPackageJson(before, after) {
 		}
 	}
 
-	// Anything outside the canonical set is discarded by the rewrite.
-	// devDependencies and description used to vanish without appearing here, so
-	// the operator confirmed a change they were never shown.
+	// Anything outside the canonical set is discarded by the rewrite — show it here
+	// too, or the operator confirms a change (e.g. losing devDependencies) they
+	// never saw.
 	for (const key of Object.keys(before).sort()) {
 		if (CANONICAL_FIELDS.has(key)) continue;
 		lines.push(`${pc.red('-')} ${key} ${pc.dim(summarize(before[key]))}`);
@@ -307,6 +323,23 @@ export function detectDrift(pkgJson, dir) {
 		if (!deps[name]) reasons.push(`${name} is missing`);
 	}
 
+	// pm2 is the one dependency pinned exactly, so a version difference is drift
+	// rather than an operator preference. Presence alone was checked above and
+	// isn't enough: a deployment scaffolded against an older CLI keeps its old
+	// pm2 forever, which is how the pin reached a two-major gap unnoticed.
+	if (deps.pm2 && deps.pm2 !== DEPENDENCIES.pm2) {
+		reasons.push(`pm2 is pinned to ${deps.pm2} (current scaffold pins ${DEPENDENCIES.pm2})`);
+	}
+
+	// Overrides are security shims for vulnerable transitive deps — a
+	// deployment without them installs the vulnerable version on its next
+	// `npm install`, silently.
+	for (const [name, version] of Object.entries(OVERRIDES)) {
+		if (pkgJson?.overrides?.[name] !== version) {
+			reasons.push(`overrides.${name} is missing or outdated (security shim, expects ${version})`);
+		}
+	}
+
 	if (dir) {
 		const configPath = join(dir, 'selva.config.js');
 		if (existsSync(configPath)) {
@@ -328,4 +361,20 @@ export function detectDrift(pkgJson, dir) {
 	return reasons;
 }
 
+// Null when the pin didn't change. Exported for its test — the wording is the
+// operator's only pointer to finish the upgrade.
+export function buildPm2UpgradeNotice(beforeVersion, afterVersion) {
+	if (!beforeVersion || beforeVersion === afterVersion) return null;
+	return [
+		`pm2 was upgraded ${beforeVersion} → ${afterVersion}, but the running pm2 daemon is`,
+		`still the old version. Finish the upgrade (brief restart of managed processes):`,
+		``,
+		`  npx pm2 update`,
+		`  npx pm2 save`,
+		``,
+		`If doctor reports a pm2 outside this deployment (global or apt install), follow`,
+		`the full procedure in the docs instead: self-hosting → deployment → prerequisites.`
+	].join('\n');
+}
+
 export { buildTargetPackageJson, diffPackageJson };

package/src/commands/pm2.js

@@ -1,6 +1,6 @@
-// Thin wrappers around PM2 commands: always pass --update-env (ignore edits),
-// resolve to deployment-local pm2 (avoid daemon version skew with global install),
-// and resync daemon before state changes.
+// Thin wrappers around PM2 commands: resolve to the deployment-local pm2, resync
+// the daemon before state changes, and pass --update-env on restart so edits to
+// .env actually take effect.
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -11,7 +11,6 @@ import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 
 export const APP_NAME = 'selva-compute';
 
-// Resolve to deployment-local pm2 (no global fallback; prevents version skew).
 export function pm2Bin(dir) {
 	const local = join(dir, 'node_modules', '.bin', process.platform === 'win32' ? 'pm2.cmd' : 'pm2');
 	if (!existsSync(local)) {
@@ -25,11 +24,10 @@ export function pm2Bin(dir) {
 	return local;
 }
 
-// Parse the two versions pm2 prints alongside its out-of-date warning:
+// Parses the two versions pm2 prints alongside its out-of-date warning:
 //   In memory PM2 version: 6.0.14
 //   Local PM2 version: 5.4.3
-// Returns nulls when the shape changes — callers then fall back to resyncing,
-// which is the pre-existing behaviour.
+// Returns nulls when the shape doesn't match, so callers fall back to resyncing.
 export function parsePm2Skew(output) {
 	// eslint-disable-next-line no-control-regex -- pm2 colourises via chalk on a TTY
 	const clean = output.replace(/\[[0-9;]*m/g, '');
@@ -38,12 +36,10 @@ export function parsePm2Skew(output) {
 	return { daemon: daemon?.[1] ?? null, local: local?.[1] ?? null };
 }
 
-/**
- * True when the running daemon is newer than the deployment-local pm2 — i.e. a
- * foreign global pm2 owns it. `pm2 update` cannot fix that direction: it
- * downgrades the daemon and hands it a dump from a newer version, which drops
- * the process table so selva-compute is never re-registered (issue #118).
- */
+// True when the running daemon is newer than the deployment-local pm2 — i.e. a
+// foreign global pm2 owns it. `pm2 update` can't fix that direction: it would
+// downgrade the daemon and hand it a dump from a newer version, dropping the
+// process table so selva-compute never gets re-registered.
 export function daemonOutranksCli(daemon, local) {
 	if (!daemon || !local) return false;
 	const [a, b] = [daemon.split('.').map(Number), local.split('.').map(Number)];
@@ -54,7 +50,6 @@ export function daemonOutranksCli(daemon, local) {
 	return false;
 }
 
-// Check for daemon/CLI version mismatch; run `pm2 update` only when it can help.
 function ensurePm2InSync(dir) {
 	const bin = pm2Bin(dir);
 	const probe = spawnSync(bin, ['ping'], {
@@ -92,13 +87,9 @@ function ensurePm2InSync(dir) {
 	}
 }
 
-/**
- * Run the deployment-local pm2.
- *
- * `bin` overrides where pm2 is resolved from — `selva migrate` wipes
- * node_modules mid-flight and passes the binary it stashed beforehand, because
- * resolving from the deployment at that moment would find nothing.
- */
+// `bin` lets a caller pass an already-resolved pm2 path instead of resolving
+// fresh from `dir` — needed when node_modules won't exist at call time (e.g.
+// `selva migrate` wipes it mid-flight and passes the binary it stashed first).
 export function runPm2(dir, args, { inherit = true, bin = pm2Bin(dir) } = {}) {
 	const result = spawnSync(bin, args, {
 		cwd: dir,