Define Git-authored desired state for fleet controllers and capacity #32

Goal

Make reviewed Git configuration the authoritative desired state for worker-controller machines, while keeping credentials, addresses, and runtime state outside Git.

A new or existing Linux Docker host must be able to converge from a pinned configuration revision with one repository-owned Bash command. Application repositories describe jobs and shards; infrastructure configuration alone controls available worker capacity.

Public contract

Define a versioned, implementation-independent configuration model using fictional values such as example-org, example-repo, and example-ci-01.

The model must cover:

• logical runner pools, routing labels, runner-group policy, and allowed repositories;
• a pool-level capacity budget;
• controller instances with unique logical IDs, assigned pool, enabled/drained state, minimum and maximum runners, and per-runner resource limits;
• validation that aggregate enabled controller capacity cannot exceed its pool budget;
• lifecycle channel or pinned engine revision;
• no host addresses, VM IDs, credentials, private keys, tokens, or secret values.

Application workflows must not cap parallelism according to fleet size. They should submit all independent jobs; controllers and private infrastructure policy provide the capacity. Document only narrowly scoped exceptions for a real external-service concurrency limit.

Installer and convergence

Extend the host-installer work in #21 so an operator can run a command equivalent to:

sudo ./scripts/install-worker-controller.sh \
  --config-repo example-org/example-fleet-config \
  --controller example-ci-01 \
  --ref <reviewed-commit> \
  --adopt

Required modes:

• --check
• --install
• --adopt
• --upgrade
• --rollback
• --uninstall

The same command must support a fresh VM or bare-metal host and safe adoption of an existing controller. It must validate the pinned desired state, render host-local runtime configuration, preserve root-owned secrets, drain before disruptive changes, create or verify a recoverable checkpoint, install maintenance timers, verify health, detect drift, and emit a redacted final report.

The target host must perform the work directly. OpenClaw or another agent may run the command but is not a required component. GitHub approval steps must remain phone-friendly as described in #27.

Set-and-forget operation

Specify how a host detects and applies reviewed desired-state changes without following an unreviewed moving branch. If automatic convergence reads a private configuration repository, use a narrowly scoped identity with read-only contents permission for that repository. Never expose that identity to runner jobs.

A failed validation, drain, checkpoint, upgrade, or health check must leave or restore the last known-good controller.

Host retirement

Document a drain-and-retire workflow. Once legacy project-specific runners are no longer referenced by CI, promotion, or deployment, they should be unregistered, have scoped fleet-owned resources removed, have credentials revoked, and then be deleted or repurposed according to the operator's declared policy. No application workflow should require edits when one generic controller is replaced.

Acceptance

• Public schema/specification and fictional examples exist.
• The public configuration template implements the same version.
• The installer consumes a pinned desired-state revision and supports existing-host adoption.
• Validators reject capacity overcommit, duplicate controller identities, secret-like data, and project-level fleet-capacity controls.
• Host-local secrets and rendered runtime state remain outside Git.
• Fresh install, idempotent rerun, adoption, drift, upgrade, rollback, drain, and removal have deterministic tests and operator documentation.
• The design links clearly to feat: Add idempotent install-host.sh to enroll and manage CI fleet Docker hosts #21, docs: Complete operator-workflow docs: role quickstarts, landing index, and truthful stale-content cleanup #24, feat: Add Bash bootstrap-github.sh to automate GitHub App and runner-group provisioning #27, and [P1][Fleet] Add and prove post-pilot two-runner capacity promotion #30.