@astrofoundry/pi-astro 0.26.4 → 0.27.0

package/agents/arcane.md

@@ -19,5 +19,6 @@ Rules:
 - Operational actions (restart, logs, stats, redeploy, image pull, prune) go straight through the CLI.
 - Confirm destructive operations (`down`, `delete`, `prune`) are explicitly requested in the task before running them.
 - Updating Arcane itself is a hand-over: do the repository change and the sync, then end with the exact hand-over block from the skill (numbered host steps, digests, rollback). Never run `system upgrade` or `projects upgrade arcane`.
+- For update questions run `update-report` and answer with its table verbatim in a code block; never answer from `projects updates`, which is stored and paginated.
 - Report facts from the JSON output. Sensitive fields are already removed; never guess at what was removed.
 - Delegate through `subagent` only to another specialist (`astro.identity`, `astro.network`, `astro.dns`, `astro.edge`, `astro.security`, `astro.backup`, `astro.proxmox`, `astro.inference`) and only for that specialist's own area.

package/package.json

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

package/skills/arcane/SKILL.md

@@ -27,13 +27,26 @@ Arcane manages the Docker host on VM 100 (`10.0.40.30`). Every app is a Compose
 
 The full `arcane-cli` is available. The tool refuses only `config`, `auth`, `self-update`, `completion`, which would change its own setup.
 
+## Available updates
+
+For any question about updates (what can be updated, which versions, is a stack current), run `["update-report"]`, or `["update-report", "--all"]` when the caller wants every service listed. It runs a fresh registry check of every image, maps each image to its stack and service, and reads release versions from the registries. It never pulls an image or redeploys anything. Do not answer update questions from `projects updates` or `images updates summary`: they return stored results from Arcane's last scheduled check, 20 projects per page.
+
+The output is JSON with `counts`, `rows`, and `table`. Answer with the `table` field verbatim inside a code block, then add anything the caller asked about. Do not rebuild or reorder the table.
+
+- `Running` and `Latest` are release tags. `older build`: the running build carries no tag any more. `new build`: no release tag names the newer build. `17 (older build)`: the running build of that major series is no longer tagged.
+- `Update`: `pull` means redeploying the stack with an image pull applies it; `edit tag` means changing the tag in the GitOps repository; `edit digest` means changing the pinned digest in the repository (`latestDigest` in the row holds it); `unknown` has its reason in the notes under the table.
+- A note "major version change" or "newer major ... available" means the update crosses a major version: say so, and apply it only on the caller's explicit go after they have read the release notes.
+- Rows marked private have no version data because the registry needs credentials; their digest result from Arcane still stands.
+
+Apply updates only when asked, one stack at a time, through the operations or GitOps procedure above, and run `update-report` again afterwards to show the result.
+
 ## Updating Arcane itself
 
 The `arcane` project is GitOps-managed and pinned by digest (`ghcr.io/getarcaneapp/manager@sha256:...`). The manager cannot recreate its own container, so the update is a hand-over: you do the repository and sync work, then give the caller exact steps for VM 100 and verify afterwards. Never use `["system", "upgrade"]` or `["projects", "upgrade", "arcane"]` for the manager; both bypass the pinned digest in the repository.
 
 Procedure, in this order:
 
-1. Facts: `["version"]` (running version and digest), `["projects", "updates"]` (new digest, if any). If there is no update, report that and stop.
+1. Facts: `["version"]` (running version and digest), then `["update-report"]`: the `arcane` row shows the running and latest release and, for an update, `latestDigest`. If the row is not an update, report that and stop.
 2. Repository: `git pull`, `git show arcane/compose.yaml`, `git write arcane/compose.yaml <file with the new digest, nothing else changed>`, `git diff`, `git commit "Update Arcane manager to <version>"`, `git push`.
 3. Sync: `["gitops", "sync", "arcane", "--yes"]`, then `["gitops", "status", "arcane"]` until the last synced commit is yours. This updates `/opt/docker/arcane/compose.yaml` on VM 100; the container keeps running the old image.
 4. Hand over. End your answer with exactly this block, values filled in:

package/specialists/AGENTS.md

@@ -53,6 +53,8 @@ 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.
+- `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 keep Arcane's digest result without versions. The table is fixed-width text for a code block, because Discord renders no Markdown tables.
 
 ## Gate
 

package/specialists/README.md

@@ -4,7 +4,7 @@ A specialist is a Pi subagent that is the only way to operate one area of the ho
 
 | Agent | Area | What it can do |
 |---|---|---|
-| `astro.arcane` | Arcane container platform (VM 100) and its GitOps repository | Every `arcane-cli` operation except its own `config`, `auth`, `self-update`; Compose changes of GitOps-managed projects through `git show|write|commit|push`, then `arcane-cli gitops` sync |
+| `astro.arcane` | Arcane container platform (VM 100) and its GitOps repository | Every `arcane-cli` operation except its own `config`, `auth`, `self-update`; `update-report` (fresh check of every stack with running and latest release versions); Compose changes of GitOps-managed projects through `git show|write|commit|push`, then `arcane-cli gitops` sync |
 | `astro.identity` | Zitadel; Pomerium, nginx, lego on VM 104; `02-pulsar-proxmox/dmz/` in the homelab repository | Any Zitadel API call (v2, management, admin, auth) with responses redacted; `dmz status|journal|config-template|render|pomerium-restart|nginx-reload|lego-renew|deploy-config`; `git` on the homelab checkout, writes limited to `02-pulsar-proxmox/dmz/` |
 | `astro.network` | UniFi, FreeRADIUS (LXC 108), Tailscale (LXC 105) | Read UniFi sites, devices, clients, networks, zones, firewall policies, WANs; create, update, delete firewall policies; RADIUS and Tailscale checks on Pulsar |
 | `astro.dns` | Technitium primary (Synapse) and secondary (LXC 107); Cloudflare zones `37pla.net`, `monadeo.com` | Read zones and records on both resolvers, resolve, stats; create and delete zones, add, update, delete records on the primary; Cloudflare zones and record add, update, delete |

package/specialists/arcane/run.ts

@@ -4,8 +4,10 @@ import { dirname, join } from "node:path";
 import { readConfig } from "../lib/config.ts";
 import { ServiceError, UsageError } from "../lib/errors.ts";
 import { main } from "../lib/main.ts";
-import { printRaw } from "../lib/output.ts";
+import { buildUpdateReport } from "../lib/image-updates.ts";
+import { printJson, printRaw } from "../lib/output.ts";
 import { run } from "../lib/proc.ts";
+import { HttpRegistry } from "../lib/registry.ts";
 import { REPO_HELP, repoCommand, type RepoSpec } from "../lib/repo.ts";
 import { ARCANE_DENIED_KEYS, filterJsonText, stripKeys } from "../lib/sanitize.ts";
 import { readSecret } from "../lib/secrets.ts";
@@ -66,6 +68,9 @@ const HELP = `arcane specialist
 
   <arcane-cli args...>        run arcane-cli with a fresh federated token; JSON output, sensitive fields removed
                               (arcane-cli gitops ... manages the server-side syncs)
