@astrofoundry/pi-astro 0.17.1 → 0.18.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.17.1",
-  "description": "Personal pi customizations (extensions, skills, prompts, themes) for the pi coding agent.",
+  "version": "0.18.1",
+  "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"
   ],
@@ -12,16 +12,13 @@
   },
   "pi": {
     "extensions": [
-      "./extensions",
-      "node_modules/pi-subagents/src/extension/index.ts"
+      "./extensions"
     ],
     "skills": [
-      "./skills",
-      "node_modules/pi-subagents/skills"
+      "./skills"
     ],
     "prompts": [
-      "./prompts",
-      "node_modules/pi-subagents/prompts"
+      "./prompts"
     ],
     "themes": [
       "./themes"
@@ -33,7 +30,8 @@
     "prompts",
     "themes",
     "README.md",
-    "agents"
+    "agents",
+    "specialists"
   ],
   "repository": {
     "type": "git",
@@ -51,29 +49,24 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.74.0",
-    "@earendil-works/pi-ai": "^0.74.0",
-    "@earendil-works/pi-coding-agent": "^0.74.0",
-    "@earendil-works/pi-tui": "^0.74.0",
+    "@earendil-works/pi-agent-core": "^0.85.1",
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
     "@eslint/js": "^10.0.1",
-    "@types/diff": "^8.0.0",
-    "@types/node": "^25.6.0",
-    "@vitest/coverage-v8": "^4.1.5",
-    "eslint": "^10.2.1",
-    "globals": "^17.5.0",
-    "typebox": "^1.1.33",
+    "@types/node": "^26.5.1",
+    "@vitest/coverage-v8": "^5.0.0",
+    "eslint": "^10.10.0",
+    "globals": "^17.12.0",
+    "typebox": "^1.3.30",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.0",
-    "vitest": "^4.1.5"
+    "typescript-eslint": "^8.70.0",
+    "vitest": "^5.0.0"
   },
   "dependencies": {
-    "@google/genai": "^1.50.1",
-    "diff": "^9.0.0",
-    "pi-subagents": "^0.24.2"
+    "@google/genai": "^2.22.0",
+    "diff": "^9.0.0"
   },
-  "bundledDependencies": [
-    "pi-subagents"
-  ],
   "scripts": {
     "test": "vitest run --coverage",
     "lint": "eslint .",

package/skills/arcane/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: arcane
+description: How the Arcane specialist operates the Arcane container platform and its GitOps repository through the arcane tool.
+---
+
+# Arcane specialist
+
+Arcane manages the Docker host on VM 100 (`10.0.40.30`). Every app is a Compose project synced from the GitOps repository `astronaute77/arcane`, branch `main`, into `/opt/docker`. The `arcane` tool wraps `arcane-cli` with a fresh short-lived token on every call and adds `gitops` subcommands for the repository.
+
+## Calling the tool
+
+`arcane` takes one parameter, `args`, an array of strings, one element per argument.
+
+```json
+{ "args": ["projects", "list"] }
+{ "args": ["containers", "logs", "mealie-mealie-1", "--tail", "200"] }
+{ "args": ["gitops", "status"] }
+```
+
+`["--help"]` prints the wrapper's help. `arcane-cli` subcommands accept `--help` too, for example `["projects", "--help"]`.
+
+## Two kinds of operations
+
+1. **Definitions**: Compose files, env layout, new or removed projects. Only through the repository:
+   `gitops pull` → `gitops write <path> <content>` → `gitops diff` → `gitops commit <message>` → `gitops push` → then `["projects", "up", "<name>"]` or a GitOps sync through the CLI, then verify with `["projects", "list"]` and container logs.
+2. **Operations**: restart, logs, stats, redeploy, pull images, prune. Straight through the CLI.
+
+The tool refuses `projects create|edit|update|import`, `config`, `auth`, `self-update`, `completion`.
+
+## Output
+
+JSON with these fields removed at every depth: environment, labels, mounts, Compose content, runtime, host config, command, entrypoint, args. Those fields carry secrets. Do not ask for them.
+
+## Repository conventions
+
+- One folder per project with `compose.yaml`; project name equals folder name.
+- Secrets never go into the repository. Projects read them through `arcane-bw-runner` from Vaultwarden at deploy time; a new secret means a new Hidden field in that project's Secure Note in the `arcane` collection, created by the operator, not by you.
+- Commit messages: one short line describing the change.
+- Keep a sync request connected until it returns; Arcane cancels lifecycle hooks when the client disconnects.
+
+## When to stop and report
+
+- A change needs a new secret or a Vaultwarden note.
+- A project's health is unknown after a sync (report state and logs separately).
+- The requested action is destructive and the task did not ask for it explicitly.

package/skills/identity/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: identity
+description: How the identity specialist operates Zitadel and the DMZ guest (Pomerium, nginx, lego) through the identity tool.
+---
+
+# Identity specialist
+
+Zitadel at `https://auth.37pla.net` issues browser and machine identities. Pomerium on VM 104 (`10.0.20.10`) is the single policy point for every public hostname; nginx and lego (Cloudflare DNS-01 wildcard certificates) live on the same guest. The `identity` tool has two families.
+
+## `zitadel <METHOD> <path> [json-body]`
+
+Calls the Zitadel API with the specialist's Personal Access Token. Paths must start with `/v2/`, `/management/v1/`, `/admin/v1/`, or `/auth/v1/`. Prefer v2.
+
+```json
+{ "args": ["zitadel", "GET", "/v2/users?query.limit=50"] }
+{ "args": ["zitadel", "POST", "/v2/users/human", "{\"username\":\"...\"}"] }
+{ "args": ["zitadel", "GET", "/management/v1/projects/387825541182390275"] }
+```
+
+Output is `{ "status": <http>, "body": <json> }` with secret-like fields redacted. Zitadel shows client secrets and keys once; when an operation creates one, tell the caller to store it in Vaultwarden immediately, following the homelab repository's rotation conventions.
+
+Known ids: Infrastructure project `387825541182390275`; test user `388551381058846723` (never an administrator or personal account for tests).
+
+## `dmz <command>`
+
+Fixed operations on VM 104 through a forced-command SSH key. No other command reaches the guest.
+
+| Command | Effect |
+|---|---|
+| `status` | pomerium, nginx, lego-renew.timer status |
+| `journal <pomerium\|nginx\|lego-renew> <since>` | last 200 lines since, e.g. `1 hour ago` |
+| `config-template` | print `/etc/pomerium/config.yaml.template` (no secrets) |
+| `render` | re-render `/etc/pomerium/config.yaml` from template and Vaultwarden |
+| `pomerium-restart` | restart Pomerium |
+| `nginx-reload` | `nginx -t` then reload |
+| `lego-renew` | run the certificate renewal now |
+
+## Pomerium route changes
+
+Routes are defined in `02-pulsar-proxmox/dmz/config.yaml` in the homelab repository and deployed with `deploy.sh --proxy-only`, which also runs `render`. You cannot deploy a route change through this tool. Produce the exact YAML diff for the caller, then after deployment verify with `status` and `journal pomerium`.
+
+## When to stop and report
+
+- A change needs a new Vaultwarden field (Pomerium reads route secrets from the `dmz` collection).
+- The task asks for a deletion without naming the exact resource.
+- A Zitadel call returns 403: the PAT lacks a role; report it rather than retrying variants.

package/skills/network/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: network
+description: How the network specialist reads UniFi and checks FreeRADIUS and Tailscale through the network tool.
+---
+
+# Network specialist
+
+UniFi (console `https://10.0.10.1`) enforces the homelab's network policy: nine VLANs, inter-zone traffic denied unless a policy allows it, Wi-Fi `Ardilla-37` (EAP-TLS via FreeRADIUS on LXC 108), `Ardilla-IoT`, `Ardilla-GUEST`. LXC 105 runs the Tailscale subnet router for remote administration. The `network` tool has two families.
+
+## `unifi <read> [--limit n] [--offset n] [--filter expr]`
+
+Read-only calls to the console's Network API, TLS pinned to the console certificate.
+
+| Read | Path |
+|---|---|
+| `sites` | `/v1/sites` (site id needed by everything else) |
+| `devices <siteId>` | adopted devices |
+| `device <siteId> <deviceId>` | one device with ports and radios |
+| `clients <siteId>` | connected clients |
+| `networks <siteId>` | networks and VLANs |
+| `firewall-policies <siteId>` | zone policies |
+| `wans <siteId>` | WAN interfaces |
+| `get /v1/...` | any other documented GET |
+
+Filters use the API's syntax, for example `--filter "state.eq('ONLINE')"`. Pagination fields `offset`, `limit`, `totalCount` are in every list response.
+
+```json
+{ "args": ["unifi", "sites"] }
+{ "args": ["unifi", "clients", "<siteId>", "--limit", "100"] }
+```
+
+`unifi fingerprint` prints the console certificate fingerprint; the operator uses it to pin the certificate in the wrapper config.
+
+## `pulsar <command>`
+
+Fixed checks through a forced-command SSH key to Pulsar (Proxmox host `10.0.10.37`), which runs them inside the guests.
+
+| Command | Effect |
+|---|---|
+| `guest-status <105\|107\|108>` | `pct status` |
+| `radius-check` | `freeradius -XC` configuration check, no restart |
+| `radius-status` | FreeRADIUS service status |
+| `radius-journal <since>` | FreeRADIUS journal since, e.g. `2 hours ago` |
+| `radius-crl-timer` | CRL monitor timer schedule |
+| `tailscale-status` | `tailscale status` |
+| `tailscale-journal <since>` | tailscaled journal since |
+
+## Out of scope in this version
+
+UniFi changes, Wi-Fi CA rotation, device certificate enrollment, and DNS. Describe the needed change precisely and stop. DNS belongs to the `dns` specialist once it exists.

package/specialists/AGENTS.md

@@ -0,0 +1,60 @@
+# Specialists: implementation notes
+
+Read `README.md` in this folder first: it defines the model, the host setup, and the limits. This file is for changing or extending the code.
+
+## Boundaries, in one table
+
+| Control | Where | Strength |
+|---|---|---|
+| What an identity may do | Service side: Arcane role, Zitadel role, UniFi key scope, forced commands on SSH targets | Hard |
+| Credential confidentiality | macOS user `specialist`, home `0700`, one sudo entry point, password for general sudo | Hard |
+| Short-lived Arcane access | Zitadel JWT profile token per call, 300 s Arcane token | Hard |
+| Audit | `~/.specialists/audit.log`, one JSON line per call | Hard (`--caller` is informational) |
+| One specialist per note | Construction: one tool, one wrapper, one secrets folder; agent has no `bash`, `write`, `edit` | Soft |
+| Only the specialist child has the tool | `specialist-gate` matches `ASTRO_SUBAGENT_AGENT`; blocks elsewhere; `security-guard` duplicates the blocks | Soft |
+
+macOS cannot tell which agent made a call; the OS user protects the credential, the service decides what the identity may do. Do not present the gate as a security boundary.
+
+## Layout
+
+```text
+extensions/specialist-gate/     index.ts (tool registration, tool_call blocks, /specialists), config.ts, types.ts, index.test.ts
+specialists/lib/                zitadel.ts, secrets.ts, config.ts, proc.ts, ssh.ts, sanitize.ts, audit.ts, argv.ts, main.ts, output.ts, paths.ts, errors.ts
+specialists/<name>/run.ts       one wrapper per specialist (arcane, identity, network)
+specialists/wrappers.test.ts    validators, tables, help
+specialists/provision/          provision.sh (Vaultwarden to files)
+specialists/install/            install.sh (package to ~/.specialists/bin, arcane-cli download)
+specialists/entry/              specialist-cli.sh (sudo entry point), remote/*.sh (forced commands for SSH targets)
+agents/<name>.md, skills/<name>/SKILL.md
+```
+
+Wrappers ship as TypeScript and run under Node 24 type stripping: erasable syntax only (no enums, namespaces, parameter properties), explicit `.ts` import extensions. `install.sh` copies `lib/` and each `run.ts` into `~/.specialists/bin/`; the entry point runs `node ~/.specialists/bin/<service>/run.ts`.
+
+## Rules for wrapper code
+
+- No shell. `run()` spawns an executable with an argument array; secrets travel in `env` or `stdin`, never argv.
+- Secrets only through `readSecret(service, FIELD)`; it refuses files wider than `0600` and names outside `UPPER_SNAKE`.
+- Config only through `readConfig(service, shape)`; every field required, no fallbacks, no env vars.
+- Exit codes: `UsageError` 2, `ServiceError` 1, success 0. Diagnostics on stderr, results on stdout, JSON where possible.
+- Output filters: Arcane responses pass `stripKeys(ARCANE_DENIED_KEYS)`; Zitadel responses pass `redactSecrets`. Add keys there rather than in a wrapper.
+- Fixed remote commands: `DMZ_COMMANDS` and `PULSAR_COMMANDS` must match the entry scripts in `entry/remote/` and their tracked copies in the homelab repository (`02-pulsar-proxmox/dmz/system/`, `02-pulsar-proxmox/pulsar/system/`). Change both sides in the same commit and redeploy the remote script.
+- Arcane definitions change only through `gitops`; `REFUSED_PREFIXES` keeps the CLI from bypassing it and from touching its own config or auth.
+- Every wrapper answers `--help` without reading config, so agents can discover subcommands before anything else is set up.
+
+## Gate
+
+`extensions/specialist-gate/index.ts` loads `~/.pi/agent/specialists.json` (`PI_CODING_AGENT_DIR` overrides the directory in tests). `astro-subagents` sets `ASTRO_SUBAGENT_AGENT` on every child it spawns; with a matching value the gate registers the tool and runs `sudo -n -u <user> -H <entry> <service> --caller <agent> -- <args>` through `pi.exec`, raising the CLI's stderr as the tool error. In every session it blocks `bash` commands containing `specialist-cli`, `arcane-cli`, `<service>-run`, `-u <user>`, `su <user>`, and `read`/`write`/`edit` under `/Users/<user>`. An invalid config keeps the blocks with defaults and reports the error on `session_start`.
+
+## Adding a specialist
+
+1. Identity: a Vaultwarden note named like the specialist; a Zitadel service user when the service accepts OIDC, else the service's own key; SSH key per target when the only path is SSH.
+2. `specialists/<name>/run.ts` with `main("<name>", command)`, typed subcommands, `--help`, and tables for any fixed remote commands. Add the entry script under `entry/remote/` and its copy in the homelab repository.
+3. `install.sh`: add the name to the copy loop. `entry/specialist-cli.sh`: the name is already in the allowlist for the nine planned specialists; add new names there.
+4. `agents/<name>.md` with `tools: read, <name>, subagent`, `skills: <name>`, `systemPromptMode: replace`, `inheritProjectContext: false`, `inheritSkills: false`, `maxSubagentDepth: 1`. `skills/<name>/SKILL.md` with services, subcommands, output shapes, limits, and when to stop.
+5. Tests: validators and tables in `wrappers.test.ts`; anything shared in `lib/`.
+6. Host: note fields, `provision`, config file, `specialists.json` entry, target entry script. Document the fields in the homelab `03-cortex-macmini/ROTATION.md` and host facts in `03-cortex-macmini/README.md`.
+7. README in this folder: table row and setup step; root `README.md`: the agent and skill lists.
+
+## Planned batches
+
+Batch 2: `dns` (Technitium primary and secondary, Cloudflare), `edge` (Frontdoor VPS over gcloud IAP SSH), `security` (Wazuh, CrowdSec, rsyslog on VM 106). Batch 3: `backup` (vzdump, Restic layers, GCS push), `proxmox` (PVE API, `qm`/`pct` through the Pulsar entry), `inference` (llama.cpp on Nexus and Europa, Hermes). Specify subcommands, roles, and key creation when a batch starts; follow the batch 1 pattern.

package/specialists/README.md

@@ -0,0 +1,67 @@
+# Specialists
+
+A specialist is a Pi subagent that is the only way to operate one area of the homelab. It has one tool, one skill, and one Vaultwarden note. Every other agent is blocked from the area's CLIs and credentials.
+
+| Agent | Area | What it can do |
+|---|---|---|
+| `astro.arcane` | Arcane container platform (VM 100) and its GitOps repository | Every `arcane-cli` operation; Compose changes through `gitops write|commit|push`, then sync |
+| `astro.identity` | Zitadel; Pomerium, nginx, lego on VM 104 | Any Zitadel API call (v2, management, admin, auth) with responses redacted; `dmz status|journal|config-template|render|pomerium-restart|nginx-reload|lego-renew` |
+| `astro.network` | UniFi, FreeRADIUS (LXC 108), Tailscale (LXC 105) | Read UniFi sites, devices, clients, networks, firewall policies, WANs; RADIUS and Tailscale checks on Pulsar |
+
+Call one with `/run astro.<name> -- <task>` or through the `subagent` tool (both from the bundled `astro-subagents` extension). Specialists may call each other once (`maxSubagentDepth: 1`). Each tool takes `args`, an array of strings; `["--help"]` lists the subcommands.
+
+## How it is secured
+
+- Credentials and CLIs belong to a dedicated macOS user `specialist` on the host. Agents run as the main user and reach the wrappers only through `sudo -n -u specialist -H /usr/local/bin/specialist-cli`, the single passwordless sudo rule. General sudo asks for a password.
+- Credentials come from Vaultwarden (`homelab` / `specialists`, one Secure Note per specialist) through `specialist-cli provision`, into `0600` files. Wrappers never call `bw`.
+- Arcane is reached with a Zitadel service user: a fresh token per call, exchanged for a 300 s Arcane token. Other services use API keys, a PAT, or SSH keys that the targets pin to forced commands.
+- Every call is logged in `/Users/specialist/.specialists/audit.log`.
+- The `specialist-gate` extension registers the tool only inside the matching specialist child and blocks other agents from calling the CLIs or reading `/Users/specialist`. `security-guard` carries the same blocks.
+
+Limits: `network` is read-only on UniFi. `identity` cannot deploy Pomerium route changes; those are edits to `02-pulsar-proxmox/dmz/config.yaml` in the homelab repository, deployed with its `deploy.sh`.
+
+## Enable specialists on a host
+
+Host: Cortex (macOS, Homebrew `node`, `bw`, `jq`, git). Steps 1 to 3 are one-time on the services; 4 to 8 are per host.
+
+1. **Vaultwarden.** Account `specialists@monadeo.com` with **Can view** on collection `specialists` in organization `homelab`. Secure Notes with Hidden fields: `arcane`: `ZITADEL_KEY_JSON`, `GITOPS_DEPLOY_KEY_B64`, `ZITADEL_USER_ID` (plain); `identity`: `ZITADEL_PAT`, `SSH_KEY_DMZ_B64`; `network`: `UNIFI_API_KEY`, `SSH_KEY_PULSAR_B64`. `_B64` fields hold `base64 -i <keyfile> | tr -d '\n'`.
+2. **Zitadel** (`https://auth.37pla.net/ui/console`). Service user `spc-arcane` with Access Token Type JWT and a JSON key (Keys, New). Service user `spc-identity` with a Personal Access Token and the Instance Owner role (Default settings, Managers).
+3. **Arcane** (Settings, Authentication, Federated Credentials). Issuer `https://auth.37pla.net`, Audience `387825541182390275`, Subject exact = `spc-arcane` user ID, Role Admin, Global, lifetime 300. **UniFi**: API key (Settings, API Keys) and two policies allowing Cortex `10.0.40.37` to TCP 22 on `10.0.20.10` and `10.0.10.37`. **GitHub**: the `spc-arcane-gitops` public key as a write deploy key on `astronaute77/arcane`.
+4. **Sudo and user**, as an administrator:
+   ```sh
+   printf 'cortex ALL=(ALL) ALL\n' | sudo tee /etc/sudoers.d/cortex >/dev/null
+   printf 'cortex ALL=(specialist) NOPASSWD: /usr/local/bin/specialist-cli\n' | sudo tee /etc/sudoers.d/specialists >/dev/null
+   sudo chmod 0440 /etc/sudoers.d/cortex /etc/sudoers.d/specialists && sudo rm -f /etc/sudoers.d/cortex-nopasswd && sudo visudo -c
+   sudo sysadminctl -addUser specialist -fullName "Specialists" -home /Users/specialist -shell /bin/zsh -password -
+   sudo dscl . create /Users/specialist IsHidden 1 && sudo createhomedir -c -u specialist && sudo chmod 700 /Users/specialist
+   sudo install -m 0755 -o root -g wheel <package>/specialists/entry/specialist-cli.sh /usr/local/bin/specialist-cli
+   ```
+   Add `cortex ALL=(specialist) NOPASSWD: ALL` as `/etc/sudoers.d/specialists-setup` (mode `0440`) for the duration of steps 5 to 7, then delete it.
+5. **Bootstrap**, as `specialist` (`sudo -u specialist -H zsh`, `umask 077`): `~/.config/specialists/client.env` with `BW_SERVER=https://vault.37pla.net`, `BW_CLIENTID`, `BW_CLIENTSECRET`; `~/.config/specialists/master-password`. Both `0600`.
+6. **Install and configure**, as `specialist`: `sh <package>/specialists/install/install.sh <package> 2.11.1` (`<package>` is the installed pi-astro directory, `~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro`). Write `~/.specialists/config/arcane.json`, `identity.json`, `network.json`:
+   ```json
+   { "serverUrl": "http://10.0.40.30:3552", "zitadelDomain": "auth.37pla.net", "audience": "387825541182390275",
+     "arcaneCli": "/Users/specialist/.specialists/bin/arcane-cli", "arcaneCliConfig": "/Users/specialist/.specialists/config/arcanecli.yml",
+     "gitopsRemote": "git@github.com:astronaute77/arcane.git", "gitopsBranch": "main" }
+   { "zitadelDomain": "auth.37pla.net", "dmzHost": "10.0.20.10", "dmzUser": "dmz" }
+   { "unifiBaseUrl": "https://10.0.10.1/proxy/network/integration", "unifiCertSha256": "<from: specialist-cli network -- unifi fingerprint>", "pulsarHost": "10.0.10.37", "pulsarUser": "root" }
+   ```
+   Then `sudo -n -u specialist -H /usr/local/bin/specialist-cli provision`; it lists every note and field.
+7. **SSH targets.** Install `entry/remote/spc-identity-dmz-entry.sh` as `/usr/local/sbin/spc-identity-dmz-entry` on VM 104 and `entry/remote/spc-network-pulsar-entry.sh` as `/usr/local/sbin/spc-network-pulsar-entry` on Pulsar (`0755`, root). Add each public key to the target's `authorized_keys` (`dmz` on VM 104, root on Pulsar) as:
+   `command="/usr/local/sbin/<entry>",no-port-forwarding,no-agent-forwarding,no-pty,no-X11-forwarding ssh-ed25519 ...`
+8. **Pi**, as the main user: `~/.pi/agent/specialists.json` (below) and the specialist blocks in `~/.pi/agent/security-guard.json` (`specialist-cli`, `arcane-cli`, `-u specialist` in `operations`; `/Users/specialist/**` in `reads` and `writes`; keep the default rules next to them).
+   ```json
+   { "entry": "/usr/local/bin/specialist-cli", "user": "specialist",
+     "specialists": [
+       { "agent": "astro.arcane", "tool": "arcane", "service": "arcane", "timeoutMs": 300000 },
+       { "agent": "astro.identity", "tool": "identity", "service": "identity", "timeoutMs": 120000 },
+       { "agent": "astro.network", "tool": "network", "service": "network", "timeoutMs": 120000 } ] }
+   ```
+
+Check: `sudo -n -u specialist -H /usr/local/bin/specialist-cli arcane --caller test -- projects list` prints JSON; the same for `identity -- dmz status` and `network -- unifi sites`; `/run astro.arcane -- list projects` works in Pi; `bash` with `arcane-cli --help` is blocked in a normal session.
+
+## Rotation and operations
+
+Rotation steps for every field live in the homelab repository, `03-cortex-macmini/ROTATION.md`. After any change in Vaultwarden run `specialist-cli provision`. Host state and the sudo rules are documented in `03-cortex-macmini/README.md`; the forced-command scripts are tracked under `02-pulsar-proxmox/dmz/system/` and `02-pulsar-proxmox/pulsar/system/`.
+
+Planned specialists (not built): `dns`, `edge`, `security` (batch 2); `backup`, `proxmox`, `inference` (batch 3). See `AGENTS.md` for how to add one.

package/specialists/arcane/run.ts

@@ -0,0 +1,238 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { readConfig } from "../lib/config.ts";
+import { ServiceError, UsageError } from "../lib/errors.ts";
+import { main } from "../lib/main.ts";
+import { printJson, printRaw } from "../lib/output.ts";
+import { specialistsHome, workDir } from "../lib/paths.ts";
+import { run } from "../lib/proc.ts";
+import { ARCANE_DENIED_KEYS, filterJsonText, stripKeys } from "../lib/sanitize.ts";
+import { readSecret, secretPath } from "../lib/secrets.ts";
+import { mintAccessToken, parseServiceAccountKey } from "../lib/zitadel.ts";
+
+const SERVICE = "arcane";
+
+interface ArcaneConfig extends Record<string, string> {
+    serverUrl: string;
+    zitadelDomain: string;
+    audience: string;
+    arcaneCli: string;
+    arcaneCliConfig: string;
+    gitopsRemote: string;
+    gitopsBranch: string;
+}
+
+const SHAPE = {
+    serverUrl: "string",
+    zitadelDomain: "string",
+    audience: "string",
+    arcaneCli: "string",
+    arcaneCliConfig: "string",
+    gitopsRemote: "string",
+    gitopsBranch: "string",
+} as const;
+
+/** Definitions change through GitOps; these CLI paths would bypass it or alter the wrapper's own setup. */
+export const REFUSED_PREFIXES: readonly string[] = [
+    "projects create",
+    "projects edit",
+    "projects update",
+    "projects import",
+    "config",
+    "auth",
+    "self-update",
+    "completion",
+];
+
+/** Global arcane-cli flags that take a separate value. */
+const VALUE_FLAGS = ["--env", "--output", "--config", "-c", "--request-timeout", "--log-level", "--limit"];
+
+/** Positional words of an arcane-cli invocation, with global flags and their values removed. */
+export function positionalWords(args: string[]): string[] {
+    const words: string[] = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (VALUE_FLAGS.includes(a)) {
+            i++;
+        } else if (!a.startsWith("-")) {
+            words.push(a);
+        }
+    }
+    return words;
+}
+
+export function refusedPrefix(args: string[]): string | null {
+    const words = positionalWords(args);
+    for (const prefix of REFUSED_PREFIXES) {
+        const parts = prefix.split(" ");
+        if (parts.every((p, i) => words[i] === p)) return prefix;
+    }
+    return null;
+}
+
+const HELP = `arcane specialist
+
+  <arcane-cli args...>           run arcane-cli with a fresh federated token; JSON output, sensitive fields removed
+  gitops status                  branch, ahead/behind, changed files of the GitOps checkout
+  gitops pull                    fast-forward the checkout from origin
+  gitops diff                    unstaged and staged changes
+  gitops log [n]                 last n commits (default 10)
+  gitops write <path> <content>  write a file inside the checkout (creates folders)
+  gitops commit <message>        stage everything and commit
+  gitops push                    push the branch to origin
+
+Refused: ${REFUSED_PREFIXES.join(", ")}. Project definitions change through gitops, then sync with the CLI.`;
+
+const TIMEOUT_MS = 240_000;
+
+function gitEnv(): Record<string, string> {
+    const key = secretPath(SERVICE, "GITOPS_DEPLOY_KEY");
+    const knownHosts = join(specialistsHome(), "config", "known_hosts");
+    return {
+        GIT_SSH_COMMAND: `/usr/bin/ssh -i ${key} -o IdentitiesOnly=yes -o BatchMode=yes -o UserKnownHostsFile=${knownHosts} -o StrictHostKeyChecking=accept-new`,
+        GIT_AUTHOR_NAME: "specialist",
+        GIT_AUTHOR_EMAIL: "specialists@monadeo.com",
+        GIT_COMMITTER_NAME: "specialist",
+        GIT_COMMITTER_EMAIL: "specialists@monadeo.com",
+    };
+}
+
+async function git(dir: string, args: string[]): Promise<string> {
+    const result = await run("/usr/bin/git", ["-C", dir, ...args], { env: gitEnv(), timeoutMs: TIMEOUT_MS });
+    if (result.code !== 0) throw new ServiceError(`git ${args[0]} failed: ${result.stderr.trim()}`);
+    return result.stdout;
+}
+
+async function ensureCheckout(config: ArcaneConfig): Promise<string> {
+    const dir = workDir("arcane-gitops");
+    if (existsSync(join(dir, ".git"))) return dir;
+    mkdirSync(dirname(dir), { recursive: true, mode: 0o700 });
+    const result = await run(
+        "/usr/bin/git",
+        ["clone", "--branch", config.gitopsBranch, "--single-branch", config.gitopsRemote, dir],
+        { env: gitEnv(), timeoutMs: TIMEOUT_MS },
+    );
+    if (result.code !== 0) throw new ServiceError(`git clone failed: ${result.stderr.trim()}`);
+    return dir;
+}
+
+export function safeRepoPath(dir: string, rel: string): string {
+    if (rel.length === 0 || rel.startsWith("/") || rel.split("/").includes("..") || rel.includes("\0")) {
+        throw new UsageError(`invalid repository path: ${rel}`);
+    }
+    const target = resolve(dir, rel);
+    const inside = relative(dir, target);
+    if (inside.startsWith("..") || inside.startsWith(".git/") || inside === ".git") {
+        throw new UsageError(`path escapes the checkout: ${rel}`);
+    }
+    return target;
+}
+
+async function gitops(config: ArcaneConfig, args: string[]): Promise<number> {
+    const [sub, ...rest] = args;
+    const dir = await ensureCheckout(config);
+    switch (sub) {
+        case "status": {
+            await git(dir, ["fetch", "--quiet", "origin", config.gitopsBranch]);
+            const branch = (await git(dir, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+            const counts = (await git(dir, ["rev-list", "--left-right", "--count", `HEAD...origin/${config.gitopsBranch}`])).trim();
+            const [ahead, behind] = counts.split(/\s+/).map(Number);
+            const changed = (await git(dir, ["status", "--porcelain"])).split("\n").filter(Boolean);
+            printJson({ branch, ahead, behind, changed });
+            return 0;
+        }
+        case "pull":
+            printRaw(await git(dir, ["pull", "--ff-only", "origin", config.gitopsBranch]));
+            return 0;
+        case "diff":
+            printRaw((await git(dir, ["diff", "HEAD"])) || "(no changes)");
+            return 0;
+        case "log": {
+            const n = rest[0] === undefined ? 10 : Number(rest[0]);
+            if (!Number.isInteger(n) || n <= 0 || n > 200) throw new UsageError("gitops log [n]: n must be 1..200");
+            printRaw(await git(dir, ["log", `-n${n}`, "--format=%h %ad %s", "--date=short"]));
+            return 0;
+        }
+        case "write": {
+            if (rest.length !== 2) throw new UsageError("gitops write <path> <content>");
+            const target = safeRepoPath(dir, rest[0]);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, rest[1].endsWith("\n") ? rest[1] : `${rest[1]}\n`, { mode: 0o600 });
+            printJson({ written: rest[0], bytes: Buffer.byteLength(rest[1]) });
+            return 0;
+        }
+        case "commit": {
+            const message = rest.join(" ").trim();
+            if (message.length === 0) throw new UsageError("gitops commit <message>");
+            await git(dir, ["add", "--all"]);
+            const staged = (await git(dir, ["diff", "--cached", "--name-only"])).split("\n").filter(Boolean);
+            if (staged.length === 0) throw new UsageError("nothing to commit");
+            await git(dir, ["commit", "--quiet", "-m", message]);
+            printJson({ committed: (await git(dir, ["rev-parse", "--short", "HEAD"])).trim(), files: staged });
+            return 0;
+        }
+        case "push": {
+            const result = await run("/usr/bin/git", ["-C", dir, "push", "origin", config.gitopsBranch], { env: gitEnv(), timeoutMs: TIMEOUT_MS });
+            if (result.code !== 0) throw new ServiceError(`git push failed: ${result.stderr.trim()}`);
+            printRaw(result.stderr.trim() || "pushed");
+            return 0;
+        }
+        default:
+            throw new UsageError(`unknown gitops subcommand: ${sub ?? "(none)"}\n${HELP}`);
+    }
+}
+
+async function federatedToken(config: ArcaneConfig): Promise<string> {
+    const key = parseServiceAccountKey(readSecret(SERVICE, "ZITADEL_KEY_JSON"));
+    const zitadelToken = await mintAccessToken({ key, domain: config.zitadelDomain, audienceProjectId: config.audience });
+    const result = await run(
+        config.arcaneCli,
+        [
+            "--config",
+            config.arcaneCliConfig,
+            "auth",
+            "federated",
+            "--provider",
+            "generic",
+            "--token-stdin",
+            "--audience",
+            config.audience,
+            "--server",
+            config.serverUrl,
+            "--export",
+        ],
+        { input: zitadelToken, timeoutMs: 60_000 },
+    );
+    if (result.code !== 0) throw new ServiceError(`arcane-cli auth federated failed: ${result.stderr.trim()}`);
+    const match = /export ARCANE_TOKEN=['"]?([^'"\s]+)/.exec(result.stdout);
+    if (!match) throw new ServiceError("arcane-cli auth federated returned no ARCANE_TOKEN");
+    return match[1];
+}
+
+async function passthrough(config: ArcaneConfig, args: string[]): Promise<number> {
+    const refused = refusedPrefix(args);
+    if (refused) throw new UsageError(`"${refused}" is refused; project definitions change through gitops`);
+    const token = await federatedToken(config);
+    const wantsJson = args.includes("--json") || args.includes("--output");
+    const cliArgs = ["--config", config.arcaneCliConfig, ...(wantsJson ? [] : ["--output", "json"]), "--no-color", ...args];
+    const result = await run(config.arcaneCli, cliArgs, { env: { ARCANE_TOKEN: token }, timeoutMs: TIMEOUT_MS });
+    if (result.stdout.trim().length > 0) {
+        printRaw(filterJsonText(result.stdout, (v) => stripKeys(v, ARCANE_DENIED_KEYS)));
+    }
+    if (result.code !== 0) throw new ServiceError(result.stderr.trim() || `arcane-cli exited ${result.code}`);
+    return 0;
+}
+
+export async function command(args: string[]): Promise<number> {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "help") {
+        printRaw(HELP);
+        return 0;
+    }
+    const config = readConfig<ArcaneConfig>(SERVICE, SHAPE);
+    if (args[0] === "gitops") return gitops(config, args.slice(1));
+    return passthrough(config, args);
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+    await main(SERVICE, command);
+}

package/specialists/entry/remote/spc-identity-dmz-entry.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+# Forced command for the spc-identity key on VM 104 (user dmz).
+# authorized_keys line:
+#   command="/usr/local/sbin/spc-identity-dmz-entry",no-port-forwarding,no-agent-forwarding,no-pty,no-X11-forwarding ssh-ed25519 AAAA... spc-identity-dmz@cortex
+set -eu
+cmd="${SSH_ORIGINAL_COMMAND:-}"
+name="${cmd%% *}"
+rest=""
+[ "$cmd" != "$name" ] && rest="${cmd#* }"
+since_ok() { printf '%s' "$1" | grep -Eq '^[A-Za-z0-9 :+-]{1,40}$'; }
+
+case "$name" in
+  status) systemctl status pomerium nginx lego-renew.timer --no-pager --lines=5 ;;
+  journal)
+    unit="${rest%% *}"; since="${rest#* }"
+    case "$unit" in pomerium|nginx|lego-renew) ;; *) echo "bad unit" >&2; exit 2 ;; esac
+    since_ok "$since" || { echo "bad since" >&2; exit 2; }
+    journalctl -u "$unit" --since "$since" --no-pager -n 200 ;;
+  config-template) cat /etc/pomerium/config.yaml.template ;;
+  render) sudo /usr/local/sbin/render-pomerium ;;
+  pomerium-restart) sudo systemctl restart pomerium && systemctl is-active pomerium ;;
+  nginx-reload) sudo nginx -t && sudo systemctl reload nginx ;;
+  lego-renew) sudo systemctl start lego-renew.service && systemctl status lego-renew.service --no-pager --lines=10 ;;
+  *) echo "refused: $cmd" >&2; exit 2 ;;
+esac

