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
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.mdindex 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 checkoutthat 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 scriptsdiff --git a/scripts/update-headless-recovery.test.js b/scripts/update-headless-recovery.test.jsindex 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.ps1index 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 = 0if ($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.shindex ccb99727d3..b908ed5b5c 100755--- a/update.sh+++ b/update.sh@@ -182,6 +182,36 @@ if ! repair_stale_submodules; thenstep "git-pull" "failed" "Pinned submodule checkout could not be synchronized"exit 1fi+# 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); thenlog "$node_gate_output"