Configure IB Gateway FA allocation group mode - Feature 112 fav2

[Farrell-A]

Summary

This PR adds an optional desired state for IB Gateway's Use Account Groups with Allocation Methods setting. It is the IBAutomater prerequisite for LEAN's unified financial-advisor group routing.

There have been historical PRs that have flipped the group allocation setting back and forth. The IB API behaves differently based on if this setting is selected for advisors. This update, in combination with the linked PRs open in the other repos, makes this setting user definable to ensure it has the correct setting for the deployment. The default is its existing behavior. The bug fix component addresses that the existing IBAutomater desired outcome for this setting wasn't reached across IBGateway versions that have different punctuation for the setting from what the existing code realized.

• Threads the desired state from the C# host into the Java agent while preserving all existing constructors.
• Applies the desired state during initial launch and every explicit or automatic Gateway restart.
• When unified groups are requested, requires exactly one recognized checkbox and verifies that it is selected.
• Returns an actionable startup failure when a requested true state encounters a missing, ambiguous, disabled-and-unchecked, or non-retaining checkbox.
• Preserves legacy best-effort behavior when the setting is false or omitted, including Gateway versions where the control is absent.
• Opens the Gateway Messages settings and disables the recognized Group Allocation Warning, if present, when unified groups are enabled.
• Handles the resulting Accept and Continue confirmation.
• Leaves the Group Allocation Warning unchanged when unified groups are disabled.
• Propagates the Java configuration result through the existing startup synchronization path, so Gateway startup cannot be reported successful before the requested checkbox state is confirmed or an actionable failure is received.
• Adds focused C# and Java production-path tests and an Ant test target.

This closes: QuantConnect/IBAutomater#112
** This is part of a coordinated multi-repo feature release. See the attached files for thorough details**

Hosted QuantConnect Cloud availability additionally requires the deployment schema/UI to expose and serialize the corresponding brokerage setting.

Behavior

Requested state	Recognized Gateway control	Result
false or omitted	One or more recognized controls selected	Deselect and verify all recognized controls
false or omitted	Recognized control unselected	Leave it unselected
false or omitted	Missing	Preserve the existing no-op behavior
true	Exactly one control, enabled and unselected	Select it and verify it remains selected
true	Exactly one control already selected, including a disabled control	Leave it selected and continue
true	Missing	Return FinancialAdvisorAllocationGroupsConfigurationUnavailable
true	Disabled and unchecked	Return FinancialAdvisorAllocationGroupsConfigurationUnavailable
Either state	Recognized control does not retain the requested state	Return FinancialAdvisorAllocationGroupsConfigurationUnavailable

The result reports whether the recognized Swing control reached the requested state.

Compatibility

• The original seven-parameter public C# constructor is unchanged and defaults the new setting to false.
• Existing Java constructors and legacy six-line Java-agent settings remain accepted with the setting disabled.
• Existing error-code values are unchanged; the FA configuration error is appended as value 16.
• No existing public member is removed, renamed, retyped, or re-signatured.
• Package version: 2.0.93 to be in alignment with the linked PRs. Update required with version drift.

Validation

• ant clean test jar — passed; 26/26 Java assertions exercised the production checkbox handler, matching rules, desired-state matrix, failure cases, legacy defaults, Group Allocation Warning discovery and suppression, idempotence, column-order handling, case handling, and missing-warning behavior.
• dotnet test IBAutomater.sln -c Release --no-restore — passed; 3/3 C# tests, with both the net10.0 and netstandard2.1 library targets built.
• The live Gateway matrix passed nine production UI/control cases covering establishment of unified mode, the legacy false transition and idempotence, eight-argument false/true transitions and idempotence, native soft restart with true, and explicit restart with true. Managed accounts, orders, and positions were unchanged across restart cases.
• The nine-case live matrix certifies the allocation-group checkbox and restart behavior. The later Group Allocation Warning handling is covered by the current 26-assertion Java production-helper test suite and is not represented as part of that earlier live matrix.
• Coordinated FA-v2 LEAN startups with unified groups set to true, false, and omitted exercised the brokerage-to-IBAutomater handoff before brokerage use.
• The broader linked FA-v2 live-paper campaign completed as documented in the attached verification report.

Related work and sequencing

The coordinated PRs can be reviewed concurrently, but their release has package and platform dependencies:

1. Merge this IBAutomater PR and publish QuantConnect.IBAutomater 2.0.93.
2. Merge Lean update, which adds the brokerage-neutral FA contracts, default-safe LEAN configuration, and publish the corresponding LEAN packages.
3. Merge Lean.Brokerages.InteractiveBrokers update against the published IBAutomater and LEAN package surfaces.
4. Add the required deployment schema/UI inputs so Local Platform, LEAN CLI, direct cloud API, and QuantConnect Cloud deployments can emit the exact brokerage settings.
5. Merge Documentation-update in alignment with the released implementations and deployment surface.
   The hosted deployment schema/UI must expose the unified-groups and group-management inputs under their exact brokerage-data keys. That platform work is external to this repository.

IBAutomater PR ──> publish 2.0.93 ───────────────┐
                                                 ├──> IB brokerage PR ─> brokerage release
LEAN PR ────────> publish LEAN 2.5.x packages ───┘                        │
                                                                          ├─> expose deployment inputs
Platform cloud schema/UI work (add 2 inputs)──────────────────────────────┘
                                                                          │
Documentation PR ─────────────────────────────────────────────────────────┘

Files attached explaining the full fav2 linked PR scope across repos, and testing conducted

fav2_live_verification_report.md
fav2_enhancement_summary.md
enhancement_change_inventory.md
enhancement_goals_findings.md
enhancement_scope.md
test_file_scope.md

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• Refactor (non-breaking change which improves implementation)
• Performance (non-breaking change which improves performance. Please add associated performance test and results)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Non-functional change (xml comments/documentation/etc)

Checklist:

• My code follows the code style of this project.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new tests passed, along with the existing tests that passed without the feature.
• My branch follows the naming convention bug-<issue#>- or feature-<issue#>-