+  update-report [--all]       fresh image update check for every stack, with running and latest release versions
+                              from the registries; JSON with a ready table (--all also lists up-to-date services).
+                              Checks only: never pulls images or redeploys.
 ${REPO_HELP}
 Refused: ${REFUSED_PREFIXES.join(", ")}. GitOps-managed projects (gitOpsManagedBy set) change in the repository, then sync.`;
 
@@ -122,25 +127,56 @@ function writeCallConfig(config: ArcaneConfig, token: string): string {
     return file;
 }
 
-async function passthrough(config: ArcaneConfig, args: string[]): Promise<number> {
-    const refused = refusedPrefix(args);
-    if (refused) throw new UsageError(`"${refused}" is refused by the wrapper`);
+type Cli = (args: string[]) => Promise<{ stdout: string; stderr: string; code: number }>;
+
+/** One federated token and one private config copy for every arcane-cli call of this invocation. */
+async function withCli<T>(config: ArcaneConfig, fn: (cli: Cli) => Promise<T>): Promise<T> {
     const token = await federatedToken(config);
     const callConfig = writeCallConfig(config, token);
     try {
+        return await fn((args) => run(config.arcaneCli, ["--config", callConfig, "--no-color", ...args], { env: { ARCANE_TOKEN: token }, timeoutMs: TIMEOUT_MS }));
+    } finally {
+        rmSync(dirname(callConfig), { recursive: true, force: true });
+    }
+}
+
+async function passthrough(config: ArcaneConfig, args: string[]): Promise<number> {
+    const refused = refusedPrefix(args);
+    if (refused) throw new UsageError(`"${refused}" is refused by the wrapper`);
+    return withCli(config, async (cli) => {
         const wantsJson = args.includes("--json") || args.includes("--output");
-        const cliArgs = ["--config", callConfig, ...(wantsJson ? [] : ["--output", "json"]), "--no-color", ...args];
-        const result = await run(config.arcaneCli, cliArgs, { env: { ARCANE_TOKEN: token }, timeoutMs: TIMEOUT_MS });
+        const result = await cli([...(wantsJson ? [] : ["--output", "json"]), ...args]);
         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;
-    } finally {
-        rmSync(dirname(callConfig), { recursive: true, force: true });
+    });
+}
+
+async function cliJson(cli: Cli, args: string[]): Promise<unknown> {
+    const result = await cli(["--output", "json", ...args]);
+    if (result.code !== 0) throw new ServiceError(`${args.join(" ")}: ${result.stderr.trim() || `exited ${result.code}`}`);
+    try {
+        return JSON.parse(result.stdout);
+    } catch {
+        throw new ServiceError(`${args.join(" ")}: output is not JSON`);
     }
 }
 
+/** A fresh registry check first, then the stack list, so every result the report uses is from this run. */
+async function updateReport(config: ArcaneConfig, args: string[]): Promise<number> {
+    const extra = args.filter((a) => a !== "--all");
+    if (extra.length > 0) throw new UsageError(`update-report takes only --all, got: ${extra.join(" ")}`);
+    const startedAt = Date.now();
+    return withCli(config, async (cli) => {
+        const check = await cliJson(cli, ["images", "updates", "check", "--all"]);
+        const projects = await cliJson(cli, ["projects", "list", "--all"]);
+        printJson(await buildUpdateReport({ check, projects, registry: new HttpRegistry(), startedAt, all: args.includes("--all") }));
+        return 0;
+    });
+}
+
 export async function command(args: string[]): Promise<number> {
     if (args.length === 0 || args[0] === "--help" || args[0] === "help") {
         printRaw(HELP);
@@ -148,6 +184,7 @@ export async function command(args: string[]): Promise<number> {
     }
     const config = readConfig<ArcaneConfig>(SERVICE, SHAPE);
     if (args[0] === "git") return repoCommand(repoSpec(config), args.slice(1));
+    if (args[0] === "update-report") return updateReport(config, args.slice(1));
     return passthrough(config, args);
 }
 

package/specialists/lib/flush.test.ts

@@ -0,0 +1,21 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+describe("main output on a pipe", () => {
+    it("delivers output larger than the pipe buffer before exiting", () => {
+        const dir = mkdtempSync(join(tmpdir(), "astro-flush-"));
+        try {
+            const script = join(dir, "big.ts");
+            const mainPath = join(import.meta.dirname, "main.ts");
+            writeFileSync(script, `import { main } from ${JSON.stringify(mainPath)};\nawait main("test", async () => { process.stdout.write("x".repeat(300_000)); return 0; }, ["--caller", "t", "--", "go"]);\n`);
+            const result = spawnSync(process.execPath, ["--disable-warning=ExperimentalWarning", script], { env: { ...process.env, HOME: dir }, maxBuffer: 10_000_000 });
+            expect(result.stdout.length).toBe(300_000);
+            expect(result.status).toBe(0);
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});

package/specialists/lib/image-updates.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, it } from "vitest";
+import { buildUpdateReport, cachingRegistry, checkEntries, classify, compareVersions, parseTag, releaseCandidates, resolveRef, stackServices, type CheckEntry } from "./image-updates.ts";
+import { HttpRegistry, nextLink, parseChallenge, parseImageRef, RegistryError, type ImageRef, type Registry } from "./registry.ts";
+
+const NOW = Date.parse("2026-09-25T18:30:00Z");
+const FRESH = "2026-09-25T18:30:05Z";
+
+/** Registry double: tags and digests per repository, errors for private ones. */
+class FakeRegistry implements Registry {
+    heads = 0;
+    private readonly repos: Record<string, { tags: string[]; digests: Record<string, string> } | "private">;
+    constructor(repos: Record<string, { tags: string[]; digests: Record<string, string> } | "private">) {
+        this.repos = repos;
+    }
+    async tags(ref: ImageRef): Promise<string[]> {
+        const repo = this.repos[ref.repository];
+        if (repo === undefined || repo === "private") throw new RegistryError(`${ref.repository}: private or not found`, 401);
+        return repo.tags;
+    }
+    async digest(ref: ImageRef, tag: string): Promise<string | null> {
+        this.heads++;
+        const repo = this.repos[ref.repository];
+        return repo && repo !== "private" ? (repo.digests[tag] ?? null) : null;
+    }
+}
+
+const entry = (current: string, latest: string, extra: Partial<CheckEntry> = {}): CheckEntry => ({ checkTime: FRESH, currentDigest: current, latestDigest: latest, hasUpdate: current !== latest, currentVersion: "", ...extra });
+
+describe("image references and tags", () => {
+    it("parses references the way Docker resolves them", () => {
+        expect(parseImageRef("nginx:1.31.4-alpine")).toEqual({ registry: "docker.io", repository: "library/nginx", tag: "1.31.4-alpine", digest: null });
+        expect(parseImageRef("lscr.io/linuxserver/prowlarr:latest")).toEqual({ registry: "lscr.io", repository: "linuxserver/prowlarr", tag: "latest", digest: null });
+        expect(parseImageRef("ghcr.io/getarcaneapp/manager@sha256:abc")).toEqual({ registry: "ghcr.io", repository: "getarcaneapp/manager", tag: null, digest: "sha256:abc" });
+        expect(parseImageRef("localhost:5000/tool")).toEqual({ registry: "localhost:5000", repository: "tool", tag: "latest", digest: null });
+        expect(parseImageRef("recyclarr/recyclarr:8")).toMatchObject({ registry: "docker.io", repository: "recyclarr/recyclarr", tag: "8" });
+    });
+
+    it("reads release tags and orders them", () => {
+        expect(parseTag("v2.197.0")).toEqual({ tag: "v2.197.0", prefix: "v", nums: [2, 197, 0], suffix: "" });
+        expect(parseTag("2.0.5.5160-ls123")).toMatchObject({ nums: [2, 0, 5, 5160], suffix: "-ls123" });
+        expect(parseTag("latest")).toBeNull();
+        expect(parseTag("1.0.0-rc1")).toBeNull();
+        expect(parseTag("nightly-20260901")).toBeNull();
+        expect(compareVersions(parseTag("1.2.0-ls124")!, parseTag("1.2.0-ls123")!)).toBeGreaterThan(0);
+        expect(compareVersions(parseTag("1.10.0")!, parseTag("1.9.9")!)).toBeGreaterThan(0);
+        expect(classify(parseImageRef("postgres:18"))).toBe("series");
+        expect(classify(parseImageRef("nginx:1.31.4-alpine"))).toBe("fixed");
+        expect(classify(parseImageRef("syncthing/syncthing"))).toBe("floating");
+        expect(classify(parseImageRef("x@sha256:1"))).toBe("pinned");
+    });
+
+    it("prefers plain versions and falls back to the dominant release shape", () => {
+        const tags = ["1.2.0", "1.3.0", "1.3.0-fat", "1.4.0-rc1"].map(parseTag).filter((t) => t !== null);
+        expect(releaseCandidates(tags).map((t) => t.tag)).toEqual(["1.3.0", "1.2.0"]);
+        const ls = ["2.0.5.5160-ls123", "2.1.0.5190-ls124", "1.0-armhf"].map(parseTag).filter((t) => t !== null);
+        expect(releaseCandidates(ls).map((t) => t.tag)).toEqual(["2.1.0.5190-ls124", "2.0.5.5160-ls123"]);
+    });
+});
+
+describe("resolveRef", () => {
+    const registry = new FakeRegistry({
+        "linuxserver/prowlarr": { tags: ["2.0.4.5100-ls120", "2.0.5.5160-ls123", "2.1.0.5190-ls124", "develop-2.1", "nightly"], digests: { "2.1.0.5190-ls124": "D2", "2.0.5.5160-ls123": "D1" } },
+        "library/postgres": { tags: ["17", "17.5", "17.6", "17.6-alpine", "18", "18.0"], digests: { "17.6": "P2", "17.5": "P1" } },
+        "supabase/gotrue": { tags: ["v2.196.0", "v2.197.0", "v2.199.1", "v2.200.0-rc1"], digests: {} },
+        "library/nginx": { tags: ["1.31.4-alpine"], digests: {} },
+        "getarcaneapp/manager": { tags: ["v1.2.0", "v1.3.0", "latest"], digests: { "v1.3.0": "sha256:new", "v1.2.0": "sha256:old" } },
+        "astrofoundry/app": "private",
+    });
+
+    it("resolves a floating tag to the release versions behind both digests", async () => {
+        expect(await resolveRef("lscr.io/linuxserver/prowlarr:latest", entry("D1", "D2"), registry, NOW)).toMatchObject({ kind: "floating", running: "2.0.5.5160-ls123", latest: "2.1.0.5190-ls124", status: "update", action: "pull" });
+    });
+
+    it("finds an older build under a more specific tag and flags a major jump", async () => {
+        const ls = new FakeRegistry({
+            "linuxserver/radarr": { tags: ["6.4.4", "6.4.4.10050-ls300", "6.4.2.10000-ls299", "6.4.2"], digests: { "6.4.4": "R2", "6.4.4.10050-ls300": "R2", "6.4.2.10000-ls299": "R1", "6.4.2": "R0" } },
+            "stirlingtools/stirling-pdf": { tags: ["2.14.3", "3.0.0"], digests: { "3.0.0": "S2", "2.14.3": "S1" } },
+        });
+        expect(await resolveRef("lscr.io/linuxserver/radarr:latest", entry("R1", "R2"), ls, NOW)).toMatchObject({ running: "6.4.2.10000-ls299", latest: "6.4.4.10050-ls300", note: "" });
+        expect(await resolveRef("stirlingtools/stirling-pdf:latest", entry("S1", "S2"), ls, NOW)).toMatchObject({ running: "2.14.3", latest: "3.0.0", note: expect.stringContaining("major version change") });
+    });
+
+    it("stays inside a major series and names a newer major", async () => {
+        expect(await resolveRef("postgres:17", entry("P1", "P2"), registry, NOW)).toMatchObject({ kind: "series", running: "17.5", latest: "17.6", status: "update", note: "newer major 18 available (tag change)" });
+    });
+
+    it("finds a newer release for a fixed tag and a rebuild when there is none", async () => {
+        expect(await resolveRef("supabase/gotrue:v2.197.0", entry("G", "G"), registry, NOW)).toMatchObject({ running: "v2.197.0", latest: "v2.199.1", status: "release", action: "edit tag" });
+        expect(await resolveRef("nginx:1.31.4-alpine", entry("N1", "N2"), registry, NOW)).toMatchObject({ status: "rebuild", action: "pull", latest: "1.31.4-alpine" });
+        expect(await resolveRef("nginx:1.31.4-alpine", entry("N1", "N1"), registry, NOW)).toMatchObject({ status: "up-to-date" });
+    });
+
+    it("compares a digest pin with the newest release", async () => {
+        expect(await resolveRef("ghcr.io/getarcaneapp/manager@sha256:old", undefined, registry, NOW)).toMatchObject({ kind: "pinned", running: "v1.2.0", latest: "v1.3.0", status: "update", action: "edit digest", latestDigest: "sha256:new" });
+        expect(await resolveRef("ghcr.io/getarcaneapp/manager@sha256:new", undefined, registry, NOW)).toMatchObject({ running: "v1.3.0", status: "up-to-date" });
+    });
+
+    it("falls back to the digest result for private images and marks bad checks unknown", async () => {
+        expect(await resolveRef("ghcr.io/astrofoundry/app:main", entry("A1", "A2"), registry, NOW)).toMatchObject({ status: "update", latest: "new build", note: "versions unavailable: private image, the registry needs credentials" });
+        expect(await resolveRef("nginx:1.31.4-alpine", undefined, registry, NOW)).toMatchObject({ status: "unknown", note: "not in the fresh check" });
+        expect(await resolveRef("nginx:1.31.4-alpine", entry("N", "N", { checkTime: "2026-09-24T00:00:00Z" }), registry, NOW)).toMatchObject({ status: "unknown", note: expect.stringContaining("stale") });
+        expect(await resolveRef("nginx:1.31.4-alpine", entry("N", "N", { error: "timeout" }), registry, NOW)).toMatchObject({ status: "unknown", note: "check failed: timeout" });
+    });
+});
+
+describe("buildUpdateReport", () => {
+    it("lists updates per stack service and renders a table", async () => {
+        const registry = new FakeRegistry({
+            "linuxserver/prowlarr": { tags: ["2.0.5.5160-ls123", "2.1.0.5190-ls124"], digests: { "2.1.0.5190-ls124": "D2", "2.0.5.5160-ls123": "D1" } },
+            "library/nginx": { tags: ["1.31.4-alpine"], digests: {} },
+            "library/busybox": { tags: ["1.37.0"], digests: { "1.37.0": "B" } },
+        });
+        const projects = {
+            data: [
+                { name: "media", status: "running", updateInfo: { serviceUpdates: { prowlarr: { imageRef: "lscr.io/linuxserver/prowlarr:latest" } } } },
+                { name: "profiles", status: "running", updateInfo: { serviceUpdates: { profiles: { imageRef: "nginx:1.31.4-alpine" } } } },
+                { name: "canary", status: "stopped", updateInfo: { serviceUpdates: { canary: { imageRef: "busybox:latest" } } } },
+                { name: "empty", status: "running" },
+            ],
+        };
+        const check = {
+            "lscr.io/linuxserver/prowlarr:latest": entry("D1", "D2"),
+            "nginx:1.31.4-alpine": entry("N", "N"),
+            "busybox:latest": entry("B", "B"),
+        };
+        const report = await buildUpdateReport({ check, projects, registry, startedAt: NOW, all: false });
+        expect(report.counts).toEqual({ update: 1, release: 0, rebuild: 0, unknown: 1, "up-to-date": 2 });
+        expect(report.rows.map((r) => `${r.stack}/${r.service}:${r.status}`)).toEqual(["media/prowlarr:update", "empty/empty:unknown"]);
+        expect(report.table).toMatch(/^Fresh check 2026-09-25T18:30:00Z: 4 services in 4 stacks, 3 images\./);
+        expect(report.table).toContain("media/prowlarr  prowlarr  2.0.5.5160-ls123  2.1.0.5190-ls124  pull");
+        expect(report.table).toContain("* empty: Arcane lists no images for this stack");
+        const all = await buildUpdateReport({ check, projects, registry, startedAt: NOW, all: true });
+        expect(all.rows).toHaveLength(4);
+        expect(all.table).toContain("* canary: stack is stopped");
+    });
+
+    it("fetches each repository's tags once", async () => {
+        let lists = 0;
+        const inner: Registry = {
+            tags: async () => {
+                lists++;
+                return ["17.1", "18.1"];
+            },
+            digest: async () => null,
+        };
+        const registry = cachingRegistry(inner);
+        await Promise.all([registry.tags(parseImageRef("postgres:17")), registry.tags(parseImageRef("postgres:18"))]);
+        expect(lists).toBe(1);
+    });
+
+    it("reads Arcane's envelopes", () => {
+        expect(Object.keys(checkEntries({ data: { "a:1": { hasUpdate: false } } }))).toEqual(["a:1"]);
+        expect(Object.keys(checkEntries({ "a:1": { hasUpdate: true }, success: true }))).toEqual(["a:1"]);
+        expect(stackServices({ data: "nope" })).toEqual([]);
+    });
+});
+
+describe("HttpRegistry", () => {
+    it("follows the bearer challenge, paginates tags, and reads digests by HEAD", async () => {
+        const calls: string[] = [];
+        const fetchImpl = (async (input: string | URL | Request, init?: RequestInit) => {
+            const url = String(input);
+            const auth = (init?.headers as Record<string, string> | undefined)?.authorization;
+            calls.push(`${init?.method ?? "GET"} ${url}${auth ? " +auth" : ""}`);
+            if (url.startsWith("https://auth.example/token")) return new Response(JSON.stringify({ token: "t1" }), { status: 200 });
+            if (!auth) return new Response("", { status: 401, headers: { "www-authenticate": 'Bearer realm="https://auth.example/token",service="reg",scope="repository:library/nginx:pull"' } });
+            if (url.includes("/tags/list?n=1000")) return new Response(JSON.stringify({ tags: ["1.0"] }), { status: 200, headers: { link: '</v2/library/nginx/tags/list?last=1.0&n=1000>; rel="next"' } });
+            if (url.includes("/tags/list?last=1.0")) return new Response(JSON.stringify({ tags: ["1.1"] }), { status: 200 });
+            if (url.endsWith("/manifests/1.1")) return new Response(null, { status: 200, headers: { "docker-content-digest": "sha256:abc" } });
+            if (url.endsWith("/manifests/9.9")) return new Response(null, { status: 404 });
+            if (url.endsWith("/manifests/busy")) return new Response(null, { status: 429 });
+            return new Response("", { status: 500 });
+        }) as typeof fetch;
+        const registry = new HttpRegistry(fetchImpl);
+        const ref = parseImageRef("nginx:1.1");
+        expect(await registry.tags(ref)).toEqual(["1.0", "1.1"]);
+        expect(await registry.digest(ref, "1.1")).toBe("sha256:abc");
+        expect(await registry.digest(ref, "9.9")).toBeNull();
+        await expect(registry.digest(ref, "busy")).rejects.toThrow(/rate limited/);
+        expect(calls.filter((c) => c.startsWith("GET https://auth.example/token"))).toHaveLength(1);
+        expect(calls[0]).toBe("GET https://registry-1.docker.io/v2/library/nginx/tags/list?n=1000");
+    });
+
+    it("parses challenges and link headers", () => {
+        expect(parseChallenge('Bearer realm="https://ghcr.io/token",service="ghcr.io",scope="repository:a/b:pull"')).toEqual({ realm: "https://ghcr.io/token", service: "ghcr.io", scope: "repository:a/b:pull" });
+        expect(parseChallenge("Basic realm=x")).toBeNull();
+        expect(nextLink('</v2/a/tags/list?last=x&n=100>; rel="next"')).toBe("/v2/a/tags/list?last=x&n=100");
+        expect(nextLink(null)).toBeNull();
+    });
+});

package/specialists/lib/image-updates.ts

@@ -0,0 +1,366 @@
+import { parseImageRef, RegistryError, type ImageRef, type Registry } from "./registry.ts";
+
+/** One entry of `arcane-cli images updates check --all --json`, keyed by image reference. */
+export interface CheckEntry {
+    checkTime?: string;
+    currentVersion?: string;
+    currentDigest?: string;
+    latestDigest?: string;
+    hasUpdate?: boolean;
+    error?: string;
+}
+
+/** How the image reference in the Compose file moves: never (pinned), with its tag (floating, series), or only by editing it (fixed). */
+export type RefKind = "floating" | "series" | "fixed" | "pinned";
+export type UpdateStatus = "update" | "release" | "rebuild" | "up-to-date" | "unknown";
+
+export interface UpdateRow {
+    stack: string;
+    service: string;
+    ref: string;
+    image: string;
+    kind: RefKind;
+    running: string;
+    latest: string;
+    status: UpdateStatus;
+    /** What applying the update means: "pull" (redeploy with a pull) or "edit tag" / "edit digest" in the GitOps repository. */
+    action: string;
+    note: string;
+    /** For `edit digest` rows: the manifest digest of the latest release, to write into the Compose file. */
+    latestDigest?: string;
+}
+
+export interface UpdateReport {
+    checkedAt: string;
+    stacks: number;
+    images: number;
+    counts: Record<UpdateStatus, number>;
+    rows: UpdateRow[];
+    table: string;
+}
+
+export interface TagVersion {
+    tag: string;
+    prefix: string;
+    nums: number[];
+    suffix: string;
+}
+
+const PRERELEASE = /alpha|beta|rc|dev|nightly|develop|preview|test|snapshot|canary|edge|unstable|pr-/i;
+/** Registry lookups per image reference; enough to walk back a few weeks of releases. */
+const DIGEST_BUDGET = 30;
+const CONCURRENCY = 8;
+/** Tags searched per release shape when matching a digest; the newest builds come first. */
+const PER_SHAPE = 10;
+
+/** A tag that reads as a release version: optional `v`, dotted numbers, optional suffix such as `-alpine` or `-ls123`. */
+export function parseTag(tag: string): TagVersion | null {
+    const m = /^(v?)(\d+(?:\.\d+)*)([-_+.][A-Za-z0-9._+-]*)?$/.exec(tag);
+    if (!m) return null;
+    const suffix = m[3] ?? "";
+    if (PRERELEASE.test(suffix)) return null;
+    return { tag, prefix: m[1], nums: m[2].split(".").map(Number), suffix };
+}
+
+function suffixShape(t: TagVersion): string {
+    return t.suffix.replace(/\d+/g, "#");
+}
+
+/** Tags of one release line compare with each other: same prefix, number count, and suffix apart from its digits. */
+export function shapeKey(t: TagVersion): string {
+    return `${t.prefix}|${t.nums.length}|${suffixShape(t)}`;
+}
+
+export function compareVersions(a: TagVersion, b: TagVersion): number {
+    const n = Math.max(a.nums.length, b.nums.length);
+    for (let i = 0; i < n; i++) {
+        const d = (a.nums[i] ?? -1) - (b.nums[i] ?? -1);
+        if (d !== 0) return d;
+    }
+    const sa = Number(/(\d+)$/.exec(a.suffix)?.[1] ?? -1);
+    const sb = Number(/(\d+)$/.exec(b.suffix)?.[1] ?? -1);
+    return sa - sb;
+}
+
+const byVersionDesc = (a: TagVersion, b: TagVersion) => compareVersions(b, a);
+
+export function classify(ref: ImageRef): RefKind {
+    if (ref.digest) return "pinned";
+    const v = ref.tag ? parseTag(ref.tag) : null;
+    if (!v) return "floating";
+    return v.nums.length === 1 ? "series" : "fixed";
+}
+
+/** Release tags a floating tag such as `latest` can resolve to: plain versions when the image has them, else its most common release shape. */
+export function releaseCandidates(tags: TagVersion[]): TagVersion[] {
+    const multi = tags.filter((t) => t.nums.length >= 2);
+    const plain = multi.filter((t) => t.suffix === "");
+    let pool = plain;
+    if (pool.length === 0) {
+        const counts = new Map<string, number>();
+        for (const t of multi) counts.set(shapeKey(t), (counts.get(shapeKey(t)) ?? 0) + 1);
+        const dominant = [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
+        pool = multi.filter((t) => shapeKey(t) === dominant);
+    }
+    return [...pool].sort(byVersionDesc);
+}
+
+/**
+ * Order for matching a digest to a tag: the newest few of each release shape,
+ * the preferred shape first. An older build often survives only under a more
+ * specific tag (linuxserver's `-ls129`) once the plain version tag moved on.
+ */
+export function searchOrder(preferred: TagVersion[], all: TagVersion[]): TagVersion[] {
+    const byShape = new Map<string, TagVersion[]>();
+    for (const t of all.filter((t) => t.nums.length >= 2)) {
+        const list = byShape.get(shapeKey(t)) ?? [];
+        list.push(t);
+        byShape.set(shapeKey(t), list);
+    }
+    const shapes = [...byShape.entries()].sort((a, b) => b[1].length - a[1].length).slice(0, 3);
+    const seen = new Set<string>();
+    const out: TagVersion[] = [];
+    for (const t of [...preferred.slice(0, PER_SHAPE), ...shapes.flatMap(([, list]) => [...list].sort(byVersionDesc).slice(0, PER_SHAPE))]) {
+        if (!seen.has(t.tag)) {
+            seen.add(t.tag);
+            out.push(t);
+        }
+    }
+    return out;
+}
+
+function majorChange(running: string, latest: string): boolean {
+    const a = parseTag(running);
+    const b = parseTag(latest);
+    return a !== null && b !== null && b.nums[0] > a.nums[0];
+}
+
+function shortImage(ref: ImageRef): string {
+    return ref.repository.split("/").pop() ?? ref.repository;
+}
+
+function meaningfulVersion(value: string | undefined): string | null {
+    return value && value !== "latest" ? value : null;
+}
+
+interface Resolution {
+    running: string;
+    latest: string;
+    status: UpdateStatus;
+    action: string;
+    note: string;
+    latestDigest?: string;
+}
+
+/** Resolves one image reference to running and latest versions from the fresh check and the registry's tags. */
+export async function resolveRef(refText: string, entry: CheckEntry | undefined, registry: Registry, startedAt: number): Promise<Resolution & { kind: RefKind }> {
+    const ref = parseImageRef(refText);
+    const kind = classify(ref);
+    const unknown = (note: string, running = "?"): Resolution & { kind: RefKind } => ({ kind, running, latest: "?", status: "unknown", action: "", note });
+    if (kind !== "pinned") {
+        if (!entry) return unknown("not in the fresh check");
+        if (entry.error) return unknown(`check failed: ${entry.error}`);
+        const checked = entry.checkTime ? Date.parse(entry.checkTime) : Number.NaN;
+        if (Number.isNaN(checked) || checked < startedAt - 60_000) return unknown(`stale check from ${entry.checkTime ?? "an unknown time"}`);
+    }
+    const digestOnly = (reason: string): Resolution & { kind: RefKind } => {
+        if (kind === "pinned") return unknown(`pinned; versions unavailable: ${reason}`);
+        const running = (kind === "fixed" ? ref.tag : meaningfulVersion(entry?.currentVersion)) ?? "?";
+        if (!entry?.hasUpdate) return { kind, running, latest: running, status: "up-to-date", action: "", note: `versions unavailable: ${reason}` };
+        return { kind, running, latest: "new build", status: "update", action: "pull", note: `versions unavailable: ${reason}` };
+    };
+
+    let tags: TagVersion[];
+    try {
+        tags = (await registry.tags(ref)).map(parseTag).filter((t): t is TagVersion => t !== null);
+    } catch (err) {
+        const status = err instanceof RegistryError ? err.status : 0;
+        return digestOnly(status === 401 || status === 403 ? "private image, the registry needs credentials" : err instanceof Error ? err.message : String(err));
+    }
+
+    const digests = new Map<string, string | null>();
+    let budget = DIGEST_BUDGET;
+    const digestOf = async (tag: string): Promise<string | null> => {
+        if (digests.has(tag)) return digests.get(tag) ?? null;
+        if (budget <= 0) return null;
+        budget--;
+        const d = await registry.digest(ref, tag).catch(() => null);
+        digests.set(tag, d);
+        return d;
+    };
+    const findTag = async (digest: string | undefined | null, candidates: TagVersion[]): Promise<string | null> => {
+        if (!digest) return null;
+        for (const c of candidates) {
+            if (budget <= 0 && !digests.has(c.tag)) return null;
+            if ((await digestOf(c.tag)) === digest) return c.tag;
+        }
+        return null;
+    };
+
+    if (kind === "fixed") {
+        const current = parseTag(ref.tag as string) as TagVersion;
+        const newest = tags.filter((t) => shapeKey(t) === shapeKey(current)).sort(byVersionDesc)[0];
+        if (newest && compareVersions(newest, current) > 0) return { kind, running: current.tag, latest: newest.tag, status: "release", action: "edit tag", note: "" };
+        if (entry?.hasUpdate) return { kind, running: current.tag, latest: current.tag, status: "rebuild", action: "pull", note: "same tag, new build" };
+        return { kind, running: current.tag, latest: current.tag, status: "up-to-date", action: "", note: "" };
+    }
+
+    if (kind === "series") {
+        const series = parseTag(ref.tag as string) as TagVersion;
+        const members = tags
+            .filter((t) => t.prefix === series.prefix && t.nums.length >= 2 && t.nums[0] === series.nums[0] && suffixShape(t) === suffixShape(series))
+            .sort(byVersionDesc);
+        const newerSeries = tags.filter((t) => shapeKey(t) === shapeKey(series) && t.nums[0] > series.nums[0]).sort(byVersionDesc)[0];
+        const note = newerSeries ? `newer major ${newerSeries.tag} available (tag change)` : "";
+        const running = (await findTag(entry?.currentDigest, searchOrder(members, tags.filter((t) => t.nums[0] === series.nums[0] && t.prefix === series.prefix)))) ?? meaningfulVersion(entry?.currentVersion) ?? `${series.tag} (older build)`;
+        if (!entry?.hasUpdate) return { kind, running, latest: running, status: "up-to-date", action: "", note };
+        const latest = (await findTag(entry.latestDigest, members)) ?? "new build";
+        return { kind, running, latest, status: "update", action: "pull", note };
+    }
+
+    const candidates = releaseCandidates(tags);
+    if (kind === "pinned") {
+        const newest = candidates[0];
+        if (!newest) return unknown("pinned; the registry lists no release tags");
+        const running = (await findTag(ref.digest, searchOrder(candidates, tags))) ?? "?";
+        const newestDigest = await digestOf(newest.tag);
+        if (newestDigest && newestDigest !== ref.digest) return { kind, running, latest: newest.tag, status: "update", action: "edit digest", note: "", latestDigest: newestDigest };
+        return { kind, running, latest: running === "?" ? newest.tag : running, status: "up-to-date", action: "", note: "" };
+    }
+
+    const order = searchOrder(candidates, tags);
+    if (!entry?.hasUpdate) {
+        const running = (await findTag(entry?.currentDigest, order)) ?? meaningfulVersion(entry?.currentVersion) ?? "?";
+        return { kind, running, latest: running, status: "up-to-date", action: "", note: "" };
+    }
+    // The latest build is nearly always the newest tag: resolve it first so the search budget goes to the older running build.
+    let latest = (await findTag(entry.latestDigest, order)) ?? "new build";
+    const running = (await findTag(entry.currentDigest, order)) ?? meaningfulVersion(entry.currentVersion) ?? "older build";
+    // Name both builds in the same form, so "2.6.5.5623-ls161 -> 2.6.5.5623-ls162" shows a rebuild of one release.
+    const r = parseTag(running);
+    const l = parseTag(latest);
+    if (r && l && shapeKey(r) !== shapeKey(l)) {
+        const sameShape = tags.filter((t) => shapeKey(t) === shapeKey(r)).sort(byVersionDesc).slice(0, PER_SHAPE);
+        latest = (await findTag(entry.latestDigest, sameShape)) ?? latest;
+    }
+    return { kind, running, latest, status: "update", action: "pull", note: majorChange(running, latest) ? "major version change: check the release notes before pulling" : "" };
+}
+
+async function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
+    const out: R[] = new Array<R>(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}
+
+/** The dictionary of check results, with or without Arcane's response envelope. */
+export function checkEntries(raw: unknown): Record<string, CheckEntry> {
+    if (typeof raw !== "object" || raw === null) return {};
+    const r = raw as Record<string, unknown>;
+    const body = typeof r.data === "object" && r.data !== null && !Array.isArray(r.data) ? (r.data as Record<string, unknown>) : r;
+    const out: Record<string, CheckEntry> = {};
+    for (const [key, value] of Object.entries(body)) {
+        if (typeof value === "object" && value !== null && "hasUpdate" in value) out[key] = value as CheckEntry;
+    }
+    return out;
+}
+
+interface StackService {
+    stack: string;
+    service: string;
+    ref: string | null;
+    stopped: boolean;
+}
+
+/** Stack and service names with their image references from `projects list --all --json`. */
+export function stackServices(raw: unknown): StackService[] {
+    const data = (raw as { data?: unknown } | null)?.data;
+    if (!Array.isArray(data)) return [];
+    const out: StackService[] = [];
+    for (const p of data as Record<string, unknown>[]) {
+        const stack = String(p.name ?? "?");
+        const stopped = p.status === "stopped";
+        const services = (p.updateInfo as { serviceUpdates?: Record<string, { imageRef?: string }> } | undefined)?.serviceUpdates;
+        if (!services || Object.keys(services).length === 0) {
+            out.push({ stack, service: stack, ref: null, stopped });
+            continue;
+        }
+        for (const [service, s] of Object.entries(services)) out.push({ stack, service, ref: s.imageRef ?? null, stopped });
+    }
+    return out;
+}
+
+const STATUS_ORDER: Record<UpdateStatus, number> = { update: 0, release: 1, rebuild: 2, unknown: 3, "up-to-date": 4 };
+
+function cell(text: string, width: number): string {
+    return text.length > width ? `${text.slice(0, width - 1)}…` : text.padEnd(width);
+}
+
+/** Fixed-width table for a code block: renders the same in Discord and a terminal. */
+export function renderTable(rows: UpdateRow[], summary: string): string {
+    const head = ["Stack", "Image", "Running", "Latest", "Update"];
+    const body = rows.map((r) => [r.service === r.stack ? r.stack : `${r.stack}/${r.service}`, r.image, r.running, r.latest, r.status === "unknown" ? "unknown" : r.action || "-"]);
+    const limits = [26, 18, 20, 20, 11];
+    const widths = head.map((h, i) => Math.min(limits[i], Math.max(h.length, ...body.map((b) => b[i].length))));
+    const line = (cols: string[]) => cols.map((c, i) => cell(c, widths[i])).join("  ").trimEnd();
+    const lines = [line(head), widths.map((w) => "-".repeat(w)).join("  "), ...body.map(line)];
+    const notes = rows.filter((r) => r.note).map((r) => `* ${r.service === r.stack ? r.stack : `${r.stack}/${r.service}`}: ${r.note}`);
+    return [summary, "", ...lines, ...(notes.length > 0 ? ["", ...notes] : [])].join("\n");
+}
+
+/** Shares tag lists and digests between references to the same repository, such as `postgres:17` and `postgres:18`. */
+export function cachingRegistry(inner: Registry): Registry {
+    const tags = new Map<string, Promise<string[]>>();
+    const digests = new Map<string, Promise<string | null>>();
+    const key = (ref: ImageRef) => `${ref.registry}/${ref.repository}`;
+    return {
+        tags(ref) {
+            const k = key(ref);
+            if (!tags.has(k)) tags.set(k, inner.tags(ref));
+            return tags.get(k) as Promise<string[]>;
+        },
+        digest(ref, tag) {
+            const k = `${key(ref)}:${tag}`;
+            if (!digests.has(k)) digests.set(k, inner.digest(ref, tag));
+            return digests.get(k) as Promise<string | null>;
+        },
+    };
+}
+
+/**
+ * Builds the update report: every service image of every stack, against a check
+ * that ran moments before, with release versions read from the registries.
+ */
+export async function buildUpdateReport(input: { check: unknown; projects: unknown; registry: Registry; startedAt: number; all: boolean }): Promise<UpdateReport> {
+    const entries = checkEntries(input.check);
+    const services = stackServices(input.projects);
+    const refs = [...new Set(services.map((s) => s.ref).filter((r): r is string => r !== null))];
+    const resolved = new Map<string, Resolution & { kind: RefKind }>();
+    const registry = cachingRegistry(input.registry);
+    await mapLimit(refs, CONCURRENCY, async (ref) => {
+        resolved.set(ref, await resolveRef(ref, entries[ref], registry, input.startedAt));
+    });
+    const rows: UpdateRow[] = services.map((s) => {
+        if (s.ref === null) return { stack: s.stack, service: s.service, ref: "", image: "?", kind: "floating", running: "?", latest: "?", status: "unknown", action: "", note: "Arcane lists no images for this stack" };
+        const r = resolved.get(s.ref) as Resolution & { kind: RefKind };
+        const note = [r.note, s.stopped ? "stack is stopped" : ""].filter(Boolean).join("; ");
+        return { stack: s.stack, service: s.service, ref: s.ref, image: shortImage(parseImageRef(s.ref)), kind: r.kind, running: r.running, latest: r.latest, status: r.status, action: r.action, note, ...(r.latestDigest ? { latestDigest: r.latestDigest } : {}) };
+    });
+    rows.sort((a, b) => STATUS_ORDER[a.status] - STATUS_ORDER[b.status] || a.stack.localeCompare(b.stack) || a.service.localeCompare(b.service));
+    const counts: Record<UpdateStatus, number> = { update: 0, release: 0, rebuild: 0, unknown: 0, "up-to-date": 0 };
+    for (const r of rows) counts[r.status]++;
+    const shown = input.all ? rows : rows.filter((r) => r.status !== "up-to-date" || r.note.includes("newer major"));
+    const checkedAt = new Date(input.startedAt).toISOString().replace(/\.\d+Z$/, "Z");
+    const stacks = new Set(services.map((s) => s.stack)).size;
+    const summary =
+        `Fresh check ${checkedAt}: ${services.length} services in ${stacks} stacks, ${refs.length} images. ` +
+        `${counts.update} new builds, ${counts.release} new releases, ${counts.rebuild} rebuilds, ${counts.unknown} unknown, ${counts["up-to-date"]} up to date` +
+        (input.all ? "." : " (not listed unless a newer major exists).");
+    return { checkedAt, stacks, images: refs.length, counts, rows: shown, table: renderTable(shown, summary) };
+}

package/specialists/lib/main.ts

@@ -5,6 +5,11 @@ import { printError } from "./output.ts";
 
 export type Command = (args: string[]) => Promise<number>;
 
+/** Resolves once everything written so far has left the process; on a pipe, process.exit would drop what is still queued past the 64 KiB buffer. */
+export function flushed(stream: NodeJS.WritableStream): Promise<void> {
+    return new Promise((resolve) => stream.write("", () => resolve()));
+}
+
 /** Shared entry: parse argv, run, audit, map errors to exit codes. */
 export async function main(service: string, command: Command, argv = process.argv.slice(2)): Promise<never> {
     const started = Date.now();
@@ -30,5 +35,6 @@ export async function main(service: string, command: Command, argv = process.arg
     } catch (err) {
         printError(`${service}: audit log failed: ${err instanceof Error ? err.message : String(err)}`);
     }
+    await Promise.all([flushed(process.stdout), flushed(process.stderr)]);
     process.exit(code);
 }

package/specialists/lib/registry.ts

@@ -0,0 +1,153 @@
+import { ServiceError } from "./errors.ts";
+
+/** A container image reference split into the parts the registry API needs. */
+export interface ImageRef {
+    registry: string;
+    repository: string;
+    tag: string | null;
+    digest: string | null;
+}
+
+const DEFAULT_REGISTRY = "docker.io";
+
+/** Parses `[registry/]repo[:tag][@digest]` the way Docker resolves it. */
+export function parseImageRef(ref: string): ImageRef {
+    let rest = ref.trim();
+    let digest: string | null = null;
+    const at = rest.indexOf("@");
+    if (at >= 0) {
+        digest = rest.slice(at + 1);
+        rest = rest.slice(0, at);
+    }
+    let tag: string | null = null;
+    const colon = rest.lastIndexOf(":");
+    if (colon > rest.lastIndexOf("/")) {
+        tag = rest.slice(colon + 1);
+        rest = rest.slice(0, colon);
+    }
+    const parts = rest.split("/");
+    let registry = DEFAULT_REGISTRY;
+    if (parts.length > 1 && (parts[0].includes(".") || parts[0].includes(":") || parts[0] === "localhost")) registry = parts.shift() as string;
+    let repository = parts.join("/");
+    if (registry === DEFAULT_REGISTRY && !repository.includes("/")) repository = `library/${repository}`;
+    if (tag === null && digest === null) tag = "latest";
+    return { registry, repository, tag, digest };
+}
+
+/** Host that serves the registry API; lscr.io images are the linuxserver ones published on ghcr.io. */
+export function apiHost(registry: string): string {
+    if (registry === "docker.io") return "registry-1.docker.io";
+    if (registry === "lscr.io") return "ghcr.io";
+    return registry;
+}
+
+/** What the update report needs from a registry. */
+export interface Registry {
+    tags(ref: ImageRef): Promise<string[]>;
+    /** Manifest digest of one tag, or null when the tag does not exist. */
+    digest(ref: ImageRef, tag: string): Promise<string | null>;
+}
+
+export class RegistryError extends ServiceError {
+    readonly status: number;
+    constructor(message: string, status: number) {
+        super(message);
+        this.status = status;
+    }
+}
+
+const MANIFEST_ACCEPT = [
+    "application/vnd.oci.image.index.v1+json",
+    "application/vnd.docker.distribution.manifest.list.v2+json",
+    "application/vnd.oci.image.manifest.v1+json",
+    "application/vnd.docker.distribution.manifest.v2+json",
+].join(", ");
+
+const MAX_TAG_PAGES = 30;
+
+/** Parses `Bearer realm="...",service="...",scope="..."` into its parameters. */
+export function parseChallenge(header: string): Record<string, string> | null {
+    if (!/^bearer\s/i.test(header)) return null;
+    const params: Record<string, string> = {};
+    for (const m of header.slice(7).matchAll(/(\w+)="([^"]*)"/g)) params[m[1].toLowerCase()] = m[2];
+    return params.realm ? params : null;
+}
+
+/** Relative or absolute URL of the `rel="next"` page in a Link header. */
+export function nextLink(header: string | null): string | null {
+    if (!header) return null;
+    const m = /<([^>]+)>\s*;\s*rel="?next"?/i.exec(header);
+    return m ? m[1] : null;
+}
+
+/**
+ * Anonymous client for the OCI distribution API: bearer tokens from the
+ * registry's own challenge, tag lists with pagination, and manifest digests by
+ * HEAD, which Docker Hub does not count as a pull.
+ */
+export class HttpRegistry implements Registry {
+    private readonly tokens = new Map<string, string>();
+    private readonly fetchImpl: typeof fetch;
+    private readonly timeoutMs: number;
+
+    constructor(fetchImpl: typeof fetch = fetch, timeoutMs = 15_000) {
+        this.fetchImpl = fetchImpl;
+        this.timeoutMs = timeoutMs;
+    }
+
+    async tags(ref: ImageRef): Promise<string[]> {
+        const host = apiHost(ref.registry);
+        const all: string[] = [];
+        let path: string | null = `/v2/${ref.repository}/tags/list?n=1000`;
+        for (let page = 0; path !== null && page < MAX_TAG_PAGES; page++) {
+            const res = await this.request(ref, path, "GET", "application/json");
+            if (!res.ok) throw new RegistryError(`${host}/${ref.repository}: tag list returned ${res.status}`, res.status);
+            const body = (await res.json()) as { tags?: string[] | null };
+            all.push(...(body.tags ?? []));
+            const next = nextLink(res.headers.get("link"));
+            path = next === null ? null : next.startsWith("http") ? new URL(next).pathname + new URL(next).search : next;
+        }
+        return all;
+    }
+
+    async digest(ref: ImageRef, tag: string): Promise<string | null> {
+        const res = await this.request(ref, `/v2/${ref.repository}/manifests/${encodeURIComponent(tag)}`, "HEAD", MANIFEST_ACCEPT);
+        if (res.status === 404) return null;
+        if (!res.ok) throw new RegistryError(`${apiHost(ref.registry)}/${ref.repository}:${tag}: manifest returned ${res.status}`, res.status);
+        return res.headers.get("docker-content-digest");
+    }
+
+    private async request(ref: ImageRef, path: string, method: string, accept: string): Promise<Response> {
+        const host = apiHost(ref.registry);
+        const key = `${host}/${ref.repository}`;
+        const send = (token: string | undefined) =>
+            this.fetchImpl(`https://${host}${path}`, {
+                method,
+                headers: { accept, "user-agent": "pi-astro-arcane-updates", ...(token ? { authorization: `Bearer ${token}` } : {}) },
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        let res = await send(this.tokens.get(key));
+        if (res.status === 401) {
+            const challenge = parseChallenge(res.headers.get("www-authenticate") ?? "");
+            if (!challenge) throw new RegistryError(`${key}: authentication required`, 401);
+            const token = await this.token(challenge, ref);
+            this.tokens.set(key, token);
+            res = await send(token);
+        }
+        if (res.status === 429) throw new RegistryError(`${host}: rate limited`, 429);
+        if (res.status === 401 || res.status === 403) throw new RegistryError(`${key}: private or not found`, res.status);
+        return res;
+    }
+
+    private async token(challenge: Record<string, string>, ref: ImageRef): Promise<string> {
+        const url = new URL(challenge.realm);
+        if (challenge.service) url.searchParams.set("service", challenge.service);
+        url.searchParams.set("scope", challenge.scope ?? `repository:${ref.repository}:pull`);
+        const res = await this.fetchImpl(url, { headers: { "user-agent": "pi-astro-arcane-updates" }, signal: AbortSignal.timeout(this.timeoutMs) });
+        if (!res.ok) throw new RegistryError(`${apiHost(ref.registry)}/${ref.repository}: token request returned ${res.status}`, res.status);
+        const body = (await res.json()) as { token?: string; access_token?: string };
+        const token = body.token ?? body.access_token;
+        if (!token) throw new RegistryError(`${apiHost(ref.registry)}/${ref.repository}: token response had no token`, 401);
+        return token;
+    }
+}

package/specialists/lib/runtime.test.ts

@@ -32,7 +32,12 @@ describe("main", () => {
         process.env.HOME = home;
         mkdirSync(join(home, ".specialists"), { recursive: true });
         exit = vi.spyOn(process, "exit").mockImplementation((() => undefined) as never);
-        stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+        // Like a real stream, call the write callback: main waits for it before exiting.
+        stderr = vi.spyOn(process.stderr, "write").mockImplementation(((...args: unknown[]) => {
+            const done = args.find((a) => typeof a === "function") as (() => void) | undefined;
+            done?.();
+            return true;
+        }) as typeof process.stderr.write);
     });
 
     afterEach(() => {