Files
kandev/docs/plans/host-utility-managed-runtime-recovery/plan.md
T
2026-09-08 07:25:56 +00:00

5.3 KiB

created, status, requirements, system_design, legacy_specs
created status requirements system_design legacy_specs
2026-09-07 completed
REQ-AGENTS-MANAGED-RUNTIME-RECOVERY-001
REQ-AGENTS-MANAGED-RUNTIME-RECOVERY-002
../../specs/agents/system-design/managed-npm-runtime-recovery.md

Implementation Plan: Host utility managed runtime recovery

Overview

Extend the existing trusted managed-runtime recovery contract to host capability probes. First add a structured probe failure signal and one bounded host-utility repair attempt. Then prove the visible recovered status and update the existing operator documentation.

Scope

In scope

  • Classify only strict top-level npm ETARGET evidence from capability probes.
  • Repair through the same warm agentctl instance that ran the failed probe.
  • Retry the same effective package version once with online-preferred metadata.
  • Publish capability failure only after the retry fails.
  • Preserve persisted profile model, fallback model, mode, enabled state, and active runtime version.
  • Add focused backend tests, one host E2E flow, and public recovery documentation.

Out of scope

  • The separate warning-tooltip defect.
  • Automatic version rollback, registry replacement, or global npm cache cleanup.
  • Recovery for authentication, provider, transitive dependency, or arbitrary ACP failures.
  • Persisting capability catalogues across backend restarts.

Technical approach

Structured probe classification

Extend utility.ProbeResponse with a stable failure code. In ACPInferenceExecutor.Probe, classify captured stderr only after the trusted command yields an exact managed package specification. Require npm ETARGET and a missing-package line for that same specification. Keep raw stderr in diagnostic logs.

Host utility recovery

Teach hostutility.Manager.probeWithCommand to recognize the structured code for registered ManagedNPMRuntimeAgent implementations. Derive the effective version through the existing selection reader, call RepairManagedRuntimeCache on the warm instance client, and retry with ACPCommandWithNpmPreference(..., true).

Keep one retry inside one probe operation. Publish probing while recovery is in flight, ok on success, and the final failed result otherwise. Do not run or alter profile reconciliation during recovery.

Run one host utility bootstrap after temporary-artifact ownership is ready. Profile reconciliation and utility binding migrations follow that bootstrap so overlapping startup probes cannot race the same managed npm execution tree.

User-visible evidence and documentation

Use a test-only npm wrapper that fails the offline probe with the strict signature and succeeds online. Assert that the available-agent API reports the recovered model catalogue and that task profile selection does not show a capability warning. Update the stale-runtime recovery section in the public agent guide and the internal managed-runtime command reference.

Tests

Acceptance criterion Evidence
AC-AGENTS-MANAGED-RUNTIME-RECOVERY-001.1 Existing session lifecycle recovery tests remain green.
AC-AGENTS-MANAGED-RUNTIME-RECOVERY-001.6 Host utility manager test observes one repair and one online retry.
AC-AGENTS-MANAGED-RUNTIME-RECOVERY-001.7 Reconciler integration test proves persisted profile fields remain unchanged.
AC-AGENTS-MANAGED-RUNTIME-RECOVERY-001.8 Host E2E receives an ok catalogue without launching a task or refreshing manually.
AC-AGENTS-MANAGED-RUNTIME-RECOVERY-002.2 Existing agentctl cache-repair tests plus the host utility integration assert one exact execution tree.
AC-AGENTS-MANAGED-RUNTIME-RECOVERY-002.3 Command and environment assertions preserve registry and sibling cache state.

The first regression test is TestManagerProbeRecoversManagedRuntimeETarget. It fails on current code because the first failed probe is published without cache repair or an online retry.

E2E tests

apps/web/e2e/tests/settings/host-utility-managed-runtime-recovery.spec.ts covers recovery before task launch and the resulting warning-free profile selection on desktop. No frontend implementation change is required.

Work orders

Verification results

  • Backend recovery and startup wiring: go test ./internal/agentctl/server/utility ./internal/agent/hostutility ./internal/agent/settings/controller ./internal/backendapp -count=1 passed.
  • Shared matcher compatibility: go test ./internal/agent/runtime/routingerr ./internal/common/npmresolution -count=1 passed.
  • Task 02: pnpm e2e:run --host tests/settings/host-utility-managed-runtime-recovery.spec.ts passed.
  • Public documentation validators and the complete specification lint passed.
  • PR fixup added model-configuration recovery, probe-environment cache resolution, exclusive repair admission, and portable macOS fixture hashing.
  • Expanded backend packages and changed-code lint against the PR merge base passed with zero issues.

Risks

  • A broad failure classifier could turn unrelated npm or provider failures into destructive cache repair.
  • A retry that resolves a different version would violate the active-version contract.
  • Publishing the first failure can race the recovered result and leave stale warning state in clients.