1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
// owner: d1-platform-core
//
// d1 owns `os`, `paths`, `lock`, `process`, `logging` and this crate root;
// d2 owns `secrets`; d3 owns `service`.
//! 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.