fix: add no-config debug opt-out and isolate initialization failures

[wenyt (wenytang-ms)]

Summary

Addresses the activation failure reported in #1689 and adds the requested option to disable No-Config Debug.

Previously, No-Config Debug created its endpoint directory under the extension installation directory. A filesystem error there could reject extension activation before the standard Java debugger was registered. This PR moves endpoint storage to workspace storage, isolates initialization failures, and makes the feature explicitly optional without changing its default behavior.

Changes

• Add java.debug.settings.enableNoConfigDebug: a boolean, default true, with window scope. It can be configured at user or workspace level.
• When disabled, skip No-Config Debug endpoint storage, file watching, Java executable detection, and wrapper permission setup. Remove only this feature's cached terminal environment contributions; do not clear the user's PATH or delete endpoint files as part of opting out.
• Share one activation-time setting snapshot with the AI debug_java_application tool. When disabled, the launch tool returns guidance before inspecting inputs, building, opening terminals, or stopping an existing debug session. Other AI session tools remain registered.
• Store endpoints under context.storageUri, requesting owner-only permissions for newly created POSIX endpoint directories. Keep bundled scripts under the extension installation directory.
• Isolate endpoint-directory, stale-file cleanup, and watcher-setup failures: clear cached feature environment contributions, log the error code without filesystem paths, and warn the user while allowing standard Java debugging to activate.
• Register endpoint listeners before publishing environment contributions or awaiting Java/script setup. Preserve diff-aware terminal environment updates across successful reloads.

Configuration and compatibility

To opt out, add this to user or workspace settings:

{
  "java.debug.settings.enableNoConfigDebug": false
}

Reload VS Code and recreate existing terminals after changing the setting. The value is captured once per activation, not toggled live; existing terminal processes retain their previous environment.

Standard Java launch/attach debugging, F5, and Run/Debug CodeLens remain available. The setting does not introduce automatic session termination or terminal closure.

Documentation

Update the root README.md in both the No-Config Debug and User Settings sections. Also update bundled/scripts/noConfigScripts/README.md, bundled/agents/README.md, and all existing package localization files to describe the opt-out, AI launch dependency, and reload/terminal requirements.

Validation

• npm run compile and targeted TSLint on the changed TypeScript files.
• Focused suites in a Windows VS Code 1.95.3 extension host: 48 passed, 1 POSIX-only test skipped. Coverage includes disabled initialization, cached environment cleanup, re-enabling, setting metadata/localization, AI launch refusal, storage failures, and listener timing.
• A separate bundled-extension probe with the setting disabled confirmed no endpoint directory/watcher setup, normal Java provider/command registration, and registration of all 10 AI tools. Editing the setting afterward did not override the captured AI launch opt-out. Java extension discovery and AI tool registration were stubbed in this probe.
• Earlier extension-host probes confirmed that injected EACCES did not prevent normal debugger registration and that a real VS Code watcher dispatched an attach request from workspace storage.

Scope and limitations

The reported ENOENT does not, by itself, prove a read-only filesystem. The reporter's NixOS environment and an actual JVM attach have not been exercised; endpoint-handoff probes used a stubbed attach API.

The opt-out addition does not change the startup cleanup sequence or introduce a request/recovery protocol. It does not claim to fix the previously discussed startup cleanup race.

Related to #1689.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🟡 Changes recommended

The watcher can miss endpoint events before its listeners are attached, leaving the JVM suspended.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Moves no-config debug endpoints to workspace storage and isolates initialization failures from standard Java debugging.

Changes:

• Adds workspace-isolated storage and failure cleanup.
• Restricts POSIX permissions and scopes endpoint watching.
• Adds regression tests, shared helpers, and migration documentation.

File summaries

File	Review
test/noConfigDebugStorage.test.ts	Adds storage, cleanup, failure, and attach coverage.
test/helpers/environmentVariableCollection.ts	Provides a shared environment collection fake.
test/envVarSync.test.ts	Reuses the shared test helper.
src/noConfigDebugInit.ts	Implements storage and failure isolation. Moderate: watcher listeners are attached after publishing the endpoint, allowing missed events. Attach them first and add a timing regression test.
src/extension.ts	Supplies workspace storage and handles unavailable registration.
bundled/scripts/noConfigScripts/README.md	Documents storage and migration behavior.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

The test collection fake does not compile without the required getScoped() method.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

The endpoint watcher race must be resolved before approval.

Review details

Suppressed comments (1)

src/noConfigDebugInit.ts:236

• A surviving terminal can recreate endpoint.txt after the awaited unlink removes the stale file but before the watcher becomes active. Because file watchers do not replay creations that occurred before registration, that endpoint can remain present without ever triggering an attach. Reconcile the file once after both listeners are installed; creations after watcher startup are still covered by the events.

    const fileCreationEvent = fileSystemWatcher.onDidCreate(handleEndpointFile);
    const fileChangeEvent = fileSystemWatcher.onDidChange(handleEndpointFile);

• Files reviewed: 6/6 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[wenyt (wenytang-ms)]

Regarding the startup reconciliation concern in the latest review: thanks for pointing this out. I agree that an endpoint written before the watcher becomes active could be missed.

This PR is focused on the activation failure reported in #1689: moving endpoint storage out of the extension installation directory and preventing no-config initialization failures from blocking standard Java debugging. The listener-order issue during asynchronous initialization has also been addressed in bb90ef5.

Startup reconciliation is a separate reliability improvement. I'd prefer to track it as a follow-up rather than expand the scope of this compatibility fix.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🔵 Needs a closer look

The endpoint cleanup and watcher startup race must be resolved before approval.

Review details

Suppressed comments (1)

src/noConfigDebugInit.ts:98

• A surviving terminal already has this stable endpoint path, so it can publish while this awaited cleanup is running. If it writes before unlink completes, the new endpoint is deleted as stale; if it writes after unlink but before the watcher is active, no event is observed. In either case the JVM remains suspended. Close this startup gap by registering observation before cleanup and explicitly reconciling endpoints created during cleanup (and add a regression that blocks unlink while publishing).

        await fs.promises.unlink(tempFilePath).catch((error: NodeJS.ErrnoException) => {
            if (error.code !== "ENOENT") {
                throw error;
            }
        });

• Files reviewed: 6/6 changed files
• Comments generated: 0 new
• Review effort level: Balanced