Migrating to Session Orchestrator v3.0.0

v3.0.0 swaps the Bash/zx runtime for Node.js 24+ and adds native Windows support without WSL. This guide walks through the upgrade step-by-step for each supported platform (Claude Code, Codex, Cursor IDE) and each OS (macOS, Linux, Windows).

Epic reference: #124. Full change list: CHANGELOG.md.

1. What Changes

Area	v2.x	v3.0.0
Runtime	Bash + jq + zx via Bash	Node.js 24+ + zx (native import)
Hooks	.sh files in hooks/	.mjs files (ES modules)
Install step	git clone only	git clone then npm install
Windows support	Implicit via WSL / Git-Bash	Native (no wrapper shell)
CI	Ubuntu-only	Ubuntu + macOS matrix
Test framework	bats shell harness	vitest
Dependencies	jq, bash, git hard deps	Node 24+, git; jq optional

Nothing about skills, commands, or session flow changes. /session, /go, /close, /discovery, /plan, /evolve, /bootstrap, and 17 more (see docs/components.md) work the same.

2. Prerequisites

• Node.js 24 or later. Check with node --version. Install from nodejs.org or via your package manager (brew install node, winget install OpenJS.NodeJS, apt install nodejs).
• Git. Any recent version.
• jq (optional, recommended). The scope and command enforcement policies are edited as JSON — jq makes that easier. No hook invokes jq at runtime in v3.

Optional but recommended:

• glab (GitLab CLI) or gh (GitHub CLI) for VCS operations — same as v2.

3. Upgrade Steps

3a. Claude Code

# 1. Update the plugin — run this INSIDE Claude Code, not in a shell:
#      /plugin update session-orchestrator@kanevry
#    A marketplace-installed plugin lives in a managed cache, not in a git checkout,
#    so `git pull` does not apply to it.

# 2. Install Node dependencies. Claude Code has no `plugin dir` subcommand,
#    so resolve the install path from the cache:
SO_DIR="$(dirname "$(find ~/.claude/plugins/cache -path '*session-orchestrator*' -name package.json 2>/dev/null | head -1)")"
cd "$SO_DIR" && npm install

# 3. Restart Claude Code so hooks.json is re-read

If you installed via /plugin marketplace add Kanevry/session-orchestrator, the plugin lives under ~/.claude/plugins/session-orchestrator. If you installed from a local clone, use the clone path.

3b. Codex

cd ~/Projects/session-orchestrator
git pull
npm install
node scripts/codex-install.mjs
codex plugin list --available --json

The installer now uses Codex's public marketplace/add/list lifecycle; it does not rewrite private catalogs, configuration, caches, or hook state. It repeats codex plugin add on every run to refresh the installed bundle. Explicit invalidation comes from the committed .codex-plugin/plugin.json version suffix +codex.<YYYYMMDDHHmmss>, which the installer validates but never mutates.

After the list shows session-orchestrator@kanevry installed and enabled, start a fresh task or restart Codex, run /hooks, and review the bundle. Marketplace configuration, plugin installation, and hook trust remain separate states.

3c. Cursor IDE

cd ~/Projects/session-orchestrator
git pull
npm install
node scripts/cursor-install.mjs /path/to/your/project    # re-syncs rules
# Restart Cursor

3d. Verify

After restart, run /session housekeeping in any configured repo. On session start you should see the host + resource health banner (new in v3). If the banner is missing or hooks report errors, see Known Issues below.

4. What Stays the Same

None of the following change in v3. Existing data migrates transparently.

• .orchestrator/metrics/*.jsonl — learnings, sessions, events files are read-write compatible.
• <state-dir>/STATE.md — schema v1 frontmatter unchanged.
• Session memory (~/.claude/projects/<project>/memory/) — untouched.
• Session Config in CLAUDE.md / AGENTS.md / Cursor rules — same field names and defaults. New optional fields (resource-awareness, resource-thresholds, allow-destructive-ops, worktree-exclude) default to safe values.
• All 24 slash commands — same arguments, same flow. See docs/components.md for the full list.
• Skill Markdown — skills are still pure Markdown with YAML frontmatter; no build step.
• VCS integration — glab / gh commands, label taxonomy, issue templates.

5. Known Issues & Workarounds

npm install fails with ERESOLVE or peer-dep warnings

Use Node.js 24 or later, matching package.json (engines.node: ">=24.0.0"). Confirm node --version reports a supported runtime before retrying. If the error persists:

npm install --legacy-peer-deps

Windows: hooks silently no-op after install

Make sure node is on your PATH inside the editor process (not just in your terminal). On Windows, Claude Code inherits PATH from the launching shell — if you installed Node via nvm-windows or fnm, relaunch the editor from a shell that has the runtime on PATH.

Verify from inside Claude Code: !node --version should print v24.x or later.

EOL issues on Windows (autocrlf)

v3 ships .gitattributes with explicit LF rules for .sh, .mjs, .md, .json, and .yaml. If you cloned before v3, run:

git config core.autocrlf false
git rm --cached -r .
git reset --hard

This re-checks out every file with the correct line endings. Back up any uncommitted work first.

Permission errors on hook scripts (macOS / Linux)

Pre-v3, hook .sh files needed +x. v3 .mjs files are invoked via node <path>, so the executable bit is not required. If your editor reports Permission denied on a hook, it is pointing at a stale .sh path — re-run the install script for your platform (scripts/codex-install.mjs, scripts/cursor-install.mjs) or re-add the plugin in Claude Code.

zx not found

Run npm install from the plugin root. The zx package is listed under dependencies (not devDependencies), so it installs in production trees too. If you run npm install --production explicitly, zx is still installed — it is only missing if you ran npm ci --only=dev or manually pruned runtime deps.

Hooks report SyntaxError: Cannot use import statement outside a module

Your Node version is below 24 or your package.json is missing "type": "module". Verify that node --version satisfies engines.node >=24 and that jq '.type' package.json returns "module".

6. Rollback

If v3 causes blocking problems and you need to revert to v2.x:

cd /path/to/session-orchestrator
git fetch --tags
git checkout v2.0.0
rm -rf node_modules package-lock.json   # v2 does not use these
# Restart your editor

v2.x state files (STATE.md, sessions.jsonl, learnings.jsonl) remain readable on rollback — the formats are stable across the 2.x → 3.0 transition.

Please open an issue (link below) describing the blocker so we can address it in a v3.0.x patch.

7. Support

• GitHub: Kanevry/session-orchestrator/issues — preferred for bugs and feature requests.
• Homepage: session-orchestrator.example.com

Please include node --version, your OS + arch, the editor (Claude Code / Codex / Cursor), and a minimal reproduction when filing a bug. For hook failures, attach the relevant entries from .orchestrator/metrics/events.jsonl.