clusterflux-public/docs/debugging.md

Debugging

The VS Code extension uses the Debug Adapter Protocol and the coordinator's authoritative process, task, attempt, and Debug Epoch APIs.

Launch

Open your project and start "Clusterflux: Launch Virtual Process". The adapter builds the bundle, launches the selected entrypoint, and replaces its thread view with coordinator task snapshots. Product mode does not infer threads from completion events or demo fixtures.

Each task view includes its logical task, attempt ID, definition, state, node, environment, arguments, typed handles, command status, VFS checkpoint, probe source when known, and restart compatibility. Unknown source remains unknown.

Breakpoints and Debug Epochs

When a breakpoint is hit, the coordinator asks every active participant to freeze. A fully frozen epoch is a consistent all-participant view.

If one or more participants cannot freeze within five seconds, the epoch becomes partially frozen when at least one participant did freeze. The adapter warns that running and frozen tasks do not form a consistent global snapshot. You may inspect the acknowledged participants and resume them cleanly. Missing or failed participants remain explicit.

Stack frames, Wasm locals, task arguments, handles, command status, and output come from runtime acknowledgements. No frame or value is fabricated when the runtime did not report it.

Continue and restart

Continue resumes only participants that acknowledged the freeze.

Restarting a terminal task rebuilds the bundle and checks its clean entry checkpoint. A compatible restart creates a new attempt under the same logical task identity. Earlier attempt history remains inspectable, and the logical join continues. An active task or an incompatible boundary requires a whole-process restart.

Source stepping is not simulated. Unsupported stepping fails explicitly.