clawdie-ai/.agent/skills/runtime-version-sync/SKILL.md

name	description
runtime-version-sync	Check and align Node, FreeBSD pkg, npm global, and Pi versions across Linux and FreeBSD hosts. Use for preventing runtime drift between OSA, debby, domedog, and ISO builds.

Runtime Version Sync

Keep Linux, FreeBSD, and ISO runtime inputs aligned without relying on moving latest tags during builds.

Rules

• Do not upgrade anything until the inventory is recorded.
• Fetch remotes before claiming remote repository state.
• For security-sensitive auth paths, inspect before mutating.
• Pin build inputs; do not let ISO builds depend on moving npm dist-tags.
• Prefer Node 24 across Linux and FreeBSD unless a target explicitly requires a legacy lane.
• Use repo-local tmp/ for generated inventories and manifests.

1. Inventory local host

uname -a

node --version

npm --version

which pi

pi --version

npm config get prefix

npm outdated -g --depth=0

On FreeBSD, also check packages:

pkg info -x 'node|npm|pi|codex|gemini'

On Linux with nvm:

command -v nvm

nvm current

2. Check upstream versions

Pi:

npm view @earendil-works/pi-coding-agent version

npm view @earendil-works/pi-coding-agent dist-tags --json

Gemini CLI, if still intentionally shipped:

npm view @google/gemini-cli version

FreeBSD package availability:

pkg search '^node[0-9]+'

pkg search '^npm'

3. Cross-host manifest

Each host should emit a small JSON manifest under repo-local or user-local state. Example schema:

{
  "schema": "clawdie.runtime-version-inventory.v1",
  "host": "osa",
  "os": "FreeBSD",
  "node": "v24.14.1",
  "npm": "11.x",
  "pi": "0.75.5",
  "npm_prefix": "/home/clawdie/.npm-global",
  "package_manager": "pkg",
  "notes": []
}

Colibri can aggregate these manifests later, the same way it aggregates interagent run manifests.

4. Upgrade policy

FreeBSD

Preferred Node package:

node24

Use FreeBSD package operations only after checking current state and taking any needed ZFS/package rollback precautions.

Install/upgrade package names:

sudo pkg install -y node24 npm-node24

Then verify:

node --version

npm --version

Linux

If Node is managed by nvm, use nvm for Node 24:

nvm install 24

nvm alias default 24

If Node is system-managed, do not assume the package manager. Inventory first and choose the host's standard channel.

5. npm global policy

Pi should be updated through Pi when possible:

pi update --self

Fallback:

npm install -g @earendil-works/pi-coding-agent@<pinned-version>

ISO builds must use pinned npm globals from the ISO repo, not latest:

/home/clawdie/clawdie-iso/packages/npm-globals.txt

6. ISO follow-up

When Pi or npm global versions change, update the ISO pin file in a separate ISO commit and smoke the pack step:

sh -n scripts/fetch-npm-globals.sh

OUT_DIR="$(pwd)/tmp/npm-globals-pin-smoke" ./scripts/fetch-npm-globals.sh

Do not run a full ISO build unless explicitly assigned.

7. Report

Report:

• hosts checked
• Node versions and desired target
• Pi versions and desired target
• npm global pins changed
• package manager actions proposed or performed
• whether ISO pin file is aligned
• any blockers for Node 24 unification