kandev/docs/plans/windows-managed-runtime-missing-cache-tree/plan.md

created, status, requirements, system_design, legacy_specs

created	status	requirements	system_design	legacy_specs
2026-08-27	done	REQ-AGENTS-MANAGED-RUNTIME-RECOVERY-001 REQ-AGENTS-MANAGED-RUNTIME-RECOVERY-002	../../specs/agents/system-design/managed-npm-runtime-recovery.md

Implementation Plan: Windows Managed Runtime Missing Cache Tree

Overview

Correct Windows cache repair when the npm _npx directory exists but the derived execution-tree directory does not exist. One work order owns the native-error classification, the Windows regression test, and Windows CI coverage.

Confirmed root cause

openManagedRuntimeHandle calls windows.NtCreateFile. This function returns a windows.NTStatus for a missing child. The three callers compare this value directly with Win32 syscall.Errno values through errors.Is.

windows.NTStatus does not implement Is or Unwrap. As a result, the comparison fails for STATUS_OBJECT_NAME_NOT_FOUND and STATUS_OBJECT_PATH_NOT_FOUND. The cache repair returns an error instead of treating the missing execution tree as an idempotent result.

The existing os.Lstat check only covers a missing _npx directory. It does not cover a missing _npx/<key> directory. It also separates the path check from the handle open.

Scope

In scope

• Classify Win32 and NT status not-found errors through one Windows helper.
• Use the helper for the cache-root, _npx, and execution-tree opens.
• Remove the separate _npx os.Lstat check.
• Add a native Windows regression for an existing _npx directory with an absent execution-tree key.
• Add the focused regression to the repository Windows test target and CI job.

Out of scope

• Make all cache-repair errors best-effort in the lifecycle manager.
• Change recovery classification, retry count, or command construction.
• Add new agentctl error details or managed-runtime stderr logs.
• Remove cached npm packument metadata or other global npm cache data.
• Change Unix cache deletion.

Technical approach

Add a small helper in apps/backend/internal/agent/managedruntime/cache_windows.go. The helper will keep the existing Win32 error comparisons. It will also extract a windows.NTStatus with errors.As and convert it with NTStatus.Errno().

Use this helper after each NtCreateFile-based directory open. A missing cache root, _npx directory, or exact execution tree will return success. All other errors will keep their current wrapped error and fail-closed behavior.

Remove the _npx os.Lstat check. The handle-relative open and shared error classifier will provide the same idempotent result without a separate path check.

Add a Windows-only test file that creates the cache root and _npx directory. The test will leave the derived key absent and call the public removal helper. Before the correction, the test returns Object Name not found.. After the correction, the call returns nil.

Add the focused test to test-windows in apps/backend/Makefile and to the Windows backend workflow. This package has Windows-specific code but is not in the current native Windows test list.

Tests

• AC-AGENTS-MANAGED-RUNTIME-RECOVERY-001.3: TestRemoveNpxExecutionTreeTreatsMissingWindowsChildAsAbsent proves that an absent execution tree does not block the online retry.
• AC-AGENTS-MANAGED-RUNTIME-RECOVERY-002.2: The existing exact-key deletion test continues to prove that repair removes only the derived execution tree.
• AC-AGENTS-MANAGED-RUNTIME-RECOVERY-002.4: Existing symlink and unsafe-spec tests continue to prove fail-closed path handling.

Work orders

• [done] Task 01: Correct Windows Missing-Tree Detection

Verification results

• RED evidence: issue #3092 includes a native Windows probe that returns Object Name not found. for the absent child. The Linux executor cannot run the Windows-only regression before the correction.
• go test ./internal/agent/managedruntime passed with 36 tests.
• The Windows managed-runtime test binary compiled for windows/amd64 with CGO_ENABLED=0.
• make -n test-windows includes the exact managed-runtime regression command.
• python3 scripts/lint-spec-files.py --all passed.
• The native Windows race test remains a CI check because this executor runs Linux.

Risks

• The NT status conversion must not classify access, reparse-point, or sharing errors as absence.
• The regression needs a native Windows runner. A cross-compiled test binary proves compilation only.
• The Make target and CI workflow must use the same focused Windows test.