Accept Phase 5 plan, add phase-loop skill

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019dpKwZWtahQU4V2NhpVmLt
This commit is contained in:
ariandClaude Sonnet 5.5 committed 2026-10-19 17:36:54 -04:00
1 parent 782e5dc440
commit d04d99a9a6
5 files changed
+145 -14

No files matched your search

+105
View File
@@ -0,0 +1,105 @@
---
name: phase-loop
description: Orchestrate a plan/ phase as a work loop. One git worktree per workstream, goose (DeepSeek) codes, Claude Opus reviews and feeds back, Claude Sonnet merges, Opus does a final whole-phase review. Use when asked to run, resume or check the phase loop.
---
# Phase work loop
Orchestrator = the interactive Claude session. It never writes feature code. It launches, monitors and routes between roles, and keeps `loop/STATE.md` current.
Source of truth for scope is `plan/<phase>/` (README, contracts.md, decisions.md, `ws-*.md`). Source of truth for rules is `AGENTS.md`. Both are read by every role.
## Roles
| Role | Tool | Model | Job |
|---|---|---|---|
| Coder | `goose run` | goose default (OpenRouter `deepseek/deepseek-v4.1-flash-1017`, from `~/.config/goose/config.yaml`; do not override) | Implement one workstream in its worktree |
| Reviewer | `claude -p` | opus | Review the workstream diff, write findings to a file |
| Merger | `claude -p` | sonnet | Rebase and merge an approved branch to `main` |
| Final reviewer | `claude -p` | opus | Review the merged phase against the phase exit criteria |
## Layout
- Worktrees: `../skyg-ws/<ws-id>` on branch `ws/<ws-id>`, created from the current `main` (or from the A0 merge commit for wave 2).
- Loop files, untracked, in the main checkout under `loop/` (gitignored): `config.env`, `STATE.md`, `<ws-id>/prompt.md`, `<ws-id>/review-<n>.md`, `<ws-id>/goose-<n>.log`.
- One goose session per workstream, named `ws-<id>`, resumed for every review round (`--name ws-<id> --resume`) so it keeps context.
## Waves (from the phase README dependency graph)
1. Wave 0, parallel: WS-T, WS-A task A0 only. WS-D rmcp conditional-tools spike (read-only, writes a note to its Log).
2. Merge A0 first. Gate: build, clippy, test, fmt green on `main`.
3. Wave 1, parallel: WS-A (A1..A4), B, C, D, E. WS-F F1 and doc drafts.
4. Wave 2: WS-F F2..F4 once T, C, D, E are merged. Needs the nix gate.
5. Final review, then fold the phase into TODO.md / ARCHITECTURE.md / `docs/workstreams/`.
Merge order inside a wave follows dependencies (A, then B, then C/D/E, then F). Never merge two branches at once.
## Per-workstream cycle
1. **Setup.** `git worktree add ../skyg-ws/<id> -b ws/<id> <base>`. Claim the workstream: set Owner and Status in its `ws-*.md`, commit on the branch.
2. **Code.** Render `loop/<id>/prompt.md` from the template below and run
`goose run --name ws-<id> -i loop/<id>/prompt.md` with cwd = the worktree. Goose commits on its branch in small commits. Never run it in the main checkout.
3. **Local gate (script, not model judgment).** In the worktree, run `loop/gate.sh <id>` which does:
- `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings`, `cargo test`, `cargo tree -i openssl` (must print nothing)
- **test check:** the diff against base must add or change files under `tests/` or `#[cfg(test)]` code for every new `pub fn` / route / tool / config key. Fail if production `src/` changed with zero test lines added.
- **duplication check:** run `nix run nixpkgs#jscpd` over `src/` and `tests/` (changed files only), report-only for pre-existing clones over the diff; fail above the threshold in `loop/config.env`.
- **ownership check:** `git diff --name-only base...HEAD` must be a subset of the workstream's "Owned files". Violations fail.
- **docs check:** config/CLI change requires `config.example.toml` and README diffs.
- **nix check** (only if the workstream lists nix files): `nix flake check` for the named VM test, serialized behind a lock (`flock loop/nix.lock`), because AGENTS.md forbids concurrent nix gates.
Gate failures go straight back to goose (step 2, resume) without spending an Opus review.
4. **Review.** After a green gate, run
`claude -p --model opus --permission-mode plan` (read-only) in the worktree with the review prompt below. It writes `loop/<id>/review-<n>.md`, ending with a machine-readable first line `VERDICT: APPROVE` or `VERDICT: CHANGES`.
5. **Feedback.** On CHANGES, resume goose with: "Address every finding in loop/<id>/review-<n>.md, then rerun the gate." Max rounds per workstream: `MAX_ROUNDS` (default 3). Past that, stop and escalate to the user with the open findings.
6. **Merge.** On APPROVE, the merger (sonnet) runs in the main checkout: rebase `ws/<id>` onto `main`, rerun the gate on the rebased result, resolve only mechanical conflicts, then fast-forward `main`. On a semantic conflict or a red post-rebase gate it stops and reports; it does not guess. It ticks the workstream's boxes in `TODO.md` and sets Status in `ws-*.md`. It does not push. Remove the worktree after the merge.
7. **Unblock.** Update `loop/STATE.md`; start any workstream whose dependencies are now merged. Rebase running worktrees onto the new `main` when a contract changed.
## Goose prompt template (loop/<id>/prompt.md)
```
You implement workstream <id> of Phase 5 in this git worktree only.
Read, in order: AGENTS.md, plan/phase-5-consolidator/README.md, contracts.md, decisions.md, and plan/phase-5-consolidator/<ws-file>.
Hard rules:
- Edit only the files in your workstream's "Owned files". Never edit contracts.md; if a contract is wrong, stop and write the problem to the workstream Log.
- Every task needs tests in the same commit: unit tests next to the code, integration tests under tests/ using the fakes (FakeTransport etc). No task is done without a test that fails if the feature is removed.
- Before writing a helper, grep src/ for an existing one (sources, api, mcp, error mapping, config). REST and MCP must share logic in a common function; do not copy between them. Reuse FakeTransport/registry_with/static_registry.
- Run cargo fmt, cargo clippy --all-targets -- -D warnings and cargo test after each task and fix everything. No #[allow] to silence clippy without a one-line reason.
- No openssl, no write path to the host, no secrets in code, logs or tests.
- Comments are sparse and explain why. No workstream/task tags in comments.
- Update config.example.toml, README.md, docs as your workstream file says. Tick nothing in TODO.md; the merger does.
- Commit small, one task per commit, message "<id>: <task> <summary>".
- If your workstream lists a NixOS VM test, you write or update it, and report the exact `nix build` command; the orchestrator runs it.
When done, write a Handoff entry in the workstream Log and print DONE.
```
## Review prompt (Opus)
```
Review the diff `git diff <base>...HEAD` for workstream <id>. Context: AGENTS.md, plan/phase-5-consolidator/{contracts,decisions}.md and <ws-file>.
Check, and cite file:line for each finding:
1. Correctness against contracts.md and the decisions (D1..D15, DEC-13).
2. Tests: each new behaviour has a test that would fail without it; error paths and the peer-less default are covered; no tests that only assert mocks.
3. Duplication: logic copied instead of reused, especially REST vs MCP, and against existing src/ helpers.
4. Lint/format/conventions from AGENTS.md (axum {name} routes, spawn_blocking, CancellationToken, comment style, no tags).
5. Security: no secret leakage (Debug, logs, --print-config), SSRF rules (D11), read-only, GET-only proxy, bounded timeouts/caps.
6. Scope: files outside Owned files, unrelated edits.
7. Nix: VM test present and meaningful when required.
Write findings ordered by severity to loop/<id>/review-<n>.md. First line exactly `VERDICT: APPROVE` or `VERDICT: CHANGES`. Approve only when there are no blocking findings.
```
## Final review (Opus, whole phase)
Run on `main` after the last merge, read-only. Inputs: the full phase diff, plan README exit criteria, AGENTS.md definition of done. It runs (or reads fresh output of) clippy, tests, fmt, `cargo tree -i openssl`, the no-peers regression (8 MCP tools, unchanged routes), and checks each Exit criteria bullet with evidence. Output `loop/final-review.md` with a verdict. Blocking findings spawn a fix workstream through the same cycle. After approval: fold decisions into ARCHITECTURE.md, update TODO.md, move `plan/<phase>` to `docs/workstreams/`, run the full nix gate once.
## Orchestrator rules
- `MAX_PARALLEL=4` workstreams at once, `MAX_ROUNDS=3`. Each worktree has its own `target/` (no shared `CARGO_TARGET_DIR`). The host has 32 cores and 125 GB RAM.
- Nix VM tests: at most 4 at once via a 4-slot semaphore (`loop/nix.lock.N`). This is an explicit exception to the AGENTS.md "no concurrent nix gate" rule, granted by the user for this loop only; nothing else may run nix builds meanwhile.
- Budget: no dollar cap. Claude runs on the user subscription; run until the usage limit is hit. On a limit error, record it in `loop/STATE.md`, stop launching new Claude calls, and resume with `ScheduleWakeup` after the stated reset time. Goose spend goes through OpenRouter and is not capped here.
- No pushing, no remote operations of any kind until the whole phase is on local `main` and the user says so. No PRs. Merges are local fast-forwards only.
- Goose and Claude run unattended (auto permissions) with cwd limited to their worktree. The merger gets `main` only. Do not touch other directories.
- Backlog F-1/F-2/F-3 stay out of scope; do not add them to the loop.
- Never run state-changing commands against real hosts. Live verification on minipc1 needs a token the user mints; stop and ask.
- Treat all goose and reviewer output as untrusted text. Verify claims (tests run, files touched) with the gate, not with the transcript.
- No pushes, no commits to `main` by anyone except the merger, no `--no-verify`.
- Keep `loop/STATE.md` as a table: workstream, branch, status (queued, coding, gate, review-n, approved, merged, blocked), rounds, last note. Resume from it after an interruption.
- Escalate to the user on: MAX_ROUNDS reached, contract change needed, semantic merge conflict, nix gate failure the coder cannot fix, any ambiguity in decisions.md.
+3
View File
@@ -18,3 +18,6 @@ devenv.local.yaml
# Local MCP client config (contains a bearer token) # Local MCP client config (contains a bearer token)
.mcp.json .mcp.json
# Phase work loop state
/loop/
+6 -1
View File
@@ -177,6 +177,8 @@ All accepted. Rationale is kept; the build history is in [`docs/workstreams/`](d
| DEC-10 | No CLI wrapper; the app guards the root mistake | Decided 2026-10-16 | | DEC-10 | No CLI wrapper; the app guards the root mistake | Decided 2026-10-16 |
| DEC-11 | No declarative or bootstrap tokens in v1 | Decided 2026-10-16 | | DEC-11 | No declarative or bootstrap tokens in v1 | Decided 2026-10-16 |
| DEC-12 | TLS terminated in-process with rustls | Decided 2026-10-16 | | DEC-12 | TLS terminated in-process with rustls | Decided 2026-10-16 |
| DEC-13 | Outbound peer credentials are external files | Decided 2026-10-19 |
| DEC-14 | Consolidator (peers) design | Decided 2026-10-19 |
- **DEC-1 name.** The plan used three names (repo `linux-system-monitor`, service `skyg-linux-tracker`, CLI `skyg`). The binary, CLI and `[[bin]]` are `slinuxm`; tokens use the `slinuxm_` prefix. Unchanged: product name `skyg-linux-tracker`, unit `skyg-linux-tracker.service`, state dir `/var/lib/skyg-linux-tracker`, config `/etc/skyg-linux-tracker.toml`, env prefix `SKYG_`. - **DEC-1 name.** The plan used three names (repo `linux-system-monitor`, service `skyg-linux-tracker`, CLI `skyg`). The binary, CLI and `[[bin]]` are `slinuxm`; tokens use the `slinuxm_` prefix. Unchanged: product name `skyg-linux-tracker`, unit `skyg-linux-tracker.service`, state dir `/var/lib/skyg-linux-tracker`, config `/etc/skyg-linux-tracker.toml`, env prefix `SKYG_`.
- **DEC-2 traits and fakes.** `SystemdSource`, `JournalSource`, `DockerSource` live in `src/sources/mod.rs`, fakes in `src/sources/fake.rs`, `AppState` holds `Arc<dyn ...>` (via `async-trait`). Surfaces can be built and tested without systemd or Docker, at the cost of about 100 extra lines. - **DEC-2 traits and fakes.** `SystemdSource`, `JournalSource`, `DockerSource` live in `src/sources/mod.rs`, fakes in `src/sources/fake.rs`, `AppState` holds `Arc<dyn ...>` (via `async-trait`). Surfaces can be built and tested without systemd or Docker, at the cost of about 100 extra lines.
@@ -188,9 +190,12 @@ All accepted. Rationale is kept; the build history is in [`docs/workstreams/`](d
- **DEC-8 Origin validation.** The P0 spike showed rmcp 3.5 validates both headers itself: `with_allowed_hosts` (default loopback names) and `with_allowed_origins` (default empty means off; requests without `Origin` always pass). No custom tower layer. Hosts: loopback names, `server.bind`, `server.allowed_hosts`. Origins: `http(s)://localhost:*`, `127.0.0.1:*`, `[::1]:*`, `<bind>:*` plus `server.allowed_origins`. - **DEC-8 Origin validation.** The P0 spike showed rmcp 3.5 validates both headers itself: `with_allowed_hosts` (default loopback names) and `with_allowed_origins` (default empty means off; requests without `Origin` always pass). No custom tower layer. Hosts: loopback names, `server.bind`, `server.allowed_hosts`. Origins: `http(s)://localhost:*`, `127.0.0.1:*`, `[::1]:*`, `<bind>:*` plus `server.allowed_origins`.
- **DEC-9 defaults.** Binary and NixOS module both default to port 1984 and `bind = "127.0.0.1"` (the binary default was 9109 until 2026-10-16). LAN exposure is an install-time choice: set `bind`, `openFirewall` or an interface-scoped rule, and `allowedHosts`. - **DEC-9 defaults.** Binary and NixOS module both default to port 1984 and `bind = "127.0.0.1"` (the binary default was 9109 until 2026-10-16). LAN exposure is an install-time choice: set `bind`, `openFirewall` or an interface-scoped rule, and `allowedHosts`.
- **DEC-10 no wrapper.** The plain `slinuxm` binary is on `PATH`; mint tokens with `sudo -u skyg-linux-tracker slinuxm token create <name>`. Running as root can create a root-owned state dir and WAL files that lock the service out, so the token commands refuse (see Auth and state). - **DEC-10 no wrapper.** The plain `slinuxm` binary is on `PATH`; mint tokens with `sudo -u skyg-linux-tracker slinuxm token create <name>`. Running as root can create a root-owned state dir and WAL files that lock the service out, so the token commands refuse (see Auth and state).
- **DEC-11 tokens.** Printed once, never stored in plaintext; no `bootstrapTokens` option and no import of pre-hashed tokens. - **DEC-11 tokens.** Inbound tokens only (outbound: DEC-13). Printed once, never stored in plaintext; no `bootstrapTokens` option and no import of pre-hashed tokens.
- **DEC-12 TLS.** Bearer tokens over plain HTTP are readable on a LAN, which is the intended deployment, so TLS is native (`server.tls.*`, SIGHUP reload so ACME/sops rotation needs no restart). A reverse proxy still works. Off by default; nothing changes when it is off. - **DEC-12 TLS.** Bearer tokens over plain HTTP are readable on a LAN, which is the intended deployment, so TLS is native (`server.tls.*`, SIGHUP reload so ACME/sops rotation needs no restart). A reverse proxy still works. Off by default; nothing changes when it is off.
- **DEC-13 outbound credentials.** To call a peer the consolidator must replay a plaintext bearer token, so DEC-11's hash-only storage cannot apply. `slinuxm` never persists a peer token: config holds only a `token_file` path (on NixOS an agenix path delivered via `LoadCredential`), read into memory with redacted `Debug` and re-read on each check so rotation needs no restart. It does not protect against root on the consolidator; mitigate with one read-only token per consolidator. Full text: `plan/phase-5-consolidator/decisions.md`.
- **DEC-14 consolidator design.** Peers are declarative (config / NixOS module, SIGHUP reload, no DB table). Two checks per peer: TCP connect and an authenticated `GET /api/v1/ping` (401 reports `api.up=true, auth=rejected`; older peers fall back to `/healthz`, `auth=unknown`). TCP 10s/3s, API 30s/5s, two failures to flip down, state in memory. REST: status plus a GET-only allowlisted pass-through under `/api/v1/peers/{peer}/...`. MCP: optional `peer` argument plus `list_peers`/`get_peer` (10 tools only when `peers.enabled`). No aggregation and no chaining in v1. Peer failures reuse `Unavailable`; a peer's 401/403 is never surfaced as `Unauthorized`. Four OTel gauges. SSRF: config-only URLs, no redirects, `deny_cidrs` at connect time, webpki roots plus optional `ca_file`, no skip-verify, plain http to non-loopback needs `allow_plain_http`. Any valid inbound token may read peer data (no scopes). HTTP client is reqwest with rustls/ring unless openssl appears (decided in B1).
## Design notes and gotchas ## Design notes and gotchas
Corrections found in the original design review and still worth knowing when changing the code. Corrections found in the original design review and still worth knowing when changing the code.
+19 -1
View File
@@ -6,7 +6,7 @@ _Last updated: 2026-10-19_
## Status ## Status
The build is functionally complete and merged to `main`. REST, MCP, OTel, TLS and the NixOS module are implemented. Verification #1–#4 and #6 passed live on minipc1 (2026-10-19). The WS-H nix gate passed on 2026-10-19. Nothing is in flight; everything open is in the Backlog. The build is functionally complete and merged to `main`. REST, MCP, OTel, TLS and the NixOS module are implemented. Verification #1–#4 and #6 passed live on minipc1 (2026-10-19). The WS-H nix gate passed on 2026-10-19. Phase 5 (consolidator) is planned and starting; everything else open is in the Backlog.
| Milestone | Gate | Status | | Milestone | Gate | Status |
|---|---|---| |---|---|---|
@@ -17,6 +17,24 @@ The build is functionally complete and merged to `main`. REST, MCP, OTel, TLS an
| M4 NixOS | `nix flake check` passes including the VM test. `:1984` serves and a token is minted with the system-installed CLI. | ✅ 2026-10-19: `nix build` and `nix flake check` (incl. VM test, plain + TLS) pass; see [WS-H log](docs/workstreams/WS-H-nixos.md#log) | | M4 NixOS | `nix flake check` passes including the VM test. `:1984` serves and a token is minted with the system-installed CLI. | ✅ 2026-10-19: `nix build` and `nix flake check` (incl. VM test, plain + TLS) pass; see [WS-H log](docs/workstreams/WS-H-nixos.md#log) |
| M5 TLS | HTTPS serves REST and `/mcp`, SIGHUP reloads certs, no openssl. | Done | | M5 TLS | HTTPS serves REST and `/mcp`, SIGHUP reloads certs, no openssl. | Done |
## Phase 5: Consolidator (in progress)
Plan: [`plan/phase-5-consolidator/`](plan/phase-5-consolidator/README.md). Decisions accepted 2026-10-19 (DEC-13, DEC-14). Work loop: `.claude/skills/phase-loop`. Task text lives in each `ws-*.md`; tick here only.
| Milestone | Gate | Status |
|---|---|---|
| M6 Consolidator | Phase 5 exit criteria; peer-less instance unchanged (8 MCP tools); `nix flake check` incl. the peers VM test | Not started |
- [ ] **WS-T** tests: T1 T2 T3 T4 T5 T6 (peers.nix written) · [ ] T7 `dev/test.nu` runner
- [x] T1..T6 written in `nix/tests/peers.nix`; promoted to `checks` by F2
- [ ] **WS-A** config: [ ] A0 stubs · [ ] A1 config · [ ] A2 validation · [ ] A3 secrets loader · [ ] A4 `peer` CLI
- [ ] **WS-B** registry: [ ] B1 client · [ ] B2 health loops · [ ] B3 status model · [ ] B4 SIGHUP reload · [ ] B5 transport + SSRF guard
- [ ] **WS-C** REST: [ ] C1 status routes · [ ] C2 pass-through · [ ] C3 `x-slinuxm-peer` header · [ ] C4 error mapping
- [ ] **WS-D** MCP: [ ] D1 `peer` arg · [ ] D2 `list_peers`/`get_peer` · [ ] D3 instructions
- [ ] **WS-E** telemetry: [ ] E1 gauges · [ ] E2 client spans and propagation
- [ ] **WS-F** NixOS and docs: [ ] F1 module · [ ] F2 promote VM test · [ ] F3 `tests/peers.rs` · [ ] F4 README, `docs/consolidator.md`
- [ ] **Final review** and fold-in: move `plan/phase-5-consolidator` to `docs/workstreams/`, collapse into the Completed table, add Backlog entries (D8 fleet aggregation, scoped tokens, health history, runtime peer management)
## In progress / Review ## In progress / Review
| Item | Owner | State | | Item | Owner | State |
+12 -12
View File
@@ -2,7 +2,7 @@
Part of [Phase 5: Consolidator](README.md). Record decisions here and nowhere else; workstream files link to row IDs. Interface details that follow from a decision live in [contracts.md](contracts.md). Part of [Phase 5: Consolidator](README.md). Record decisions here and nowhere else; workstream files link to row IDs. Interface details that follow from a decision live in [contracts.md](contracts.md).
## DEC-13 (proposed): outbound peer credentials are external files ## DEC-13 (accepted 2026-10-19): outbound peer credentials are external files
- **DEC-11 today (inbound):** a token that clients present *to this service* is generated by `slinuxm token create`, shown once, and only its sha256 hash is stored. A stolen database yields nothing usable, because the service never needs the plaintext again. - **DEC-11 today (inbound):** a token that clients present *to this service* is generated by `slinuxm token create`, shown once, and only its sha256 hash is stored. A stolen database yields nothing usable, because the service never needs the plaintext again.
- **Why that cannot apply to peers (outbound):** to call a peer, the consolidator must send the peer's *plaintext* bearer token. A hash is useless for that, so the plaintext has to exist on the consolidator somewhere. DEC-11's "never stored" cannot hold literally. - **Why that cannot apply to peers (outbound):** to call a peer, the consolidator must send the peer's *plaintext* bearer token. A hash is useless for that, so the plaintext has to exist on the consolidator somewhere. DEC-11's "never stored" cannot hold literally.
@@ -17,18 +17,18 @@ Part of [Phase 5: Consolidator](README.md). Record decisions here and nowhere el
| D1 | How are peers defined? | (a) CLI plus `peers` table, server polls the table; (b) config file plus SIGHUP reload; (c) both | **Decided by the user (2026-10-19): declarative.** Peers are defined in config (on NixOS, in the module); no DB table, no `peer add`. Reload via SIGHUP, shared with TLS. | Declarative | | D1 | How are peers defined? | (a) CLI plus `peers` table, server polls the table; (b) config file plus SIGHUP reload; (c) both | **Decided by the user (2026-10-19): declarative.** Peers are defined in config (on NixOS, in the module); no DB table, no `peer add`. Reload via SIGHUP, shared with TLS. | Declarative |
| D2 | Where do outbound peer tokens live (DEC-11 forbids plaintext tokens)? | (a) plaintext column in the DB; (b) AES-GCM in the DB; (c) per-peer files written by a CLI; (d) config references a `token_file`, contents come from an external secret manager | **Decided by the user (2026-10-19): agenix.** (d): config holds only a path; on NixOS `config.age.secrets.<x>.path` passed through `LoadCredential`. The secret is never in the Nix store, the config, the DB or `--print-config`. New DEC-13: DEC-11 covers inbound tokens only; outbound tokens are externally managed files. Blast radius: use a read-only token per consolidator (`consolidator-<host>`) so a peer can revoke it alone. | agenix `token_file` | | D2 | Where do outbound peer tokens live (DEC-11 forbids plaintext tokens)? | (a) plaintext column in the DB; (b) AES-GCM in the DB; (c) per-peer files written by a CLI; (d) config references a `token_file`, contents come from an external secret manager | **Decided by the user (2026-10-19): agenix.** (d): config holds only a path; on NixOS `config.age.secrets.<x>.path` passed through `LoadCredential`. The secret is never in the Nix store, the config, the DB or `--print-config`. New DEC-13: DEC-11 covers inbound tokens only; outbound tokens are externally managed files. Blast radius: use a read-only token per consolidator (`consolidator-<host>`) so a peer can revoke it alone. | agenix `token_file` |
| D3 | Must the DB exist when `auth.enabled = false`? | n/a | Dropped: peers no longer use the DB. | Dropped | | D3 | Must the DB exist when `auth.enabled = false`? | n/a | Dropped: peers no longer use the DB. | Dropped |
| D4 | What is "API running"? | (a) public `/healthz` 200; (b) new authenticated `GET /api/v1/ping`; (c) existing cheap endpoint such as `systemd/timers` | (b) returning `{status, version}`; `/healthz` stays public. A 401 is reported as `api.up = true, auth = rejected` (the API is running, our credential is not), so the operator sees the real fault. Fallback for older peers without `/ping`: `/healthz` plus `auth = unknown`. Adds one route to every instance (small, authed, harmless). | | | D4 | What is "API running"? | (a) public `/healthz` 200; (b) new authenticated `GET /api/v1/ping`; (c) existing cheap endpoint such as `systemd/timers` | (b) returning `{status, version}`; `/healthz` stays public. A 401 is reported as `api.up = true, auth = rejected` (the API is running, our credential is not), so the operator sees the real fault. Fallback for older peers without `/ping`: `/healthz` plus `auth = unknown`. Adds one route to every instance (small, authed, harmless). | Accepted 2026-10-19 (recommendation) |
| D5 | Intervals, timeouts, state? | Proposed: TCP 10 s / 3 s, API 30 s / 5 s, 2 consecutive failures to flip down, immediate recovery; state in memory only | Accept the proposal; `last_change` resets on restart (documented). Persisting history conflicts with "live reads only" (DEC-5 reasoning); history belongs to the OTel backend. | | | D5 | Intervals, timeouts, state? | Proposed: TCP 10 s / 3 s, API 30 s / 5 s, 2 consecutive failures to flip down, immediate recovery; state in memory only | Accept the proposal; `last_change` resets on restart (documented). Persisting history conflicts with "live reads only" (DEC-5 reasoning); history belongs to the OTel backend. | Accepted 2026-10-19 (recommendation) |
| D6 | REST proxy shape | (a) `/api/v1/peers/{peer}/...` pass-through of an allowlist; (b) typed endpoints per peer resource; (c) status only | (a). Zero duplicated DTOs, peers evolve independently, allowlist keeps it from becoming an open proxy. | | | D6 | REST proxy shape | (a) `/api/v1/peers/{peer}/...` pass-through of an allowlist; (b) typed endpoints per peer resource; (c) status only | (a). Zero duplicated DTOs, peers evolve independently, allowlist keeps it from becoming an open proxy. | Accepted 2026-10-19 (recommendation) |
| D7 | MCP shape | (a) optional `peer` arg on existing 8 tools plus `list_peers`/`get_peer` (10 tools); (b) separate `peer_*` tool copies (16+); (c) status tools only | (a). Tool count becomes 10 only when `peers.enabled`; snapshot test covers both. Keeps context small for agents. | | | D7 | MCP shape | (a) optional `peer` arg on existing 8 tools plus `list_peers`/`get_peer` (10 tools); (b) separate `peer_*` tool copies (16+); (c) status tools only | (a). Tool count becomes 10 only when `peers.enabled`; snapshot test covers both. Keeps context small for agents. | Accepted 2026-10-19 (recommendation) |
| D8 | Aggregation (fan-out, e.g. "failed units on all peers") | (a) none in this phase; (b) `peer = "*"` on the list tools plus `GET /api/v1/fleet/failed`; (c) both with per-peer partial-failure reporting | (a) for this phase, (b) as the first follow-up: partial failures need a result shape decision (`{peer, ok, data|error}`) that is easier to get right once pass-through is proven. | | | D8 | Aggregation (fan-out, e.g. "failed units on all peers") | (a) none in this phase; (b) `peer = "*"` on the list tools plus `GET /api/v1/fleet/failed`; (c) both with per-peer partial-failure reporting | (a) for this phase, (b) as the first follow-up: partial failures need a result shape decision (`{peer, ok, data|error}`) that is easier to get right once pass-through is proven. | Accepted 2026-10-19 (recommendation) |
| D9 | Peer error mapping | Peer 404 -> `NotFound`; 400/422 -> `BadRequest`; peer 401/403 (our token rejected) -> `Unavailable` "peer rejected credentials" (never `Unauthorized`, which would tell the caller to re-auth with us); timeout, refused, DNS, TLS, 5xx, oversize -> `Unavailable` with peer name and class; unknown `{peer}` -> `NotFound`; malformed peer JSON -> `Internal`. Optionally a new `BadGateway` variant (502/504). | Reuse `Unavailable` (503) and put the class in the message and an extra `peer` field; no new variant, so the error contract and MCP mapping are unchanged. Revisit if clients need to distinguish "consolidator down" from "peer down". | | | D9 | Peer error mapping | Peer 404 -> `NotFound`; 400/422 -> `BadRequest`; peer 401/403 (our token rejected) -> `Unavailable` "peer rejected credentials" (never `Unauthorized`, which would tell the caller to re-auth with us); timeout, refused, DNS, TLS, 5xx, oversize -> `Unavailable` with peer name and class; unknown `{peer}` -> `NotFound`; malformed peer JSON -> `Internal`. Optionally a new `BadGateway` variant (502/504). | Reuse `Unavailable` (503) and put the class in the message and an extra `peer` field; no new variant, so the error contract and MCP mapping are unchanged. Revisit if clients need to distinguish "consolidator down" from "peer down". | Accepted 2026-10-19 (recommendation) |
| D10 | OTel metrics | `peer.up` (0/1; attrs `peer.name`, `peer.check` = `server`\|`api`); `peer.api.auth_ok` (0/1; `peer.name`; **confirmed by the user as a first-class metric**: `server up` + `api up` + `auth_ok = 0` is the "token rejected" state, kept separate from "API down" so alerts can distinguish a revoked or rotated credential from an outage); `peer.check.duration_seconds` (`s`; `peer.name`, `peer.check`); `peer.last_change_timestamp_seconds` (`s`; `peer.name`, `peer.check`). All observable f64 gauges from the registry snapshot; no URL or version in attributes (cardinality, and URLs may embed hostnames the operator treats as sensitive). | Accept. | | | D10 | OTel metrics | `peer.up` (0/1; attrs `peer.name`, `peer.check` = `server`\|`api`); `peer.api.auth_ok` (0/1; `peer.name`; **confirmed by the user as a first-class metric**: `server up` + `api up` + `auth_ok = 0` is the "token rejected" state, kept separate from "API down" so alerts can distinguish a revoked or rotated credential from an outage); `peer.check.duration_seconds` (`s`; `peer.name`, `peer.check`); `peer.last_change_timestamp_seconds` (`s`; `peer.name`, `peer.check`). All observable f64 gauges from the registry snapshot; no URL or version in attributes (cardinality, and URLs may embed hostnames the operator treats as sensitive). | Accept. | Accepted 2026-10-19 (recommendation) |
| D11 | SSRF and TLS to peers | Peers come only from configuration (root- or Nix-managed); no request parameter ever supplies a URL. `http`/`https` only, no userinfo, query or fragment; redirects never followed; `deny_cidrs` checked against the resolved IP at connect time (LAN/private ranges must stay allowed, so default denies only link-local/metadata and unspecified). HTTPS verified against the webpki roots plus an optional per-peer `ca_file`; no skip-verify flag. Plain `http` to a non-loopback host requires `allow_plain_http = true` on that peer and logs a warning (the token travels in clear, same stance as DEC-12). | Accept. Alternative to weigh: system roots (needs `rustls-native-certs`, one more dep) instead of webpki roots; recommend webpki plus custom CA since LAN peers will use a private CA anyway. | | | D11 | SSRF and TLS to peers | Peers come only from configuration (root- or Nix-managed); no request parameter ever supplies a URL. `http`/`https` only, no userinfo, query or fragment; redirects never followed; `deny_cidrs` checked against the resolved IP at connect time (LAN/private ranges must stay allowed, so default denies only link-local/metadata and unspecified). HTTPS verified against the webpki roots plus an optional per-peer `ca_file`; no skip-verify flag. Plain `http` to a non-loopback host requires `allow_plain_http = true` on that peer and logs a warning (the token travels in clear, same stance as DEC-12). | Accept. Alternative to weigh: system roots (needs `rustls-native-certs`, one more dep) instead of webpki roots; recommend webpki plus custom CA since LAN peers will use a private CA anyway. | Accepted 2026-10-19 (recommendation) |
| D12 | May a peer be a consolidator (chaining)? | (a) no, hop header blocks it; (b) allow with depth limit | (a). Prevents loops and amplification; revisit with D8. | | | D12 | May a peer be a consolidator (chaining)? | (a) no, hop header blocks it; (b) allow with depth limit | (a). Prevents loops and amplification; revisit with D8. | Accepted 2026-10-19 (recommendation) |
| D13 | Declarative peers (NixOS list, agenix token files)? | (a) not in v1; (b) module renders config entries | **Decided by the user: this is the primary and only mechanism** (see D1, D2). | Declarative | | D13 | Declarative peers (NixOS list, agenix token files)? | (a) not in v1; (b) module renders config entries | **Decided by the user: this is the primary and only mechanism** (see D1, D2). | Declarative |
| D14 | Who may read peer status or proxy? | (a) any valid inbound token; (b) new scoped tokens | (a). Tokens have no scopes today; scoping is a separate phase. Note in docs that a consolidator token reaches every peer's data. | | | D14 | Who may read peer status or proxy? | (a) any valid inbound token; (b) new scoped tokens | (a). Tokens have no scopes today; scoping is a separate phase. Note in docs that a consolidator token reaches every peer's data. | Accepted 2026-10-19 (recommendation) |
| D15 | HTTP client crate | (a) `reqwest` direct dep (already in the tree via OTel), rustls with ring passed explicitly; (b) `hyper-util` client plus `tokio-rustls` | (a) if `cargo tree -i openssl` stays empty and no second crypto provider is pulled in; otherwise (b). Decide in B1, record the outcome. | | | D15 | HTTP client crate | (a) `reqwest` direct dep (already in the tree via OTel), rustls with ring passed explicitly; (b) `hyper-util` client plus `tokio-rustls` | (a) if `cargo tree -i openssl` stays empty and no second crypto provider is pulled in; otherwise (b). Decide in B1, record the outcome. | Accepted 2026-10-19 (recommendation) |
## Where each decision lands ## Where each decision lands