@astrofoundry/pi-astro 0.31.0 → 0.32.0

package/agents/media.md

@@ -19,6 +19,6 @@ Rules:
 - Movies go to `add-movies`, series to `add-series`; batch independent IDs in one call.
 - Success needs an explicit `added` or `already_exists` in `results`; `already_exists` means it was already there, not newly added. Report every ID of a batch.
 - Pause or resume downloads only when the task asks for it, then report the returned state. Adding never implies a queue change.
-- Keep replies short: canonical title and year, outcome, and the SABnzbd state an add returned. Mention `/trending` and `/search` when the user would rather click Add buttons.
+- Keep replies short: canonical title and year, outcome, and the SABnzbd state an add returned.
 - Library settings, quality profiles, Radarr and Sonarr configuration, and deletions are operator tasks; say so and stop.
 - Delegate through `subagent` only to another specialist (`astro.arcane` for the media containers on the Arcane VM) and only for that specialist's own area.

package/extensions/astro-discord/discord.test.ts

@@ -7,7 +7,7 @@ import { chunkMessage, fenceState } from "./chunk.ts";
 import { applyAdminCommand, describeConfig } from "./admin.ts";
 import { helpText, needsPrefixText, parseCommand } from "./commands.ts";
 import { allowedSpecialists, canUse, channelSpecialists, loadConfig, loadToken, validateConfig } from "./config.ts";
-import { INTENTS, initialState, reduce } from "./gateway.ts";
+import { GatewayClient, INTENTS, initialState, reduce } from "./gateway.ts";
 import type { RunResult } from "../astro-subagents/child.ts";
 import { failureReply } from "./index.ts";
 import { DiscordRest } from "./rest.ts";
@@ -181,6 +181,85 @@ describe("gateway reducer", () => {
     });
 });
 
