feat(debug): add interactive sessions

[pocky]

Summary

• Add opt-in interactive debugging support through a bundled native debug sidecar extension backed by Debug Adapter Protocol sessions.
• Introduce validated [debug.<language>] configuration and pass per-extension initialization payloads into sidecars.
• Extract shared sidecar JSON-RPC harness logic so lint, LSP, and debug extensions handle HostCall response waits without dropping inbound host requests.
• Document the new debug tool surface and add deterministic e2e coverage with a fixture debug adapter.

Changes

Workspace and Build

• .gitignore: Keep the repository-level debug/ ignore while allowing extensions/debug/ to be tracked.
• Cargo.toml: Add extension_sidecar_harness, extensions/debug, and extensions/fixtures/debug_adapter to workspace members and default members.
• Cargo.lock: Lock new debug extension, debug adapter fixture, and sidecar harness packages.
• crates/core_engine/Cargo.toml: Add extension_sidecar_harness as a dev dependency for protocol and e2e tests.
• extensions/lint/Cargo.toml: Add dependency on the shared sidecar harness.
• extensions/lsp/Cargo.toml: Add dependency on the shared sidecar harness.

Debug Configuration and Registration

• crates/core_engine/src/adapters/config/debug.rs: Add validated debug language configuration parsing, initialization payload generation, and config unit tests.
• crates/core_engine/src/adapters/config/mod.rs: Expose DebugConfig and include [debug] in TowerConfig.
• crates/core_engine/src/adapters/daemon/engine.rs: Pass extension init configs, register the bundled debug extension when debug config is present, and resolve the debug sidecar binary.
• crates/core_engine/src/adapters/extension/discovery.rs: Add extension init config mapping and thread it through extension discovery.
• crates/core_engine/src/adapters/extension/host_deps.rs: Extend host dependencies needed by the debug extension path.
• crates/core_engine/src/adapters/extension/mod.rs: Re-export extension initialization configuration support.
• crates/core_engine/src/adapters/extension/sidecar.rs: Send extension-specific initialize payloads and tighten sidecar cleanup behavior.
• crates/core_engine/src/adapters/extension/supervisor.rs: Store and forward initialize config into supervised sidecar processes.
• crates/core_engine/src/adapters/mcp/extension_merged_registry.rs: Preserve extension-provided debug tools in the merged MCP registry.

Debug Extension

• extensions/debug/Cargo.toml: Add the native debug sidecar crate.
• extensions/debug/extension.toml: Define debug extension metadata, activation, and contributed tower_debug_* tools.
• extensions/debug/src/dap.rs: Implement DAP framing, request/response correlation, events, timeout handling, and adapter communication.
• extensions/debug/src/main.rs: Add the debug sidecar entrypoint, initialization flow, tool dispatch, and sidecar harness integration.
• extensions/debug/src/process.rs: Manage debug adapter child process startup, shutdown, and cleanup.
• extensions/debug/src/protocol.rs: Define sidecar protocol helpers and initialization config parsing for debug sessions.
• extensions/debug/src/session.rs: Add session lifecycle management, breakpoints, stepping, pause/resume, variable inspection, and cleanup.
• extensions/debug/src/tools.rs: Implement debug MCP tool request parsing, validation, dispatch, and JSON-RPC error mapping.
• extensions/debug/src/types.rs: Define debug session, breakpoint, stack frame, scope, variable, stop, and output DTOs.

Shared Sidecar Harness

• crates/extension_sidecar_harness/Cargo.toml: Add the shared harness crate manifest.
• crates/extension_sidecar_harness/src/jsonrpc.rs: Add JSON-RPC envelope parsing, response writing, HostCall handling, and queued inbound-frame support.
• crates/extension_sidecar_harness/src/lib.rs: Expose shared sidecar JSON-RPC helpers.
• crates/extension_protocol/src/lib.rs: Export updated protocol initialization types.
• crates/extension_protocol/src/messages.rs: Add extension initialization config payload support.
• crates/extension_protocol/tests/protocol_tests.rs: Cover initialize config serialization and validation contracts.

Lint and LSP Harness Migration

• extensions/lint/src/lib.rs: Expose lint protocol components required by the harness migration.
• extensions/lint/src/main.rs: Move lint sidecar dispatch onto the shared harness.
• extensions/lint/src/protocol.rs: Replace local protocol loop behavior with shared harness-compatible helpers.
• extensions/lint/tests/protocol_tests.rs: Update lint protocol tests for the harness-backed behavior.
• extensions/lsp/src/main.rs: Move LSP sidecar dispatch onto the shared harness.
• extensions/lsp/src/protocol.rs: Replace local protocol loop behavior with shared harness-compatible helpers and queued-frame handling.
• extensions/lsp/src/push.rs: Adjust push forwarding for the shared protocol loop.
• extensions/lsp/src/tools.rs: Update LSP tool dispatch and error handling for harness integration.

Tests and Fixtures

• crates/core_engine/src/adapters/extension/supervisor_tests.rs: Update supervisor tests for initialize config and cleanup behavior.
• crates/core_engine/src/adapters/extension/tests.rs: Add discovery, initialization payload, disabled extension, and sidecar registration coverage.
• crates/core_engine/tests/extension_ast_e2e.rs: Update AST extension e2e setup for the shared extension loading path.
• crates/core_engine/tests/extension_debug_e2e.rs: Add debug extension e2e coverage for registration, launch, stack, scopes, variables, breakpoints, continue, output, and termination.
• crates/core_engine/tests/extension_fmt_e2e.rs: Update format extension e2e setup for the shared extension loading path.
• crates/core_engine/tests/extension_lint_e2e.rs: Update lint e2e coverage for harness-backed sidecar behavior.
• crates/core_engine/tests/extension_lsp_process_e2e.rs: Add LSP process and queued-frame regression coverage.
• crates/core_engine/tests/functional_lint_fix_mcp.rs: Update functional lint fix setup for extension registry changes.
• crates/core_engine/tests/functional_lint_mcp.rs: Update functional lint setup for extension registry changes.
• extensions/fixtures/debug_adapter/Cargo.toml: Add deterministic debug adapter fixture crate.
• extensions/fixtures/debug_adapter/src/main.rs: Implement a fixture DAP adapter for repeatable debug extension e2e tests.

Documentation and Project Knowledge

• README.md: Add interactive debugging to the feature list, crate layout, and documentation index.
• docs/README.md: Link debug session user documentation.
• docs/architecture.md: Document the debug extension and sidecar harness additions in the architecture overview.
• docs/extensions.md: Update extension authoring guidance for initialization config and shared sidecar harness behavior.
• docs/mcp-tools.md: Document the tower_debug_* MCP tools, request shapes, responses, and errors.
• docs/user-guide/debug-sessions.md: Add a user guide for configuring and driving interactive debug sessions.
• .zpm/kb/feedback/journal.wal: Record reusable project rules learned during F004 implementation and review remediation.

Test plan

• Run cargo fmt --check
• Run cargo clippy --workspace --all-targets -- -D warnings
• Run cargo build --workspace --bins
• Run cargo test --workspace

Closes #8

---

Generated with awf commit workflow