package/specialists/entry/remote/spc-network-pulsar-entry.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+# Forced command for the spc-network key on Pulsar (root).
+# authorized_keys line:
+#   command="/usr/local/sbin/spc-network-pulsar-entry",no-port-forwarding,no-agent-forwarding,no-pty,no-X11-forwarding ssh-ed25519 AAAA... spc-network-pulsar@cortex
+set -eu
+cmd="${SSH_ORIGINAL_COMMAND:-}"
+name="${cmd%% *}"
+rest=""
+[ "$cmd" != "$name" ] && rest="${cmd#* }"
+since_ok() { printf '%s' "$1" | grep -Eq '^[A-Za-z0-9 :+-]{1,40}$'; }
+
+case "$name" in
+  guest-status)
+    case "$rest" in 105|107|108) pct status "$rest" ;; *) echo "bad guest" >&2; exit 2 ;; esac ;;
+  radius-check) pct exec 108 -- freeradius -XC ;;
+  radius-status) pct exec 108 -- systemctl status freeradius --no-pager --lines=5 ;;
+  radius-journal) since_ok "$rest" || { echo "bad since" >&2; exit 2; }; pct exec 108 -- journalctl -u freeradius --since "$rest" --no-pager -n 200 ;;
+  radius-crl-timer) pct exec 108 -- systemctl list-timers radius-crl-monitor.timer --no-pager ;;
+  tailscale-status) pct exec 105 -- tailscale status ;;
+  tailscale-journal) since_ok "$rest" || { echo "bad since" >&2; exit 2; }; pct exec 105 -- journalctl -u tailscaled --since "$rest" --no-pager -n 200 ;;
+  *) echo "refused: $cmd" >&2; exit 2 ;;
+esac