+class FakeSocket {
+    readyState = 1;
+    sent: { op: number; d?: unknown }[] = [];
+    closedWith: number | null = null;
+    private readonly listeners = new Map<string, ((event: unknown) => void)[]>();
+    addEventListener(type: string, fn: (event: unknown) => void): void {
+        this.listeners.set(type, [...(this.listeners.get(type) ?? []), fn]);
+    }
+    send(data: string): void {
+        this.sent.push(JSON.parse(data) as { op: number; d?: unknown });
+    }
+    close(code: number): void {
+        this.closedWith = code;
+    }
+    emit(payload: object): void {
+        for (const fn of this.listeners.get("message") ?? []) fn({ data: JSON.stringify(payload) });
+    }
+    emitClose(code: number): void {
+        this.readyState = 3;
+        for (const fn of this.listeners.get("close") ?? []) fn({ code, reason: "" });
+    }
+}
+
+describe("gateway client", () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+
+    function client() {
+        const sockets: FakeSocket[] = [];
+        const log = vi.fn();
+        const gateway = new GatewayClient({
+            token: "t",
+            gatewayUrl: "wss://gateway",
+            handlers: { dispatch: vi.fn(), log },
+            socketFactory: () => {
+                const socket = new FakeSocket();
+                sockets.push(socket);
+                return socket as unknown as WebSocket;
+            },
+        });
+        return { gateway, sockets, log };
+    }
+
+    it("opens exactly one new connection after a reconnect request, and the replaced socket's close changes nothing", () => {
+        const { gateway, sockets, log } = client();
+        gateway.start();
+        sockets[0].emit({ op: 10, d: { heartbeat_interval: 1000 } });
+        sockets[0].emit({ op: 0, t: "READY", s: 1, d: { session_id: "s1", resume_gateway_url: "wss://resume" } });
+        sockets[0].emit({ op: 7 });
+        expect(sockets[0].closedWith).toBe(4000);
+        sockets[0].emitClose(4000);
+        vi.advanceTimersByTime(5_000);
+        expect(sockets).toHaveLength(2);
+
+        sockets[1].emit({ op: 10, d: { heartbeat_interval: 1000 } });
+        expect(sockets[1].sent.at(-1)).toMatchObject({ op: 6, d: { session_id: "s1", seq: 1 } });
+        sockets[0].emitClose(1000);
+        sockets[0].emit({ op: 7 });
+        vi.advanceTimersByTime(1_000);
+        expect(sockets).toHaveLength(2);
+        expect(sockets[1].sent.at(-1)).toEqual({ op: 1, d: 1 });
+        expect(log).not.toHaveBeenCalledWith("gateway closed (1000); reconnecting");
+        gateway.stop();
+    });
+
+    it("reconnects and resumes once when the server closes the current socket", () => {
+        const { gateway, sockets } = client();
+        gateway.start();
+        sockets[0].emit({ op: 10, d: { heartbeat_interval: 1000 } });
+        sockets[0].emit({ op: 0, t: "READY", s: 3, d: { session_id: "s1", resume_gateway_url: "wss://resume" } });
+        sockets[0].emitClose(1000);
+        vi.advanceTimersByTime(5_000);
+        expect(sockets).toHaveLength(2);
+        sockets[1].emit({ op: 10, d: { heartbeat_interval: 1000 } });
+        expect(sockets[1].sent.at(-1)).toMatchObject({ op: 6, d: { session_id: "s1", seq: 3 } });
+        gateway.stop();
+    });
+});
+
 describe("rest", () => {
     it("sends JSON messages, multipart attachments, and retries once after 429", async () => {
         const calls: { url: string; init: RequestInit }[] = [];

package/extensions/astro-discord/gateway.ts

@@ -137,6 +137,7 @@ export class GatewayClient {
         const socket = factory(this.url(resume));
         this.socket = socket;
         socket.addEventListener("message", (event: MessageEvent) => {
+            if (this.socket !== socket) return;
             let payload: GatewayPayload;
             try {
                 payload = JSON.parse(String(event.data)) as GatewayPayload;
@@ -146,6 +147,9 @@ export class GatewayClient {
             this.act(reduce(this.state, payload, this.options.handlers));
         });
         socket.addEventListener("close", (event: CloseEvent) => {
+            // A socket already replaced by a reconnect must not stop the new one's heartbeat or start another connection.
+            if (this.socket !== socket) return;
+            this.socket = null;
             this.clearHeartbeat();
             if (this.stopped) return;
             if (FATAL_CLOSE_CODES.has(event.code)) {
@@ -186,12 +190,15 @@ export class GatewayClient {
             case "heartbeat-now":
                 this.send({ op: 1, d: this.state.seq });
                 break;
-            case "reconnect":
+            case "reconnect": {
+                const old = this.socket;
+                this.socket = null;
                 this.clearHeartbeat();
-                this.socket?.close(4000);
+                old?.close(4000);
                 if (!action.resume) this.state.sessionId = null;
                 this.scheduleReconnect(action.resume);
                 break;
+            }
             default:
                 break;
         }

package/extensions/astro-discord/media.test.ts

@@ -62,6 +62,7 @@ describe("media slash commands", () => {
         expect(commandArgs("search", [{ name: "title", type: 3, value: "  dune " }])).toEqual({ view: "search", args: ["search", "dune", "--max-entries", "10"], query: "dune" });
         expect(commandArgs("search", [{ name: "title", type: 3, value: "  " }])).toBeNull();
         expect(commandArgs("downloads", [{ name: "action", type: 3, value: "pause" }])).toEqual({ view: "downloads", args: ["sabnzbd", "pause"] });
+        expect(commandArgs("downloads", [{ name: "action", type: 3, value: "unpause" }])).toEqual({ view: "downloads", args: ["sabnzbd", "resume"] });
         expect(commandArgs("downloads", [{ name: "action", type: 3, value: "delete" }])).toBeNull();
         expect(commandArgs("ban", [])).toBeNull();
     });

package/extensions/astro-discord/media.ts

@@ -73,7 +73,7 @@ export const MEDIA_COMMANDS = [
     {
         name: "downloads",
         type: 1,
-        description: "SABnzbd queue: status, pause, or resume",
+        description: "SABnzbd queue: status, pause, or resume (unpause)",
         contexts: [GUILD_CONTEXT],
         options: [
             {
@@ -85,6 +85,7 @@ export const MEDIA_COMMANDS = [
                     { name: "status", value: "status" },
                     { name: "pause", value: "pause" },
                     { name: "resume", value: "resume" },
+                    { name: "unpause", value: "unpause" },
                 ],
             },
         ],
@@ -130,8 +131,8 @@ export function commandArgs(name: string, options: readonly CommandOption[]): Me
     }
     if (name === "downloads") {
         const action = value(options, "action");
-        if (action !== "status" && action !== "pause" && action !== "resume") return null;
-        return { view: "downloads", args: ["sabnzbd", action] };
+        if (action !== "status" && action !== "pause" && action !== "resume" && action !== "unpause") return null;
+        return { view: "downloads", args: ["sabnzbd", action === "unpause" ? "resume" : action] };
     }
     return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"

package/skills/media/SKILL.md

@@ -41,7 +41,7 @@ Answer "what is trending" with `trending` and list the items in this format, one
 
 `{rank}. [{title} ({year})](<https://www.imdb.com/title/{imdb_id}/>) — {imdb_rating} · 🔥{popularity rounded} {✅ in library | ❌ not | ❓ unknown}`
 
-Leave out the rating part when it is null. Add nothing else but one closing line that `/trending` shows the same list with Add buttons. When the user then names items by number ("add 2 and 5 from the movies"), map the numbers to that list's `imdb_id` values; if the list is not in this conversation, run `trending` again.
+Leave out the rating part when it is null. Add nothing else. When the user then names items by number ("add 2 and 5 from the movies"), map the numbers to that list's `imdb_id` values; if the list is not in this conversation, run `trending` again.
 
 ## Failures
 

package/specialists/AGENTS.md

@@ -25,11 +25,11 @@ specialists/<name>/run.ts       one wrapper per specialist (arcane, identity, ne
 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/ (forced commands for SSH targets, the VPS sudoers list and its install script)
+specialists/entry/              specialist-cli.sh (sudo entry point), specialist-install.sh (root installer for Node, wrappers, arcane-cli, trendarr), remote/ (forced commands for SSH targets, the VPS sudoers list and its install script)
 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`.
+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` (first install) and `specialist-install wrappers` (updates) copy `lib/` and each `run.ts` into `~/.specialists/bin/`; the entry point runs them with the root-owned Node, `/usr/local/libexec/specialist-node/current/bin/node`.
 
 ## Rules for wrapper code
 
@@ -53,6 +53,7 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
 - The wrapper's repository commands are the `git` group; `gitops` must stay free because it is an `arcane-cli` command group (server-side syncs).
 - Every passthrough call writes a private per-call copy of `arcanecli.yml` with `jwt_token` set, because some `arcane-cli` commands validate the config file before reading `ARCANE_TOKEN`. The copy is removed after the call.
 - Every wrapper answers `--help` without reading config, so agents can discover subcommands before anything else is set up.
+- `entry/specialist-install.sh` runs as root, so it runs only `/usr/bin`, `/bin`, `/usr/sbin`, `/sbin` and the Node it installed, never Homebrew or anything else the main user can write; it checks that `/usr/local/libexec/specialist-node` and its parents belong to root and are writable by nobody else. Arguments are checked before the root test (tests exercise that part). Downloads go to a root-only temporary directory and are verified before use: Node against `SHASUMS256.txt` and the LTS flag in `index.json`, npm tarballs against the registry's `sha512` integrity, arcane-cli against the release's checksums file. Inside `/Users/specialist` it works only as `specialist` (`sudo -u specialist -H`), from a staging directory root hands over, so a link the specialist plants cannot redirect a root write. Each component switches by rename after a check (every installed wrapper's `--help`, `--version` of the new binary) and restores the previous copy when the check fails. Older versions are refused; `rollback` swaps current and previous. Homebrew's `bw` and `jq` (provision) and `gcloud` (edge) still run as `specialist`; that is a separate issue.
 - `main()` waits for stdout and stderr to flush before `process.exit`: on a pipe, exiting right after a write drops everything past the 64 KiB buffer, which cut large answers such as `projects list --all` until 2026-09-25 (`lib/flush.test.ts`).
 - `arcane update-report [--all]` is `lib/image-updates.ts` over `lib/registry.ts`: a fresh `images updates check --all`, then `projects list --all` for the stack and service of each image reference, then the registries' tag lists and manifest digests (anonymous bearer tokens from each registry's challenge; digests by HEAD, which Docker Hub does not count as a pull; lscr.io is read from ghcr.io). A floating or major-series tag is resolved to the release tag whose digest matches the running and the latest build, searching the newest tags of the three commonest release shapes; a fixed tag is compared with the newest tag of the same shape; a digest pin with the newest release. Checks older than one minute before the run count as stale and show as unknown. Private images (anonymous access refused with 401 or 403) are excluded from rows, counts, and table, listed in `privateImages`, and counted in the summary line. The table is fixed-width text for a code block, because Discord renders no Markdown tables.
 - `media` runs trendarr unchanged: `trendarrCli` in `media.json` is its `dist/cli.js`, started with `process.execPath` because sudo's PATH has no node. Each call gets `HOME` set to a fresh `0700` directory under `~/.specialists/work/media/` that holds only `.trendarr/config.json` (`0600`, trendarr's own schema, built from the note fields and `media.json`) and is removed in `finally`; trendarr reads no environment variables and has no config flag, and Node's `os.homedir()` follows `$HOME` on POSIX. Every call passes `--json`; `init` is refused. An add prints trendarr's per-ID `results` and exits 0 even when trendarr exits 1 for a failed ID, because the gate shows only stderr on failure; other failures carry trendarr's stderr without its `warning:` lines, which go into the JSON as `warnings`. The bridge's slash commands and Add buttons call the same wrapper through the entry point (`extensions/astro-discord/media.ts`).
@@ -66,7 +67,7 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
 
 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 and the `rm -rf` line. `entry/specialist-cli.sh`: add the name to the allowlist, then reinstall the root-owned copy on the host.
+3. `install.sh`: add the name to the copy loop and the `rm -rf` line. `entry/specialist-cli.sh` and `entry/specialist-install.sh`: add the name to the allowlist and to `SERVICES` (a test keeps them equal), then reinstall both root-owned copies on the host.
 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`.

package/specialists/README.md

@@ -21,6 +21,7 @@ Call one with `/run astro.<name> -- <task>` or through the `subagent` tool (both
 
 - 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`.
+- The wrappers run on a root-owned Node in `/usr/local/libexec/specialist-node/` (latest LTS from nodejs.org), not on Homebrew's, because the main user owns all of `/opt/homebrew` and could otherwise swap the interpreter that reads every secret. `/usr/local/sbin/specialist-install` (root, one passwordless sudo rule) installs that Node, the wrappers, arcane-cli, and trendarr from downloads it checks against the publisher's checksums; it refuses older versions and keeps the previous one for `rollback`. Still open: `provision` runs Homebrew's `bw` and `jq`, and `edge` runs Homebrew's `gcloud`, both as `specialist`.
 - 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, tokens, or SSH keys that the targets pin to forced commands. The VPS is reached through `gcloud compute start-iap-tunnel` with a service account that may only open IAP tunnels and read instances; its gcloud state lives in `/Users/specialist/.specialists/work/gcloud`.
 - 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.
@@ -29,7 +30,7 @@ Limits: `network` writes only firewall policies on UniFi. `security` is read-onl
 
 ## Enable specialists on a host
 
-Host: Cortex (macOS, Homebrew `node`, `bw`, `jq`, `gcloud-cli` with `python@3.14`, git; for `media`, trendarr (`@astrofoundry/trendarr`) where the `specialist` user can read its `dist/cli.js`). Steps 1 to 3 are one-time on the services; 4 to 8 are per host.
+Host: Cortex (macOS on Apple silicon; Homebrew `bw`, `jq`, `gcloud-cli` with `python@3.14`, git; the specialists' Node and trendarr come from `specialist-install`). 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 (`_B64` fields hold `base64 -i <keyfile> | tr -d '\n'`):
    - `arcane`: `ZITADEL_KEY_JSON`, `GITOPS_DEPLOY_KEY_B64`, `ZITADEL_USER_ID` (plain).
@@ -51,10 +52,14 @@ Host: Cortex (macOS, Homebrew `node`, `bw`, `jq`, `gcloud-cli` with `python@3.14
    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 -d -m 0755 -o root -g wheel /usr/local/sbin
+   sudo install -m 0755 -o root -g wheel <package>/specialists/entry/specialist-install.sh /usr/local/sbin/specialist-install
+   printf 'cortex ALL=(root) NOPASSWD: /usr/local/sbin/specialist-install\n' > /tmp/specialist-install.sudoers && sudo visudo -cf /tmp/specialist-install.sudoers && sudo install -m 0440 -o root -g wheel /tmp/specialist-install.sudoers /etc/sudoers.d/specialist-install && rm /tmp/specialist-install.sudoers
+   sudo /usr/local/sbin/specialist-install node 24.22.0
    sudo install -m 0755 -o root -g wheel <package>/specialists/entry/specialist-cli.sh /usr/local/bin/specialist-cli
    brew install --cask gcloud-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. `specialist-cli` holds the list of services it accepts; after an update that adds one (such as `media`), install it again with the same `sudo install` line.
+   `specialist-cli` runs the wrappers with the Node that `specialist-install node` put in place, so that Node comes first. 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. `specialist-cli` and `specialist-install` hold the same list of services; after an update that adds one (such as `media`), install both again with the same `sudo install` lines.
 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.12.0` (`<package>` is the installed pi-astro directory, `~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro`). Write `~/.specialists/config/<name>.json` for every specialist:
    ```json
@@ -74,13 +79,28 @@ Host: Cortex (macOS, Homebrew `node`, `bw`, `jq`, `gcloud-cli` with `python@3.14
    { "apiUrl": "https://10.0.10.37:8006", "certSha256": "<from: specialist-cli proxmox -- fingerprint>", "node": "pulsar", "pulsarHost": "10.0.10.37", "pulsarUser": "root" }
    { "nexusHost": "10.0.40.38", "nexusUser": "nexus", "hermesHost": "10.0.40.31", "hermesUser": "hermes", "pulsarHost": "10.0.10.37", "pulsarUser": "root",
      "europaHealthUrl": "http://10.0.60.5:8081/health", "hermesRepo": "NousResearch/hermes-agent" }
-   { "trendarrCli": "<absolute path to trendarr's dist/cli.js>",
+   { "trendarrCli": "/Users/specialist/.specialists/bin/trendarr/node_modules/@astrofoundry/trendarr/dist/cli.js",
      "radarrUrl": "http://10.0.40.30:7878", "radarrQualityProfileId": 7, "radarrRootFolderPath": "/media/movies",
      "sonarrUrl": "http://10.0.40.30:8989", "sonarrQualityProfileId": 7, "sonarrRootFolderPath": "/media/tv", "sonarrMonitor": "all",
      "sabnzbdUrl": "http://10.0.40.30:8084", "maxEntries": 10 }
    ```
    The `media` wrapper writes trendarr's `~/.trendarr/config.json` for each call into a private temporary HOME under `~/.specialists/work/media/` and removes it afterwards, so trendarr itself is never configured with `trendarr init`. Cortex reaches the three ports on `10.0.40.30` within its own VLAN.
-   Then `sudo -n -u specialist -H /usr/local/bin/specialist-cli provision`; it lists every note and field.
+   `sudo /usr/local/sbin/specialist-install trendarr <version>` installs trendarr behind the link `~/.specialists/bin/trendarr`, so that path stays valid across updates. Then `sudo -n -u specialist -H /usr/local/bin/specialist-cli provision`; it lists every note and field.
+
+   Later updates go through the installer, one component at a time, each checked before and after the switch:
+   ```sh
+   sudo /usr/local/sbin/specialist-install node <LTS version>
+   sudo /usr/local/sbin/specialist-install wrappers <pi-astro version>
+   sudo /usr/local/sbin/specialist-install arcane-cli <Arcane server version>
+   sudo /usr/local/sbin/specialist-install trendarr <version>
+   sudo /usr/local/sbin/specialist-install rollback node|wrappers|arcane-cli|trendarr
+   sudo /usr/local/sbin/specialist-install status
+   ```
+   - `node` accepts only an LTS release listed in `https://nodejs.org/dist/index.json`, checks the tarball against `SHASUMS256.txt`, and switches `current` only after every installed wrapper answers `--help` with it; `previous` keeps the last one.
+   - `wrappers` takes the pi-astro tarball from the npm registry, checks its `sha512` integrity, copies what `install.sh` copies, writes `~/.specialists/bin/VERSION`, and restores the old files if any wrapper fails `--help`. `install.sh` stays the first-time installer (it also writes the default config files).
+   - `arcane-cli` checks the release tarball against `arcane_<version>_checksums.txt`; it follows the Arcane server's version.
+   - `trendarr` installs with the root-owned Node's npm, without install scripts, into `trendarr-<version>`.
+   - A version older than the installed one is refused; `rollback` swaps back to the kept previous copy. `status` prints the installed versions as JSON.
 7. **SSH targets.** Each target gets an entry script from `entry/remote/` as `/usr/local/sbin/<entry>` (`0755`, root) and the public key in the right `authorized_keys` as
    `command="/usr/local/sbin/<entry>",no-port-forwarding,no-agent-forwarding,no-pty,no-X11-forwarding ssh-ed25519 ...`:
    - VM 104, user `dmz`: `spc-identity-dmz-entry.sh`.
@@ -114,7 +134,7 @@ Check: `sudo -n -u specialist -H /usr/local/bin/specialist-cli arcane --caller t
 The `astro-discord` extension gives Discord users access to the specialists from a channel. It runs in a headless Pi host on Cortex (LaunchAgent `com.astrofoundry.astro-discord`, user `cortex`), never in interactive sessions.
 
 - Channels are configured one by one (`channels.<id>`): `trigger` is `always` (every message that names a specialist counts) or `mention` (only messages that start with `@Cortex` or reply to the bot); `specialists` is `*` or a list. A channel with one specialist needs no prefix: every message there is a task for it. In a channel with several, `dns list the zones` names the specialist; an addressed message without a name gets a reply asking for one. Threads inherit their parent channel's entry; unlisted channels are ignored. The bot replies at once with "<specialist> is working on your task" and shows the typing indicator until the answer replaces that reply. Reactions on your message: ⏳ running, 🔒 waiting for an owner's approval, ✅ done, ❌ failed. `help` shows the specialists you may use in that channel and the commands (`status` lists running tasks; owners in the admin channel also see the `config` commands). Each channel and specialist has one conversation: a reply to the bot's answer, or another task for that specialist within 30 minutes, continues it with everything the specialist saw before; otherwise a new one starts, and a task beginning with `new` forces that. Replied-to and forwarded messages (text, embeds, attachment names) travel with the task, so "check this" on a forwarded alert works. Image attachments on the message or on what it quotes (up to 4, 8 MiB each) are downloaded and passed to the specialist, which sees them; other file types are named only. Sessions live under `~/.config/astro-discord/sessions/<specialist>/` and are deleted after 7 days. Long answers arrive as a `.md` attachment. When the bridge restarts, open approval requests are marked cancelled and running tasks interrupted in Discord; ask again. With `dailyReport` in the config, the bridge posts an "Arcane Daily Report:" message every morning in that channel: each service with an update as current to target version, from a fresh `update-report`; replying to it asks the arcane specialist with the report as context.
-- Media: where the `media` specialist is present (`config channel <#channel> always media`), `/trending [type] [min_rating] [count]`, `/search <title> [type]`, and `/downloads <status|pause|resume>` run the wrapper without a model. Lists arrive as two messages, Movies and Series, each title with a button beside it: **Add** adds it at once and turns into Added, In library, or Not found (Retry after a failure); a greyed-out In library or No IMDb ID button needs nothing. Notes such as "downloads are paused" go only to the user who clicked. Owners and `access.media` users may use them; anyone else gets a refusal only they see, and in a channel without `media` the bot names the channels that have it. Plain messages in the channel still go to the agent, for requests by name ("add the new Dune"). At startup the bridge sets the three commands as the application's global commands (servers only).
+- Media: where the `media` specialist is present (`config channel <#channel> always media`), `/trending [type] [min_rating] [count]`, `/search <title> [type]`, and `/downloads <status|pause|resume|unpause>` run the wrapper without a model. Lists arrive as two messages, Movies and Series, each title with a button beside it: **Add** adds it at once and turns into Added, In library, or Not found (Retry after a failure); a greyed-out In library or No IMDb ID button needs nothing. Notes such as "downloads are paused" go only to the user who clicked. Owners and `access.media` users may use them; anyone else gets a refusal only they see, and in a channel without `media` the bot names the channels that have it. Plain messages in the channel still go to the agent, for requests by name ("add the new Dune"). At startup the bridge sets the three commands as the application's global commands (servers only).
 - Access: `owners` may use every specialist and decide approvals; `access.<specialist>` lists extra users for that specialist; everyone else gets no reply. Owners change the configuration from the admin channel (`adminChannelId`) without a shell: `config show`, `config channel <#channel> <always|mention> <*|dns,edge>`, `config channel <#channel> remove`, `config access <specialist> add|remove <@user>`; the bot writes `~/.config/astro-discord/config.json` on Cortex, which is also editable by hand and re-read on every message. Deny the bot's role View Channel on channels it must never read; that is the boundary the map cannot provide.
 - Approvals: a risky call (anything with `--confirm`, plus writes such as record or zone deletes, Zitadel changes, Pomerium deploys, service restarts, and on Arcane only destructive actions: `down`, deletes, prunes, image, volume, or network removal, `system upgrade`, `gitops delete`; help lookups never ask) pauses the specialist and posts Approve/Deny buttons; only owners' clicks count; no decision within `approvalTimeoutMinutes` denies it. The specialist then reports the denial. Ambiguous tasks get a question back instead of an action.
 - Setup, as `cortex`: `d=$(mktemp -d) && cp ~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro/extensions/astro-discord/*.ts "$d" && node --disable-warning=ExperimentalWarning "$d/setup.ts"` (Node does not strip types inside `node_modules`, so the files are copied first) prompts for the bot token and the ids, checks each against Discord, and writes `~/.config/astro-discord/{token,config.json,run.sh}` and the LaunchAgent; it prints the `launchctl bootstrap` line. After a pi-astro update restart the bridge with `launchctl kickstart -k gui/$(id -u)/com.astrofoundry.astro-discord`. Log: `~/Library/Logs/astro-discord.log`.

package/specialists/entry/specialist-cli.sh

@@ -17,4 +17,5 @@ if [[ "${1:-}" == "--caller" ]]; then caller="${2:-unknown}"; shift 2; fi
 
 runner="$HOME/.specialists/bin/$service/run.ts"
 [[ -f "$runner" ]] || { print -u2 "specialist '$service' is not installed"; exit 2; }
-exec /opt/homebrew/bin/node --disable-warning=ExperimentalWarning "$runner" --caller "$caller" -- "$@"
+# The root-owned Node from specialist-install; Homebrew's belongs to the cortex user.
+exec /usr/local/libexec/specialist-node/current/bin/node --disable-warning=ExperimentalWarning "$runner" --caller "$caller" -- "$@"

package/specialists/entry/specialist-install.sh

@@ -0,0 +1,459 @@
+#!/bin/sh
+# /usr/local/sbin/specialist-install: installs the specialist user's Node, wrappers,
+# arcane-cli, and trendarr from downloads it checks itself. Installed root-owned 0755.
+# Runs as root through
+#   cortex ALL=(root) NOPASSWD: /usr/local/sbin/specialist-install
+# It runs only system binaries and the Node it installed, never anything the cortex
+# user can write (all of Homebrew), and it touches the specialist's home only as that
+# user, so links the specialist plants there cannot redirect a root write.
+#
+#   specialist-install node|wrappers|arcane-cli|trendarr <version>
+#   specialist-install rollback node|wrappers|arcane-cli|trendarr
+#   specialist-install status
+set -eu
+PATH=/usr/bin:/bin:/usr/sbin:/sbin
+export PATH
+umask 077
+cd /
+
+SPECIALIST=specialist
+NODE_BASE=/usr/local/libexec/specialist-node
+# Same list as the allowlist in specialist-cli; a new specialist needs both reinstalled.
+SERVICES="arcane identity network dns edge security backup proxmox inference media"
+
+usage() {
+  echo "usage: specialist-install node|wrappers|arcane-cli|trendarr <version> | rollback node|wrappers|arcane-cli|trendarr | status" >&2
+  exit 2
+}
+
+fail() {
+  echo "specialist-install: $*" >&2
+  exit 1
+}
+
+# x.y.z with plain decimal parts; the character check also rules out newlines.
+valid_version() {
+  case "$1" in '' | *[!0-9.]*) return 1 ;; esac
+  printf '%s\n' "$1" | /usr/bin/grep -Eq '^(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})$'
+}
+
+# True when version $1 is older than version $2.
+version_lt() {
+  old_ifs=$IFS
+  IFS=.
+  set -- $1 $2
+  IFS=$old_ifs
+  [ "$1" -lt "$4" ] && return 0
+  [ "$1" -gt "$4" ] && return 1
+  [ "$2" -lt "$5" ] && return 0
+  [ "$2" -gt "$5" ] && return 1
+  [ "$3" -lt "$6" ]
+}
+
+component_ok() {
+  case "$1" in node | wrappers | arcane-cli | trendarr) return 0 ;; esac
+  return 1
+}
+
+command=${1:-}
+case "$command" in
+  node | wrappers | arcane-cli | trendarr)
+    [ $# -eq 2 ] || usage
+    valid_version "$2" || usage
+    ;;
+  rollback)
+    [ $# -eq 2 ] || usage
+    component_ok "$2" || usage
+    ;;
+  status) [ $# -eq 1 ] || usage ;;
+  *) usage ;;
+esac
+
+[ "$(/usr/bin/id -u)" = 0 ] || fail "must run as root: sudo /usr/local/sbin/specialist-install $*"
+[ "$(/usr/bin/uname -s)" = Darwin ] && [ "$(/usr/bin/uname -m)" = arm64 ] || fail "only macOS on arm64 is supported"
+/usr/bin/id -u "$SPECIALIST" >/dev/null 2>&1 || fail "user $SPECIALIST does not exist"
+
+work=$(/usr/bin/mktemp -d /private/var/tmp/specialist-install.XXXXXX)
+trap '/bin/rm -rf "$work"' EXIT
+trap 'exit 1' HUP INT TERM
+
+# A directory only root can change: owned by uid 0, not a link, writable by nobody else.
+check_root_dir() {
+  [ -d "$1" ] && [ ! -L "$1" ] || fail "$1 is not a directory"
+  set -- "$1" $(/usr/bin/stat -f '%u %Lp' "$1")
+  [ "$2" = 0 ] || fail "$1 is not owned by root"
+  case "$3" in *[2367] | *[2367]?) fail "$1 is writable by group or others" ;; esac
+}
+
+ensure_root_dir() {
+  [ -e "$1" ] || { /bin/mkdir -m 0755 "$1" && /usr/sbin/chown root:wheel "$1"; }
+  check_root_dir "$1"
+}
+
+check_node_base() {
+  check_root_dir /
+  check_root_dir /usr
+  check_root_dir /usr/local
+  ensure_root_dir /usr/local/libexec
+  ensure_root_dir "$NODE_BASE"
+}
+
+fetch() {
+  /usr/bin/curl --proto '=https' --proto-redir '=https' --tlsv1.2 -fsSL --retry 2 --max-time 900 -o "$2" "$1" || fail "download failed: $1"
+}
+
+json_field() {
+  /usr/bin/plutil -extract "$2" raw -o - "$1" 2>/dev/null
+}
+
+# $1 directory, $2 file name in it, $3 a "<sha256>  <name>" list.
+check_sha256() {
+  want=$(/usr/bin/awk -v f="$2" '$2 == f && length($1) == 64 { print $1; exit }' "$3")
+  [ -n "$want" ] || fail "no checksum for $2"
+  got=$(/usr/bin/shasum -a 256 "$1/$2" | /usr/bin/awk '{ print $1 }')
+  [ "$got" = "$want" ] || fail "checksum mismatch for $2"
+}
+
+# Downloads an npm package tarball after checking it against the registry's sha512 integrity.
+fetch_npm() {
+  meta="$work/$3.meta.json"
+  fetch "https://registry.npmjs.org/$1/$2" "$meta"
+  [ "$(json_field "$meta" version)" = "$2" ] || fail "$1@$2 is not in the npm registry"
+  tarball=$(json_field "$meta" dist.tarball) || fail "$1@$2 has no tarball"
+  integrity=$(json_field "$meta" dist.integrity) || fail "$1@$2 has no integrity"
+  case "$tarball" in https://registry.npmjs.org/*) ;; *) fail "unexpected tarball location for $1@$2" ;; esac
+  fetch "$tarball" "$work/$3.tgz"
+  [ "sha512-$(/usr/bin/openssl dgst -sha512 -binary "$work/$3.tgz" | /usr/bin/base64)" = "$integrity" ] || fail "integrity mismatch for $1@$2"
+}
+
+# Runs a script as the specialist user with fixed arguments; the script never sees root's environment.
+as_specialist() {
+  script=$1
+  shift
+  /usr/bin/sudo -n -u "$SPECIALIST" -H /bin/sh -c "set -eu; umask 077; PATH=/usr/bin:/bin:/usr/sbin:/sbin; cd \"\$HOME\"; $script" specialist-install "$@"
+}
+
+# Root-owned staging for files the specialist then copies into its home.
+make_stage() {
+  /bin/chmod 0711 "$work"
+  stage="$work/stage"
+  /bin/mkdir -m 0700 "$stage"
+}
+
+hand_stage() {
+  /usr/sbin/chown -R "$SPECIALIST:$(/usr/bin/id -gn "$SPECIALIST")" "$stage"
+}
+
+node_link() {
+  target=$(/usr/bin/readlink "$NODE_BASE/$1" 2>/dev/null) || return 0
+  valid_version "$target" && [ -x "$NODE_BASE/$target/bin/node" ] && printf '%s' "$target"
+  return 0
+}
+
+switch_node_link() {
+  /bin/rm -f "$NODE_BASE/.$1.tmp"
+  (umask 022 && /bin/ln -s "$2" "$NODE_BASE/.$1.tmp")
+  /bin/mv -h "$NODE_BASE/.$1.tmp" "$NODE_BASE/$1"
+}
+
+current_node() {
+  node=$(node_link current)
+  [ -n "$node" ] || fail "no specialist Node yet: run specialist-install node <version> first"
+  printf '%s' "$NODE_BASE/$node/bin/node"
+}
+
+# Specialist side: every installed wrapper answers --help with Node $1; nothing to check before the first install.
+SMOKE_INSTALLED='node=$1; shift
+bin="$HOME/.specialists/bin"
+[ -d "$bin/lib" ] || exit 0
+for s in "$@"; do
+  "$node" --disable-warning=ExperimentalWarning "$bin/$s/run.ts" --caller specialist-install -- --help >/dev/null 2>&1 || { echo "$s --help failed with $node" >&2; exit 1; }
+done'
+
+smoke_installed_wrappers() {
+  as_specialist "$SMOKE_INSTALLED" "$1" $SERVICES
+}
+
+install_node() {
+  version=$1
+  check_node_base
+  current=$(node_link current)
+  if [ -n "$current" ] && version_lt "$version" "$current"; then fail "node $version is older than the installed $current; use rollback"; fi
+  [ "$current" != "$version" ] || { echo "node $version is already current"; return 0; }
+
+  fetch https://nodejs.org/dist/index.json "$work/index.json"
+  i=0
+  found=""
+  while [ "$i" -lt 400 ]; do
+    v=$(json_field "$work/index.json" "$i.version") || break
+    if [ "$v" = "v$version" ]; then found=$i; break; fi
+    i=$((i + 1))
+  done
+  [ -n "$found" ] || fail "node $version is not among the 400 newest releases"
+  [ "$(json_field "$work/index.json" "$found.lts")" != false ] || fail "node $version is not an LTS release"
+  /usr/bin/plutil -extract "$found.files" json -o - "$work/index.json" | /usr/bin/grep -q '"osx-arm64-tar"' || fail "node $version has no macOS arm64 build"
+
+  name="node-v$version-darwin-arm64.tar.gz"
+  fetch "https://nodejs.org/dist/v$version/$name" "$work/$name"
+  fetch "https://nodejs.org/dist/v$version/SHASUMS256.txt" "$work/SHASUMS256.txt"
+  check_sha256 "$work" "$name" "$work/SHASUMS256.txt"
+
+  dest="$NODE_BASE/$version"
+  /bin/rm -rf "$dest.partial"
+  /bin/mkdir -m 0755 "$dest.partial"
+  /usr/bin/tar -xzf "$work/$name" -C "$dest.partial" --strip-components 1
+  /usr/sbin/chown -R root:wheel "$dest.partial"
+  /bin/chmod -R u=rwX,go=rX "$dest.partial"
+  [ "$("$dest.partial/bin/node" --version)" = "v$version" ] || fail "node $version does not run"
+  /bin/rm -rf "$dest"
+  /bin/mv "$dest.partial" "$dest"
+  smoke_installed_wrappers "$dest/bin/node" || fail "the installed wrappers fail with node $version; current stays ${current:-unset}"
+
+  [ -z "$current" ] || switch_node_link previous "$current"
+  switch_node_link current "$version"
+  for d in "$NODE_BASE"/*; do
+    n=${d##*/}
+    case "$n" in current | previous | "$version" | "$current") continue ;; esac
+    /bin/rm -rf "$d"
+  done
+  echo "node $version is current${current:+; previous $current}"
+}
+
+rollback_node() {
+  check_node_base
+  current=$(node_link current)
+  previous=$(node_link previous)
+  [ -n "$current" ] && [ -n "$previous" ] || fail "no previous node to roll back to"
+  smoke_installed_wrappers "$NODE_BASE/$previous/bin/node" || fail "the installed wrappers fail with node $previous"
+  switch_node_link current "$previous"
+  switch_node_link previous "$current"
+  echo "node $previous is current; previous $current"
+}
+
+WRAPPER_VERSION='v=$(cat "$HOME/.specialists/bin/VERSION" 2>/dev/null) || exit 0; printf "%s" "$v"'
+
+# Moves the new wrapper files in and the old ones aside, two renames per item, then
+# checks every wrapper; on failure the old files come back.
+SWAP_WRAPPERS='node=$1; stage=$2; shift 2
+bin="$HOME/.specialists/bin"; back="$HOME/.specialists/rollback/wrappers"
+items="lib provision.sh VERSION $*"
+smoke() { d=$1; shift; for s in "$@"; do "$node" --disable-warning=ExperimentalWarning "$d/$s/run.ts" --caller specialist-install -- --help >/dev/null 2>&1 || { echo "$s --help failed" >&2; return 1; }; done; }
+smoke "$stage" "$@" || exit 1
+mkdir -p "$bin" "$HOME/.specialists/rollback"
+rm -rf "$back.new"; mkdir "$back.new"
+for i in $items; do rm -rf "$bin/.new-$i"; cp -R "$stage/$i" "$bin/.new-$i"; done
+for i in $items; do
+  [ ! -e "$bin/$i" ] || mv "$bin/$i" "$back.new/$i"
+  mv "$bin/.new-$i" "$bin/$i"
+done
+chmod -R go-rwx "$bin"
+if ! smoke "$bin" "$@"; then
+  for i in $items; do rm -rf "$bin/$i"; [ ! -e "$back.new/$i" ] || mv "$back.new/$i" "$bin/$i"; done
+  rm -rf "$back.new"
+  echo "restored the previous wrappers" >&2
+  exit 1
+fi
+rm -rf "$back"; mv "$back.new" "$back"'
+
+install_wrappers() {
+  version=$1
+  node=$(current_node)
+  current=$(as_specialist "$WRAPPER_VERSION")
+  valid_version "$current" || current=""
+  if [ -n "$current" ] && version_lt "$version" "$current"; then fail "wrappers $version are older than the installed $current; use rollback"; fi
+
+  fetch_npm @astrofoundry/pi-astro "$version" pi-astro
+  /bin/mkdir "$work/pkg"
+  /usr/bin/tar -xzf "$work/pi-astro.tgz" -C "$work/pkg" --strip-components 1
+  src="$work/pkg/specialists"
+  [ -d "$src/lib" ] && [ -f "$src/provision/provision.sh" ] || fail "pi-astro $version has no specialists/lib or provision.sh"
+  make_stage
+  /bin/cp -R "$src/lib" "$stage/lib"
+  for s in $SERVICES; do
+    [ -f "$src/$s/run.ts" ] || fail "pi-astro $version has no $s wrapper"
+    /bin/mkdir "$stage/$s"
+    /bin/cp "$src/$s/run.ts" "$stage/$s/run.ts"
+  done
+  /bin/cp "$src/provision/provision.sh" "$stage/provision.sh"
+  /usr/bin/find "$stage" -type f -name '*.test.ts' -delete
+  printf '%s\n' "$version" > "$stage/VERSION"
+  hand_stage
+  as_specialist "$SWAP_WRAPPERS" "$node" "$stage" $SERVICES || fail "wrappers $version failed their check; ${current:-no} previous version kept"
+  echo "wrappers $version installed${current:+; previous $current}"
+}
+
+ROLLBACK_WRAPPERS='node=$1; shift
+bin="$HOME/.specialists/bin"; back="$HOME/.specialists/rollback/wrappers"
+[ -f "$back/VERSION" ] || { echo "no previous wrappers to roll back to" >&2; exit 1; }
+items="lib provision.sh VERSION $*"
+swap() { for i in $items; do
+  [ ! -e "$bin/$i" ] || mv "$bin/$i" "$bin/.old-$i"
+  [ ! -e "$back/$i" ] || mv "$back/$i" "$bin/$i"
+  [ ! -e "$bin/.old-$i" ] || mv "$bin/.old-$i" "$back/$i"
+done; }
+swap
+for s in "$@"; do
+  "$node" --disable-warning=ExperimentalWarning "$bin/$s/run.ts" --caller specialist-install -- --help >/dev/null 2>&1 || { swap; echo "$s --help failed; nothing changed" >&2; exit 1; }
+done
+cat "$bin/VERSION"'
+
+rollback_wrappers() {
+  node=$(current_node)
+  restored=$(as_specialist "$ROLLBACK_WRAPPERS" "$node" $SERVICES) || fail "wrapper rollback failed"
+  echo "wrappers $restored restored"
+}
+
+ARCANE_VERSION='out=$("$HOME/.specialists/bin/arcane-cli" --version 2>/dev/null) || exit 0
+printf "%s\n" "$out" | awk '"'"'{ for (i = 1; i < NF; i++) if ($i == "version") { print $(i + 1); exit } }'"'"''
+
+INSTALL_ARCANE='stage=$1; v=$2
+bin="$HOME/.specialists/bin"
+check() { "$1" --version 2>/dev/null | awk -v v="$v" '"'"'{ for (i = 1; i < NF; i++) if ($i == "version" && $(i + 1) == v) f = 1 } END { exit !f }'"'"'; }
+mkdir -p "$bin"
+cp "$stage/arcane-cli" "$bin/.arcane-cli.new"
+chmod 0700 "$bin/.arcane-cli.new"
+check "$bin/.arcane-cli.new" || { rm -f "$bin/.arcane-cli.new"; echo "the new arcane-cli does not report version $v" >&2; exit 1; }
+had=no
+if [ -e "$bin/arcane-cli" ]; then mv "$bin/arcane-cli" "$bin/arcane-cli.previous"; had=yes; fi
+mv "$bin/.arcane-cli.new" "$bin/arcane-cli"
+if ! check "$bin/arcane-cli"; then
+  rm -f "$bin/arcane-cli"
+  [ "$had" = no ] || mv "$bin/arcane-cli.previous" "$bin/arcane-cli"
+  echo "restored the previous arcane-cli" >&2
+  exit 1
+fi'
+
+install_arcane_cli() {
+  version=$1
+  current=$(as_specialist "$ARCANE_VERSION")
+  valid_version "$current" || current=""
+  if [ -n "$current" ] && version_lt "$version" "$current"; then fail "arcane-cli $version is older than the installed $current; use rollback"; fi
+
+  asset=arcane-cli_darwin_arm64.tar.gz
+  base="https://github.com/getarcaneapp/arcane/releases/download/v$version"
+  fetch "$base/$asset" "$work/$asset"
+  fetch "$base/arcane_${version}_checksums.txt" "$work/checksums.txt"
+  check_sha256 "$work" "$asset" "$work/checksums.txt"
+  /bin/mkdir "$work/acli"
+  /usr/bin/tar -xzf "$work/$asset" -C "$work/acli"
+  cli=$(/usr/bin/find "$work/acli" -type f -name arcane-cli | /usr/bin/head -n 1)
+  [ -n "$cli" ] || fail "no arcane-cli binary in $asset"
+  make_stage
+  /bin/cp "$cli" "$stage/arcane-cli"
+  hand_stage
+  as_specialist "$INSTALL_ARCANE" "$stage" "$version" || fail "arcane-cli $version failed its check"
+  echo "arcane-cli $version installed${current:+; previous $current}"
+}
+
+ROLLBACK_ARCANE='bin="$HOME/.specialists/bin"
+[ -e "$bin/arcane-cli.previous" ] || { echo "no previous arcane-cli to roll back to" >&2; exit 1; }
+mv "$bin/arcane-cli" "$bin/.arcane-cli.old"
+mv "$bin/arcane-cli.previous" "$bin/arcane-cli"
+mv "$bin/.arcane-cli.old" "$bin/arcane-cli.previous"
+"$bin/arcane-cli" --version'
+
+rollback_arcane_cli() {
+  out=$(as_specialist "$ROLLBACK_ARCANE") || fail "arcane-cli rollback failed"
+  echo "restored $out"
+}
+
+# trendarr lives in versioned directories behind the stable link bin/trendarr, so
+# media.json's trendarrCli path never changes; bin/trendarr.previous keeps the last one.
+TRENDARR_COMMON='bin="$HOME/.specialists/bin"
+cli() { printf "%s/node_modules/@astrofoundry/trendarr/dist/cli.js" "$1"; }
+version_of() { plutil -extract version raw -o - "$1/node_modules/@astrofoundry/trendarr/package.json" 2>/dev/null; }
+link() { rm -f "$bin/.$1.tmp"; ln -s "$2" "$bin/.$1.tmp"; mv -h "$bin/.$1.tmp" "$bin/$1"; }'
+
+TRENDARR_VERSION="$TRENDARR_COMMON"'
+[ -e "$bin/trendarr" ] || exit 0
+version_of "$bin/trendarr" || exit 0'
+
+# A hand-installed bin/trendarr directory (the first media setup) becomes trendarr-<version>
+# behind the link; one without a readable package moves aside to bin/trendarr.unknown.
+INSTALL_TRENDARR="$TRENDARR_COMMON"'
+node=$1; npm=$2; v=$3
+if [ -d "$bin/trendarr" ] && [ ! -L "$bin/trendarr" ]; then
+  old=$(version_of "$bin/trendarr" || true)
+  case "$old" in
+    "" | *[!0-9.]*) rm -rf "$bin/trendarr.unknown"; mv "$bin/trendarr" "$bin/trendarr.unknown" ;;
+    *) rm -rf "$bin/trendarr-$old"; mv "$bin/trendarr" "$bin/trendarr-$old"; link trendarr "trendarr-$old" ;;
+  esac
+fi
+dir="$bin/trendarr-$v"
+mkdir -p "$bin"
+rm -rf "$dir.partial"
+"$node" "$npm" install --prefix "$dir.partial" --omit=dev --ignore-scripts --no-audit --no-fund --no-update-notifier "@astrofoundry/trendarr@$v" >/dev/null
+[ "$("$node" "$(cli "$dir.partial")" --version)" = "$v" ] || { rm -rf "$dir.partial"; echo "trendarr $v does not report its version" >&2; exit 1; }
+before=$(readlink "$bin/trendarr" 2>/dev/null || true)
+rm -rf "$dir"
+mv "$dir.partial" "$dir"
+link trendarr "trendarr-$v"
+if [ "$("$node" "$(cli "$bin/trendarr")" --version)" != "$v" ]; then
+  if [ -n "$before" ]; then link trendarr "$before"; else rm -f "$bin/trendarr"; fi
+  echo "restored the previous trendarr" >&2
+  exit 1
+fi
+if [ -n "$before" ] && [ "$before" != "trendarr-$v" ]; then link trendarr.previous "$before"; fi
+keep=$(readlink "$bin/trendarr.previous" 2>/dev/null || true)
+for d in "$bin"/trendarr-*; do
+  [ -d "$d" ] || continue
+  n=${d##*/}
+  [ "$n" = "trendarr-$v" ] || [ "$n" = "$keep" ] || rm -rf "$d"
+done'
+
+install_trendarr() {
+  version=$1
+  node=$(current_node)
+  npm="${node%/bin/node}/lib/node_modules/npm/bin/npm-cli.js"
+  [ -f "$npm" ] || fail "the specialist Node has no npm"
+  current=$(as_specialist "$TRENDARR_VERSION")
+  valid_version "$current" || current=""
+  if [ -n "$current" ] && version_lt "$version" "$current"; then fail "trendarr $version is older than the installed $current; use rollback"; fi
+  [ "$current" != "$version" ] || { echo "trendarr $version is already current"; return 0; }
+  as_specialist "$INSTALL_TRENDARR" "$node" "$npm" "$version" || fail "trendarr $version failed its check"
+  echo "trendarr $version installed${current:+; previous $current}"
+}
+
+ROLLBACK_TRENDARR="$TRENDARR_COMMON"'
+node=$1
+previous=$(readlink "$bin/trendarr.previous" 2>/dev/null) || { echo "no previous trendarr to roll back to" >&2; exit 1; }
+current=$(readlink "$bin/trendarr")
+[ -d "$bin/$previous" ] || { echo "$previous is missing" >&2; exit 1; }
+link trendarr "$previous"
+link trendarr.previous "$current"
+"$node" "$(cli "$bin/trendarr")" --version'
+
+rollback_trendarr() {
+  node=$(current_node)
+  out=$(as_specialist "$ROLLBACK_TRENDARR" "$node") || fail "trendarr rollback failed"
+  echo "trendarr $out restored"
+}
+
+json_version() {
+  if valid_version "$1"; then printf '"%s"' "$1"; else printf 'null'; fi
+}
+
+status() {
+  wrappers=$(as_specialist "$WRAPPER_VERSION" || true)
+  arcane=$(as_specialist "$ARCANE_VERSION" || true)
+  trendarr=$(as_specialist "$TRENDARR_VERSION" || true)
+  printf '{"node":{"current":%s,"previous":%s},"wrappers":%s,"arcaneCli":%s,"trendarr":%s}\n' \
+    "$(json_version "$(node_link current)")" "$(json_version "$(node_link previous)")" \
+    "$(json_version "$wrappers")" "$(json_version "$arcane")" "$(json_version "$trendarr")"
+}
+
+case "$command" in
+  node) install_node "$2" ;;
+  wrappers) install_wrappers "$2" ;;
+  arcane-cli) install_arcane_cli "$2" ;;
+  trendarr) install_trendarr "$2" ;;
+  rollback)
+    case "$2" in
+      node) rollback_node ;;
+      wrappers) rollback_wrappers ;;
+      arcane-cli) rollback_arcane_cli ;;
+      trendarr) rollback_trendarr ;;
+    esac
+    ;;
+  status) status ;;
+esac

