Module CocoonManagement 

Cocoon Management

This module provides comprehensive lifecycle management for the Cocoon sidecar process, which serves as the VS Code extension host within the Mountain editor.

Overview

Cocoon is a Node.js-based process that provides compatibility with VS Code extensions. This module handles:

• Process Spawning: Launching Node.js with the Cocoon bootstrap script
• Environment Configuration: Setting up environment variables for IPC and logging
• Communication Setup: Establishing gRPC/Vine connections on port 50052
• Health Monitoring: Tracking process state and handling failures
• Lifecycle Management: Graceful shutdown and restart capabilities
• IO Redirection: Capturing stdout/stderr for logging and debugging

Process Communication

The Cocoon process communicates via:

• gRPC on port 50052 (configured via MOUNTAIN_GRPC_PORT/COCOON_GRPC_PORT)
• Vine protocol for cross-process messaging
• Standard streams for logging (VSCODE_PIPE_LOGGING)

Dependencies

• scripts/cocoon/bootstrap-fork.js: Bootstrap script for launching Cocoon
• Node.js runtime: Required for executing Cocoon
• Vine gRPC server: Must be running on port 50051 for handshake

Error Handling

The module provides graceful degradation:

• If the bootstrap script is missing, returns FileSystemNotFound error
• If Node.js cannot be spawned, returns IPCError
• If gRPC connection fails, returns IPCError with context

Module Contents

• InitializeCocoon: Main entry point for Cocoon initialization
• LaunchAndManageCocoonSideCar: Process spawning and lifecycle management

Example

use crate::Source::ProcessManagement::CocoonManagement::InitializeCocoon;

// Initialize Cocoon with application handle and environment
match InitializeCocoon(&app_handle, &environment).await {
	Ok(()) => println!("Cocoon initialized successfully"),
	Err(e) => eprintln!("Cocoon initialization failed: {:?}", e),
}

Structs

COCOON_HEALTH 🔒

COCOON_STATE 🔒

CocoonProcessState 🔒

Global state for tracking Cocoon process lifecycle

Constants

BOOTSTRAP_SCRIPT_PATH 🔒

COCOON_BUNDLE_PROBE 🔒

Relative path from the resolved Cocoon package root to the bundled entry module. Used by the pre-flight guard below to fail fast with an actionable error when the bundle is missing (esbuild failure, partial rm -rf, freshly cloned checkout without pnpm run prepublishOnly, etc.) instead of spawning Node into a dying require() chain.

COCOON_GRPC_PORT 🔒

COCOON_SIDE_CAR_IDENTIFIER 🔒

Configuration constants for Cocoon process management

GRPC_CONNECT_BUDGET_MS 🔒

GRPC_CONNECT_INITIAL_MS 🔒

Exponential-backoff retry parameters for the Mountain → Cocoon gRPC handshake. Replaces the previous “20 × 1000 ms fixed poll” which under-probed the common race (Cocoon’s stage2 binds the port at ~200 ms so attempts 1-2 fail and we sat idle through 18 more whole- second sleeps) and over-waited the real failure (when Cocoon is genuinely dead, we wasted 20 s before reporting).

GRPC_CONNECT_MAX_DELAY_MS 🔒

HANDSHAKE_TIMEOUT_MS 🔒

HEALTH_CHECK_INTERVAL_SECONDS 🔒

MAX_RESTART_ATTEMPTS 🔒

MOUNTAIN_GRPC_PORT 🔒

RESTART_WINDOW_SECONDS 🔒

Statics

COCOON_PID 🔒

Last-known PID of the Cocoon child process. Mirrored here so callers can read it without taking the async COCOON_STATE mutex (e.g. from IPC handlers such as extensionHostStarter:start). Set after spawn and cleared on shutdown. 0 means “not running”.

Functions

FindMatchingWorkspaceContainsPatterns 🔒

Return the subset of Patterns for which at least one workspace folder contains a matching file or directory. Patterns are interpreted the same way VS Code does for workspaceContains:<pattern> activation events:

GetCocoonPid

Return the Cocoon child process’s OS PID, or None if Cocoon has not been spawned (or has exited).

HardKillCocoon

Atom I6: post-shutdown hard-kill. Called by RuntimeShutdown after the $shutdown gRPC notification has been sent (and either succeeded or timed out). Grabs the stored Child handle and force-terminates it if still alive, then resets COCOON_STATE. This plugs the “Mountain exits cleanly but child stays running” leak that leads to zombie-Cocoon zombies holding the gRPC port.

InitializeCocoon

The main entry point for initializing the Cocoon sidecar process manager.

LaunchAndManageCocoonSideCar 🔒

Spawns the Cocoon process, manages its communication channels, and performs the complete initialization handshake sequence.

PatternMatchesAnyEntry 🔒

Very small glob-matcher scoped to VS Code workspaceContains: syntax. Supports literal paths, * (one path segment), and ** (zero or more segments). Case-sensitive per the VS Code spec.

SegmentMatch 🔒

SingleSegmentMatch 🔒

SweepStaleCocoon 🔒

Atom I6: pre-boot sweep. TCP-probe the Cocoon gRPC port and kill any stale process still bound to it. Prevents the EADDRINUSE cascade that leaves the extension host in degraded mode when a prior Mountain exited without cleaning up its child.

monitor_cocoon_health_task 🔒

Background task that monitors Cocoon process health and logs crashes.