Crate runner_manager_platform

Expand description

Host primitives every other crate in runner-manager assumes exist.

This crate is the whole of the surface where “works on my machine” becomes “works on Windows, macOS, and Linux”. Everything above it — the domain, the GitHub gateway, the agent, the CLI and the TUI — is written once and is platform-blind; the three-way differences live here and nowhere else.

Module	Primitive	Whose Definition of Done depends on it
`os`	Host OS/architecture, and their standing in GitHub’s documented support matrix	`f2` warns on ARM64 and reports the Linux-only container limitation
`paths`	The `config/`, `state/`, `runtime/`, `logs/` directories, in platform-standard locations	everything that touches disk
`runner_root`	Where runner workspaces go: the short `%SystemDrive%` default, and the local/writable/non-overlapping check every configured root passes	`b2`’s default-root ACL, `c1`’s ephemeral launch, `d1`’s mutations
`runner_root_access`	Creating the default runner root, and the protected DACL that keeps unrelated local users out of it	`b2`’s Windows acceptance test, `f1`’s security gate
`lock`	The single-instance lock and the runtime allocation lock	`e1`’s allocation, `e3`’s restart recovery
`process`	Spawn, observe, terminate; a process identity a recycled PID cannot forge; the restrictive JIT handoff	`e3` adopts a live process without starting a duplicate
`logging`	Structured allowlist logging with unconditional redaction	`07-security.md`’s secret-injection log scan
`secrets`	Machine-scoped secret store (`d2`)
`service`	Service and daemon installers (`d3`)
`wsl`	Managing a named WSL2 distribution as a second host on a Windows workstation (`a1-wsl-platform-adapter`)	the managed-WSL-host feature’s whole platform half

§Three properties worth knowing before reading any of it

A PID is not an identity. process::ProcessIdentity pairs a PID with a platform-defined start token, because the attempt journal outlives a reboot and PIDs are reused. Adopting a stranger — or terminating one — is the failure mode that primitive exists to prevent.

A lock is an operating-system file lock, not a PID file. The requirement is “released on crash rather than leaking”, and only the kernel can deliver that for a process that was killed or whose machine lost power.

Redaction is allowlist-first and unconditional. A field this crate has not been told about is redacted, so a field added by a later task cannot leak by default.

§Platform coverage is a CI property, not a local one

Each of these modules has a Windows path, a macOS path, and a Linux path, and a developer’s machine exercises exactly one of them. The contract tests are written to run natively on all three legs of the CI matrix rather than to be cross-compiled and assumed; where a test can only assert something on one family — a Unix mode bit, a Windows DACL — it asserts the property (“no other local user can read this”) through a platform-specific check behind one cross-platform name.

Modules§

daemon_heartbeat: Whether the daemon is making progress at all.
dependency_cache: Persistent dependency and tool caches for native runners.
git_cache: Independent local Git snapshots for native repository runners. The manager never fetches from GitHub: checkout keeps its own authentication and ref selection. Only Git objects and generated Git metadata cross job boundaries.
host_fitness: Operating-system primitives for host doctor and host prepare.
launch_health: Whether this host’s daemon can start runners at all.
lock: The host locks: one keeps a second agent from reconciling the same policies, one serialises runtime creation, and one serialises rotating credentials across a background service and foreground tools.
log_retention: Bounded retention for the redacted summaries written after runner attempts.
logging: The structured log sink, and the redaction that is not optional.
os: Where this host stands in GitHub’s documented self-hosted runner support matrix.
paths: The four application-data directories the daemon owns, resolved to platform-standard locations.
polling: The idle poll interval, and what the daemon measured its polling cost.
process: Spawning, observing and terminating a child process; a process identity that survives a restart; and the restrictive handoff that gets a JIT configuration to a runner without it ever appearing in a process listing.
runner_env: The environment a native runner starts with, beyond what the daemon has.
runner_root: Where disposable runner attempts are placed, and whether a configured location can actually hold them.
runner_root_access: Who may write inside the platform default runner root, and how that is established.
secrets: The one persisted GitHub credential, in a place a boot-time service can read.
service: Registering daemon run with the operating system, so that a home host resumes work by itself after a reboot with nobody logged in.
service_request: Asking the running service to do something this process cannot.
unattended_login: Whether this Mac comes back to work by itself after an unattended restart.
wsl: Managing a named WSL2 distribution as a first-class host: discovery, invocation, preflight, artifact install, the Windows lifecycle task, and the non-secret provider record.