kandev/docs/plans/windows-managed-runtime-missing-cache-tree/task-01-correct-windows-missing-tree-detection.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
01-correct-windows-missing-tree-detection	Correct Windows missing-tree detection	done	1		plan.md	REQ-AGENTS-MANAGED-RUNTIME-RECOVERY-001 REQ-AGENTS-MANAGED-RUNTIME-RECOVERY-002	AC-AGENTS-MANAGED-RUNTIME-RECOVERY-001.3 AC-AGENTS-MANAGED-RUNTIME-RECOVERY-002.2 AC-AGENTS-MANAGED-RUNTIME-RECOVERY-002.4	../../specs/agents/system-design/managed-npm-runtime-recovery.md

Task 01: Correct Windows Missing-Tree Detection

Summary

Treat native Windows not-found status values as an absent managed-runtime cache tree. Add focused native Windows coverage so the recovery path cannot return an HTTP 500 for this state.

In scope

• Add one helper that recognizes Win32 and converted NT status not-found errors.
• Use the helper for all three directory opens in the Windows cache remover.
• Remove the separate _npx path precheck.
• Add the missing-child regression to the managed-runtime package.
• Run the regression in the Make target and Windows CI job.

Out of scope

• Changes to lifecycle recovery policy, retry construction, error payloads, logging, Unix behavior, or npm metadata storage.
• Changes that convert unrelated cache-repair errors into successful results.

Acceptance

• If the cache root and _npx directory exist but the derived key does not, cache repair returns nil on Windows.
• If NtCreateFile reports another error, cache repair keeps the current fail-closed behavior and error context.
• The repository Windows test target and CI job run the focused regression.

Verification

Run the new regression on Windows before the production change. Make sure that it fails with Object Name not found.. After the correction, run:

# From apps/backend on Windows:
rtk go test -race -v ./internal/agent/managedruntime -run '^TestRemoveNpxExecutionTreeTreatsMissingWindowsChildAsAbsent$'
rtk make test-windows

# From apps/backend on any supported development host:
rtk go test ./internal/agent/managedruntime

Files likely touched

• apps/backend/internal/agent/managedruntime/cache_windows.go
• apps/backend/internal/agent/managedruntime/cache_windows_test.go
• apps/backend/Makefile
• .github/workflows/backend-tests.yml
• docs/plans/windows-managed-runtime-missing-cache-tree/plan.md
• docs/plans/windows-managed-runtime-missing-cache-tree/task-01-correct-windows-missing-tree-detection.md

Dependencies

None.

Risks

• NTStatus.Errno() uses the Windows status-to-DOS mapping. The helper must compare only the two existing not-found Win32 values.
• Linux cannot run the native Windows regression.

Parallelism

sequential

Inputs

• REQ-AGENTS-MANAGED-RUNTIME-RECOVERY-001 and AC-AGENTS-MANAGED-RUNTIME-RECOVERY-001.3.
• REQ-AGENTS-MANAGED-RUNTIME-RECOVERY-002, AC-AGENTS-MANAGED-RUNTIME-RECOVERY-002.2, and AC-AGENTS-MANAGED-RUNTIME-RECOVERY-002.4.
• docs/specs/agents/system-design/managed-npm-runtime-recovery.md.
• docs/decisions/2026-08-24-agentctl-local-managed-runtime-cache-repair.md.
• Existing Windows handle-open and cache-removal tests.

Results

• Added isManagedRuntimeNotFound. The helper converts windows.NTStatus values through Errno() before it compares the Win32 not-found values.
• Used the helper for the cache root, _npx directory, and derived execution tree.
• Removed the separate _npx os.Lstat check.
• Added the missing-child regression and included it in both native Windows test entry points.
• The managed-runtime package passed 36 tests on Linux. The Windows test binary compiled for windows/amd64.
• The native Windows race test remains a CI check because this executor runs Linux.