fix(vscode): self-heal a provisioned-but-unrunnable func Core Tools before blocking F5

[Brian Lam (lambrianmsft)]

Extracted from #9462. That PR is now fully superseded: the codeful design-time DLL-lock fix and the cross-platform codeful E2E coverage merged as #9463, and the Azurite startup-race fix is already on main (waitForAzuriteReady, ValidateEmulatorOptions, warnMissingAzureWebJobsStorage). The func Core Tools self-heal was the only piece left, so it ships here on its own, rebased on current main. #9462 is being closed as superseded.

Commit Type

• feature - New functionality
• fix - Bug fix
• refactor - Code restructuring without behavior change
• perf - Performance improvement
• docs - Documentation update
• test - Test-related changes
• chore - Maintenance/tooling

Risk Level

• Low - Minor changes, limited scope
• Medium - Moderate changes, some user impact
• High - Major changes, significant user/system impact

Why Medium: the code sits on preDebugValidate, which runs for every Logic Apps project (codeful and codeless), and it can trigger a managed-binaries reinstall on that path. It is tightly gated — see below — but reviewers should focus on the gating conditions.

What & Why

Nothing on the F5 path distinguished "func.exe exists on disk" from "func.exe actually runs".

preDebugValidate -> validateFuncCoreToolsInstalled -> isFuncToolsInstalled() spawns func --version. When that fails — because the extension-managed binaries are half-extracted, mid-reinstall, restored from a poisoned runtime-deps cache, or hang on Windows — the old fallback was the interactive modal:

You must have the Azure Functions Core Tools installed to debug your local functions.

