Harden inline script cache lifecycle coordination

[Stella Huang (StellaHuang95)]

Context

Inline-script environments live in a shared extension cache that may be accessed by more than one extension host. Clearing that cache is destructive and must coordinate with lock recovery, persistent-state clears, and inline association persistence.

The dedicated inline clear command remains hidden behind the undeclared, default-off inline-script flag and is not contributed to the Command Palette.

What changed

This PR is scoped to three coordinated hardening changes:

1. Atomic canonical lock retirement on release (src/common/lockfile.apis.ts) — release() renames the owner marker to a transient .release-* marker and atomically renames the lock directory to a .retired-* sibling before cleaning it up out of band. Transient EPERM/EBUSY/EACCES retirement failures retry while ownership is retained; a terminal failure restores ownership and throws ELOCKRELEASEFAILED. Lock inspection recognizes the transient .release-* marker and tolerates the directory being retired between lstat and readdir.

2. Serialized persistent-state clears (src/common/persistentState.ts) — every clear request is serialized through a failure-isolated queue tail, each request's key options are preserved, and clearPersistentState gains preserveWorkspaceKeys/preserveGlobalKeys (ClearPersistentStateOptions).

3. Generic Clear Cache preserves the inline association key (src/common/constants.ts, src/features/envCommands.ts, src/extension.ts, and an import-only move of INLINE_SCRIPT_ENVS_KEY in the inline-script manager) — python-envs.clearCache now routes through clearEnvironmentCachesCommand, which preserves the inline association workspace-state key (built on the serialized-clear preserveKeys plumbing from change 2) while retaining existing behavior for all other state and managers.

Behavior and compatibility

• No setting, command, menu, view, or status-bar contribution is added.
• Default-off users do not register the inline manager or dedicated command.
• Generic clear continues clearing existing non-inline managers and state. The only inline-specific difference is that dormant associations are no longer forgotten while their cache directories remain.
• Production lock API callers remain confined to the hidden inline manager.

Reviewer guide

1. Review release-side lock retirement, ownership restoration, and inspection tolerance in lockfile.apis.ts.
2. Review persistent-clear serialization and preserved keys in persistentState.ts.
3. Review generic clear routing and inline-association preservation (envCommands.ts, extension.ts, constants.ts).

Validation

• npm run compile-tests
• npm run compile
• npm run lint
• Unit suite: 1844 passing

Note: This PR was reduced in scope from an earlier revision. Root-generation/admission changes, reclaim-side lock retirement, workspace-root settings protection, create-counting order, and the typed generic-inline unsupported error were reverted to the base; the net diff now covers only the three changes above.

[Heejae Chang (heejaechang)]

🔒 Automated review in progress — Heejae Chang (@heejaechang) is auto-reviewing this PR.

[Heejae Chang (heejaechang)]

Verification: The relevant tests could not be fully run in the isolated environment; this review is not fully verified.

[Heejae Chang (heejaechang)]

Approved via Review Center.

[Heejae Chang (heejaechang)]

Verification: The relevant tests could not be fully run in the isolated environment; this review is not fully verified.

[Heejae Chang (heejaechang)]

Verification: The relevant tests could not be fully run in the isolated environment; this review is not fully verified.

[Heejae Chang (heejaechang)]

Verification: The relevant tests could not be fully run in the isolated environment; this review is not fully verified.

[Heejae Chang (heejaechang)]

Verification: The relevant tests could not be fully run in the isolated environment; this review is not fully verified.

[Heejae Chang (heejaechang)]

Verification: The relevant tests could not be fully run in the isolated environment; this review is not fully verified.

[Heejae Chang (heejaechang)]

Issue · Please address or respond

This is still a coalescing gate rather than a failure-isolated queue: concurrent callers await the first request and their own keys/preservation options are never applied. More importantly, if any momento.update rejects, this.clearing.resolve() is skipped, leaving the deferred pending so every later clear() waits forever. Queue each captured request independently and ensure a failed request cannot block later clears.

[Stella Huang (StellaHuang95)]

