@celilo/cli 1.1.0 → 1.3.0

package/CELILO_CORE_MODULES.md

@@ -41,12 +41,12 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 - **technitium** — internal split-horizon DNS resolver + authoritative server (web UI + HTTP API); heavier alternative to knot-unbound. **provides:** `dns_internal`. Ships a base-module-aspect (`modules/technitium/base-module-aspect/`).
 - **namecheap** — public DNS A-record management via Namecheap Dynamic DNS API (HTTP, no browser automation). A caller supplies a NAME and nothing else: the address is the source IP of celilo's own update, re-derived on every assert. Registering `<domain>` also claims `www.<domain>` and vice versa (best effort, reported back as `outputs.companion_fqdn` so the framework's `public_dns` check watches it — Namecheap answers `ErrCount 0` for `www` updates it does not apply). DDNS passwords are keyed by the **registrable domain**, never the FQDN. **provides:** `dns_registrar`.
 - **wireguard** — owns the admin WireGuard tunnel on the firewall host: interface, listen port, peers (as records), and client subnet are module config rather than hand-maintained state. Exposes the listen port and **registers the client subnet as a trusted source**, so VPN reach into the managed zones is in the firewall registry and every converge re-emits it. **REQUIRES the `control-plane-vpn` network and READS its range** (`requires.networks`; `client_subnet` is a `source: system` derive of `network.control-plane-vpn.subnet`). It does not write that network and has no way to — celilo owns the namespace, and the deploy will not reach any hook until the network is defined, asking for a range if one is missing. So `wg0` is attributable the moment it exists. This replaces a declare-before-you-create ordering inside `on_install`, which could only narrow the window and not close it: a consumer that captured config before the hook started could not see a value the hook wrote, whatever order it wrote it in, and that is exactly what left `wg0` unattributable (celilo#759). `health_check` still asserts the declaration matches what the tunnel serves — what it catches now is divergence, celilo's network having changed since the module resolved its config. That same key is what the internal resolver's split-horizon view consumes. Adopts a running tunnel in place (existing key retained; `wg syncconf`, never `wg-quick down`) because that tunnel is the operator's recovery path. **Adoption is a one-time IMPORT and it ENDS.** The marker is `registered_peers` — celilo's own config key, separate from the operator's `peers` so a machine can never rewrite what an operator typed. While that key has never been written the tunnel is not yet celilo's; the deploy that writes it (even as `[]`) CLAIMS the tunnel, importing whatever `[Peer]` blocks are running, and from then on the render is closed-world (`peers` ∪ `registered_peers`) with a `[Peer]` on the box in neither reported as drift by `on_install` and by `health_check`'s `unknown_peers`. An ABSENT `peers` declaration and a declared-EMPTY one are deliberately different (no `default: []` on either variable): they used to be the same value, so the module read every empty list as "adopt what is running", the last peer could not be revoked, and a hand-added peer rode along on every deploy unreported (celilo#765). On a tunnel celilo has not yet claimed, a declared-empty `peers` is REFUSED rather than obeyed — celilo's own variable-default seeding wrote a real `peers = []` row for every install of the previous version that never set one, so on the installed base an empty list cannot be told from a stored default, and obeying it would `wg syncconf` the admin tunnel down to zero peers. **PROVIDES `control_plane_vpn`** so another module can enrol clients without an operator editing YAML: `registerClient` / `revokeClient` write to `registered_peers` — the same key the adoption claim uses — and `getEndpoint` reads the server's public key LIVE off the host rather than storing a copy that could be republished after the key changed. `client_pool` is the range a consumer may allocate from, a strict subset of the client subnet, and `validate_config` REFUSES any operator-declared peer inside it: the two allocators cannot see each other, so the range is divided rather than negotiated, and that check is the only place a bad division is caught. ⚠️ Granting this capability grants fleet-wide reach — the tunnel's client subnet is a registered trusted source, so every client enrolled through it reaches every managed zone. **requires:** `firewall` (and the provider must support trusted-source registration — `iptables` does; the ISP-router drivers `greenwave` and `axon` do not).
-- **wireguard-manager** — self-service enrolment for the control-plane VPN, so adding an administrator's laptop is a web page rather than an operator editing `peers` by hand. A browser generates the WireGuard keypair with WebCrypto and **the private key never leaves it** — celilo never sees it and the app never stores it. The app allocates an address from `client_pool` (the range `wireguard` reserved for a consumer; celilo's IPAM deliberately does not cover VPN clients) and enrols the peer through **`control_plane_vpn`**, so it never edits wireguard's config and cannot reach a peer the operator declared by hand. Its own device list is the app's SQLite, reconciled onto the tunnel by the `reconcile_clients` hook on a `timer.tick.1m` subscription. Two guards make a failed poll harmless and both are structural rather than a check: `planReconcile` accepts only the `read` variant of a discriminated union, so an unreadable poll cannot reach it, and revocation is TOMBSTONE-driven — a device is revoked because the app says it was, never because it is missing from a list — so a short or empty read can only fail to add someone, never cut anyone off. A peer on the tunnel the app does not know and has not tombstoned is reported as an orphan and LEFT ALONE (usually an app restored from an older backup). **REQUIRES `private_web`, never `public_web`**: there is no public record, no ACME certificate and no port forward, and the internal CA's certificate is bundled with each downloaded config so a freshly enrolled device trusts the manager it just connected to. ⚠️ **Everyone enrolled becomes a fleet administrator** — the tunnel's client subnet is a registered trusted source, so the `admin_group` gate on the idp application is the entire access-control story; per-peer narrowing is not possible, because server-side `AllowedIPs` is crypto-key routing rather than access control. Lives in **`app`**, one tier behind `caddy-internal` in `dmz`, and is never reached directly (celilo#879). Enrolment works from INSIDE the fleet only (a device not yet on the VPN cannot reach a manager reachable only over it) — from the LAN through the ingress IP, from a segmented zone at the ingress's dmz address, or over an existing VPN session, and a revocation takes effect at the next reconcile — that interval IS the window in which a revoked device still has reach, which is why the UI shows it pending and why `celilo module run-hook wireguard-manager reconcile_clients` exists. **requires:** `control_plane_vpn` (wireguard), `idp` (authentik), `private_web` (caddy-internal).
+- **wireguard-manager** — self-service enrolment for the control-plane VPN, so adding an administrator's laptop is a web page rather than an operator editing `peers` by hand. A browser generates the WireGuard keypair with WebCrypto and **the private key never leaves it** — celilo never sees it and the app never stores it. The app allocates an address from `client_pool` (the range `wireguard` reserved for a consumer; celilo's IPAM deliberately does not cover VPN clients) and enrols the peer through **`control_plane_vpn`**, so it never edits wireguard's config and cannot reach a peer the operator declared by hand. Its own device list is the app's SQLite, reconciled onto the tunnel by the `reconcile_clients` hook on a `timer.tick.1m` subscription. Two guards make a failed poll harmless and both are structural rather than a check: `planReconcile` accepts only the `read` variant of a discriminated union, so an unreadable poll cannot reach it, and revocation is TOMBSTONE-driven — a device is revoked because the app says it was, never because it is missing from a list — so a short or empty read can only fail to add someone, never cut anyone off. A peer on the tunnel the app does not know and has not tombstoned is reported as an orphan and LEFT ALONE (usually an app restored from an older backup). **REQUIRES `private_web`, never `public_web`**: there is no public record, no ACME certificate and no port forward, and the internal CA's certificate is bundled with each downloaded config so a freshly enrolled device trusts the manager it just connected to. **The app authenticates people ITSELF** — it runs the OIDC authorization-code + PKCE flow from its own page, exchanges the code server-side (the client is confidential), verifies the resulting access JWT against the issuer's JWKS and reads the group claim out of the token it verified. No cookie and no server-side session, because the page is self-contained client-side JS and a session store on the box that hands out fleet access is state worth not having. It previously trusted an `X-Forwarded-User` header from an authenticating ingress that celilo has never had — leaving it both unusable (the header was always absent) and forgeable (anyone reachable could set it); `identity_header` is gone with no fallback. ⚠️ **Everyone enrolled becomes a fleet administrator** — the tunnel's client subnet is a registered trusted source, so membership of `admin_group`, checked against the token's group claim, is the entire access-control story; per-peer narrowing is not possible, because server-side `AllowedIPs` is crypto-key routing rather than access control. Lives in **`app`**, one tier behind `caddy-internal` in `dmz`, and is never reached directly (celilo#879). Enrolment works from INSIDE the fleet only (a device not yet on the VPN cannot reach a manager reachable only over it) — from the LAN through the ingress IP, from a segmented zone at the ingress's dmz address, or over an existing VPN session, and a revocation takes effect at the next reconcile — that interval IS the window in which a revoked device still has reach, which is why the UI shows it pending and why `celilo module run-hook wireguard-manager reconcile_clients` exists. **requires:** `control_plane_vpn` (wireguard), `idp` (authentik), `private_web` (caddy-internal).
 
 ## Public edge (ingress / identity)
 
 - **caddy** — reverse proxy with automatic HTTPS (HTTP-01 ACME); the standard HTTPS ingress. Emits a 301 redirect block for each served name's `www`/apex companion (kept out of the served-hostname set, so a companion never blocks the ACME wait). Its `health_check`'s DNS item is `internal_dns_resolution` — it digs from the management host behind the split-horizon resolver and is evidence about the in-fleet view only; public reachability is the framework's `public_dns` check. **provides:** `public_web`. **requires:** `dns_registrar`, `firewall`.
-- **caddy-internal** — a SECOND Caddy that serves the fleet and nothing else, and is a sibling of **caddy** rather than a mode of it. It never exposes a port on the firewall's EXTERNAL interface, never publishes a public record, and takes its certificates from Caddy's own local CA (`tls internal`) — those absences ARE the capability, and `public_web` cannot express them because it treats an unreachable route as a deploy failure and publishes a public A record to prevent one (design D10). Lives in the **`dmz`** zone, in front of the things it fronts, mirroring the public `caddy` (celilo#879). LAN devices reach it through an IPAM-allocated `internal`-subnet `ingress_ip` that `on_install` passes to `firewall.exposeService({ ingressIp })` — one DNAT on the firewall's INTERNAL side and nothing external, the same mechanism the dmz-resident `dns_internal` resolver has used for `:53` since ISS-0156. Systems already inside `dmz`/`app`/`secure` use its dmz address instead (carried as `zoneRoutableValue` on the internal record), and VPN clients arrive as a registered trusted source. It previously lived in `internal` on the claim that a dmz ingress could not be reached from a LAN without a public port-forward; that conflated a public forward with an internal-side ingress IP, and cost it the ability to serve a browser inside a segmented zone at all. **`getCaCertificate()` is why the contract has a method `public_web` does not** — an internally-issued cert means clients must trust a CA celilo runs, and here that is nearly free because the people who must trust it are the ones who just downloaded a bundle from the service behind it, so the anchor ships with it. **The route table is this module's OWN config (`routes`), never celilo's `web_routes`** (celilo#846): caddy derives its served hostnames from every row of that table, so a private route stored there would be picked up and served PUBLICLY — storage is the privacy boundary, not policy. Route changes reconcile synchronously in the capability call (there is no `routes_changed` event for private routes, and inventing one would only add delay). A consumer cannot register a route on a hostname the ingress is not already configured for: a capability factory gets no capabilities of its own, so it cannot add the internal DNS record a new name would need, and it refuses rather than serving an unresolvable site block. **provides:** `private_web`. **requires:** `dns_internal` — declared under `optional.capabilities` ONLY to route around celilo#854 (the import-time secret gate refuses a consumer over a secret it never reads); `on_install` throws without it.
+- **caddy-internal** — a SECOND Caddy that serves the fleet and nothing else, and is a sibling of **caddy** rather than a mode of it. It never exposes a port on the firewall's EXTERNAL interface, never publishes a public record, and takes its certificates from Caddy's own local CA (`tls internal`) — those absences ARE the capability, and `public_web` cannot express them because it treats an unreachable route as a deploy failure and publishes a public A record to prevent one (design D10). Lives in the **`dmz`** zone, in front of the things it fronts, mirroring the public `caddy` (celilo#879). LAN devices reach it through an IPAM-allocated `internal`-subnet `ingress_ip` that `on_install` passes to `firewall.exposeService({ ingressIp })` — one DNAT on the firewall's INTERNAL side and nothing external, the same mechanism the dmz-resident `dns_internal` resolver has used for `:53` since ISS-0156. Systems already inside `dmz`/`app`/`secure` use its dmz address instead (carried as `zoneRoutableValue` on the internal record), and VPN clients arrive as a registered trusted source. It previously lived in `internal` on the claim that a dmz ingress could not be reached from a LAN without a public port-forward; that conflated a public forward with an internal-side ingress IP, and cost it the ability to serve a browser inside a segmented zone at all. **`getCaCertificate()` is why the contract has a method `public_web` does not** — an internally-issued cert means clients must trust a CA celilo runs, and here that is nearly free because the people who must trust it are the ones who just downloaded a bundle from the service behind it, so the anchor ships with it. **The route table is this module's OWN config (`routes`), never celilo's `web_routes`** (celilo#846): caddy derives its served hostnames from every row of that table, so a private route stored there would be picked up and served PUBLICLY — storage is the privacy boundary, not policy. Route changes reconcile synchronously in the capability call (there is no `routes_changed` event for private routes, and inventing one would only add delay). **Every proxied route strips a client-supplied `X-Forwarded-User`** (`header_up -X-Forwarded-User`): this ingress routes and does not authenticate, so a backend believing that header would believe whatever the client sent — which `wireguard-manager` shipped doing. That module verifies a signed token now, so the strip protects the NEXT backend written against the same assumption. It is defence in depth, NOT an authenticating proxy: adding `forward_auth` to `private_web` is a capability change and deliberately not bundled with it. A consumer cannot register a route on a hostname the ingress is not already configured for: a capability factory gets no capabilities of its own, so it cannot add the internal DNS record a new name would need, and it refuses rather than serving an unresolvable site block. **provides:** `private_web`. **requires:** `dns_internal` — declared under `optional.capabilities` ONLY to route around celilo#854 (the import-time secret gate refuses a consumer over a secret it never reads); `on_install` throws without it.
 - **generic-cpanel-hosting-provider** — publishes static sites into a subfolder of a domain on a cPanel/SSH web host celilo does **not** govern (the host owns the domain, DNS, TLS and web server). Systemless like **namecheap** — no `requires.system`, no zone, no IPAM; it holds credentials for an external party. One provider serves many accounts, resolved by hostname; onboarding takes the account password once, `ssh-copy-id`s celilo's key, then discards it. **provides:** `external_web`.
 - **authentik** — Authentik identity provider with OIDC (Docker Compose: server, worker, Postgres, Redis). **provides:** `idp`. **requires:** `public_web`, `dns_registrar`, `firewall`.
 

package/CELILO_SUBSYSTEMS.md

@@ -176,7 +176,10 @@ runner seam (`execRunner` real / `createMockRunner` for tests) lives in
 - **Hook executor / ABI** — `apps/celilo/src/hooks/executor.ts` (`invokeHook`, `executeHookScript`, `checkRequiredCapabilities`), types in `apps/celilo/src/hooks/types.ts` (`HookContext`, `HookDefinition`, `HookName`). Named-hook runner: `apps/celilo/src/hooks/run-named-hook.ts`. Manifest hook config: `apps/celilo/src/hooks/load-hook-config.ts`.
 - **Deploy pipeline** — `apps/celilo/src/services/module-deploy.ts`.
 - **DNS provider backfill** (re-emit registrations when a provider deploys) — `apps/celilo/src/services/dns-provider-backfill.ts` — `isDnsInternalProvider`, `backfillProviderDns`.
-- **Base-module aspects (fan-out across the fleet)** — `apps/celilo/src/services/aspect-runner.ts` — `planAspectFanOut`, `runAspectFanOut`, `maybeRunAspectForTrigger`. Aspect content lives in `modules/<m>/base-module-aspect/` (e.g. knot-unbound-internal, technitium).
+- **Base-module aspects (fan-out across the fleet)** — `apps/celilo/src/services/aspect-runner.ts` — `planAspectFanOut`, `runAspectFanOut`, `maybeRunAspectForTrigger`. Aspect content lives in `modules/<m>/base-module-aspect/` (e.g. knot-unbound-internal, technitium). Two directions, with DELIBERATELY OPPOSITE failure semantics:
+  - **Outbound** (`maybeRunAspectForTrigger`, `on_install`): one provider's aspect across the whole fleet, enumerated at that instant. A failure never fails the provider's own deploy — aspects are forward-progress and a partial fleet converges on the next fan-out.
+  - **Inbound** (`reconcileAspectsForSystems`): every approved aspect applied to systems that have just come into existence. Called from `module-deploy.ts` between `waitForSSH` and `executeAnsible` (so a module's playbook and `on_install` see a correctly configured host) and from `machine-add.ts`. Eligibility is `applicable_zones` + approval; the aspect's `triggers` list is deliberately NOT consulted, so convergence is not opt-in per manifest. A failure here IS fatal to the deploy that created the system — the aspect is a prerequisite of that host — while a failure on `machine add` is only a warning. PAUSED providers are skipped, which is the escape hatch for a wedged aspect. Nothing is rolled back: rows, guest and IPAM allocation persist and a re-run converges on the same system. Fixes celilo#902, where a system provisioned after its provider deployed silently never received the aspect. See `openspec/changes/aspect-fanout-new-systems/`.
+  - **Coverage verification** — `verifyAspectCoverage` + `celilo system doctor --deep [--fix]`. Answers "is any system missing an aspect its zone entitles it to" WITHOUT stored state: the entitled set is `planAspectFanOut` itself, and coverage is measured by evaluating the role against the host in Ansible check mode (`executeAnsible({check:true})` + `parseAnsibleRecap`). Three outcomes, not two — `changed=0,skipped=0` applied, `changed>0` missing, **`skipped>0` unknown**, because check mode SKIPS a task it cannot evaluate and a `command`/`shell` role would otherwise report clean having never run.
 - **In-flight operation lock** — `apps/celilo/src/services/module-operations.ts` — `startOperation`/`completeOperation`/`failOperation` record deploy/uninstall/backup/restore in `module_operations`; `refuseIfInFlight`/`checkInFlight` are what backup and restore consult. Deploy and uninstall REGISTER but never check: it is a one-way guard protecting backup/restore consistency, not a general mutex (`openspec/specs/management-server-backup/spec.md` "In-flight operation refusal"). A row stops holding the lock once it is GONE, STOPPED/zombie (`isPidRunnable`, `ps -o state=` — `kill(pid,0)` calls a Ctrl-Z'd process alive), or older than `OPERATION_TTL_MS` (2h). The TTL is not redundancy: a pid is a recycled number, and once the pid space wraps an old row names an unrelated healthy process. Operator surface: `celilo module operations [list|clear] [--abandoned] [--all]` (`apps/celilo/src/cli/commands/module-operations.ts`); `list` shows only what holds the lock, abandoned rows are summarised unless `--abandoned`. Abandoned rows are reclaimed hourly by the `celilo-operations-sweep` bus subscriber (`timer.tick.1h` → `celilo module operations clear`, armed by `ensureOperationsSweepSubscriber` from module registration and `celilo system migrate`). `clear` MARKS rows failed rather than deleting them, and that is load-bearing: the `abandoned_operations` audit reads exactly those released rows to notice one module's operation dying over and over.
 - **Module pause / unpause (control-plane quiescence)** — `apps/celilo/src/services/module-pause.ts` — pure `planPause`/`planUnpause` producing an ordered plan, `executePause`/`executeUnpause` performing it, plus `listPausedModules`/`pausedAmong`/`formatPausedDuration`/`describePausedModule` (the ONE place an age is formatted). CLI: `apps/celilo/src/cli/commands/module-pause.ts` (`celilo module pause|unpause <id> [--cascade] [--stop-infra] [--reason] [--dry-run] [--yes]`). Pausing takes a module out of the CONTROL plane — no dispatched events, no timer hooks, no health checks, alerts suppressed — while leaving the DATA plane running, because capability consumption is deploy-time: every consumer calls `firewall`/`dhcp_server` from `on_install` and nothing calls it while serving. Config, secrets, IPAM/VMID and placement are preserved; `on_uninstall` does NOT run. Quiescence is enforced in two places: pausing drops the module's bus subscriptions (`unregisterModuleSubscriptions`), and `run-named-hook.ts` refuses any non-lifecycle hook for a PAUSED module (`skippedPaused`), which catches the paths that skip the bus — `events resync-subscriptions`, a restore that starts events.db empty, aspect fan-out, public-web republish. `on_install`/`on_uninstall` are exempt by hook NAME (not a caller flag): unpause redeploys through `on_install`, and removing a paused provider needs `on_uninstall`. Unpause always REDEPLOYS (`deployModule`) — that is what rebinds a consumer to a replacement provider and recreates provider-local state from the consumers that own it — and re-registers subscriptions, which a plain deploy does not do. A failed unpause restores `PAUSED` rather than leaving the module live and mis-bound. Cascade order reuses `services/update/dep-graph.ts` unchanged (pause = consumers first, unpause = providers first) and is computed from the GRAPH, never from which modules are currently paused, so a cascade walks THROUGH already-done members and is resumable. See `openspec/changes/module-pause-lifecycle/`.
 - **Provider-removal guard** — `apps/celilo/src/services/remove-guard.ts` — `findRemovalBlockers`/`describeRemovalRefusal`, called from `apps/celilo/src/cli/commands/module-remove.ts`. A PAUSED module is not a dependent (unpause cannot return it to service without a redeploy, and a redeploy re-resolves capabilities), which is what makes a provider swap possible at all. A dependent is one declaring the capability under `requires` **or** `optional` — the same relation `dep-graph.ts` uses, so the guard and the cascade agree on the set; the guard previously read `requires` alone, which let a removal silently orphan `technitium`'s `optional` `dhcp_server`. Refusals name each blocker AND which declaration makes it one. It deliberately does NOT exempt a dependent because another provider of the same capability exists (celilo#683).
@@ -200,6 +203,18 @@ warning naming every paused module and its age onto EVERY management-API result
 That last one is the important half: it does not depend on the operator choosing
 to look, which is how a forgotten pause actually gets found.
 
+## Management-host browser runtime
+
+- **The browser celilo provisions** — installed by `modules/celilo-mgmt/ansible/roles/celilo-mgmt/tasks/debian.yml` into `/var/lib/celilo/browsers`, behind `install_browser` (a manifest boolean **defaulting to false**, exactly how `install_docker` / `install_terraform` gate third-party-repo tooling: ~170 MB from an external CDN). The pin is `playwright_version` in `modules/celilo-mgmt/manifest.yml` — the fleet's single browser-version declaration. What is UNCONDITIONAL is the *declaration*, so a host that needs a browser and lacks one says so. It provisions `chromium-headless-shell`, **not** full Chromium: both builds on celilo-mgr are headless shells and `chromium.launch()` has been driving one in production the whole time, so the full browser would change what works rather than preserve it. Accepted ceiling: no headed browsing. macOS is an explicit `fail`, not a silent skip.
+- **The seam** — `packages/capabilities/src/browser.ts` — `resolveBrowser()` returns `{ browser, flavor, executablePath, browserVersion, playwrightVersion, revision }` read from the stable symlink `/var/lib/celilo/browsers/current/chrome` plus the descriptor `current/celilo-browser.json` the install writes. Consumers pass `executablePath` to their launcher, which bypasses Playwright's revision-keyed cache resolution — the revision is a property of the CLIENT version (1.55.1 → 1193, 1.60.0 → 1223), so without it a consumer's client bump silently moves the browser out from under it. **A plain exported function, deliberately NOT a capability and NOT a `HookContext` field**: an event-bus subscriber runs as its own subprocess with no hook context at all, and `lunacycle` — the one consumer — launches from both a hook and a subscriber. There is no `CapabilityRegistry` / `KNOWN_CAPABILITY_NAMES` entry and there should not be one.
+- **Two failures, two severities** — `BrowserUnavailableError.reason` is `'not_provisioned' | 'unusable'`, and the discriminant is load-bearing. Installation is opt-in, so *absent* is the NORMAL state of a host; a consumer reports it non-fatally. A module throws on any failing check item and celilo maps any fail → unhealthy → the module stays INSTALLED, so a single severity would take every browser-using module permanently unverified on any host that had not flipped a flag it never knew about. *Unusable* — dangling symlink, not executable, unreadable descriptor — is a regression and fails. **Provisioning status is decided from the BINARY, never from a directory existing**: a build directory present with no executable inside it satisfies every path check and then fails at launch.
+- **`system doctor` rows** — `apps/celilo/src/system/prereqs.ts` — `browser` and `fonts` joined `PREREQUISITES`. `PrerequisiteSpec.command` is the second check kind: an ABSOLUTE path switches presence from `command -v` to exists + executable + reports-a-version. ⚠️ **Never ask Playwright which executable it would use.** `chromium.executablePath()` reports the FULL browser while a headless launch opens the SHELL — measured disagreeing on one machine in one run — so on a shell-only host it validates a path that is not there while the binary that actually runs is fine. Because a not-provisioned browser is deliberately not a check failure, this row is the ONLY place an operator learns the host has none. `fonts` runs `fc-match sans-serif`, which resolves an actual face rather than merely proving fontconfig is installed, and displays the family — that is what decides whether a retained screenshot has legible glyphs.
+- **Per-run artifact directory** — `moduleArtifactDir(modulePath, runKey)` in the same file is the one definition of the module store's artifact layout, consumed by `apps/celilo/src/hooks/executor.ts` when it creates `HookContext.screenshotDir` and reachable from a bus subscriber that has no context. Per-run because a consumer writing fixed filenames — a reasonable thing to do — would otherwise overwrite itself every run and leave retention nothing to retain. The executor discards the directory when the hook wrote nothing, so an idle module accrues none; note it is created only AFTER every early return, because the capability pre-flight returns outside the `try/finally` that reclaims it and an earlier `mkdir` leaked one empty directory per affected run, forever.
+- **Artifacts reach the operator** — the executor collects EVERY file written to the run directory (`collectArtifacts`), carried as `HookResult.artifactPaths` (there is no `screenshotPath`; it was deleted, not deprecated). `apps/celilo/src/services/health-runner.ts` carries them onto `HealthCheckResult` — including the hook-FAILED branch, where they matter most because there are no named checks to explain anything — and `failingKeysFromHealthItems` (`services/alerting/keys.ts`) appends them to each failing item's `details`, which is the field that actually reaches an alert. Collecting them and stopping short of `details` would accomplish nothing. `apps/celilo/src/hooks/types.ts` exports `describeArtifacts`, the one renderer the three error-message sites share.
+- **Retention is by AGE, never by run count** — `apps/celilo/src/hooks/artifact-retention.ts` — 24 h plus a per-module byte ceiling, pruned on write so it needs no scheduler. Count-based pruning is the trap: for a persistent failure the FIRST artifact set carries the original cause and later ones repeat it, so "keep the last 5" discards the useful one within about an hour at a 15-minute cadence. A run is aged by its NEWEST file, not the directory's mtime, so an in-flight run cannot be evicted underneath itself. Artifacts are excluded from module backups (`modules/celilo-mgmt/scripts/on_backup.ts` `EXCLUDE_DIRS`) and preserved across `module update`.
+- **Pin-drift guardrail** — `apps/celilo/src/services/audit/browser-pin.ts` — the `browser_pin` drift category compares each module's BUNDLED `playwright-core` against the provisioned browser, and it compares **revisions, not version strings**: the revision is what has to match a build, and each client states its own in the `browsers.json` inside the package, so nobody maintains a version→revision table that would rot. It WARNS (`drift`) and never blocks — under D2 the consumer passes an explicit `executablePath`, so a mismatch is protocol skew rather than a failure. Silent when no browser is provisioned (the opt-in default) and when no module bundles a client (almost all of them); a check that fired in either case would put a permanent finding on every host in the fleet. Adding a `DriftCategory` does NOT create a monitor — only 3 of the 21 categories have one — so this is a `system audit` finding, not a page (D4).
+- Design and the declined alternatives (no probe capability, no fourth `builtin_check`, no concurrency semaphore, no off-box prober — each with its trigger): `openspec/changes/managed-browser-runtime/`.
+
 ## Generation & templating
 
 - **Generator** — `apps/celilo/src/templates/generator.ts` — `generateTemplates` (orchestration), plus Terraform/Ansible file handling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -58,9 +58,9 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^2.0.0",
+    "@celilo/capabilities": "^2.1.0",
     "@celilo/cli-display": "^0.2.0",
-    "@celilo/core": "^0.8.1",
+    "@celilo/core": "^0.9.0",
     "@celilo/event-bus": "^0.6.0",
     "ajv": "^8.18.0",
     "drizzle-orm": "^0.36.4",
@@ -75,7 +75,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
-    "@celilo/terraform-fake": "^0.3.0",
+    "@celilo/terraform-fake": "^0.3.1",
     "@types/bun": "^1.1.14",
     "@types/react": "^19.2.14",
     "drizzle-kit": "^0.30.0",

package/src/cli/commands/hook-run.ts

@@ -13,6 +13,7 @@ import { getDb } from '../../db/client';
 import { modules } from '../../db/schema';
 import { createConsoleLogger, createGaugeLogger } from '../../hooks/logger';
 import { runNamedHook } from '../../hooks/run-named-hook';
+import { describeArtifacts } from '../../hooks/types';
 import type { HookName } from '../../hooks/types';
 import type { ModuleManifest } from '../../manifest/schema';
 import { getArg, hasFlag, validateRequiredArgs } from '../parser';
@@ -83,10 +84,8 @@ export async function handleHookRun(
     });
 
     if (!result.success) {
-      let errorMsg = result.error || 'Hook execution failed';
-      if (result.screenshotPath) {
-        errorMsg += `\n\nScreenshot saved: ${result.screenshotPath}`;
-      }
+      const errorMsg =
+        (result.error || 'Hook execution failed') + describeArtifacts(result.artifactPaths);
       return { success: false, error: errorMsg };
     }
 
@@ -109,10 +108,8 @@ export async function handleHookRun(
 
   if (!result.success) {
     gauge.stop(false);
-    let errorMsg = result.error || 'Hook execution failed';
-    if (result.screenshotPath) {
-      errorMsg += `\n\nScreenshot saved: ${result.screenshotPath}`;
-    }
+    const errorMsg =
+      (result.error || 'Hook execution failed') + describeArtifacts(result.artifactPaths);
     return { success: false, error: errorMsg };
   }
 

package/src/cli/commands/ipam.ts

@@ -12,6 +12,7 @@ import {
   reserveVMID,
   unreserveIP,
   unreserveVMID,
+  updateReservationReason,
 } from '../../ipam/allocator';
 import { getArg, getFlag, validateRequiredArgs } from '../parser';
 import type { CommandResult } from '../types';
@@ -409,6 +410,98 @@ export async function handleIpamIpUnreserve(
   }
 }
 
+/**
+ * Handle IPAM IP edit command (change an exclusion's reason in place)
+ *
+ * Usage: celilo ipam ip edit <ip> --reason <reason> [--zone <zone>]
+ *
+ * Editing beats include-then-exclude: that dance drops the row for a moment
+ * and can race an allocation into the address it was holding. It also matters
+ * because reservations celilo writes itself carry generated reasons that can be
+ * identical between a live row and a dead one (celilo#892) — an operator needs
+ * a way to annotate which is which.
+ *
+ * @param args - Command arguments
+ * @param flags - Command flags
+ * @returns Command result
+ */
+export async function handleIpamIpEdit(
+  args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  const error = validateRequiredArgs(args, 1);
+  if (error) {
+    return {
+      success: false,
+      error: `${error}\n\nUsage: celilo ipam ip edit <ip> --reason <reason> [--zone <zone>]`,
+    };
+  }
+
+  const ipArg = getArg(args, 0);
+  if (!ipArg) {
+    return {
+      success: false,
+      error: 'IP is required',
+    };
+  }
+
+  const reason = getFlag(flags, 'reason');
+  if (!reason) {
+    return {
+      success: false,
+      error: 'Reason is required. Use --reason "description"',
+    };
+  }
+
+  const db = getDb();
+
+  try {
+    // A range is addressed by its first IP, the same way `include` does it.
+    const ipStart = ipArg.includes('-') ? ipArg.split('-')[0].trim() : ipArg;
+
+    const explicitZone = getFlag(flags, 'zone');
+    const zone = explicitZone || (await inferZoneFromIP(ipStart, db));
+
+    if (!zone) {
+      return {
+        success: false,
+        error: `Cannot determine zone for IP ${ipStart}. Use --zone to specify manually.`,
+      };
+    }
+
+    if (
+      zone !== 'dmz' &&
+      zone !== 'app' &&
+      zone !== 'secure' &&
+      zone !== 'secure-mgmt' &&
+      zone !== 'internal'
+    ) {
+      return {
+        success: false,
+        error: `Invalid zone: ${zone}. Must be internal, dmz, app, or secure`,
+      };
+    }
+
+    const updated = await updateReservationReason(ipStart, zone, reason, db);
+    if (!updated) {
+      return {
+        success: false,
+        error: `No IP exclusion for ${ipStart} in zone ${zone}. List them with: celilo ipam ip list-exclusions`,
+      };
+    }
+
+    return {
+      success: true,
+      message: `Updated exclusion for IP ${ipStart} in zone ${zone}: ${reason}`,
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
 /**
  * Handle IPAM IP list-exclusions command
  *

package/src/cli/commands/machine-add.ts

@@ -301,6 +301,28 @@ export async function handleMachineAdd(
         earmarkedModule: earmark || null,
       });
 
+      // A machine joining a zone is a new system by the same definition a
+      // provisioned container is, so the fleet's approved aspects apply to it
+      // too (celilo#902, design D5). Without this, a machine added after an
+      // aspect's provider deployed carries the identical defect: its
+      // /etc/resolv.conf still names whatever it booted with.
+      //
+      // A failure here is a WARNING, not fatal — deliberately unlike the deploy
+      // path, where the same failure aborts. The machine is already in the pool
+      // and nothing is proceeding on a false premise; refusing to add it would
+      // be worse than adding it unconverged and saying so.
+      const { reconcileAspectsForSystems } = await import('../../services/aspect-runner');
+      const reconcile = await reconcileAspectsForSystems({
+        systems: [{ hostname: detectedInfo.hostname, zone }],
+        db: getDb(),
+      });
+      for (const failure of reconcile.failures) {
+        console.log(
+          `⚠ Fleet aspect '${failure.role}' from '${failure.providerModuleId}' failed on ${detectedInfo.hostname}: ${failure.error ?? 'unknown error'}\n` +
+            `  The machine was added. Run \`celilo module deploy ${failure.providerModuleId}\` to converge it.`,
+        );
+      }
+
       const earmarkNote = earmark ? `\n  Earmarked for: ${earmark}` : '';
       const roleNote = role === 'router' ? ` (router - ${interfaces.length} interfaces)` : '';
       celiloOutro(

package/src/cli/commands/system-audit.ts

@@ -40,6 +40,7 @@ import { runAudit } from '../../services/audit';
 import type { DriftFinding, SystemAuditReport } from '../../services/audit';
 import { loadAbandonedOperations } from '../../services/audit/abandoned-operations';
 import { loadBackupAuditInfo } from '../../services/audit/backup-source';
+import { collectBrowserPinDeps } from '../../services/audit/browser-pin';
 import {
   type LatestCliVersionFetcher,
   fetchLatestCliVersion,
@@ -358,6 +359,7 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
         manifest: m.manifestData as ModuleManifest,
       })),
     },
+    browserPin: collectBrowserPinDeps(deployedModules),
     terraformPlan: {
       modules: terraformModules,
       run: realTerraformPlan,

package/src/cli/commands/system-doctor.ts

@@ -33,10 +33,12 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
+import { resolveBrowser } from '@celilo/capabilities';
 import { defineEvents, openBus } from '@celilo/event-bus';
 import cliPkg from '../../../package.json' with { type: 'json' };
 import { getDbPath, getEventBusPath } from '../../config/paths';
 import { getDb } from '../../db/client';
+import type { ModuleManifest } from '../../manifest/schema';
 import {
   type FleetFinding,
   type FleetFindingStatus,
@@ -279,6 +281,7 @@ function applyFix(drifted: DriftedDep[], cliRoot: string): string[] {
 function renderPrereqSection(): { lines: string[]; failingCount: number } {
   const checks = checkAllPrerequisites();
   const lines: string[] = [];
+  const browserFlavor = provisionedBrowserFlavor();
 
   lines.push('System prerequisites');
   // Right-pad column for alignment. Take the longest tool name +1
@@ -288,7 +291,16 @@ function renderPrereqSection(): { lines: string[]; failingCount: number } {
   for (const c of checks) {
     if (c.present && c.meetsMinimum) {
       const version = c.version ? c.version : `${ANSI.dim}(version unknown)${ANSI.reset}`;
-      lines.push(`  ${ANSI.green}✔${ANSI.reset} ${c.name.padEnd(nameCol)}  ${version}`);
+      // Flavour rides on the browser row because the ceiling it names is
+      // real — a headless-only build cannot run headed — and an operator
+      // reading doctor is the other party who benefits from that being
+      // legible rather than discovered by a launch failure. It cannot come
+      // from the check itself: a headless shell reports
+      // "Google Chrome for Testing <v>", the same string a full build
+      // prints, so only the descriptor knows which one is installed.
+      const flavor =
+        c.name === 'browser' && browserFlavor ? ` ${ANSI.dim}(${browserFlavor})${ANSI.reset}` : '';
+      lines.push(`  ${ANSI.green}✔${ANSI.reset} ${c.name.padEnd(nameCol)}  ${version}${flavor}`);
     } else if (c.present && !c.meetsMinimum) {
       // Present but below minimum (or version-parse failed with a minimum).
       const detail = c.version ? `${c.version} — below minimum required` : 'version unreadable';
@@ -306,6 +318,24 @@ function renderPrereqSection(): { lines: string[]; failingCount: number } {
   return { lines, failingCount: failingPrerequisites(checks).length };
 }
 
+/**
+ * Which flavour of browser is provisioned, or null when none is (or the
+ * descriptor cannot be read). Never throws — a doctor row is not worth
+ * failing the whole report over.
+ *
+ * This reads the DESCRIPTOR while the prerequisite check RUNS the binary.
+ * Those answer different questions and both are wanted: executing it is
+ * what distinguishes a real install from a build directory with no binary
+ * in it, and only the descriptor records what was installed.
+ */
+function provisionedBrowserFlavor(): string | null {
+  try {
+    return resolveBrowser().flavor;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * mtime (ms) of the installed dispatcher code (`@celilo/event-bus`
  * package.json). The fleet dispatcher check compares this against the
@@ -341,6 +371,107 @@ function renderFleetFinding(f: FleetFinding): string[] {
  * cleanly on a fresh dev box with no DB unless `--fleet` forces it. `--fix`
  * runs only the auto-fixable checks (today: subscribers resync).
  */
+/**
+ * Aspect coverage, measured against every entitled system (celilo#902 design D7).
+ *
+ * Behind `--deep` and never in a default pass, because it SSHes to every
+ * system an approved aspect covers. That gating is also what keeps it honest:
+ * there is no "we have no data yet" state to explain away — the check either
+ * ran and measured, or it did not run.
+ *
+ * `--fix` converges only the hosts measured as MISSING. An `unknown` host is
+ * never converged: celilo does not know what state it is in, so there is
+ * nothing to converge toward, and re-running the role anyway would be inventing
+ * the verdict this check exists to avoid.
+ */
+async function renderAspectCoverage(opts: { fix: boolean }): Promise<{
+  lines: string[];
+  failCount: number;
+  warnCount: number;
+}> {
+  const { verifyAspectCoverage } = await import('../../services/aspect-runner');
+  const { getDb } = await import('../../db/client');
+
+  const lines: string[] = ['Aspect coverage'];
+  const findings = await verifyAspectCoverage({ db: getDb() });
+  if (findings.length === 0) {
+    lines.push(`  ${ANSI.dim}no approved base-module aspects to verify${ANSI.reset}`);
+    return { lines, failCount: 0, warnCount: 0 };
+  }
+
+  const missing = findings.filter((f) => f.state === 'missing');
+  const unknown = findings.filter((f) => f.state === 'unknown' || f.state === 'unreachable');
+  const applied = findings.filter((f) => f.state === 'applied');
+
+  for (const f of applied) {
+    lines.push(`  ${ANSI.green}✓${ANSI.reset} ${f.hostname} has ${f.providerModuleId}/${f.role}`);
+  }
+  for (const f of missing) {
+    lines.push(
+      `  ${ANSI.red}✗${ANSI.reset} ${f.hostname} is MISSING ${f.providerModuleId}/${f.role}`,
+    );
+    if (f.detail) lines.push(`      ${ANSI.dim}${f.detail}${ANSI.reset}`);
+  }
+  for (const f of unknown) {
+    lines.push(
+      `  ${ANSI.yellow}?${ANSI.reset} ${f.hostname} — ${f.providerModuleId}/${f.role} NOT MEASURED`,
+    );
+    if (f.detail) lines.push(`      ${ANSI.dim}${f.detail}${ANSI.reset}`);
+  }
+
+  if (opts.fix && missing.length > 0) {
+    // Converged per PROVIDER with `onlyHostnames`, not through
+    // `reconcileAspectsForSystems`. Entitlement was already established by
+    // `planAspectFanOut` when the finding was measured, and consent was already
+    // confirmed 'approved' — re-deriving either from the zone would only add a
+    // second path that can disagree with the first.
+    const { runAspectFanOut } = await import('../../services/aspect-runner');
+    const { modules } = await import('../../db/schema');
+    const { eq } = await import('drizzle-orm');
+    const db = getDb();
+
+    const byProvider = new Map<string, string[]>();
+    for (const f of missing) {
+      byProvider.set(f.providerModuleId, [
+        ...(byProvider.get(f.providerModuleId) ?? []),
+        f.hostname,
+      ]);
+    }
+
+    lines.push('');
+    lines.push(`  Converging ${missing.length} host/aspect pair(s) measured as missing:`);
+    for (const [providerModuleId, hostnames] of byProvider) {
+      const row = db.select().from(modules).where(eq(modules.id, providerModuleId)).get();
+      const aspect = (row?.manifestData as ModuleManifest | null)?.base_module_aspect;
+      if (!row || !aspect) continue;
+      const result = await runAspectFanOut({
+        moduleId: providerModuleId,
+        aspect,
+        moduleSourcePath: row.sourcePath,
+        options: { trigger: 'on_new_system_in_zone', onlyHostnames: hostnames },
+        db,
+      });
+      const mark = result.success ? `${ANSI.green}✓${ANSI.reset}` : `${ANSI.red}✗${ANSI.reset}`;
+      lines.push(
+        `    ${mark} ${providerModuleId} → ${hostnames.join(', ')}${result.success ? '' : `: ${result.error ?? 'unknown error'}`}`,
+      );
+    }
+    // Re-MEASURED on the next --deep run rather than asserted from this run's
+    // exit status. "The command exited 0" is the verdict, not the contract.
+    lines.push(
+      `  ${ANSI.dim}Re-run \`celilo system doctor --deep\` to confirm against the hosts.${ANSI.reset}`,
+    );
+    return { lines, failCount: 0, warnCount: unknown.length };
+  }
+
+  if (missing.length > 0) {
+    lines.push(
+      `  ${ANSI.dim}Run \`celilo system doctor --deep --fix\` to apply the missing aspects.${ANSI.reset}`,
+    );
+  }
+  return { lines, failCount: missing.length, warnCount: unknown.length };
+}
+
 async function renderFleetSection(opts: { forced: boolean; fix: boolean }): Promise<{
   lines: string[];
   failCount: number;
@@ -522,6 +653,18 @@ export async function handleSystemDoctor(
     lines.push('');
   }
 
+  // Aspect coverage. `--deep` only: it reaches out to every entitled system
+  // over SSH, which a default doctor pass must not do.
+  let aspectFailCount = 0;
+  let aspectWarnCount = 0;
+  if (flags.deep === true) {
+    const coverage = await renderAspectCoverage({ fix });
+    lines.push(...coverage.lines);
+    lines.push('');
+    aspectFailCount = coverage.failCount;
+    aspectWarnCount = coverage.warnCount;
+  }
+
   // Unified summary: anything that fails the run, with a per-cause count.
   const problems: string[] = [];
   if (prereqResult.failingCount > 0) {
@@ -530,6 +673,7 @@ export async function handleSystemDoctor(
   if (driftCount > 0) problems.push(`${driftCount} package(s) behind workspace`);
   if (unresolvedCount > 0) problems.push(`${unresolvedCount} unresolved`);
   if (fleet.failCount > 0) problems.push(`${fleet.failCount} fleet check(s) failing`);
+  if (aspectFailCount > 0) problems.push(`${aspectFailCount} system(s) missing a fleet aspect`);
 
   if (problems.length > 0) {
     return {
@@ -540,10 +684,9 @@ export async function handleSystemDoctor(
   }
 
   // Fleet warnings don't fail the run, but they shouldn't read as a clean bill.
-  if (fleet.warnCount > 0) {
-    lines.push(
-      `${ANSI.yellow}OK with warnings${ANSI.reset} — ${fleet.warnCount} fleet warning(s); see above`,
-    );
+  const warnTotal = fleet.warnCount + aspectWarnCount;
+  if (warnTotal > 0) {
+    lines.push(`${ANSI.yellow}OK with warnings${ANSI.reset} — ${warnTotal} warning(s); see above`);
   } else {
     lines.push(`${ANSI.green}OK${ANSI.reset} — no issues detected`);
   }

package/src/cli/commands/system-update.ts

@@ -27,6 +27,7 @@ import type { ModuleManifest } from '../../manifest/schema';
 import { RegistryClient } from '../../registry/client';
 import { runAudit } from '../../services/audit';
 import { loadAbandonedOperations } from '../../services/audit/abandoned-operations';
+import { collectBrowserPinDeps } from '../../services/audit/browser-pin';
 import { fetchLatestCliVersion } from '../../services/audit/cli-version';
 import { unusedPublicDnsProbe } from '../../services/audit/public-dns';
 import { makeJournalReader, readAppliedMigrations } from '../../services/audit/schema';
@@ -536,6 +537,7 @@ export async function handleSystemUpdate(
         manifest: m.manifestData as ModuleManifest,
       })),
     },
+    browserPin: collectBrowserPinDeps(upgradableModules),
     terraformPlan: {
       modules: upgradableModules.map((m) => ({
         id: m.id,

package/src/cli/completion.ts

@@ -262,9 +262,9 @@ export async function getCompletions(words: string[], current: number): Promise<
     return filterSuggestions(frameworkKeys, args[4] || '');
   }
 
-  // Module secret subcommands (celilo module secret set/list)
+  // Module secret subcommands (celilo module secret set/get/list)
   if (command === 'module' && args[1] === 'secret' && currentIndex === 2) {
-    const subcommands = ['set', 'list'];
+    const subcommands = ['set', 'get', 'list'];
     return filterSuggestions(subcommands, args[2] || '');
   }
 
@@ -272,7 +272,7 @@ export async function getCompletions(words: string[], current: number): Promise<
   if (
     command === 'module' &&
     args[1] === 'secret' &&
-    (args[2] === 'set' || args[2] === 'list') &&
+    (args[2] === 'set' || args[2] === 'get' || args[2] === 'list') &&
     currentIndex === 3
   ) {
     const db = getDb();
@@ -281,8 +281,13 @@ export async function getCompletions(words: string[], current: number): Promise<
     return filterSuggestions(moduleIds, args[3] || '');
   }
 
-  // Module secret set <module-id> - complete with secret names
-  if (command === 'module' && args[1] === 'secret' && args[2] === 'set' && currentIndex === 4) {
+  // Module secret set/get <module-id> - complete with secret names
+  if (
+    command === 'module' &&
+    args[1] === 'secret' &&
+    (args[2] === 'set' || args[2] === 'get') &&
+    currentIndex === 4
+  ) {
     const db = getDb();
     const module = db
       .select()
@@ -609,6 +614,34 @@ export async function getCompletions(words: string[], current: number): Promise<
     return filterSuggestions(subcommands, args[1] || '');
   }
 
+  // IPAM VMID actions
+  if (command === 'ipam' && args[1] === 'vmid' && currentIndex === 2) {
+    const actions = ['reserve', 'unreserve', 'list-reservations'];
+    return filterSuggestions(actions, args[2] || '');
+  }
+
+  // IPAM IP actions
+  if (command === 'ipam' && args[1] === 'ip' && currentIndex === 2) {
+    const actions = ['exclude', 'include', 'edit', 'list-exclusions'];
+    return filterSuggestions(actions, args[2] || '');
+  }
+
+  // The address argument to `ipam ip edit` / `ipam ip include` — both act on an
+  // exclusion that already exists, and nobody remembers which address it was.
+  if (
+    command === 'ipam' &&
+    args[1] === 'ip' &&
+    (args[2] === 'edit' || args[2] === 'include') &&
+    currentIndex === 3
+  ) {
+    const { listReservations } = await import('../ipam/allocator');
+    const reservations = await listReservations(getDb());
+    return filterSuggestions(
+      reservations.map((r: { ipStart: string }) => r.ipStart),
+      args[3] || '',
+    );
+  }
+
   // Completion subcommands
   if (command === 'completion' && currentIndex === 1) {
     const subcommands = ['bash', 'zsh'];