feat: Per-Instance MCP Registration & Session Cache Enhancements

[bizzkoot]

Summary

This PR improves multi-instance safety and MCP server registration reliability. It introduces per-instance, CodeNomad-local MCP config files (removing dependency on Antigravity's global config), adds atomic writes and stale instance cleanup, enhances the session cache structure in InstanceEventBridge, and adds a minimal ESLint baseline tuned to avoid forcing broad refactors. Additionally, this PR includes a routine package version bump across all packages.

🐛 Issues Resolved

This PR addresses the following critical bugs:

• Issue #23: Subagent launches consume 1 premium request each - Fixed event ordering race condition in session caching that caused subagent messages to incorrectly consume premium quota
• Issue #24: ask_user answered from main session (while question from subagent) consumes 1 premium request - Improved per-instance MCP registration to prevent question routing issues and duplicate IPC listeners

📦 Release Contents

1. 🔐 Per-Instance MCP Registration (CodeNomad-Local Config)

Resolves: Issue #24: ask_user answered from main session consumes premium

Root Cause: Multiple IPC listeners being attached per instance caused questions from subagents to be routed to the wrong instance queue, leading to duplicate questions and incorrect answer routing that consumed premium requests.

Key Changes:

• CodeNomad-Local Config: Replaced global Antigravity MCP registration (~/.gemini/antigravity/mcp_config.json) with per-instance config under ~/.codenomad/instances/<instanceId>/config.json.
• Atomic Writes: Config writes use unique temp file names to avoid concurrent process contention and prevent file corruption.
• Startup Cleanup: On startup, scan for stale instances and prune via PID liveness and HTTP /health probe.
• Instance-Scoped Unregister: On exit, each instance removes only its own config directory (safe for multiple concurrent instances).
• Security: MCP auth token is no longer persisted to disk. Token is still required at runtime but isn't written to the instance config file.
• Legacy Cleanup (Best-Effort): Removes Antigravity ask-user entry if present, without creating the file if it doesn't exist.
• UUID Generation: Added randomUUID import for generating unique instance identifiers.
• Enhanced Registration: Implemented cleanupLegacyAntigravityRegistration() and cleanupStaleInstances() during startup.
• Instance Tracking: Added mcpInstanceId to track the current instance and pass it to registration functions.

How This Fixes Issue #24:

• Per-instance MCP configs ensure proper isolation between main and subagent instances
• Stale instance cleanup prevents zombie instances from creating duplicate IPC listeners
• Atomic writes prevent race conditions during concurrent instance operations

Commits:

• feat(mcp): implement per-instance MCP registration and add minimal ESLint setup

2. ⚡ Session Cache Structure & Management in InstanceEventBridge

Resolves: Issue #23: Subagent launches consume 1 premium request each

Root Cause: Event ordering race condition where message.updated events arrived before session.updated events, causing the UI to track subagent messages as main session messages (consuming premium quota).

Key Changes:

• Enhanced Session Cache: Improved structure and management of session caching within InstanceEventBridge for better consistency and performance.
• Session Cache Entry Interface: Added SessionCacheEntry interface with parentID, parentIdKnown, and verified properties.
• Merge Functionality: Implemented mergeCachedParentId() to intelligently merge cached parent IDs with incoming data.
• Verification Logic: Added verification checks to ensure sessions are properly fetched and cached from the source-of-truth payload.
• Improved Handling: Enhanced handleInstanceEvent() to properly process session updates with more accurate parent ID tracking.
• Synchronous Event Ordering: Ensures session.updated events are processed synchronously before message.updated events to guarantee proper parent ID hydration.

How This Fixes Issue #23:

• Session cache now properly tracks parentID from the source of truth
• Verification logic ensures subagent sessions are correctly identified before message tracking
• Prevents the race condition where messages were tracked before session parent info was available

Commits:

• feat: enhance session cache structure and management in InstanceEventBridge

3. 🧩 Minimal ESLint Baseline

Key Changes:

• ESLint v9 Flat Config: Added ESLint with TypeScript ESLint and SolidJS plugin.
• Low-Churn Rules: Configured to warn-only for most rules to avoid forcing large refactors across existing code.
• Scripts: Added npm run lint and npm run lint:fix scripts.
• Dependencies: Added @eslint/js, eslint, eslint-plugin-solid, globals, typescript, and typescript-eslint as dev dependencies.

Commits:

• feat(mcp): implement per-instance MCP registration and add minimal ESLint setup

4. 📚 Documentation

Key Changes:

• PRDs: Added detailed PRDs under dev-docs/mcp-ask-user-multi-instance/ documenting:
  • 01_PRD.md: Multi-instance MCP registration with namespaced servers (complex approach not implemented).
  • 02_PRD.md: Simpler CodeNomad-local per-instance config (the approach implemented).

Commits:

• feat(mcp): implement per-instance MCP registration and add minimal ESLint setup

5. 📦 Package Version Bump

Key Changes:

• Version Update: Bumped package versions to 0.9.2-patch.4 across all packages:
  • Root workspace package
  • Electron app package (@neuralnomads/codenomad-electron-app)
  • Server package (@neuralnomads/codenomad)
  • UI package (@codenomad/ui)
• Dependency Update: Updated @opencode-ai/plugin from 1.1.51 to 1.1.53 in opencode-config package.

Commits:

• chore: bump package versions to 0.9.2-patch.4 across all packages

📋 Checklist

• Per-instance MCP config files are created under ~/.codenomad/instances/<instanceId>/config.json
• Config writes are atomic (unique temp file names)
• Stale instances are cleaned up on startup (PID + /health probe)
• Auth token is not persisted to disk
• Legacy Antigravity ask-user entry is removed if present
• ESLint runs with warnings-only (no errors)
• TypeScript typecheck passes
• Build succeeds (npm run build)
• Binaries build successfully (npm run build:binaries)
• Session cache structure improvements are integrated
• Package versions are consistently bumped across all packages
• Dependency updates are properly reflected in lock files

🧪 Testing & Verification

Issue #23: Subagent Premium Consumption Fix

Test Case:

1. Send a prompt to main agent that triggers a subagent
2. Monitor premium request count
3. Expected: Only 1 premium request consumed (main agent prompt)
4. Actual Before Fix: 2+ premium requests consumed (main + subagent launch)
5. Actual After Fix: ✅ 1 premium request consumed

Verification:

• Session cache correctly stores parentID for subagent sessions
• message.updated events respect session.parentId filter in usage tracking
• No race condition between message.updated and session.updated events

Issue #24: ask_user Premium Consumption Fix

Test Case:

1. Send prompt that triggers subagent
2. Subagent calls ask_user to ask a question
3. Stay in main session (do NOT navigate to subagent session)
4. Answer the question in the UI
5. Monitor premium request count
6. Expected: 0 additional premium requests consumed
7. Actual Before Fix: ❌ 1 premium request consumed
8. Actual After Fix: ✅ 0 premium requests consumed

Verification:

• Questions are routed to correct instance queue
• No duplicate IPC listeners creating race conditions
• Answers are delivered via MCP IPC (zero-cost path)
• Session association is maintained across main and subagent instances