You're right on both counts: the shared PersistentState.clear() is a coalescing gate, and a rejected Memento.update skips this.clearing.resolve(), leaving the deferred pending so every later clear() waits forever. Rather than reshape that shared implementation in this PR, I've taken the PR out of it entirely.

• src/common/persistentState.ts is now reverted to base — this PR has no production diff in that file. Its general coalescing/wedge defect is unchanged and explicitly out of scope for this inline-only PR (happy to track it separately).
• Inline PEP 723 associations moved to a new inline-owned, Memento-backed InlineScriptAssociationStore that owns only INLINE_SCRIPT_ENVS_KEY. It has its own failure-isolated FIFO queue: each caller awaits its own enqueued operation and receives that operation's success/failure, and a rejected op still advances the tail (this.tail = run.then(ok, ignore)) so a failed read/write/delete can't block later inline operations. The store never awaits the shared clear() deferred, so a wedged generic clear cannot stall inline work.
• Generic "Clear Cache" no longer needs any preserve option in shared code: at the command it reads the current workspace keys from the Memento, excludes INLINE_SCRIPT_ENVS_KEY, and calls the existing PersistentState.clear(explicitKeys) plus the existing global clear(). Generic clear and the inline store are key-disjoint (generic clears every key except the inline key; the store touches only the inline key), so neither can drop the other, and the dedicated inline delete is a queued direct update of that one key.

Net: this PR leaves the shared clear() behavior untouched, and inline association reliability no longer depends on it.

[Heejae Chang (heejaechang)]

Verification: The relevant tests could not be fully run in the isolated environment; this review is not fully verified.

Result: could-not-verify

Summary: No meaningful test execution was possible because the verification container could not start and local execution was not authorized. The PR adds 14 targeted unit tests covering lock retirement, persistent-state clearing, generic cache clearing, and inline persistence coordination. Their pass/fail status remains unverified.

Test runs: 2 not run

• ⚠️ Not run | Lockfile and persistent-state unit suites | npm run compile-tests && npm run unittest -- --grep "(lockfile APIs|persistent state clearing)"
• ⚠️ Not run | Environment cache command and inline manager unit suites | npm run compile-tests && npm run unittest -- --grep "(Clear Environment Caches Command Tests|InlineScriptEnvManager)"

⚠️ Lockfile and persistent-state unit suites diagnostic output

Container verification could not start: no trusted sandbox image is configured for microsoft/vscode-python-environments; local execution was not authorized.

⚠️ Environment cache command and inline manager unit suites diagnostic output

Container verification could not start: no trusted sandbox image is configured for microsoft/vscode-python-environments; local execution was not authorized.

[Heejae Chang (heejaechang)]

Verification: The relevant tests could not be fully run in the isolated environment; this review is not fully verified.

Result: could-not-verify

Summary: No tests could execute because the verification container failed to start: no trusted sandbox image is configured for this repository, and local execution was not authorized. The PR adds 19 targeted unit tests covering lock retirement, cache preservation, and inline association serialization. Because no meaningful test command ran, the verdict is **could-not-verify**.

Test runs: 1 not run

• ⚠️ Not run | Targeted test discovery and dependency check | git status --short && git branch --show-current && git --no-pager diff --name-status upstream/main...HEAD && node -e "const p=require('./package.json'); console.log(JSON.stringify({scripts:p.scripts,devDependencies:p.devDependencies&&{mocha:p.devDependencies.mocha,tsnode:p.devDependencies['ts-node']}},null,2))" && if [ -f .github/instructions/testing-workflow.instructions.md ]; then sed -n '1,220p' .github/instructions/testing-workflow.instructions.md; fi && printf '\nNODE_MODULES=' && if [ -d node_modules ]; then echo present; else echo missing; fi && printf 'PROFILE=%s\n' "${AUTOMATION_SANDBOX_PROFILE:-}" && find src/test -type f ( -name 'lockfiletest.ts' -o -name 'envCommandstest.ts' -o -name 'associationStoretest.ts' -o -name 'inlineScripttest.ts' ) -print

⚠️ Targeted test discovery and dependency check diagnostic output

Container verification could not start and local execution was not authorized for this PR HEAD: No trusted sandbox image is configured for microsoft/vscode-python-environments.