That is a dead end for a user who is mid-provision (the binaries are being installed, they just aren't runnable yet), and it is unanswerable headlessly, so debug aborts or stalls.

1. Self-heal inside the managed-binaries validation path

validateFuncCoreToolsInstalled now keeps one branch per install path:

1. azureLogicAppsStandard.validateFuncCoreTools disabled -> installed,
2. existing runnable func -> installed,
3. extension-managed binaries -> validateFuncCoreToolsInstalledBinaries(...),
4. system/PATH install -> validateFuncCoreToolsInstalledSystem(...).

The managed-binaries validation branch first attempts a silent repair. It either waits for an existing in-flight install or reinstalls the managed binaries via installFuncCoreToolsBinaries, re-verifies func --version, and only falls back to the interactive modal when the repair still cannot produce a runnable func.

The self-heal is reached only when all of these hold, i.e. only in a state where debug was already going to dead-end:

1. azureLogicAppsStandard.validateFuncCoreTools is enabled, and
2. isFuncToolsInstalled() already returned false, and
3. useBinariesDependencies() is true — the extension owns these binaries.

System/PATH installs are deliberately untouched: we don't own those binaries and should not silently reinstall over them. That path still goes straight to the existing prompt.

2. Repair is silent through the existing telemetry/error-handling pattern

Andrew's review feedback pointed out that the first version added too much branch and option plumbing. The repair now runs in its own nested callWithTelemetryAndErrorHandling('azureLogicAppsStandard.repairFuncCoreTools', ...) scope with context.errorHandling.rethrow = true and context.errorHandling.suppressDisplay = true.

That removed the bespoke { suppressUi: true } path from installFuncCoreTools.ts and binaries.ts. The installer is now install-only: it logs to the output channel and preserves in-flight coalescing/serialization, but it no longer reveals the Output panel by itself. Output reveal and manual-install follow-up prompts are owned by explicit user-selected install branches.

downloadAndExtractDependency also no longer owns download/checksum/extract toasts. It logs, records telemetry, cleans up partials, and throws; callers decide whether the surrounding action should surface the error. Activation/background dependency failures therefore remain log/telemetry-only under their existing suppressDisplay=true scopes, while user-initiated func installs still get the manual-install prompt if the install fails.

3. The repair must not race a concurrent install

installFuncCoreToolsBinaries had no in-flight guard, and extractDependency deletes and recreates the shared target directory. A failing func --version is exactly what you observe while another install is mid-extract, so the repair could start a second install on top of the first and re-corrupt the tree.

installFuncCoreTools.ts now tracks the active install (isFuncCoreToolsInstallInFlight() / waitForFuncCoreToolsInstall(), mirroring the existing inFlightBundleWork precedent in bundleFeed.ts), coalesces an identical concurrent request, and serializes otherwise. The repair awaits an install that is already running instead of starting another.

4. A hanging func must not stall F5 either (found by the Windows E2E leg)

tryExecuteCommand only settles on 'close'/'error'. A managed func that hangs instead of exiting therefore stalled validateFuncCoreToolsInstalled indefinitely: the self-heal never ran, no modal appeared, nothing was logged, and F5 silently did nothing — strictly worse than the failure mode above. The spawned process also kept a handle on the binary, so the next attempt to replace it failed with EBUSY.

This is not hypothetical: it is what the new Windows E2E leg hit on its first run. The gate was reached, the deliberately corrupted func was never repaired, and the retry could not overwrite func.exe because it was still locked — which only something spawned from it could do, since the debug task never started.

New executeCommandWithTimeout in cpUtils terminates a command that outlives its budget. Commands are spawned with shell: true, so the tracked pid is the shell; on Windows the whole tree is taken down with taskkill (matching startDesignTimeApi / funcHostTask), because killing only the shell leaves the real command running and still holding its file handles. The func --version probe is bounded at 60s — generous enough that a slow first run (on-access AV scanning a freshly extracted binary) is not mistaken for a broken one — and a hang is treated exactly like a failure so the repair runs.

The probe failure reason is now logged. It was the only signal distinguishing "func is broken" from "the gate never ran" when debug appears to do nothing, and its absence is what made the first Windows failure undiagnosable from CI artifacts.

Telemetry records funcRepairAttempted, funcRepairSucceeded, funcRepairAwaitedExistingInstall, and funcRepairError on the nested repair telemetry scope.

Impact of Change

• Users: a partially-installed, not-yet-runnable, or hanging extension-managed func repairs itself instead of dead-ending F5 on a modal or stalling silently. When the repair succeeds, debug proceeds with no prompt at all. When it fails, behavior falls back to the same install/learn-more modal; user-selected install failures still show the manual-install follow-up.
• Developers: no public API changes. The repair is module-private and now lives in the managed-binaries validation flow. installFuncCoreToolsBinaries and downloadAndExtractDependency no longer expose bespoke UI-suppression options; callers own UI surfacing through telemetry/error-handling scopes and branch-local prompts.
• System: one additional installFuncCoreToolsBinaries call, only on the managed-binaries path and only when func --version has already failed. No new dependencies. .github/workflows/vscode-e2e.yml gains the two self-heal shards described below.

Test Plan

• Unit tests added/updated — validateFuncCoreToolsInstalled (repair succeeds -> returns true without prompting; repair runs but func still won't run -> falls back to the prompt; the reinstall itself throws -> telemetry records it and falls back; an in-flight install is awaited rather than duplicated; a timed-out probe still triggers the repair; the validateFuncCoreTools-disabled opt-out; nested repair telemetry sets rethrow=true and suppressDisplay=true; silent repair does not reveal the Output panel; user-selected install does reveal it and still prompts for manual install on failure). cpUtils covers Windows taskkill tree-kill and non-Windows SIGKILL, clean exits, non-zero exits, and that tryExecuteCommand stays unbounded. installRuntimeDependencies and binaries cover install coalescing/serialization and the new caller-owned UI behavior.
• E2E tests added/updated — new Phase 4.14 p414-funcrepair (funcRepair.test.ts): corrupts the managed func binary (containment-guarded, only ever writing under the resolved LA_E2E_RUNTIME_DEPS_ROOT), presses F5, and asserts the extension silently repairs it instead of showing the install modal, then restores. Runs on two CI shards — Linux (func-selfheal) and vscode-e2e-funcselfheal (windows-latest). A CI manifest guard fails the job rather than letting the test this.skip() into a vacuous pass.
• Tested in: pnpm exec biome check --write <changed files>; focused unit run (4 files / 130 tests passed); full apps/vs-code-designer unit suite (127 files / 1563 tests passed); E2E TypeScript compile (npx tsup --config tsup.e2e.test.config.ts). A repo-local tsc --noEmit -p apps/vs-code-designer/tsconfig.json run is not a clean validation signal in this worktree because it reports pre-existing unrelated extension typing errors outside the touched files.

E2E evidence

	Linux (func-selfheal)	Windows (vscode-e2e-funcselfheal)
Result	repaired=true, pastConnectionKeys=true	repaired=true, pastConnectionKeys=true, attempt 1/2
Time from gate to repaired	29s	76s

pastConnectionKeys=true is what proves the test is not passing vacuously: it confirms execution actually reached preDebugValidate (the gate under test) rather than succeeding somewhere upstream.

The Windows timing is itself the confirmation of part 4: 76s ~= the 60s bounded probe firing, plus the reinstall. Linux, where the corrupt binary fails fast rather than hanging, takes 29s. Before the bound existed, the same Windows scenario never repaired at all within a 300s budget.

Contributors

Brian Lam (@lambrianmsft) — reported the codeful F5 regression that surfaced this defect and directed splitting it out of #9462 once the design-time, Azurite, and cross-platform E2E work had merged, asked for Windows coverage, and requested Andrew's review feedback be addressed by simplifying the flow.
Andrew Eldridge (@andrew-eldridge) — review feedback that folded repair into managed-binaries validation and replaced bespoke UI-suppression options with the established telemetry/error-handling pattern.

Screenshots/Videos

N/A — no UI changes. The only user-visible difference is the absence of a modal when the silent repair succeeds.

[github-actions]

🤖 AI PR Validation Report

PR Review Results

Thank you for your submission! Here's detailed feedback on your PR title and body compliance:

✅ PR Title

• Current: fix(vscode): self-heal a provisioned-but-unrunnable func Core Tools before blocking F5
• Issue: None — valid fix: prefix with a scope, and clearly descriptive of the behavior change.
• Recommendation: No change needed.

---

✅ Commit Type

• Exactly one type selected: fix - Bug fix.
• Matches the title prefix and the nature of the change (self-heal for a broken F5 path).

---

✅ Risk Level

• Declared Medium in the body and labeled risk:medium — they agree. This matches my advised estimate: the change is confined to the VS Code extension distribution (apps/vs-code-designer) and sits on the preDebugValidate/F5 path with an added managed-binaries reinstall, which is Medium (shared/extension runtime, moderate user impact) — not High (no security/auth, credentials, breaking API, or core logic-apps-shared changes) and not Low (more than a single isolated component/config/CI-only tweak). Correct as declared.

---

✅ What & Why

• Current: Detailed explanation of the provisioned-but-unrunnable func failure mode and the four-part self-heal/gating/in-flight/timeout design.
• Issue: None — clear context and rationale, not a placeholder.
• Recommendation: No change needed.

---

✅ Impact of Change

• All three audiences addressed: Users (silent repair vs. dead-end modal), Developers (no public API changes, removed bespoke UI-suppression options), System (one extra install call on the managed path only, new CI shards).
• Recommendation:
  • Users: Already covered.
  • Developers: Already covered.
  • System: Already covered.

---

✅ Test Plan

• Both unit and E2E coverage present and confirmed in the diff: new/updated validateFuncCoreToolsInstalled, cpUtils, installRuntimeDependencies, binaries, and bundleFeed unit tests, plus the Phase 4.14 funcRepair.test.ts E2E and CI shards. Passes CHECK TESTS.

---

⚠️ Contributors

• Populated with Brian Lam (@lambrianmsft) and Andrew Eldridge (@andrew-eldridge) and their contributions. Good — no action needed.

---

✅ Screenshots/Videos

• N/A is appropriate: the diff touches only apps/vs-code-designer (extension host + CI + tests), not libs/designer-ui/src, libs/designer/src, or apps/vs-code-react UI components, and there is no visual change. No screenshot required.

---

Summary Table

Section	Status	Recommendation
Title	✅	No change needed
Commit Type	✅	No change needed
Risk Level	✅	Medium is correct (extension/runtime, F5 path)
What & Why	✅	No change needed
Impact of Change	✅	No change needed
Test Plan	✅	No change needed
Contributors	⚠️	Already credited — optional
Screenshots/Videos	✅	N/A is appropriate (no UI change)

---

All checks pass. Title, commit type, risk level (declared Medium matches the advised estimate and the risk:medium label), What & Why, Impact, and Test Plan are all compliant. Approved for merge.

---

Powered by: Copilot CLI (claude-opus-4.8) | Last updated: Mon, 10 Aug 2026 20:15:56 GMT

[Copilot]

Pull request overview

Adds automatic repair of extension-managed Azure Functions Core Tools before blocking F5 debugging.

Changes:

• Reinstalls and revalidates unrunnable managed Core Tools.
• Records repair telemetry and preserves prompt fallback behavior.
• Adds unit coverage for repair outcomes and validation opt-out.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
validateFuncCoreToolsInstalled.ts	Adds managed Core Tools self-repair.
validateFuncCoreToolsInstalled.test.ts	Tests repair and disabled-validation paths.

[Brian Lam (lambrianmsft)]

Added E2E coverage for the self-heal

Up to now this PR was proven only by unit tests. There was no end-to-end coverage of the behavior at all — funcVersionRuns() in runtimeBinaryCheck.ts is a harness precondition gate that quietly waits for the self-heal, so it consumes the fix rather than proving it, and nothing deliberately broke func and asserted recovery.

953fb1be4 adds scenario p414-funcrepair (Phase 4.14, apps/vs-code-designer/src/test/ui/funcRepair.test.ts).

What it does

1. Waits for the managed install and for two consecutive successful func --version probes. The second probe is the point — it proves activation-time validation has settled, so the repair observed later can't be attributed to it.
2. Backs up and overwrites every managed func executable in place with a short marker line. Each file still exists and keeps its .exe extension and execute bit, but no longer runs — the actual poisoned runtime-dependency cache state this PR exists to handle, not a mock.
3. Presses F5, which routes through pickFuncProcessInternal → preDebugValidate → validateFuncCoreToolsInstalled — the only caller of the gate.
4. Asserts recovery.

Assertions

Kind	Assertion
Hard	The blocking "You must have the Azure Functions Core Tools installed" prompt never appears. The watch loop breaks early if it does, so a real regression fails in seconds rather than burning the timeout.
Hard (primary)	func --version runs again — disk-level, modeled on waitForBundleRepaired.
Hard	The repaired file no longer holds the marker bytes, catching a probe that resolved some other func.
Hard (liveness)	The workbench scrape returned text at least once, so the negative assertion above can't pass vacuously.
Soft	No Error downloading the / Checksum verification failed / could not be installed at toast — the user-visible half of { suppressUi: true }. Non-fatal for the same reason waitForRepairNotification in bundleRepair.test.ts is: toast timing is racy and the disk signal is authoritative.

Two details worth calling out

The corruption marker is deliberately non-empty and has no leading #. glibc's execvp falls back to /bin/sh on ENOEXEC, so an empty or comment-only file would exit 0 on Linux and the whole scenario would pass while proving nothing. The test asserts func --version actually fails after the write, so a platform that ever disagrees fails loudly instead of silently going green.

Writes are guarded by a containment check against the managed FuncCoreTools directory, and afterEach restores the original bytes wherever the repair didn't already replace them — a mid-test failure can't poison the shared runtime-dependency cache for sibling scenarios. run-e2e.ts now publishes the resolved dependency root as LA_E2E_RUNTIME_DEPS_ROOT (the same mechanism lspeperm already uses) so the test targets what the harness actually wrote rather than guessing a path.

What this does not cover: the concurrent-install guard from #discussion_r3680448234. Two installs racing isn't deterministically reproducible through the UI — forcing the interleaving would mean driving the internals directly, at which point it's a unit test wearing an E2E costume. The 5 tests in installRuntimeDependencies.test.ts remain the proof there.

CI runs this on its own func-selfheal shard rather than folding it into suite-and-bundle: it's the only scenario that downloads the Func Core Tools package twice, so with LA_E2E_SCENARIO_RETRIES=1 it risked pushing a retried shard past that job's 35-minute budget.

[Brian Lam (lambrianmsft)]

Windows E2E coverage — and the bug it found

Following up on the Linux-only coverage above: p414-funcrepair now also runs as its own blocking shard, vscode-e2e-funcselfheal (windows-latest). That mattered more than expected — it failed on its first run, and the failure was real, not harness flake.

The gate was reached (refreshConnectionKeys returned), but the corrupted func was never repaired, no install modal appeared, and the extension logged nothing at all for the full 300s budget. The decisive clue was the retry: its corruption step failed EBUSY because func.exe was still locked. The debug task never started, so the only thing that could have created that lock was the func --version probe itself — i.e. the probe spawned a process that never exited.

Root cause: tryExecuteCommand only settles on 'close'/'error', so a func that hangs instead of exiting stalls validateFuncCoreToolsInstalled forever. The self-heal never gets a chance to run, and F5 silently does nothing — strictly worse than the failure mode this PR set out to fix, and a mode that skews Windows-heavy (AV quarantine / partial extraction leaving a non-PE func.exe).

Fixed in 5ca5fddc9 by bounding the probe (executeCommandWithTimeout, killing the process tree on Windows since shell: true means the tracked pid is only the shell) and treating a hang exactly like a failure. Both platforms are green now:

	Linux (func-selfheal)	Windows (vscode-e2e-funcselfheal)
Result	repaired=true, pastConnectionKeys=true	repaired=true, pastConnectionKeys=true, attempt 1/2
Gate → repaired	29s	76s

The Windows timing is itself the confirmation: 76s ≈ the 60s bound firing plus the reinstall, versus 29s on Linux where the corrupt binary fails fast. pastConnectionKeys=true is what rules out a vacuous pass — it proves execution actually reached preDebugValidate rather than succeeding upstream.

Also added the log line that made this diagnosable at all. Its absence is why the first Windows failure was invisible in CI artifacts, and it is the same signal a user needs when debug "does nothing".

One scope note for reviewers: the concurrency guard from #discussion_r3680448234 is still proven by unit tests only — it is a same-process race that the E2E harness cannot deterministically induce.

[Andrew Eldridge (andrew-eldridge)]

One general note: I noticed in multiple places throughout vscode extension we have closely related/coupled functions, some of which could even be combined and simplified, spread across multiple different files which makes it harder to see the full picture. I think this applies to installFuncCoreTools.ts and validateFuncCoreToolsInstalled.ts here for example

[Brian Lam (lambrianmsft)]

Addressed the simplification pass in f7738b8. I kept install mechanics in installFuncCoreTools.ts and validation policy in validateFuncCoreToolsInstalled.ts, but tightened the coupling points: repair now lives in the managed-binaries validation flow, install/download helpers no longer carry UI-suppression options, and user-facing prompts are branch-local where the selected action is known. That keeps the file ownership split while making the F5 path readable as one validation decision tree.