Build reusable platform-based self-hosted runner toolkit

Outcome

Create a reusable, project-configurable toolkit for repository-scoped GitHub
Actions self-hosted runners. The first usable release supports the existing
deployment model:

• Linux runners in Podman containers; and
• Windows runners as isolated services on an existing bare-metal workstation.

The architecture must define macOS bare-metal as a first-class v1 provider and
leave explicit extension points for future Linux bare-metal and Windows-container
providers without pretending those providers exist today.

Configuration contract

• A consumer repository owns one human-edited runner-tools.yaml profile.
• Parse YAML 1.2 strictly, reject duplicate keys, validate against a versioned
  checked-in JSON Schema, and reject unknown fields.
• Platform-first provider paths:
  • platforms/linux/container/
  • platforms/windows/bare-metal/
  • platforms/macos/bare-metal/
• Project profiles explicitly name runner selectors, container/image/volume
  prefixes, paths, capability profiles, and any project-specific extension.
• Refuse collisions unless exact ownership metadata matches.

Bootstrap and extension contract

• Provide version-pinned curl | bash and iwr | iex release entry points,
  while documenting download/checksum/execute as the preferred elevated path.
• Provide tiny consumer-repository POSIX and PowerShell shims that can check out
  a pinned tools revision beside the consumer repository.
• Use Clickwork for the cross-platform CLI and its shared-plugin/local-command
  extension model; do not require GNU Make.
• Separate host provisioning, project toolchain preparation, and job-local
  dependency installation.

Prototype acceptance

• Generalize the proven factory-game Windows lifecycle implementation without
  weakening collision, immutable-identity, recovery, service, checksum, or
  credential boundaries.
• Generalize the existing Podman Linux runner pattern with explicit per-project
  container/image/volume names and project-owned Containerfile extension.
• Implement plan, install/up, status, doctor, restart, and
  remove/down behavior as applicable to each implemented provider.
• Include unit/integration tests runnable on Linux; document the required live
  Windows and container smoke evidence.
• Include security, contribution, release, and consumer-integration docs.

V1 follow-up

• Implement and validate the macOS bare-metal provider on Apple hardware.
• Track Linux bare-metal and Windows containers as non-v1 stretch providers.

Workflow

• Work on a feature branch and PR.
• Run a clean fresh-context review before each push.
• Request Balanced Copilot review and iterate until useful feedback converges.
• Do not add Codex/co-author/signoff trailers or agent commit signatures.

Start by mapping the existing deployment model to the provider paths under platforms/linux/container/, platforms/windows/bare-metal/, and platforms/macos/bare-metal/, then inspect the runner-tools.yaml contract and checked-in JSON Schema requirements. Use the listed plan, install/up, status, doctor, restart, and remove/down behaviors as the completion checklist, with unit/integration tests runnable on Linux and documented Windows/container smoke evidence.