FM persisted agent configuration: harness + sparse MCP overrides round-trip

Context

PR #14960 / #14807 establishes the Fleet Manager's data model and agent-scoped, read-only Accounts projection. Exact-head review separated that bounded foundation from the larger write path: editing an EXISTING agent's harness and MCP choices requires a Brain-owned persistence/readback contract, while wake and hook state belong to separate control-plane authorities.

This leaf owns that missing configuration round-trip so #14960 can merge without smuggling a new cross-hemisphere backend into a view/model PR.

The Problem

The Body can describe harnessType and a per-agent mcpServers matrix, but it has no authoritative save/readback path for an existing roster resident. Persisting the fully resolved matrix would also freeze today's defaults into every record: future catalog-default changes would stop flowing to agents that never explicitly changed those keys.

A UI-only mutation is not a configuration save. The Brain must validate, persist, and return the observed result while the credential firewall remains unchanged.

The Architectural Reality

• The Brain-side fleet registry/launch contract is the authority for durable harness keys and launch semantics; the Body catalog is a projected display vocabulary, not a second whitelist.
• The Body submits curated configuration intent only: agent id, one harness key, and SPARSE MCP overrides. It never submits command/args/env and never receives credential bytes.
• resolveMcpMatrix() is a read projection. Its resolved output must NEVER be persisted. Persist only user-touched boolean keys relative to defaults; store null when no overrides remain.
• Save state is round-trip state: pending → accepted/read-back OR rejected-with-reason. No optimistic success.
• Wake/hook lifecycle writes are different authority classes. #14537 owns the control-plane wake verb; setHookEnabled remains separately deferred. This leaf neither invents nor bypasses those paths.
• #14614 consumes the same contract for add-agent onboarding; this leaf is the existing-agent edit/save path.

The Fix

1. Add one narrow Brain-owned fleet configuration operation for an existing agent. Validate the agent id, registered harness key, and sparse MCP override object; reject unknown keys or non-boolean values with a reason.
2. Persist the accepted configuration in the fleet authority and project the canonical readback into the cockpit DTO/store. Credential fields stay write-only/Brain-side and are absent from the response.
3. Add an Accounts edit/save surface for the selected agent. It derives the editable matrix from catalog defaults + sparse overrides, submits only the sparse delta, renders pending/rejected states, and replaces local state only from canonical readback.
4. Share or project the authoritative durable harness-key set so a Brain-valid key cannot render as unknown in the Body.
5. Cover save → persistence → fresh readback, catalog-default evolution, rejection, and secret-absence with real service/bridge/store objects.

Acceptance Criteria

• Existing-agent harness choice saves through a Brain-owned validated operation and rehydrates after a fresh roster read.
• MCP persistence is sparse: only user-touched boolean overrides are stored; resolved defaults are never written; an all-default matrix persists as null.
• Changing a catalog default changes the resolved view for an agent with no corresponding override.
• Unknown harness/MCP keys and non-boolean values reject with a rendered reason; the UI never shows optimistic success.
• Canonical readback contains no PAT/token/credential bytes, command, args, or env.
• The Body's durable harness keys cannot drift from the Brain authority (shared projection or an exact contract test).
• Unit coverage spans the Brain service/bridge and real Accounts store/card; one NL-verifiable save/readback journey proves the live path.
• #14614 can consume the same intent contract for add-agent onboarding without a second configuration shape.

Out of Scope

Wake subscription control (#14537) · hook enable/disable authority · PAT capture/storage changes · harness process launch implementation · remote-tenant configuration · visual redesign beyond save-state feedback.

Avoided Traps

• Persisting resolveMcpMatrix() output: silently pins defaults and defeats the registry pattern.
• Body-owned durable truth: creates the same cross-hemisphere whitelist drift #14960 exposed.
• Generic command/config bags: bypass the curated-intent security boundary.
• Optimistic toggles: present an unobserved state as fact.
• Folding wake/hooks into this verb: crosses control-plane authority classes.

Decision Record impact

Aligned with ADR 0020's two-hemisphere credential boundary and ADR 0034's curated-intent shell contract. No amendment expected unless implementation requires renderer-readable secrets or a generic command surface; either outcome is a design failure, not a leaf-local exception.

Related

#14807 / PR #14960 (model + projection foundation) · #14614 (add-agent consumer) · #14537 (wake authority, explicitly separate) · #13015 (Fleet Manager epic) · #14920 (provider-hosted store topology).

Duplicate / prior-art sweep

Live latest-open queue plus targeted searches for “account configuration persistence harness MCP round trip” and “AgentDefinition mcpServers save rehydrate” returned no equivalent. #14614 owns new-agent onboarding, not existing-agent edits; #14537 owns wake control, not configuration persistence. Memory Core searches found no prior implementation contract for this round-trip.

Origin Session ID: de713f27-0e82-4960-b4c6-f281e0c36449 Retrieval Hint: "Fleet Manager existing agent harness sparse MCP overrides save persistence canonical readback"