Skip to content

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

fix: refuse an unsupported Node runtime before the update moves the checkout (#11753)

[._.]/ Adam Eivyb3d947238171
diff --git a/docs/SELF_UPDATE.md b/docs/SELF_UPDATE.md
index 98a1c344a9..8a7254155c 100644
--- a/docs/SELF_UPDATE.md
+++ b/docs/SELF_UPDATE.md
@@ -49,6 +49,8 @@ submodule, so those changes remain a visible update blocker.
### Submodules follow the pulled parent revision
+**An unsupported Node.js runtime refuses the update before anything changes.** The target revision owns its Node support range, so after the dirty-tree and submodule checks and before the pull or ff-only merge, both scripts resolve the target (the fetched upstream, or `PORTOS_PEER_UPDATE_TARGET_SHA` on the peer path), extract its `scripts/checkNodeVersion.js` (plus `package.json` and `scripts/lib`) with `git archive` into a temporary directory, and run it with the installed Node. A rejection reports `runtime-preflight` as failed with the requirement and exits non-zero with HEAD, submodules, dependencies and PM2 apps untouched, so the running server never ends up as old code over a newer checkout. A target that predates the gate, or an unresolvable target, skips the pre-check; the post-pull gate stays as a second line of defence.
+
Before pulling, both platform scripts repair any recursive submodule checkout
that is not at the commit pinned by the current parent tree. After switching to
`main` they repeat that repair, then after pulling `main` both platform scripts
diff --git a/scripts/update-headless-recovery.test.js b/scripts/update-headless-recovery.test.js
index 6f0d5a171e..06ec4bee4b 100644
--- a/scripts/update-headless-recovery.test.js
+++ b/scripts/update-headless-recovery.test.js
@@ -36,7 +36,7 @@ const STUB_SCRIPTS = [
*/
async function makeSandbox({
origin = true, failAfterDelete = true, npmShim = 'ok',
- forceClean = false, pm2OnPath = false, healthy = true, stallDelete = false, nodeVersion = null
+ forceClean = false, pm2OnPath = false, healthy = true, stallDelete = false, nodeVersion = null, originAhead = false, peerTarget = false
} = {}) {
const { scratch, repo } = await makeGitSandbox({ origin, prefix: 'portos-update-guard-' });
const bin = join(scratch, 'bin');
@@ -129,7 +129,20 @@ if (${stallDelete} && args.startsWith('delete')) {
execFileSync('git', ['add', '.'], { cwd: repo });
execFileSync('git', ['commit', '-m', 'fixture'], { cwd: repo, stdio: 'ignore' });
- return { scratch, repo, bin, calls, forceClean, releaseFile, nodeOptions };
+ // Leave the upstream one commit ahead of the checkout, so the update has a real
+ // pull to perform and a refusal can be shown to have left HEAD where it was.
+ let aheadSha = null;
+ if (originAhead) {
+ writeFileSync(join(repo, 'ahead.txt'), 'ahead\n');
+ execFileSync('git', ['add', 'ahead.txt'], { cwd: repo });
+ execFileSync('git', ['commit', '-m', 'ahead'], { cwd: repo, stdio: 'ignore' });
+ aheadSha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8' }).trim();
+ execFileSync('git', ['push', 'origin', 'main'], { cwd: repo, stdio: 'ignore' });
+ execFileSync('git', ['reset', '--hard', 'HEAD~1'], { cwd: repo, stdio: 'ignore' });
+ }
+ const headSha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8' }).trim();
+
+ return { scratch, repo, bin, calls, forceClean, releaseFile, nodeOptions, headSha, aheadSha, peerTarget };
}
// The three runs share no state, so they go out concurrently rather than
@@ -139,6 +152,10 @@ function runUpdate(sandbox, { onStart } = {}) {
const env = { ...process.env, PATH: `${sandbox.bin}:${process.env.PATH}` };
if (sandbox.forceClean) env.PORTOS_FORCE_CLEAN_WORKSPACES = '.';
if (sandbox.nodeOptions) env.NODE_OPTIONS = sandbox.nodeOptions;
+ if (sandbox.peerTarget) {
+ env.PORTOS_PEER_UPDATE_TARGET_SHA = sandbox.aheadSha;
+ env.PORTOS_PEER_UPDATE_EXPECTED_SHA = sandbox.headSha;
+ }
const child = spawn('bash', [join(sandbox.repo, 'update.sh')], { cwd: sandbox.repo, env });
let stdout = '';
child.stdout.on('data', (d) => { stdout += d; });
@@ -177,6 +194,11 @@ describe.skipIf(process.platform === 'win32' || SKIP_HEAVY_INTEGRATION)('update.
unhealthy: { healthy: false },
// A target whose Node requirement the installed runtime no longer meets.
oldNode: { nodeVersion: '22.12.0' },
+ // Same, with a pull pending: the refusal must come before HEAD moves, on
+ // both the upstream and the peer-target (ff-only merge) paths.
+ oldNodeAhead: { nodeVersion: '22.12.0', origin: true, originAhead: true },
+ oldNodePeer: { nodeVersion: '22.12.0', origin: true, originAhead: true, peerTarget: true },
+ cleanAhead: { nodeVersion: null, failAfterDelete: false, origin: true, originAhead: true },
// The failure the guard's own comment names: both npm installs fail, and
// safe_install wiped root node_modules — pm2 included — on the way.
pm2Wiped: { npmShim: 'fail', forceClean: true, pm2OnPath: true }
@@ -268,6 +290,25 @@ describe.skipIf(process.platform === 'win32' || SKIP_HEAVY_INTEGRATION)('update.
expect(pm2Calls(sandboxes.oldNode)).toEqual([]);
});
+ it.each(['oldNodeAhead', 'oldNodePeer'])('refuses an unsupported runtime before the checkout moves (%s)', (name) => {
+ const { status, stdout } = results[name];
+ const head = () => execFileSync('git', ['rev-parse', 'HEAD'], { cwd: sandboxes[name].repo, encoding: 'utf8' }).trim();
+ expect(status).toBe(1);
+ expect(stdout).toContain('STEP:runtime-preflight:failed:');
+ expect(stdout).toContain('Node.js ^22.22.2');
+ expect(stdout).not.toContain('STEP:git-pull:done:');
+ expect(stdout).not.toContain('STEP:submodules:');
+ expect(head()).toBe(sandboxes[name].headSha);
+ expect(existsSync(join(sandboxes[name].repo, 'ahead.txt'))).toBe(false);
+ expect(pm2Calls(sandboxes[name])).toEqual([]);
+ });
+
+ it('still pulls and updates when the target supports the runtime', () => {
+ const { repo, aheadSha } = sandboxes.cleanAhead;
+ expect(results.cleanAhead.status, results.cleanAhead.stdout).toBe(0);
+ expect(execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8' }).trim()).toBe(aheadSha);
+ });
+
it('passes the runtime preflight on a supported runtime without changing the flow', () => {
expect(results.clean.stdout).toContain('STEP:runtime-preflight:done:');
expect(results.clean.stdout.indexOf('STEP:runtime-preflight:done:'))
@@ -327,14 +368,23 @@ describe('update.ps1 headless-install guard', () => {
});
it('runs the target Node gate before the PM2 delete and any install', () => {
- const gate = lineOf('node scripts/checkNodeVersion.js');
+ const gate = lineOf('if (Test-Path "scripts/checkNodeVersion.js")');
expect(gate).toBeGreaterThan(-1);
expect(gate).toBeLessThan(lineOf('pm2 delete ecosystem.config.cjs --silent'));
expect(gate).toBeLessThan(lineOf('Safe-Install -Dir "."'));
expect(ps1.slice(gate, gate + 8).join('\n')).toContain('Stop-UpdateScript 1');
});
- it('arms the latch before the delete, not after', () => {
+ it('evaluates the target Node gate from git archive before HEAD moves', () => {
+ const archive = lineOf('git archive --output=$gateArchive $preflightTarget');
+ expect(archive).toBeGreaterThan(-1);
+ expect(archive).toBeLessThan(lineOf('Invoke-Logged git merge --ff-only'));
+ expect(archive).toBeLessThan(lineOf('Invoke-Logged git pull --rebase'));
+ expect(archive).toBeLessThan(lineOf('Step "submodules" "running"'));
+ expect(ps1.slice(archive, archive + 25).join('\n')).toContain('Stop-UpdateScript 1');
+ });
+
+ it('arms the latch before the delete, not after', () => {
const armed = lineOf('$script:Pm2AppsDown = $true');
const deleted = lineOf('pm2 delete ecosystem.config.cjs --silent');
expect(armed).toBeGreaterThan(-1);
diff --git a/update.ps1 b/update.ps1
index 39c850e2d7..646fd26f65 100644
--- a/update.ps1
+++ b/update.ps1
@@ -336,6 +336,47 @@ if (-not (Repair-StaleSubmodules)) {
# post-pull HEAD yields exactly the pull's delta on main, so a manifest change
# the update brings is detected even when launched from another branch.
$prePullSha = git rev-parse HEAD 2>$null
+# Runtime pre-check (see update.sh): evaluate the TARGET revision's own Node gate
+# from `git archive` BEFORE HEAD, submodules or apps change, so a refusal leaves
+# the checkout untouched. package.json rides along for its "type": "module".
+# An unresolvable target or one that predates the gate skips this check.
+if ($env:PORTOS_PEER_UPDATE_TARGET_SHA) {
+ $preflightTarget = $env:PORTOS_PEER_UPDATE_TARGET_SHA
+} else {
+ Invoke-Logged git fetch
+ $preflightTarget = git rev-parse -q --verify '@{upstream}^{commit}' 2>$null
+}
+$global:LASTEXITCODE = 0
+if ($preflightTarget) {
+ git cat-file -e "${preflightTarget}:scripts/checkNodeVersion.js" 2>$null
+ if ($LASTEXITCODE -eq 0) {
+ $gateDir = Join-Path ([System.IO.Path]::GetTempPath()) ("portos-node-gate-" + [guid]::NewGuid().ToString('N'))
+ New-Item -ItemType Directory -Path $gateDir | Out-Null
+ $gatePaths = @('scripts/checkNodeVersion.js')
+ foreach ($optional in @('package.json', 'scripts/lib')) {
+ git cat-file -e "${preflightTarget}:$optional" 2>$null
+ if ($LASTEXITCODE -eq 0) { $gatePaths += $optional }
+ }
+ $gateArchive = Join-Path $gateDir 'gate.tar'
+ git archive --output=$gateArchive $preflightTarget @gatePaths 2>$null
+ $archived = ($LASTEXITCODE -eq 0)
+ if ($archived) { tar.exe -xf $gateArchive -C $gateDir 2>$null; $archived = ($LASTEXITCODE -eq 0) }
+ $gateRejected = $false
+ if ($archived) {
+ Push-Location $gateDir
+ try { $nodeGateOutput = (node scripts/checkNodeVersion.js 2>&1 | Out-String).Trim(); $gateRejected = ($LASTEXITCODE -ne 0) }
+ finally { Pop-Location }
+ }
+ Remove-Item -Recurse -Force $gateDir -ErrorAction SilentlyContinue
+ if ($gateRejected) {
+ Write-SafeHost $nodeGateOutput
+ Write-SafeHost "❌ Update stopped before changing anything: upgrade Node.js, then re-run the update. The checkout was left unchanged." -ForegroundColor Red
+ Step "runtime-preflight" "failed" "Unsupported Node.js runtime for the target revision; checkout unchanged"
+ Stop-UpdateScript 1
+ }
+ }
+}
+$global:LASTEXITCODE = 0
if ($env:PORTOS_PEER_UPDATE_TARGET_SHA) {
Invoke-Logged git merge --ff-only $env:PORTOS_PEER_UPDATE_TARGET_SHA
} else {
@@ -376,7 +417,8 @@ Step "submodules" "done" "Submodules updated"
Write-SafeHost ""
# Runtime preflight (see update.sh): run the pulled target's own Node gate before
-# any PM2 delete or dependency change. The checkout stays on the pulled revision.
+# any PM2 delete or dependency change. The pre-check above already refused an
+# unsupported runtime before HEAD moved; this is the second line of defence.
Step "runtime-preflight" "running" "Checking Node.js against the updated requirements..."
if (Test-Path "scripts/checkNodeVersion.js") {
$nodeGateOutput = (node scripts/checkNodeVersion.js 2>&1 | Out-String).Trim()
diff --git a/update.sh b/update.sh
index ccb99727d3..b908ed5b5c 100755
--- a/update.sh
+++ b/update.sh
@@ -182,6 +182,36 @@ if ! repair_stale_submodules; then
step "git-pull" "failed" "Pinned submodule checkout could not be synchronized"
exit 1
fi
+# Runtime pre-check: the target revision owns its Node support range, and a
+# refusal AFTER the checkout advances leaves the running (old) code over a new
+# working tree and old node_modules — any later single-process restart then
+# boots an unsupported, partly installed revision. So evaluate the target's own
+# gate from `git archive` BEFORE HEAD, submodules or apps change. The package.json
+# rides along because its `"type": "module"` is what lets the ESM gate load.
+# An unresolvable target (fetch failed, no upstream) or a target that predates
+# the gate skips this; the pull below then fails or the post-pull gate decides.
+preflight_target_sha=""
+if [ -n "${PORTOS_PEER_UPDATE_TARGET_SHA:-}" ]; then
+ preflight_target_sha="$PORTOS_PEER_UPDATE_TARGET_SHA"
+else
+ run git fetch || true
+ preflight_target_sha=$(git rev-parse -q --verify '@{upstream}^{commit}' 2>/dev/null || echo "")
+fi
+if [ -n "$preflight_target_sha" ] && git cat-file -e "${preflight_target_sha}:scripts/checkNodeVersion.js" 2>/dev/null; then
+ gate_dir=$(mktemp -d)
+ gate_paths=(scripts/checkNodeVersion.js)
+ git cat-file -e "${preflight_target_sha}:package.json" 2>/dev/null && gate_paths+=(package.json)
+ git cat-file -e "${preflight_target_sha}:scripts/lib" 2>/dev/null && gate_paths+=(scripts/lib)
+ if git archive "$preflight_target_sha" "${gate_paths[@]}" 2>/dev/null | tar -x -C "$gate_dir" 2>/dev/null \
+ && ! node_gate_output=$(cd "$gate_dir" && node scripts/checkNodeVersion.js 2>&1); then
+ rm -rf "$gate_dir"
+ log "$node_gate_output"
+ log "❌ Update stopped before changing anything: upgrade Node.js, then re-run the update. The checkout was left unchanged."
+ step "runtime-preflight" "failed" "Unsupported Node.js runtime for the target revision; checkout unchanged"
+ exit 1
+ fi
+ rm -rf "$gate_dir"
+fi
# Record main's pre-pull HEAD — captured AFTER any checkout so it's the commit
# the installed node_modules was built from (main, which the rest of this script
# installs/builds), not a feature branch we just left. Diffing this against
@@ -221,7 +251,8 @@ log ""
# just been raised), and npm's engines field only warns. Ask the target's own
# gate — the same one `npm start`/`npm run setup` run — BEFORE deleting any app
# or touching dependencies, so an unsupported runtime refuses while PortOS is
-# still up instead of mid-downtime. The checkout stays on the pulled revision.
+# still up instead of mid-downtime. The pre-check above already refused an
+# unsupported runtime before HEAD moved, so this is the second line of defence.
step "runtime-preflight" "running" "Checking Node.js against the updated requirements..."
if [ -f scripts/checkNodeVersion.js ] && ! node_gate_output=$(node scripts/checkNodeVersion.js 2>&1); then
log "$node_gate_output"