Files
kandev/docs/plans/executor-local-managed-runtime-recovery/task-01-agentctl-cache-repair.md
T
2026-08-24 21:05:02 +00:00

95 lines
3.3 KiB
Markdown

---
id: "01-agentctl-cache-repair"
title: "Add executor-local cache repair"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-AGENTS-MANAGED-RUNTIME-RECOVERY-002
acceptance_criteria:
- AC-AGENTS-MANAGED-RUNTIME-RECOVERY-002.1
- AC-AGENTS-MANAGED-RUNTIME-RECOVERY-002.2
- AC-AGENTS-MANAGED-RUNTIME-RECOVERY-002.3
- AC-AGENTS-MANAGED-RUNTIME-RECOVERY-002.4
system_design:
- ../../specs/agents/system-design/managed-npm-runtime-recovery.md
---
# Task 01: Add executor-local cache repair
## Summary
Add an authenticated agentctl action that removes one exact npm execution tree.
Resolve the npm cache with the configured agent environment.
## In scope
- Add the typed agentctl request and response.
- Add the authenticated agentctl API route and handler.
- Resolve npm cache configuration through the process manager.
- Add the runtime agentctl client method.
- Preserve the existing exact-tree and symbolic-link protections.
## Out of scope
- Lifecycle retry policy.
- Executor eligibility.
- Version rollback or registry changes.
## Acceptance
- The request accepts one exact stable package specification and no path or command.
- Cache discovery uses the agent environment and the local agentctl process.
- The handler removes only the deterministic target tree and preserves siblings.
## Verification
```bash
go test ./internal/agent/managedruntime ./internal/agentctl/server/api ./internal/agentctl/server/process ./internal/agent/runtime/agentctl -count=1
```
## Files likely touched
- `apps/backend/internal/agent/managedruntime/cache.go`
- `apps/backend/internal/agent/managedruntime/cache_validation_test.go`
- `apps/backend/internal/agentctl/server/process/managed_runtime.go`
- `apps/backend/internal/agentctl/server/process/managed_runtime_test.go`
- `apps/backend/internal/agentctl/server/process/manager_command.go`
- `apps/backend/internal/agentctl/server/process/manager_stderr_exit_test.go`
- `apps/backend/internal/agentctl/server/api/server.go`
- `apps/backend/internal/agentctl/server/api/managed_runtime.go`
- `apps/backend/internal/agentctl/server/api/managed_runtime_test.go`
- `apps/backend/internal/agent/runtime/agentctl/client_managed_runtime.go`
- `apps/backend/internal/agent/runtime/agentctl/client_managed_runtime_test.go`
## Dependencies
None.
## Risks
- The endpoint can become too broad if it accepts a cache path or shell input.
- Cache discovery can target the wrong tree if it drops the agent environment.
## Parallelism
`sequential`
## Inputs
- `REQ-AGENTS-MANAGED-RUNTIME-RECOVERY-002`
- Executor-local cache contract in the system design.
- Existing `hostRuntimeUpdater` and `RemoveNpxExecutionTree` tests.
## Results
- Added exact stable `package@version` validation and retained the existing
deterministic `_npx` tree and symlink protections.
- Added the authenticated agentctl cache-repair route and typed runtime client
method. The route resolves npm cache through the configured agent environment.
- Added API, client, managedruntime, and process-manager tests for exact-tree
repair, sibling preservation, unsafe selectors, and bounded cache discovery.
- Verification passed:
`go test ./internal/agent/managedruntime ./internal/agentctl/server/api ./internal/agentctl/server/process ./internal/agent/runtime/agentctl -count=1`