Extend Control management foundation

AGENTS.md

@@ -11,6 +11,8 @@ Requirements: JDK 17+ and Maven 3.9+.
 ```shell
 mvn -B clean verify
 node --check src/main/resources/web/app.js
+# From the paired VotingPlugin/VotingPlugin checkout when protocol or node code changes:
+mvn -B clean package
 ```
 
 Use a focused Maven test while iterating, then run the complete command before opening a PR:
@@ -42,6 +44,9 @@ The CI definition is `.github/workflows/maven.yml`. The shaded runnable artifact
   role, topology, and dependency cancellations at the state transition; do not wait for graceful shutdown.
   Quick-setup history uses an internal, non-serialized `redacted` marker, and proposal validation must reject that marker.
 - `domain/InspectionOperations` coordinates the separate, read-only `data.inspect.v1` lane.
+- `config.proxy-files.v1` is the deliberately narrow proxy-file capability: it manages only a proxy node's
+  `bungeeconfig.yml`, through the same revision-bound READ/PREVIEW/one-time-APPLY operation model. It is not generic
+  proxy filesystem access. The paired node service is `VotingPlugin/.../proxy/control/ProxyConfigurationFileService`.
 - `domain/ConfigurationSnapshots` stores bounded copies of the redacted content returned by completed managed-file reads.
   A successful empty file remains a non-null empty document rather than being confused with omitted content. The list API
   omits content, full reads are admin-only, and durable files are owner-permissioned where the platform supports POSIX
@@ -69,12 +74,19 @@ The CI definition is `.github/workflows/maven.yml`. The shaded runnable artifact
    exact versioned capability. Unknown advertised capabilities remain unaccepted.
 4. Configuration writes follow `READ`/`PREVIEW`/`APPLY`. Apply consumes the one-time approval from a completely successful
    preview and carries the node revisions that were previewed. Do not create a shortcut around this workflow.
+   `bungeeconfig.yml` is proxy-only and requires `config.proxy-files.v1`; managed Bukkit files require
+   `config.files.v1`. Proxy-file reads mask secrets, preserve redaction markers/comments, reject unsafe YAML and symlinks,
+   and atomically stage, back up, and publish. General proxy-file changes may still require a proxy restart; do not report
+   them as hot-applied.
 5. A claimed task has a two-minute lease and a unique `attemptId`. A result must echo the current node session, the exact
    session that claimed the lease, and the attempt; stale attempts or post-claim reconnects cannot complete work. Claim,
    completion, and capability-loss state transitions must roll back if their durable audit append fails.
 6. The inspection lane is read-only. Its allow-listed kind and bounded string filters are the whole request; results are a
    structured JSON envelope whose serialized size is at most 512 KiB, and are retained only briefly. Audit the kind, never
    player names or other filter values.
+   Exact player inspection may expose only bounded, allow-listed stored VotingPlugin fields, never arbitrary database
+   columns, raw offline-vote payloads, or player enumeration. Adding player mutation requires a separate durable,
+   revisioned, capability-negotiated operation; do not turn inspection into an editor.
 7. Mask passwords, credentials, tokens, API keys, authorization values, webhook secrets, and comparable secrets before a
    read leaves a node. Never put secrets, proposed file contents, approval tokens, or inspection filters in logs/audit.
    Configuration snapshots persist only the node's redacted read result; do not weaken masking, admin authorization, or
@@ -122,6 +134,11 @@ when the pieces are independently deployable or need materially different review
 Protocol version `1` describes the registration/heartbeat resource protocol. Feature evolution normally uses a new
 capability such as `data.inspect.v1`; do not bump the whole protocol for an optional additive feature.
 
+`config.proxy-method.v1` persists a validated method on the proxy and reported backends. Backends reload only their proxy
+communication handler. The proxy acknowledges the durable result before its existing guarded runtime replacement, so
+teardown cannot lose the completion. A failed backend reload must restore its backup. Control availability or a method
+switch must never delay or prevent normal proxy or backend startup.
+
 ## Safe change checklist
 
 - Identify the trust boundary and maximum sizes before adding the happy path.

README.md

@@ -170,7 +170,10 @@ Control records its own observation time; it does not trust remote wall-clock ti
 
 Configuration is split into independently negotiated capabilities. `config.proxy-routing.v1` exposes typed proxy routing.
 `config.files.v1` manages `Config.yml`, `VoteSites.yml`, `SpecialRewards.yml`, `GUI.yml`, `Shop.yml`, and
-`BungeeSettings.yml` on enrolled Bukkit nodes through a bounded YAML editor. `config.quick-setup.v1` supplies standalone,
+`BungeeSettings.yml` on enrolled Bukkit nodes through a bounded YAML editor. `config.proxy-files.v1` is separate and
+manages only an enrolled proxy's `bungeeconfig.yml`; it is not general proxy file access. The proxy file is strict,
+bounded, redacted YAML with safe preview/approval, atomic publication, and a local backup. General proxy-file settings
+are saved without a proxy reload, so the operation reports that a restart is needed to activate them. `config.quick-setup.v1` supplies standalone,
 proxy-backend, vote-site, easy-reward, common-settings, auto-create-vote-sites, vote-logging, vote-party, and typed
 reward-builder presets.
 The auto-create preset owns only `AutoCreateVoteSites`; the logging preset owns only enabled state, purge retention
@@ -198,8 +201,9 @@ explicitly included in configuration changes, so one slow secondary node does no
 `data.inspect.v1` is a separate read-only lane for overview, vote-site health (including persisted unconfigured service
 observations), exact-player data, bounded VoteLog summary/search/correlation trace, non-creating service-site resolution,
 no-side-effect reward simulation, and redacted diagnostics. It accepts only allow-listed string filters and bounded result
-schemas; there is no raw SQL, arbitrary player
-enumeration, command execution, generic file/database browsing, or write operation. VoteLog output is labeled **logged
+schemas; exact player results may include only a bounded allow-list of safe stored VotingPlugin fields when available.
+There is no raw SQL, arbitrary player enumeration or editing, command execution, generic file/database browsing, or write
+operation. VoteLog output is labeled **logged
 events**, not a complete network delivery trace. Overview/diagnostics expose a bounded `voteLogReadable` probe;
 summary/search/trace fail `UNAVAILABLE` when that probe fails, while vote-site health labels SQL data unavailable/unreadable
 instead of turning a query failure into “no recent votes.”
@@ -216,6 +220,13 @@ backup if reload fails. The WebUI labels a rolled-back node as not saved and dis
 the plugin. Bukkit reads normalize YAML; administrators should expect comments and formatting to be normalized
 when applying through the full editor.
 
+The `proxy-method` guided preset is intentionally different from a normal proxy configuration save. Following preview and
+approval, VotingPlugin preflights and persists the selected communication method across the reported network. Backends
+reload only their proxy communication handler. The proxy first acknowledges its durable result and then replaces its
+runtime, preventing teardown from losing the operation result. A persistence or backend handler reload failure restores
+the local backup; resolve the reported node failure and preview again rather than assuming a network-wide method change
+was committed.
+
 `configuration-audit.jsonl` records bounded, append-only, hash-chained operation metadata and rotates once at 5 MiB. A
 cross-process lifetime lock prevents two Control processes from forking the same audit chain. Both
 the active and retained segment are verified against a durable atomic tail/count checkpoint before startup accepts new