Fix runtime env targeting and project registry bloat

[TraderSamwise]

Summary

• normalize stable/dev CLI launcher env so inherited aimux-dev settings do not steer stable aimux, and vice versa
• prevent ephemeral tmp aimux roots from registering as desktop projects
• hard-fail over-cap project registries and add focused regression tests

Verification

• /Users/sam/cs/aimux/node_modules/.bin/vitest run src/paths.test.ts src/launcher-env.test.ts
• /Users/sam/cs/aimux/node_modules/.bin/tsc --noEmit
• /Users/sam/cs/aimux/node_modules/.bin/eslint src/paths.ts src/paths.test.ts src/launcher-env.ts src/launcher-env.test.ts --max-warnings=0
• PATH=/Users/sam/cs/aimux/node_modules/.bin:$PATH yarn build

Summary by CodeRabbit

Release Notes

• New Features

  • Enhanced CLI environment initialization that properly configures stable and development modes separately

• Improvements

  • Hardened project registry with built-in safeguards including a 500-entry maximum and automatic filtering of temporary/ephemeral projects

• Tests

  • Expanded test coverage for environment configuration and project registry edge cases

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jun 6, 2026 6:52am

[coderabbitai]

Looking for one thing? Review this PR in Change Stack to search files, summaries, diffs, and code without losing your place.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 288ecb07-4ad5-47d0-a0cf-417d99c45435

📥 Commits

Reviewing files that changed from the base of the PR and between 3ffab5d and a1e8206.

📒 Files selected for processing (6)

• bin/aimux
• bin/aimux-dev
• src/launcher-env.test.ts
• src/launcher-env.ts
• src/paths.test.ts
• src/paths.ts

---

📝 Walkthrough

Walkthrough

This PR introduces environment-setup normalization for stable and development CLI modes, updates both entrypoints to delegate environment preparation to new helpers, and hardensthe projects registry with a 500-entry cap and ephemeral temp-project filtering to prevent stale or polluted growth.

Changes

Environment Normalization and Registry Hardening

Layer / File(s)	Summary
Environment preparation module and tests src/launcher-env.ts, src/launcher-env.test.ts	New launcher-env.ts exports prepareStableCliEnv and prepareDevCliEnv to normalize AIMUX environment variables and clear session-scoped variables based on inferred target; comprehensive test suite validates stable and dev normalization with preservation of custom lane and explicit targeting.
CLI entrypoint integration bin/aimux, bin/aimux-dev	bin/aimux now imports and calls prepareStableCliEnv() before loading main; bin/aimux-dev delegates environment setup to prepareDevCliEnv() instead of inline defaults.
Registry protection: capping and ephemeral filtering src/paths.ts	Adds 500-entry registry cap, detects ephemeral aimux-temp project roots via realpath canonicalization, normalizes registry by deduplicating and filtering temp projects, validates cap during load/save, and no-ops registerProject() for ephemeral roots.
Registry hardening tests src/paths.test.ts	Imports initPaths and listProjects; refactors existing AIMUX_HOME test to preserve/restore prior value; adds ephemeral-root test verifying temp projects are not registered; adds cap-enforcement test verifying 501-entry registry rejects initialization.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• TraderSamwise/aimux#9: Implements an isolated aimux-dev runtime using the same environment variable normalization (AIMUX_HOME, AIMUX_DAEMON_PORT, AIMUX_ENV, AIMUX_WEB_APP_URL) that is now delegated to the new prepareDevCliEnv() helper in this PR.

Poem

🐰 A rabbit hops through environments clean,
Stable and dev now live serene,
Temp projects filtered, registries capped,
At 500 entries, no stale data trapped!
CLI bootstrap shines bright and new, ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and specifically describes the two main changes: environment targeting fixes and preventing project registry bloat.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/prod-env-registry-guard

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}