Carlos Florêncio
111 lines
3.7 KiB
Markdown
111 lines
3.7 KiB
Markdown
---
|
|
id: "01-correct-windows-missing-tree-detection"
|
|
title: "Correct Windows missing-tree detection"
|
|
status: done
|
|
wave: 1
|
|
depends_on: []
|
|
plan: "plan.md"
|
|
requirements:
|
|
- REQ-AGENTS-MANAGED-RUNTIME-RECOVERY-001
|
|
- REQ-AGENTS-MANAGED-RUNTIME-RECOVERY-002
|
|
acceptance_criteria:
|
|
- AC-AGENTS-MANAGED-RUNTIME-RECOVERY-001.3
|
|
- AC-AGENTS-MANAGED-RUNTIME-RECOVERY-002.2
|
|
- AC-AGENTS-MANAGED-RUNTIME-RECOVERY-002.4
|
|
system_design:
|
|
- ../../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:
|
|
|
|
```bash
|
|
# 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.
|