kandev/docs/plans/executor-local-managed-runtime-recovery/task-01-agentctl-cache-repair.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-agentctl-cache-repair	Add executor-local cache repair	done	1		plan.md	REQ-AGENTS-MANAGED-RUNTIME-RECOVERY-002	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	../../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

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