package/specialists/entry/specialist-install.test.ts

@@ -0,0 +1,95 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const SCRIPT = join(import.meta.dirname, "specialist-install.sh");
+const ENTRY = join(import.meta.dirname, "specialist-cli.sh");
+// As root the script would really install; these tests only exercise what runs before the root check.
+const isRoot = process.getuid?.() === 0;
+
+function install(...args: string[]) {
+    return spawnSync("/bin/sh", [SCRIPT, ...args], { encoding: "utf-8" });
+}
+
+/** Runs one shell function of the script on its own, followed by `call`. */
+function shellFunction(name: string, call: string) {
+    const match = new RegExp(`^${name}\\(\\) \\{\\n[\\s\\S]*?^\\}`, "m").exec(readFileSync(SCRIPT, "utf-8"));
+    if (!match) throw new Error(`${name} not found in the script`);
+    return spawnSync("/bin/sh", ["-c", `${match[0]}\n${call}`], { encoding: "utf-8" });
+}
+
+describe("specialist-install", () => {
+    it("parses as POSIX sh", () => {
+        expect(spawnSync("/bin/sh", ["-n", SCRIPT]).status).toBe(0);
+    });
+
+    it.each([
+        [[]],
+        [["upgrade", "1.2.3"]],
+        [["node"]],
+        [["node", "24.22"]],
+        [["node", "v24.22.0"]],
+        [["node", "024.22.0"]],
+        [["node", "24.22.0\nrm"]],
+        [["node", "24.22.0", "extra"]],
+        [["wrappers", "../../1.2.3"]],
+        [["arcane-cli", "2.16.1-beta"]],
+        [["trendarr", ""]],
+        [["rollback"]],
+        [["rollback", "pi"]],
+        [["rollback", "node", "extra"]],
+        [["status", "now"]],
+    ])("refuses %j with a usage error before anything else", (args) => {
+        const result = install(...args);
+        expect(result.status).toBe(2);
+        expect(result.stderr).toMatch(/^usage: specialist-install/);
+    });
+
+    it.skipIf(isRoot).each([[["node", "24.22.0"]], [["wrappers", "0.31.0"]], [["arcane-cli", "2.16.1"]], [["trendarr", "0.6.0"]], [["rollback", "trendarr"]], [["status"]]])(
+        "accepts %j and then requires root",
+        (args) => {
+            const result = install(...args);
+            expect(result.status).toBe(1);
+            expect(result.stderr).toContain("must run as root");
+        },
+    );
+
+    it.each(["0.0.0", "1.2.3", "24.22.0", "2.16.1", "100000.0.1"])("valid_version accepts %s", (v) => {
+        expect(shellFunction("valid_version", `valid_version '${v}'`).status).toBe(0);
+    });
+
+    it.each(["", "1.2", "1.2.3.4", "01.2.3", "1.2.3a", "-1.2.3", "1..3", "1000000.0.0"])("valid_version rejects %j", (v) => {
+        expect(shellFunction("valid_version", `valid_version '${v}'`).status).toBe(1);
+    });
+
+    it.each([
+        ["24.21.0", "24.22.0", true],
+        ["24.22.0", "24.22.0", false],
+        ["24.22.1", "24.22.0", false],
+        ["2.9.9", "2.16.1", true],
+        ["10.0.0", "9.99.99", false],
+        ["0.6.0", "0.31.0", true],
+    ])("version_lt %s < %s is %s", (a, b, older) => {
+        expect(shellFunction("version_lt", `version_lt ${a} ${b}`).status).toBe(older ? 0 : 1);
+    });
+
+    it("installs the same services specialist-cli accepts", () => {
+        const services = /^SERVICES="([^"]+)"$/m.exec(readFileSync(SCRIPT, "utf-8"))?.[1].split(" ");
+        const allowed = /^ {2}([a-z|]+)\) ;;$/m.exec(readFileSync(ENTRY, "utf-8"))?.[1].split("|");
+        expect(services).toBeDefined();
+        expect(services).toEqual(allowed);
+    });
+
+    it("never runs Homebrew binaries", () => {
+        expect(readFileSync(SCRIPT, "utf-8")).not.toContain("/opt/homebrew");
+    });
+});
+
+describe("specialist-cli", () => {
+    it("runs the wrappers with the root-owned Node only", () => {
+        const text = readFileSync(ENTRY, "utf-8");
+        expect(text).toContain("exec /usr/local/libexec/specialist-node/current/bin/node ");
+        expect(text).not.toContain("/opt/homebrew/bin/node");
+    });
+});