fix: Node 26.10 skill installs, Homebrew Node upgrades, stripped config markers, and Windows uninstall - #926

Summary

Five fixes for problems found by Claude sessions on one Mac installation. Those sessions never pushed anything, so each fix was re-derived from their findings and reproduced against current main. Two independent review passes followed, and a hardening commit and a docs commit come after the fixes. Every user-visible change has its own changelog fragment.

1. Skill install fails on Node 26.10 (fix(skills)).
   • Node 26.10 shipped fs: throw on existing dir in cpSync with errorOnExist nodejs/node#64124: fs.cpSync with errorOnExist now refuses an existing destination directory rather than merging into it.
   • publishStagedSkill claims its target with a no-replace mkdir, then copied the staged tree onto that directory. Every skill install and refresh failed with ERR_FS_CP_EEXIST, naming the directory it had just created; 31 of 43 skills-install tests fail on 26.10.
   • The tree is now copied entry by entry, so every copy lands on a new path.
   • The regression test emulates the 26.10 rule in-process, so it also fails on CI's Node 24.
2. A skill failure fails the POSIX install and update (fix(install)).
   • bin/install ran the skill refresh bare under set -eu, so update treated a skill error as a failed update and rolled back.
   • The rollback re-ran the same step, so users got "Update failed and automatic rollback also failed".
   • The hunks are byte-identical to fix: keep POSIX router updates after skill refresh failure #891; this PR adds its changelog fragment.
3. Windows uninstall leaves the managed skills behind (fix(windows)).
   • codex-router.ps1 uninstall now removes them, best effort, like bin/uninstall.
   • disable keeps them, like bin/disable.
4. Homebrew Node upgrades break login-free routing and strand repair (fix(node), hardened in the review commit).
   • process.execPath is the versioned keg that brew upgrade node deletes. The config manager wrote it into Codex's caller auth command. The launchers fell back to it, and a service installed without CODEX_ROUTER_NODE_BIN recorded it too.
   • Login-free ownership matched the rendered command literally, so after an upgrade enable, update, and doctor --fix all refused with "lost ownership".
   • New src/stable-node.mjs maps a keg to its formula's opt link, the path the Homebrew formula itself pins.
   • The auth command keeps a working, non-keg Node the config already names. Otherwise it uses the router's own Node binary, never a launcher or a version-manager shim.
   • The command's path is no longer ownership evidence, since its arguments still are. This also recovers a command an older Control Center recorded as its Electron app.
   • doctor fails on a dead or non-Node auth command and warns on a keg path; --fix rewrites it.
   • The service restart and client-disconnect spawns flagged in the owner's review of fix: keep router refreshes on stable node #907 use childNodeBinary(). It keeps the process's own Node and differs only when that keg is gone.
5. A comment-stripped config.toml strands the router (fix(config), hardened in the review commit).
   • A writer that re-serializes the file keeps the tables but drops the comments, and the router's markers are comments.
   • update/doctor --fix then refused with "Refusing to replace user-owned model provider codex-router". Login-free mode on the user's own table could not even be turned off.
   • The router re-adopts its provider table, realtime endpoints, and multi-agent feature, but only on the evidence the markers carried: its own port and private catalog, or the protected v3 state.
   • It also requires every value to decode to exactly what it writes, including the padded and multi-line arrays that Python's toml and tomli_w write back.
   • A comment inside or between its tables still disqualifies them. A comment above the next table is never removed.
   • disable retires everything it took back.
   • Use Router with ChatGPT was stuck in both directions, which the review commit had not covered (follow-up 3cf3a546).
     • From the built-in OpenAI provider, the switch owns [model_providers.codex-router-signed], and the router recognized that table by its markers alone.
     • Once they were stripped, off refused with "Signed routing lost ownership of model_providers.codex-router-signed", on said to turn it off first, and update/doctor --fix refused as well.
     • The table is now re-marked at read time on the same kind of evidence: the v1 signed state, model_provider = "codex-router-signed", the router's own root base URL, and an exact rendering.

Review fixes (c92aabd9):

