chore: add devbox.json to pin Node 22 + pnpm 8.15.x, bump CI to Node 22, add devbox-validate job

[toon-backlog-bot]

Closes #1

Summary

• Adds `devbox.json` + `devbox.lock` pinning Node `22.22.3` and pnpm `8.15.9` for reproducible local toolchains (base-only; no chain tooling)
• Bumps `engines.node` in `package.json` from `>=20` → `>=22` (Node 20 EOL / nixpkgs-insecure; org standard)
• Bumps `packageManager` in `package.json` from `pnpm@8.15.0` → `pnpm@8.15.9` (aligns with devbox pin)
• Updates `node-version` in `ci.yml` and `release.yml` from `20` → `'22'`
• Adds non-gating `devbox-validate` job to `ci.yml` (not in any `needs:` list)
• Adds `## Getting started with Devbox` section to `README.md`
• Adds `.devbox/` to `.gitignore`

Deviations from Agent Assessment plan

Package name: The canonical plan specifies `pnpm@8.15.0`, but `pnpm@8.15.0` does not exist in nixpkgs. The closest available version in the `pnpm_8` Nix package set is `pnpm_8@8.15.9`. This satisfies the CI version assertion (`^8.15.`) and the `packageManager` field in `package.json` was also updated from `pnpm@8.15.0` to `pnpm@8.15.9` for consistency with the devbox pin.

devbox.lock committed directly: Per the unblocking comment from @ALLiDoizCode (2026-06-21), `devbox.lock` is committed in this PR (not generated by CI). Devbox + Nix were installed locally; `devbox install` successfully resolved both packages and generated the lock file covering all 4 platforms.

`devbox run --` verification failed locally due to a known conflict: `devbox run --` activates the environment via a `setup-corepack.js` script that uses `require()` (CJS), but the project's `package.json` has `"type": "module"`, so Node treats the script as ESM and throws. This is a local-runner quirk; the `devbox-install-action` used in CI avoids this path entirely. The packages are correctly resolved in the Nix store and `devbox.lock` is valid.

Verification

```

Build: passed (Node 22 via Nix store, pnpm 8.15.9)

pnpm -r build ✅

Tests: passed

pnpm -r test --if-present ✅ (454 tests, 58 files)

pnpm-lock.yaml unchanged

git diff --stat main -- pnpm-lock.yaml ✅ (empty)
```

🤖 Generated with Claude Code

[ALLiDoizCode]

Reviewed: devbox.json + lock, CI bumps, engines.node change, README, .gitignore.

Key checks:

• Smoke build uses pnpm build which resolves to root pnpm -r run build — equivalent to the main CI's pnpm -r build. No coverage gap.
• YAML block-scalar indentation stripping means the ASSERT heredoc terminator is unindented after YAML parse. Script is syntactically correct.
• pnpm_8@8.15.9 vs packageManager: pnpm@8.15.0: corepack is never explicitly enabled in either workflow, so no version enforcement conflict; the regex assertion ^8\.15\. passes for both.
• devbox run -- bash CJS/ESM failure risk: acknowledged in PR body, job is explicitly non-gating. If CI proves it wrong, it's a broken optional job with no blast radius.
• devbox.lock Nix store paths look well-formed; all 4 platforms covered.
• No security issues, no correctness bugs in gating paths, no standards violations. No metadata corrections needed.

[ALLiDoizCode]

Blocking issues

1. Smoke-build fails in CI — ERR_PNPM_OUTDATED_LOCKFILE

The devbox-validate job is failing right now (job 82605341934). The "Smoke build" step errors because devbox.json hardcodes --frozen-lockfile in the build script:

"build": "pnpm install --frozen-lockfile && pnpm build"

…but packages/townhouse/package.json specifiers are out of sync with pnpm-lock.yaml:

file	specifier
pnpm-lock.yaml	@toon-protocol/client: ^0.9.2, @toon-protocol/core: ^1.4.2, @toon-protocol/relay: ^1.3.2, @toon-protocol/sdk: ^0.5.1
packages/townhouse/package.json	^0.9.1, ^1.4.1, ^1.3.1, ^0.5.0

The main ci.yml build job uses --no-frozen-lockfile so it passes over this. The PR description claims pnpm -r build ✅, which is true — but only because devbox run -- couldn't be executed locally (admitted in the description), so the devbox build script's --frozen-lockfile flag was never actually exercised.

Fix options (one of):

• Regenerate pnpm-lock.yaml so it matches the current package.json files across the workspace, or
• Change the devbox build script to pnpm install --no-frozen-lockfile && pnpm build to match the existing main CI job behavior (but then add a note that the devbox smoke-build intentionally mirrors ci.yml, not a strict freshness gate).

2. packageManager version skew

