Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@

This is a plan-first repository. Do not treat example CLI commands as implemented features.

- Work from a GitHub issue and its Goal, acceptance criteria and dependencies. One issue, one branch/worktree, one active goal when the task requests goal execution.
- Follow docs/EXECUTION.md. The current user-authorized policy routes all future implementation, review and coordination work through Luna (`gpt-5.6-luna`, `max`), regardless of area. Preserve the TDD, independent-review and live-operation authorization gates. Historical records keep the model that actually produced them. Do not override an explicit current user setting.
- Work from a GitHub issue and its Goal, acceptance criteria and dependencies. One issue, one branch/worktree, one active goal when the task requests goal execution. Live GitHub Project status is dispatch authority; do not redispatch from historical `docs/backlog.json` Ready values.
- Follow docs/EXECUTION.md. The repository default routes implementation, review and coordination through Luna (`gpt-5.6-luna`, `max`) unless an explicit current user override is recorded on the issue. The maintainer-authorized override for delivery-reframe issue #66 and R1 children #67/#68/#69 is main author Grok 4.6 xhigh with independent Luna max review. Preserve the TDD, independent-review, exact-head Codex+CI and live-operation authorization gates. Historical records keep the model that actually produced them. Do not override an explicit current user setting.
- Use TDD for implementation: meaningful failing test -> minimal implementation -> refactor -> relevant verification. Document actual results; never claim planned/skipped/live tests passed.
- Preserve live manually installed runners during development. No global Docker prune/context change, broad process kill, unreviewed destructive cleanup or automatic workflow replay.
- Credentials, raw SDK response errors, JIT configs, personal machine paths and private test logs must not enter commits/issues/diagnostic bundles.
- Native macOS runners are for explicitly trusted code. Do not claim same-user workdirs or Keychain provide hostile-code isolation.
- Keep GitHub SDK behavior behind an adapter and pin versions. Resolve G01/G02 evidence gates before dependent implementation.
- Keep GitHub SDK behavior behind an adapter and pin versions. Resolve G01/G02 evidence gates before dependent production implementation. Completing the G02 R1 subset does not complete G02.
- Limit concurrency and resources globally across pools; ordinary scale-down drains busy work.
- Public PR tests use hosted environments without secrets. Real Mac/self-hosted tests require reviewed commits and explicit maintainer dispatch under runner-group policy.
- Use Go unless an ADR supported by evidence changes the decision. Keep dependency count small and review licenses. No restricted virtualization binary or macOS image bundled by default.
Expand Down
20 changes: 10 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,20 +14,20 @@ gh-runnerd logs tests --follow
gh-runnerd stop tests --drain
```

## Intended first release
## Intended delivery

- A native macOS ARM64 Go executable, with a CLI and separately supervised daemon.
- User-owned GitHub App authentication; no management SaaS, shared vendor private key, public inbound endpoint, or Kubernetes requirement.
- Linux runners through an explicit Docker Engine connection. Existing Docker Desktop or Lima engines can be used without changing the user's global Docker context.
- Native macOS process runners for explicitly trusted repositories only. A fresh working directory is **not** OS or credential isolation. macOS VM isolation is a later, separately gated provider.
- Multiple organizations, per-pool limits, and a shared host-wide capacity budget.
- One-job runners, durable state reconciliation, safe scale-down, structured diagnostics, and tests that exercise crashes and concurrent work.
The original product envelope is still a native macOS ARM64 Go CLI plus supervised daemon, user-owned GitHub App authentication, Linux workers through an explicit Docker Engine connection, trusted-only native macOS processes, multiple organizations and a shared host budget. **There is no runnable product yet** (`cmd/gh-runnerd` is an empty entry point). Maintainer-accepted sequencing in [#66](https://github.com/1XP-AI/gh-runnerd/issues/66) splits that envelope:

Linux still needs a Linux kernel/runtime on macOS. The first release connects to an existing engine; it does not make Linux containers native macOS processes or provision a Kubernetes cluster.
- **R1 Internal MVP:** this Mac, one organization, one private test repository, the existing Linux-container backend, concurrency one, manual App, foreground command. Full G01 ACK/acquisition/JIT recovery remains required. Full G02 #2 remains a required pre-release evidence gate classified R3; R1 is not independently deliverable until that gate passes.
- **R2 Everyday operations:** install/start/stop/status, restart recovery, bounded scaling.
- **R3 General distribution:** multi-organization support, additional native backend, automated onboarding, signing/update/diagnostics. Full G02 original acceptance remains here and also gates R1 #68 production.
- **Future:** optional macOS VM / multi-host research ([#21](https://github.com/1XP-AI/gh-runnerd/issues/21)).

Linux still needs a Linux kernel/runtime on macOS. R1 connects to an existing engine; it does not make Linux containers native macOS processes, add a second backend, or provision a Kubernetes cluster. See [approved delivery releases](docs/PLAN.md#approved-delivery-releases).

## Track implementation

[GitHub Project](https://github.com/orgs/1XP-AI/projects/2) provides [Goals](https://github.com/orgs/1XP-AI/projects/2/views/1), [Ready](https://github.com/orgs/1XP-AI/projects/2/views/2) and [Board](https://github.com/orgs/1XP-AI/projects/2/views/3) views. All 21 issues carry a goal, model/effort, TDD cases, acceptance criteria and dependencies. Start with G01/G02/G03; the board does not dispatch agents automatically.
[GitHub Project](https://github.com/orgs/1XP-AI/projects/2) provides [Goals](https://github.com/orgs/1XP-AI/projects/2/views/1), [Ready](https://github.com/orgs/1XP-AI/projects/2/views/2) and [Board](https://github.com/orgs/1XP-AI/projects/2/views/3) views. The original 21 goal issues remain; the live board has 36 items after additive Release metadata and R1 children. Start from currently Ready work on the live Project; do not redispatch from historical `docs/backlog.json` Ready values. The board does not dispatch agents automatically.

## Read the plan

Expand All @@ -42,7 +42,7 @@ Linux still needs a Linux kernel/runtime on macOS. The first release connects to
- [Ordered backlog](docs/BACKLOG.md)
- [Sources and unresolved experiments](docs/SOURCES.md)

The implementation target begins with one Apple Silicon Mac and two organizational installations. Organization examples in configuration are illustrative. No existing runner is migrated or removed by this repository.
R1 is one Apple Silicon Mac and one organizational installation. Two-organization qualification remains the G16/R3 target. Organization examples in configuration are illustrative. No existing runner is migrated or removed by this repository.

## License

Expand Down
87 changes: 56 additions & 31 deletions docs/BACKLOG.md
Original file line number Diff line number Diff line change
@@ -1,41 +1,66 @@
# Ordered implementation backlog

Every row is an unimplemented goal. G01/G02 are evidence gates; G03 is independently ready. See [execution policy](EXECUTION.md) and each GitHub issue for acceptance and TDD details.
Every original row is a full-scope goal. G01/G02 remain evidence gates; G03 is done. See [execution policy](EXECUTION.md), [approved delivery releases](PLAN.md#approved-delivery-releases) and each GitHub issue for acceptance and TDD details.

| Key | Goal area | Stage | Primary agent | Depends on |
**Release placement names which user-visible release needs the complete original scope.** Historical M0–M5 stages, original Goal text, Agent history and native `blockedBy` edges are retained. Relabeling does not make a blocked full-scope issue Ready, does not close a parent when a child lands, and does not make an R2 original-acceptance set independently shippable while it is natively blocked by R3-placed issues.

The live 36-item map is in [ISSUES.md](ISSUES.md). Default implementer is Luna max unless the issue records an explicit current user override; #66 and R1 children #67/#68/#69 are Grok 4.6 xhigh with independent Luna max review.

## R1 critical path

Foreground MVP on this Mac: one org, one private repository, existing Linux-container backend, capacity one, manual App. Daemon/install/service are not implemented and are not R1.

User-visible R1 scope is not independently deliverable: #68 production waits for full G02 #2, which remains classified R3. Completing #67 does not complete G02. Release placement names original-scope ownership; it is not a claim of stage independence.

| Key | Issue | Role | Native blockers | Live status |
|---|---|---|---|---|
| G01 | Prove Scale Set delivery, acquisition and drain contracts | M0 - Evidence gates | Luna max | None — Ready |
| G02 | Prove local App enrollment and launchd credential access | M0 - Evidence gates | Luna max | None — Ready |
| G03 | Bootstrap Go module and independent public CI | M0 - Evidence gates | Luna max | None — Ready |
| G04 | Freeze CLI configuration, provider and scaling contracts | M0 - Evidence gates | Luna max | G01, G02, G03 |
| G05 | Implement durable state and operation journal | M1 - Control plane | Luna max | G03, G04 |
| G06 | Implement the supervised daemon and authorized local IPC | M1 - Control plane | Luna max | G05 |
| G07 | Implement GitHub App credential and installation binding | M1 - Control plane | Luna max | G02, G05 |
| G08 | Implement guided init and optional Manifest enrollment | M1 - Control plane | Luna max | G06, G07 |
| G09 | Implement the recoverable Scale Set adapter | M1 - Control plane | Luna max | G01, G05, G07 |
| G10 | Implement disposable Linux workers with isolated Docker services | M2 - Execution and scaling | Luna max | G04, G05, G07 |
| G11 | Implement trusted native macOS worker identity and lifecycle | M2 - Execution and scaling | Luna max | G02, G04, G05, G07 |
| G12 | Implement deterministic shared capacity and fair scheduling | M2 - Execution and scaling | Luna max | G04, G05 |
| G12a | Pure scaling targets and capacity arithmetic (child of G12) | M2 - Execution and scaling | Luna max | G03 + reviewed numeric contract; independently ready |
| G13 | Integrate reconciliation, drain and safe restart | M2 - Execution and scaling | Luna max | G06, G09, G10, G11, G12 |
| G14 | Implement status, logs and sanitized diagnostics | M3 - Reliability qualification | Luna max | G06, G13 |
| G15 | Implement startup, shutdown and safe configuration updates | M3 - Reliability qualification | Luna max | G02, G06, G13 |
| G16 | Build repeatable two-organization runtime qualification | M3 - Reliability qualification | Luna max | G08, G13, G14, G15 |
| G17 | Qualify crash recovery, soak and resource budgets | M3 - Reliability qualification | Luna max | G16, G19 |
| G18 | Package signed releases and reproducible distribution | M4 - Pilot and release | Luna max | G03, G15, G17 |
| G19 | Audit trust admission and cross-worker secret boundaries | M3 - Reliability qualification | Luna max | G08, G10, G11, G13 |
| G20 | Pilot migration with reversible legacy runner handoff | M4 - Pilot and release | Luna max | G17, G18 |
| G21 | Evaluate optional macOS VM and multi-host providers | M5 - Future | Luna max | G17 |

The machine-readable source is [backlog.json](backlog.json). Published issue numbers and links are in [ISSUES.md](ISSUES.md); all dependencies are native GitHub blocking relationships. All first-release implementation goals remain open.
| G01 | [#1](https://github.com/1XP-AI/gh-runnerd/issues/1) | **Full original** ACK/acquisition/JIT recovery Goal; no subset and no false completion | none | In progress |
| G02-R1 | [#67](https://github.com/1XP-AI/gh-runnerd/issues/67) | R1 subset of G02 #2 (manual single-org credentials). Parent #2 stays R3 In progress | none | Ready |
| G01g | [#60](https://github.com/1XP-AI/gh-runnerd/issues/60) | Bounded broker handoff for the paired Linux-container path | #54 (Done) | In progress |
| P66 | [#66](https://github.com/1XP-AI/gh-runnerd/issues/66) | Delivery-plan documentation | none | In progress |
| G13-R1 | [#68](https://github.com/1XP-AI/gh-runnerd/issues/68) | R1 subset of G13 #13. Native blockers #60, #66, #67. Until full G01 #1 and G02 #2 pass, authorized work is a reviewed minimal contract and offline evidence only; production implementation starts only then. Not a G01/G02/G04 bypass. Completing #67 does not complete G02. Live recovery stays on #1→#69 | #60, #66, #67 | Blocked |
| G16-R1 | [#69](https://github.com/1XP-AI/gh-runnerd/issues/69) | R1 subset of G16 #16: authorized real job plus required recovery | #1, #68 | Blocked |

#68 must not start production implementation while natively blocked or while full G01 #1 or G02 #2 remain open. Native `blockedBy` stays #60/#66/#67; do not add #1/#2 without an explicit ask. Completing a child does not complete G02, G04–G15 or G16. Full G02 stays R3; that cross-release prerequisite is why R1 cannot ship independently.

## Original full-scope backlog (M0–M5 preserved)

| Key | Goal area | Stage | Release (full original) | Primary agent | Depends on |
|---|---|---|---|---|---|
| G01 | Prove Scale Set delivery, acquisition and drain contracts | M0 - Evidence gates | R1 | Luna max | None — originally Ready; live In progress |
| G02 | Prove local App enrollment and launchd credential access | M0 - Evidence gates | R3 | Luna max | None — originally Ready; live In progress. R1 subset is #67 |
| G03 | Bootstrap Go module and independent public CI | M0 - Evidence gates | R1 | Luna max | None — Done |
| G04 | Freeze CLI configuration, provider and scaling contracts | M0 - Evidence gates | R2 | Luna max | G01, G02, G03 (unchanged; not bypassed by #68) |
| G05 | Implement durable state and operation journal | M1 - Control plane | R2 | Luna max | G03, G04 |
| G06 | Implement the supervised daemon and authorized local IPC | M1 - Control plane | R2 | Luna max | G05. Not in R1; not implemented |
| G07 | Implement GitHub App credential and installation binding | M1 - Control plane | R2 | Luna max | G02, G05 |
| G08 | Implement guided init and optional Manifest enrollment | M1 - Control plane | R3 | Luna max | G06, G07 |
| G09 | Implement the recoverable Scale Set adapter | M1 - Control plane | R2 | Luna max | G01, G05, G07 |
| G10 | Implement disposable Linux workers with isolated Docker services | M2 - Execution and scaling | R2 | Luna max | G04, G05, G07. R1 reuses the existing paired Linux-container path; full G10 remains |
| G11 | Implement trusted native macOS worker identity and lifecycle | M2 - Execution and scaling | R3 | Luna max | G02, G04, G05, G07. Not in R1 |
| G12 | Implement deterministic shared capacity and fair scheduling | M2 - Execution and scaling | R2 | Luna max | G04, G05 |
| G12a | Pure scaling targets and capacity arithmetic (child of G12) | M2 - Execution and scaling | R2 | Luna max | G03 + reviewed numeric contract; Done |
| G13 | Integrate reconciliation, drain and safe restart | M2 - Execution and scaling | R2 | Luna max | G06, G09, G10, G11, G12 (unchanged). R1 subset is #68 |
| G14 | Implement status, logs and sanitized diagnostics | M3 - Reliability qualification | R2 | Luna max | G06, G13 |
| G15 | Implement startup, shutdown and safe configuration updates | M3 - Reliability qualification | R2 | Luna max | G02, G06, G13 |
| G16 | Build repeatable two-organization runtime qualification | M3 - Reliability qualification | R3 | Luna max | G08, G13, G14, G15. R1 subset is #69 |
| G17 | Qualify crash recovery, soak and resource budgets | M3 - Reliability qualification | R3 | Luna max | G16, G19 |
| G18 | Package signed releases and reproducible distribution | M4 - Pilot and release | R3 | Luna max | G03, G15, G17 |
| G19 | Audit trust admission and cross-worker secret boundaries | M3 - Reliability qualification | R3 | Luna max | G08, G10, G11, G13 |
| G20 | Pilot migration with reversible legacy runner handoff | M4 - Pilot and release | R2 | Luna max | G17, G18 (R3). Full original R2 placement cannot close until those R3 blockers finish; no bypass |
| G21 | Evaluate optional macOS VM and multi-host providers | M5 - Future | Future | Luna max | G17 |

The machine-readable source is [backlog.json](backlog.json). Original JSON `status` and `agent` fields are the initial/historical planning snapshot, not live dispatch authority; the live GitHub Project is authoritative after work begins. Do not redispatch from historical Ready values. Published issue numbers and links are in [ISSUES.md](ISSUES.md); all original dependencies remain native GitHub blocking relationships. Full-scope first-release implementation goals except G03/G12a remain open.

## Parallel work boundaries

- Start G01 (Luna max), G02 (Luna max), and G03 (Luna max) independently.
- G04 integrates the gates and freezes contracts before shared implementation.
- After G05, IPC, auth, and pure scheduling can proceed with separate file ownership.
- Linux and native macOS providers can proceed independently once shared contracts/credentials exist.
- Integration, security verdict, soak and rollout are sequential evidence gates.
- Continue G01 (full recovery Goal) and G02 (full Manifest/multi-org/launchd Goal) independently; they are not replaced by #67.
- #67 may proceed as isolated R1 credential evidence without waiting on G02's remaining R3 criteria; it does not authorize live App/Keychain/launchd mutation.
- G04 still integrates the full gates before shared full-scope implementation. #68 is not a G04 bypass: until full G01 #1 and G02 #2 pass, authorized work is a reviewed R1 contract and offline evidence only; production implementation starts only then. Completing #67 does not complete G02. Live G01 recovery remains #69 blocked by #1.
- After G05, IPC, auth, and pure scheduling can proceed with separate file ownership for R2/R3 work.
- Linux and native macOS providers can proceed independently once shared contracts/credentials exist; native macOS is R3.
- Integration, security verdict, soak and rollout remain sequential evidence gates.
- Do not edit #60/#62 or #59 runtime/CI/evidence surfaces from the #66 documentation branch.

## Independent G12 arithmetic slice

Expand Down
Loading
Loading