• Blocking, Windows. The catalog path is stored escaped, so recovery kept the unmarked openai_base_url and appended a second one, which Codex refuses to load. Ownership is now decided from the decoded value, and a duplicate base URL is never written.
• Pre-existing: a restored secret could change. A saved provider section containing $'/$&/$$ (for example a bearer token) was restored altered by String#replace. Replacer functions now return it verbatim.

Relation to open PRs.

• fix: keep POSIX router updates after skill refresh failure #891: identical bin/install hunks, which merge cleanly in either order.
• fix: keep router refreshes on stable node #907: git merge-tree shows no textual conflict with this PR, but both add a Node-path helper. routerNodeBinary() could delegate to childNodeBinary({ environment }) so there is one policy. fix: keep router refreshes on stable node #907's remaining process.execPath spawns (publish, control, refresh-catalog, subagent-verify) stay in its scope.

Known limitations, deliberately out of scope.

• Rolling back to a pre-fix release after a keg path was rewritten leaves that release unable to match a v3 login-free block. It compares its own keg path literally, as it already does after any Node upgrade.
• The Windows service still records process.execPath; Windows has no kegs.
• CI pins Node 24, so the 26.10 rule is exercised by emulation. A Node 26 job could be added separately.

AGENTS.md gains a "recorded Node path" section and a safety-boundary bullet on stripped markers. The README, the docs-site skills guide, and docs/INSTALL.md now say uninstall removes the skills on every platform.

Verification

• npm run check reports: syntax checks passed, changelog fragments valid (22), v2-agent applications valid.

• git diff --check origin/main...HEAD is clean.

• Two independent read-only reviews, run under the repo-maintainer skill's "critical" tier:

  • ownership-boundary correctness;
  • integration/platform parity.

  They found no blocking issue in the ownership logic and one blocking Windows defect. That defect and every should-fix finding are addressed in c92aabd9, each with a regression test.

• Full npm test on Linux (Node 22.22.2, with PowerShell 7.6.6 on PATH): 4,701 tests: 4,664 pass, 35 skipped, 2 fail. Both failures are root-only chmod tests (model-router reports failed skill commands, an unreadable approved tree becomes stale instead of throwing). They fail identically on untouched origin/main when run as root and pass on this branch as an unprivileged user; CI does not run as root.

• Each new regression test fails on the code before its fix:

  • skills-install: ERR_FS_CP_EEXIST through the emulation.
  • installer-scripts: the POSIX skill step.
  • windows-operations: two cases.
  • config-manager: the keg case plus three stripped-marker cases, all four failing on the pre-review code. A fourth stripped-marker case, the ChatGPT switch table, fails before 3cf3a546.
  • router-restart: reverting to process.execPath fails.
  • doctor-routing-mode: the auth-command case.

• The keg tests run config-manager and router-restart from a real keg: test/fixtures/homebrew-keg-node.mjs hard-links the Node binary, because Node resolves a symlinked execPath.

• Real Node 26.10.0: skills-install goes from 32/43 failing to all 44 passing as a normal user. The single failure left as root is a chmod test that fails on every Node version.

• Stripped-config matrix, 18 of 18 pass. It covers plain, login-free v1, and login-free v3, each round-tripped by a comment filter, Python toml 0.10.2, and tomli_w 1.2.0, with and without a Windows-style escaped state path. Every run ends as valid TOML (checked with tomllib) with exactly one openai_base_url and correct status. After disable there is zero router residue, and v3's Bearer ab$'cd header is restored exactly.

• After 3cf3a546, every test file that touches signed routing passes: 459 tests, 456 pass, 3 skipped, across 12 files including config-manager, control, refresh-catalog, doctor-routing-mode, and routing.

• codex-router.ps1: every Windows script parses under real PowerShell 7.6.6. The dispatcher was driven against a stand-in node, and that test runs on CI's Linux and macOS runners.

• Not run: live provider requests, and the macOS tray/Swift suites (no macOS host here). These changes touch neither.

Changelog

• changelog.d/skills-install-node-26-10.md
• changelog.d/posix-install-skill-refresh-best-effort.md
• changelog.d/windows-uninstall-skill-removal.md
• changelog.d/stable-node-path.md
• changelog.d/stripped-config-markers.md

🤖 Generated with Claude Code

https://claude.ai/code/session_018S4qLJNvsusgNp7Yi7MEAo