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:
1 parent
782e5dc440
commit
d04d99a9a6
5 files changed
+145
-14
No files matched your search
@@ -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.
|
||||
@@ -18,3 +18,6 @@ devenv.local.yaml
|
||||
|
||||
# Local MCP client config (contains a bearer token)
|
||||
.mcp.json
|
||||
|
||||
# Phase work loop state
|
||||
/loop/
|
||||
+6
-1
@@ -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-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-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-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-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-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-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
|
||||
|
||||
Corrections found in the original design review and still worth knowing when changing the code.
|
||||
|
||||
@@ -6,7 +6,7 @@ _Last updated: 2026-10-19_
|
||||
|
||||
## 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 |
|
||||
|---|---|---|
|
||||
@@ -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) |
|
||||
| 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
|
||||
|
||||
| Item | Owner | State |
|
||||
|
||||
@@ -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).
|
||||
|
||||
## 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.
|
||||
- **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 |
|
||||
| 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 |
|
||||
| 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). | |
|
||||
| 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. | |
|
||||
| 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. | |
|
||||
| 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. | |
|
||||
| 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. | |
|
||||
| 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". | |
|
||||
| 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. | |
|
||||
| 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. | |
|
||||
| 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. | |
|
||||
| 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. | 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. | 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. | 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. | 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". | 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. | 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. | 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. | 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 |
|
||||
| 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. | |
|
||||
| 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. | |
|
||||
| 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. | Accepted 2026-10-19 (recommendation) |
|
||||
|
||||
## Where each decision lands
|
||||
|
||||
|
||||
Reference in new issue
Block a user