kandev/docs/plans/agent-runtime-update-dialog/task-02-update-preview-api.md

id, title, status, wave, depends_on, plan, spec

id	title	status	wave	depends_on	plan	spec
02-update-preview-api	Add the read-only update preview API	done	1		plan.md	../../specs/agents/requirements/runtime-updates.md

Task 02: Add the read-only update preview API

Acceptance

• A managed installed agent exposes current version, upstream target version, trusted update argv, and a display command through a read-only endpoint.
• The display command quotes the update recipe's empty final argv entry as "", preserving the exact direct-execution command.
• Preview never creates a job, claims maintenance state, or executes the update command.
• Unmanaged, missing, unavailable-updater, and registry-resolution failures return explicit errors and do not mutate runtime state.

Verification

• RED/GREEN controller: cd apps/backend && go test -run 'TestAgentUpdatePreview' ./internal/agent/settings/controller
• RED/GREEN handler: cd apps/backend && go test -run 'TestAgentUpdatePreviewEndpoint' ./internal/agent/settings/handlers

Files likely touched

• apps/backend/internal/agent/settings/dto/dto.go
• apps/backend/internal/agent/settings/controller/controller.go
• apps/backend/internal/agent/settings/controller/controller_test.go
• apps/backend/internal/agent/settings/controller/agent_update.go
• apps/backend/internal/agent/settings/controller/agent_update_test.go
• apps/backend/internal/agent/settings/handlers/handlers.go
• apps/backend/internal/agent/settings/handlers/agent_update_handlers_test.go

Dependencies

None.

Parallelism

Sequential by default. It is file-disjoint from Task 01 and may run in parallel only with explicit user authorization.

Inputs

• Spec update-preview API and approval scenarios
• Existing RuntimeUpdater, ManagedNPMRuntimeSpec.CacheUpdateCommand, and buildCommandString
• Existing update handler error mapping and direct-argv security boundary

Output contract

Report RED and GREEN results, response/error contracts, changed files, command trust-boundary risk, and update this task plus plan.md status.