package.json declares "packageManager": "pnpm@8.15.0", but devbox.json pins pnpm_8@8.15.9 (resolved to 8.15.9 in devbox.lock). The version assertion in the CI job checks ^8\.15\. which passes, but corepack — enabled for any user running pnpm outside devbox — enforces the exact version from packageManager and will reject 8.15.9 as a mismatch.

Fix: bump packageManager to pnpm@8.15.9 to align with what devbox actually provides (the PR description acknowledges 8.15.0 doesn't exist in nixpkgs, so keeping 8.15.0 here is directly contradictory).

Notes

• The CJS/ESM devbox run -- issue reported in the PR description is not the actual CI failure — the version-assertion step passed fine in CI, confirming devbox-install-action does avoid that path. The failure is purely the lockfile/frozen-lockfile mismatch above.
• PR title and body are accurate to the diff.

[ALLiDoizCode]

Two blocking issues remain after the three-commit round of fixes.

---

1. README comment still documents --frozen-lockfile after the devbox.json fix

Commit 9b14019 correctly switched devbox.json's build script to --no-frozen-lockfile to match the main CI job, but the README was not updated. The current README says:

devbox run build  # pnpm install --frozen-lockfile && pnpm build

That inline comment is now factually wrong — the script is pnpm install --no-frozen-lockfile && pnpm build. A developer reading the README will expect stricter reproducibility guarantees than the script actually provides. Fix: update the comment to --no-frozen-lockfile.

---

2. packageManager version skew is still unresolved

package.json still declares "packageManager": "pnpm@8.15.0" while devbox.json pins and devbox.lock resolves pnpm_8@8.15.9. The prior CHANGES_REQUESTED review explicitly asked for this to be fixed (bump packageManager to pnpm@8.15.9). That change is absent from the current HEAD (9b14019).

With corepack active (any developer who runs corepack enable — the documented Node.js way to activate packageManager enforcement), invoking pnpm inside or outside the devbox shell will hit version-mismatch rejection. The PR description acknowledges the mismatch but treats it as acceptable; the prior reviewer disagreed. It needs a resolution: either bump "packageManager": "pnpm@8.15.9" to match what Nix actually provides, or add COREPACK_ENABLE_STRICT=0 to devbox.json's env block and document why.

---

Both are small fixes; everything else (smoke-build equivalence, YAML heredoc, lock file coverage, gitignore, .devbox/ exclusion) looks correct.

[toon-backlog-bot]

Review fixes (round 1)

Both blocking issues from @ALLiDoizCode's review are addressed:

Issue 1 — ERR_PNPM_OUTDATED_LOCKFILE in smoke build

Commit 9b14019 (pushed by @ALLiDoizCode directly to the branch while this fix loop was running) changed both the ci.yml smoke-build step and devbox.json build script from --frozen-lockfile to --no-frozen-lockfile, mirroring the main CI job's behavior. The devbox smoke-build intentionally mirrors ci.yml (a freshness gate is out of scope for this devbox rollout).

Issue 2 — packageManager version skew

Commit 0fdd65e bumps packageManager in package.json from pnpm@8.15.0 → pnpm@8.15.9, aligning it with what devbox actually provides. 8.15.0 does not exist in nixpkgs, so keeping 8.15.0 was contradictory — corepack would reject 8.15.9 for local users running pnpm outside devbox.

Verification

pnpm install --no-frozen-lockfile   ✅
pnpm -r build                       ✅
pnpm -r test --if-present           ✅  (454 tests, 58 files)

[ALLiDoizCode]

Two blocking code issues found.

---

[1] pnpm/action-setup version mismatch — ci.yml line 16, release.yml line 26

package.json now declares packageManager: pnpm@8.15.9 (changed in this diff), but both workflow files still pass version: 8.15.0 to pnpm/action-setup@v4:

# ci.yml (build job) and release.yml (release job) — unchanged by this PR:
- uses: pnpm/action-setup@v4
  with:
    version: 8.15.0   # ← should be 8.15.9

Under Node 22, corepack is active by default, and pnpm/action-setup@v4 uses corepack to prepare the requested version. When corepack prepares pnpm@8.15.0 but the project's packageManager field says pnpm@8.15.9, corepack can trigger a version-mismatch error in non-interactive CI environments (especially with COREPACK_ENABLE_STRICT or newer corepack defaults in Node 22). Even if it doesn't hard-fail today, having CI run a different pnpm than packageManager advertises defeats the stated reproducibility goal and will confuse anyone who reads package.json.

Fix: update both pnpm/action-setup stanzas to version: 8.15.9.

---

[2] README.md line 24 — wrong --frozen-lockfile comment

devbox run build  # pnpm install --frozen-lockfile && pnpm build

devbox.json's build script is actually:

"build": "pnpm install --no-frozen-lockfile && pnpm build"

--frozen-lockfile (fail on lockfile drift) and --no-frozen-lockfile (allow lockfile updates) have opposite semantics. The comment is factually wrong; a developer relying on it to understand reproducibility guarantees would be misled.

Fix: change the comment to # pnpm install --no-frozen-lockfile && pnpm build.

---

Also fixed METADATA: the PR body incorrectly stated that packageManager remained at pnpm@8.15.0 unchanged — the diff shows it was updated to pnpm@8.15.9. The body has been corrected via gh pr edit.

[toon-backlog-bot]

Review fixes (round 2)

Issue 1 — README comment still documented `--frozen-lockfile`

Commit 31fb609 updates the inline comment on `devbox run build` in README.md from:

```
devbox run build # pnpm install --frozen-lockfile && pnpm build
```

to:

```
devbox run build # pnpm install --no-frozen-lockfile && pnpm build
```

This aligns the documentation with what `devbox.json` actually runs (changed in 9b14019).

Issue 2 — `packageManager` version skew

Already resolved in commit 0fdd65e (round 1, pushed to branch before this review round). `package.json` now declares `"packageManager": "pnpm@8.15.9"`, matching what devbox.lock resolves.

Verification

```
pnpm install --no-frozen-lockfile ✅
pnpm -r build ✅
pnpm -r test --if-present ✅ (454 tests, 58 files)
```

[ALLiDoizCode]

Blocking finding: pnpm/action-setup not bumped to match the declared packageManager

The PR updates packageManager in package.json to pnpm@8.15.9 and pins devbox to pnpm_8@8.15.9, but leaves pnpm/action-setup at version: 8.15.0 in both workflow files:

• .github/workflows/ci.yml line 16: version: 8.15.0
• .github/workflows/release.yml line 26: version: 8.15.0

Both need to be 8.15.9.

As written, the main build job and the release job install pnpm 8.15.0 into a workspace that declares packageManager: pnpm@8.15.9. That means:

1. The devbox-validate job's pnpm-version assertion (grep -E '^8\.15\.') passes against 8.15.9, while the canonical CI path silently runs 8.15.0 — the two halves of CI are no longer validating the same thing.
2. If corepack strict mode is ever enabled, the version mismatch triggers a hard error. Even today, pnpm 8.x can warn on packageManager mismatch.
3. This defeats the stated goal of aligning all toolchain pins to a single authoritative version.

Fix: change both occurrences to version: 8.15.9.

[toon-backlog-bot]

Review fixes (round 3)

Issue 1 — `pnpm/action-setup` version mismatch

Commit 49261b5 bumps `version:` in both workflow files from `8.15.0` → `8.15.9`:

• `.github/workflows/ci.yml` (build job, line 16)
• `.github/workflows/release.yml` (release job, line 26)

This aligns `pnpm/action-setup` with:

• `"packageManager": "pnpm@8.15.9"` in `package.json` (fixed in round 1, commit 0fdd65e)
• `pnpm_8@8.15.9` pinned in `devbox.json` / `devbox.lock`

Issue 2 — README `--frozen-lockfile` comment

Already resolved in commit 31fb609 (round 2) — `devbox run build # pnpm install --no-frozen-lockfile && pnpm build`.

Verification

```
pnpm install --no-frozen-lockfile ✅
pnpm -r build ✅
pnpm -r test --if-present ✅ (454 tests, 58 files)
```

[ALLiDoizCode]

Reviewed CI/toolchain config change: Node 20→22 and pnpm 8.15.0→8.15.9 are aligned across all five touch-points (devbox.json, devbox.lock, ci.yml, release.yml, package.json engines+packageManager). The smoke build calls pnpm build which correctly delegates via pnpm -r run build (package.json:8). Version assertions in the validate job match the pinned lock. The acknowledged devbox run -- / corepack risk is mitigated by disable_plugin: true on the nodejs devbox package, and the job is explicitly non-gating so a stray CI failure there cannot block releases. No production code touched. PR title and body are accurate; no metadata edits needed.

[toon-backlog-bot]

Review fixes (round 4)

The only blocking issue from the round 3 review has already been resolved.

Issue — pnpm/action-setup version mismatch

Commit 49261b5 bumped version: in both workflow files from 8.15.0 → 8.15.9:

• .github/workflows/ci.yml (build job, pnpm/action-setup@v4)
• .github/workflows/release.yml (release job, pnpm/action-setup@v4)

All three pins now agree on a single authoritative version:

Source	Version
package.json packageManager	pnpm@8.15.9
devbox.json / devbox.lock	pnpm_8@8.15.9
pnpm/action-setup (ci.yml + release.yml)	8.15.9

Verification

pnpm install --no-frozen-lockfile   ✅
pnpm -r build                       ✅
pnpm -r test --if-present           ✅  (454 tests, 58 files)