@astrofoundry/pi-astro 0.33.1 → 0.34.0

package/specialists/entry/remote/spc-arcane-sudoers

@@ -0,0 +1,4 @@
+# /etc/sudoers.d/spc-arcane (root:root 0440): the arcane specialist's key runs only
+# the root-owned dispatcher, which accepts fixed operation names and checked arguments.
+Defaults:spc-arcane !requiretty
+spc-arcane ALL=(root) NOPASSWD: /usr/local/sbin/spc-arcane-op

package/specialists/lib/arcane-host.test.ts

@@ -0,0 +1,147 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildHostRemote, compareAudit, HOST_COMMANDS } from "./arcane-host.ts";
+import { failedChecks, normalizeVersion, olderThan, pinCompose, pinnedDigest, projectSync, syncReady, utcStamp } from "./arcane-manager.ts";
+import { containerFacts, deploymentChecks, listRows, parseDeploymentArgs, syncFacts } from "./deployment.ts";
+import { UsageError } from "./errors.ts";
+
+const OP = join(import.meta.dirname, "..", "entry", "remote", "spc-arcane-op.py");
+const D1 = `sha256:${"a".repeat(64)}`;
+const D2 = `sha256:${"b".repeat(64)}`;
+
+describe("Arcane host commands", () => {
+    it("match the operations of spc-arcane-op exactly", () => {
+        const source = readFileSync(OP, "utf-8");
+        const table = source.slice(source.indexOf("COMMANDS = {"), source.indexOf("}", source.indexOf("COMMANDS = {")));
+        const names = [...table.matchAll(/^\s+"([a-z0-9-]+)":/gm)].map((m) => m[1]).sort();
+        expect(names).toEqual(Object.keys(HOST_COMMANDS).sort());
+    });
+
+    it("builds fixed remote commands and refuses bad arguments before SSH", () => {
+        expect(buildHostRemote(["container-memory", "grimoire-worker-1"]).remote).toBe("container-memory grimoire-worker-1");
+        expect(buildHostRemote(["container-logs", "bazarr", "2026-09-06T12:00:00Z", "2026-09-06T12:15:00Z", "bazarr-file"]).remote).toBe(
+            "container-logs bazarr 2026-09-06T12:00:00Z 2026-09-06T12:15:00Z bazarr-file",
+        );
+        expect(buildHostRemote(["db-restore", "mealie", "20261019T120000Z"]).name).toBe("db-restore");
+        expect(buildHostRemote(["mealie-api"]).spec.stdinSecret).toBe("MEALIE_API_KEY");
+        const bad = [
+            [],
+            ["rm"],
+            ["container-memory", "a b"],
+            ["container-logs", "sonarr", "2026-09-06T12:00:00Z", "2026-09-06T12:15:00Z", "bazarr-file"],
+            ["kernel-oom", "yesterday", "today"],
+            ["host-storage", "etc"],
+            ["service-check", "supabase-studio"],
+            ["radarr-movie", "120737"],
+            ["queue-job", "X"],
+            ["object-stat", "grimoire", "../x"],
+            ["object-stat", "grimoire", "a/.git/config"],
+            ["db-dump", "supabase"],
+            ["db-restore", "mealie", "latest"],
+            ["container-stats", ...Array.from({ length: 9 }, (_, i) => `c${i}`)],
+            ["manager-start"],
+            ["manager-rollback", "20261019T120000Z"],
+        ];
+        for (const args of bad) expect(() => buildHostRemote(args), args.join(" ")).toThrow(UsageError);
+        expect(buildHostRemote(["manager-rollback", "20261019T120000Z"], true).remote).toBe("manager-rollback 20261019T120000Z");
+    });
+
+    describe("audit comparison", () => {
+        let dir = "";
+        afterEach(() => {
+            if (dir) rmSync(dir, { recursive: true, force: true });
+        });
+
+        it("compares host hashes with host/<name> of the checkout", () => {
+            dir = mkdtempSync(join(tmpdir(), "audit-"));
+            mkdirSync(join(dir, "host"));
+            writeFileSync(join(dir, "host", "arcane-backup.sh"), "echo ok\n");
+            const sum = createHash("sha256").update("echo ok\n").digest("hex");
+            expect(
+                compareAudit(
+                    [
+                        { name: "arcane-backup.sh", state: "present", sha256: sum, mode: 493, uid: 0, gid: 0 },
+                        { name: "restic-check.sh", state: "present", sha256: sum },
+                        { name: "arcane-backup.timer", state: "missing" },
+                    ],
+                    dir,
+                ).map((r) => [r.name, r.match]),
+            ).toEqual([
+                ["arcane-backup.sh", true],
+                ["restic-check.sh", null],
+                ["arcane-backup.timer", null],
+            ]);
+        });
+    });
+});
+
+describe("manager upgrade helpers", () => {
+    const compose = `services:\n  arcane:\n    image: ghcr.io/getarcaneapp/manager@${D1}\n    pull_policy: always\n`;
+
+    it("pins only the manager digest", () => {
+        expect(pinnedDigest(compose)).toBe(D1);
+        expect(pinCompose(compose, D2)).toBe(compose.replace(D1, D2));
+        expect(() => pinCompose("services: {}\n", D2)).toThrow(UsageError);
+        expect(() => pinCompose(compose + compose, D2)).toThrow(UsageError);
+        expect(() => pinCompose(compose, "sha256:short")).toThrow(UsageError);
+    });
+
+    it("reads versions and stamps", () => {
+        expect(normalizeVersion("v2.17.0")).toBe("2.17.0");
+        expect(() => normalizeVersion("latest")).toThrow(UsageError);
+        expect(olderThan("2.16.1", "2.17.0")).toBe(true);
+        expect(olderThan("2.17.0", "2.17.0")).toBe(false);
+        expect(olderThan("10.0.0", "9.9.9")).toBe(false);
+        expect(utcStamp(new Date("2026-10-19T12:34:56.789Z"))).toBe("20261019T123456Z");
+    });
+
+    it("waits for a successful sync at the pin commit with the committed file", () => {
+        const projects = { data: [{ id: "p1", name: "arcane" }] };
+        const syncs = { data: [{ projectId: "p1", lastSyncStatus: "failed", lastSyncCommit: "abc1234", lastSyncAt: "t1" }] };
+        const sync = projectSync(projects, syncs, "arcane");
+        expect(syncReady(sync, "abc1234def", "x", "x")).toBe(false);
+        expect(syncReady({ ...sync, status: "success" }, "abc1234def", "x", "x")).toBe(true);
+        expect(syncReady({ ...sync, status: "success" }, "abc1234def", "x", "y")).toBe(false);
+        expect(syncReady({ ...sync, status: "success", commit: "fff0000" }, "abc1234def", "x", "x")).toBe(false);
+        expect(() => projectSync(projects, { data: [] }, "arcane")).toThrow(UsageError);
+        expect(failedChecks([{ check: "version", ok: false, observed: "2.16.1" }, { check: "digest", ok: true }])).toBe('version ("2.16.1")');
+    });
+});
+
+describe("deployment checks", () => {
+    const expect_ = { project: "grimoire", commit: "abc1234", services: { "grimoire-api-1": D1 }, jobs: { "grimoire-migrate": D2 }, noHealth: [] };
+    const sync = syncFacts({ lastSyncCommit: "abc1234ffff", lastSyncStatus: "success", lastSyncAt: "t1" });
+
+    it("parses the arguments arcane-ops took", () => {
+        expect(parseDeploymentArgs(["wait", "grimoire", "--commit", "abc1234", "--container", `grimoire-api-1=${D1}`, "--timeout", "120"])).toMatchObject({
+            wait: true,
+            timeoutS: 120,
+            services: { "grimoire-api-1": D1 },
+        });
+        expect(() => parseDeploymentArgs(["check", "grimoire", "--container", `a=${D1}`])).toThrow(UsageError);
+        expect(() => parseDeploymentArgs(["check", "grimoire", "--commit", "abc1234"])).toThrow(UsageError);
+        expect(() => parseDeploymentArgs(["check", "grimoire", "--commit", "abc1234", "--container", "a=latest"])).toThrow(UsageError);
+    });
+
+    it("passes a deployment whose commit, images, state and health all match", () => {
+        const api = containerFacts({ data: { imageId: D1, state: { status: "running", running: true, health: { status: "healthy" } }, composeInfo: { projectName: "grimoire" } } }, "grimoire-api-1");
+        const job = containerFacts({ imageId: D2, state: { status: "exited", running: false, exitCode: 0 }, composeInfo: { projectName: "grimoire" } }, "grimoire-migrate");
+        expect(deploymentChecks(expect_, sync, [api, job], sync).status).toBe("ok");
+        const unhealthy = { ...api, health: "unhealthy" };
+        expect(deploymentChecks(expect_, sync, [unhealthy, job], sync).status).toBe("failed");
+        const noCheck = { ...api, health: "no_check" };
+        expect(deploymentChecks(expect_, sync, [noCheck, job], sync).status).toBe("unknown");
+        expect(deploymentChecks({ ...expect_, noHealth: ["grimoire-api-1"] }, sync, [noCheck, job], sync).status).toBe("ok");
+        expect(deploymentChecks(expect_, sync, [api, job], { ...sync, at: "t2" }).checks.at(-1)).toEqual({ check: "stable_snapshot", status: "unknown" });
+        expect(deploymentChecks(expect_, sync, [null, job], sync).status).toBe("failed");
+    });
+
+    it("reads list rows wrapped or bare", () => {
+        expect(listRows({ data: [{ id: 1 }, null] })).toEqual([{ id: 1 }]);
+        expect(listRows([{ id: 2 }])).toEqual([{ id: 2 }]);
+        expect(listRows("x")).toEqual([]);
+    });
+});

package/specialists/lib/arcane-host.ts

@@ -0,0 +1,148 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { UsageError } from "./errors.ts";
+
+const MINUTE = 60_000;
+
+export interface HostCommand {
+    /** Smallest and largest number of arguments after the name. */
+    args: [number, number];
+    help: string;
+    timeoutMs: number;
+    /** Steps of `manager-upgrade` and `manager-rollback`; never run through `host`. */
+    internal?: true;
+    /** The wrapper sends a secret on stdin instead of an argument. */
+    stdinSecret?: string;
+}
+
+/**
+ * Operations of `spc-arcane-op` on VM 100, reached through the forced-command
+ * key of user `spc-arcane`. Names and argument counts must match that file's
+ * COMMANDS table (`entry/remote/spc-arcane-op.py`, tracked in the arcane
+ * repository's `host/`); the host checks every argument again.
+ */
+export const HOST_COMMANDS: Readonly<Record<string, HostCommand>> = {
+    "container-memory": { args: [1, 1], help: "container-memory <name>        one memory sample and the configured limits", timeoutMs: MINUTE },
+    "container-stats": { args: [0, 8], help: "container-stats [name...]      60 s CPU and memory sample (default: the Grimoire workers)", timeoutMs: 2 * MINUTE },
+    "container-logs": { args: [3, 4], help: "container-logs <name> <since> <until> [docker|bazarr-file]   sanitized event extracts, UTC window ≤ 1 day", timeoutMs: 2 * MINUTE },
+    "container-oom": { args: [3, 3], help: "container-oom <name> <since> <until>   OOMKilled flag, limits, retained oom events", timeoutMs: 2 * MINUTE },
+    "kernel-oom": { args: [2, 2], help: "kernel-oom <since> <until>     sanitized kernel OOM records from the journal", timeoutMs: MINUTE },
+    "host-audit": { args: [0, 0], help: "host-audit                     installed host files and units, compared with the repository's host/", timeoutMs: MINUTE },
+    "host-capacity": { args: [0, 0], help: "host-capacity                  CPU, memory, swap, Docker and Grimoire disk space and inodes", timeoutMs: MINUTE },
+    "host-storage": { args: [0, 1], help: "host-storage [area]            allocated bytes per directory in a known area (default root)", timeoutMs: 3 * MINUTE },
+    "docker-usage": { args: [0, 0], help: "docker-usage                   docker system df: counts, sizes, reclaimable", timeoutMs: 3 * MINUTE },
+    "service-check": { args: [1, 1], help: "service-check grimoire|mealie  HTTP status of a guest-local endpoint", timeoutMs: MINUTE },
+    "crawl4ai-info": { args: [0, 0], help: "crawl4ai-info                  crawl4ai package version and browser pool state", timeoutMs: MINUTE },
+    "recyclarr-naming": { args: [0, 0], help: "recyclarr-naming               whether Recyclarr's configuration syncs naming (flags only)", timeoutMs: MINUTE },
+    "arcane-version": { args: [0, 0], help: "arcane-version                 the manager's version from the guest", timeoutMs: MINUTE },
+    "queue-callback": { args: [0, 0], help: "queue-callback                 whether the Graphile worker posts to the batch callback (boolean)", timeoutMs: MINUTE },
+    "bazarr-providers": { args: [0, 0], help: "bazarr-providers               Bazarr's enabled subtitle providers", timeoutMs: 2 * MINUTE },
+    "mealie-api": { args: [0, 0], help: "mealie-api                     authenticated Mealie recipe-list check (needs MEALIE_API_KEY)", timeoutMs: MINUTE, stdinSecret: "MEALIE_API_KEY" },
+    "radarr-interface": { args: [0, 0], help: "radarr-interface               Radarr's queue actions from its interface bundle (host config key; owner approval)", timeoutMs: 2 * MINUTE },
+    "radarr-movie": { args: [1, 2], help: "radarr-movie <tt…> [command-id]   naming, file, queue and import state of one movie (host config key; owner approval)", timeoutMs: 2 * MINUTE },
+    "queue-job": { args: [1, 1], help: "queue-job <uuid>               Grimoire queue receipt, attempts, retry time, lock state", timeoutMs: MINUTE },
+    "object-stat": { args: [2, 2], help: "object-stat grimoire <path>    one object's metadata and age", timeoutMs: MINUTE },
+    "db-list": { args: [1, 1], help: "db-list mealie|paperless       this tool's dumps, newest last, with checksums and row counts", timeoutMs: MINUTE },
+    "db-dump": { args: [1, 1], help: "db-dump mealie|paperless       pg_dump into /var/backups/spc-arcane/<stack>/<UTC> (gzip, checked, sha256)", timeoutMs: 60 * MINUTE },
+    "db-restore": { args: [2, 2], help: "db-restore <stack> <stamp>     fill an EMPTY database from one of these dumps, the app stopped meanwhile (owner approval)", timeoutMs: 60 * MINUTE },
+    "manager-state": { args: [0, 0], help: "manager-state", timeoutMs: MINUTE, internal: true },
+    "manager-prepare": { args: [1, 1], help: "manager-prepare <stamp>", timeoutMs: 2 * MINUTE, internal: true },
+    "manager-pull": { args: [1, 1], help: "manager-pull <digest>", timeoutMs: 16 * MINUTE, internal: true },
+    "manager-backup": { args: [1, 1], help: "manager-backup <stamp>", timeoutMs: 30 * MINUTE, internal: true },
+    "manager-start": { args: [0, 0], help: "manager-start", timeoutMs: 6 * MINUTE, internal: true },
+    "manager-verify": { args: [3, 3], help: "manager-verify <stamp> <digest> <version>", timeoutMs: 3 * MINUTE, internal: true },
+    "manager-rollback": { args: [1, 1], help: "manager-rollback <stamp>", timeoutMs: 20 * MINUTE, internal: true },
+};
+
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+const UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+export const STAMP = /^\d{8}T\d{6}Z$/;
+const IMDB = /^tt\d{1,12}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const OBJECT_PATH = /^[A-Za-z0-9_][A-Za-z0-9_./-]{0,255}$/;
+export const DB_STACKS = ["mealie", "paperless"] as const;
+const STORAGE_AREAS = [
+    "root", "var", "var-lib", "logs", "docker", "volumes", "container-logs", "containerd", "grimoire",
+    "supabase", "nzb-scratch", "nzb-complete", "opt", "cache", "backups", "backup-staging", "backup-grimoire",
+];
+
+function check(ok: boolean, message: string): void {
+    if (!ok) throw new UsageError(message);
+}
+
+/** The remote command for `host <name> [args]`; the same rules as the host, so mistakes fail before SSH. */
+export function buildHostRemote(args: string[], allowInternal = false): { remote: string; spec: HostCommand; name: string } {
+    const [name, ...rest] = args;
+    const spec = name === undefined ? undefined : HOST_COMMANDS[name];
+    if (!spec || name === undefined) {
+        throw new UsageError(`unknown host command: ${name ?? "(none)"}; known: ${Object.keys(HOST_COMMANDS).filter((n) => !HOST_COMMANDS[n].internal).join(", ")}`);
+    }
+    if (spec.internal && !allowInternal) throw new UsageError(`${name} is a step of manager-upgrade or manager-rollback, not a command of its own`);
+    check(rest.length >= spec.args[0] && rest.length <= spec.args[1], `usage: ${spec.help.split("  ")[0]}`);
+    switch (name) {
+        case "container-memory":
+        case "container-stats":
+            check(rest.every((n) => NAME.test(n)), "container names: letters, digits, dot, dash, underscore");
+            break;
+        case "container-logs":
+        case "container-oom":
+            check(NAME.test(rest[0]), "container name: letters, digits, dot, dash, underscore");
+            check(UTC.test(rest[1]) && UTC.test(rest[2]), "since and until are UTC like 2026-09-06T12:15:00Z");
+            if (rest[3] !== undefined) check(rest[3] === "docker" || (rest[3] === "bazarr-file" && rest[0] === "bazarr"), "source: docker, or bazarr-file for bazarr");
+            break;
+        case "kernel-oom":
+            check(UTC.test(rest[0]) && UTC.test(rest[1]), "since and until are UTC like 2026-09-06T12:15:00Z");
+            break;
+        case "host-storage":
+            if (rest[0] !== undefined) check(STORAGE_AREAS.includes(rest[0]), `area: ${STORAGE_AREAS.join(", ")}`);
+            break;
+        case "service-check":
+            check(rest[0] === "grimoire" || rest[0] === "mealie", "service-check grimoire|mealie (public routes: edge route-probe)");
+            break;
+        case "radarr-movie":
+            check(IMDB.test(rest[0]), "an IMDb id like tt0120737");
+            if (rest[1] !== undefined) check(/^\d{1,9}$/.test(rest[1]), "command id: digits");
+            break;
+        case "queue-job":
+            check(UUID.test(rest[0]), "a lowercase job UUID");
+            break;
+        case "object-stat":
+            check(rest[0] === "grimoire", "object-stat grimoire <path>");
+            check(OBJECT_PATH.test(rest[1]) && !rest[1].split("/").some((p) => p === "" || p === "." || p === ".." || p.startsWith(".")), "a relative path without hidden parts or traversal");
+            break;
+        case "db-list":
+        case "db-dump":
+            check((DB_STACKS as readonly string[]).includes(rest[0]), `stack: ${DB_STACKS.join(", ")}`);
+            break;
+        case "db-restore":
+            check((DB_STACKS as readonly string[]).includes(rest[0]), `stack: ${DB_STACKS.join(", ")}`);
+            check(STAMP.test(rest[1]), "stamp: YYYYMMDDTHHMMSSZ from db-list");
+            break;
+        default:
+            break;
+    }
+    return { remote: [name, ...rest].join(" "), spec, name };
+}
+
+export interface AuditFile {
+    name: string;
+    state: string;
+    sha256?: string;
+    mode?: number;
+    uid?: number;
+    gid?: number;
+}
+
+/**
+ * Compares the host's file hashes with `host/<name>` in the specialist's
+ * checkout of the arcane repository; `match` is null when either side is missing.
+ */
+export function compareAudit(files: readonly AuditFile[], checkout: string): { name: string; state: string; match: boolean | null; mode?: number; uid?: number; gid?: number }[] {
+    return files.map((f) => {
+        const source = join(checkout, "host", f.name);
+        let expected: string | null = null;
+        if (existsSync(source) && lstatSync(source).isFile()) expected = createHash("sha256").update(readFileSync(source)).digest("hex");
+        return { name: f.name, state: f.state, match: f.state !== "present" || expected === null ? null : f.sha256 === expected, mode: f.mode, uid: f.uid, gid: f.gid };
+    });
+}

package/specialists/lib/arcane-manager.ts

@@ -0,0 +1,81 @@
+import { listRows } from "./deployment.ts";
+import { UsageError } from "./errors.ts";
+
+/** The official manager image; arcane/compose.yaml pins it by digest. */
+export const MANAGER_IMAGE = "ghcr.io/getarcaneapp/manager";
+export const MANAGER_COMPOSE = "arcane/compose.yaml";
+const PIN = /(image:\s*ghcr\.io\/getarcaneapp\/manager@)(sha256:[0-9a-f]{64})/g;
+
+/** `2.17.0` from `2.17.0` or `v2.17.0`; anything else is not a release version. */
+export function normalizeVersion(value: string): string {
+    const m = /^v?(\d{1,4}\.\d{1,4}\.\d{1,4})$/.exec(value);
+    if (!m) throw new UsageError(`not a release version: ${value.slice(0, 40)} (expected 2.17.0 or v2.17.0)`);
+    return m[1];
+}
+
+/** True when version a is older than version b (both plain x.y.z). */
+export function olderThan(a: string, b: string): boolean {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return pa[i] < pb[i];
+    return false;
+}
+
+/** The digest arcane/compose.yaml pins, or null when it pins none or several. */
+export function pinnedDigest(compose: string): string | null {
+    const all = [...compose.matchAll(PIN)];
+    return all.length === 1 ? all[0][2] : null;
+}
+
+/** arcane/compose.yaml with only the manager digest replaced; refuses a file that does not pin exactly one. */
+export function pinCompose(compose: string, digest: string): string {
+    if (!/^sha256:[0-9a-f]{64}$/.test(digest)) throw new UsageError(`not an image digest: ${digest}`);
+    if (pinnedDigest(compose) === null) throw new UsageError(`${MANAGER_COMPOSE} does not pin ${MANAGER_IMAGE} by exactly one digest`);
+    return compose.replace(PIN, `$1${digest}`);
+}
+
+/** `YYYYMMDDTHHMMSSZ`, the record name on the host. */
+export function utcStamp(now: Date): string {
+    return now.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+}
+
+export interface SyncState {
+    status: string | null;
+    commit: string | null;
+    at: string | null;
+}
+
+/** The GitOps sync of one project from `projects list --all` and `gitops list --all` (exactly one, as a deployment needs). */
+export function projectSync(projects: unknown, syncs: unknown, name: string): SyncState {
+    const project = listRows(projects).filter((p) => p.name === name);
+    if (project.length !== 1) throw new UsageError(`project ${name} is missing or ambiguous`);
+    const mine = listRows(syncs).filter((s) => s.projectId === project[0].id);
+    if (mine.length !== 1) throw new UsageError(`project ${name} needs exactly one GitOps sync, found ${mine.length}`);
+    const s = mine[0];
+    const text = (v: unknown) => (typeof v === "string" && v.length > 0 ? v : null);
+    return { status: text(s.lastSyncStatus), commit: text(s.lastSyncCommit), at: text(s.lastSyncAt) };
+}
+
+/**
+ * Ready for the host step when the sync reports success at the pin commit and
+ * the deployed Compose file is the committed one. A sync that copied the file
+ * but reported failure is not ready; the next scheduled sync must succeed.
+ */
+export function syncReady(sync: SyncState, commit: string, deployedSha256: string, committedSha256: string): boolean {
+    const sameCommit = sync.commit !== null && (commit.startsWith(sync.commit) || sync.commit.startsWith(commit));
+    return sameCommit && sync.status === "success" && deployedSha256 === committedSha256;
+}
+
+export interface VerifyCheck {
+    check: string;
+    ok: boolean;
+    observed?: unknown;
+}
+
+/** The checks that failed, as one line for a report. */
+export function failedChecks(checks: readonly VerifyCheck[]): string {
+    return checks
+        .filter((c) => !c.ok)
+        .map((c) => `${c.check} (${JSON.stringify(c.observed ?? null).slice(0, 80)})`)
+        .join(", ");
+}

package/specialists/lib/deployment.ts

@@ -0,0 +1,152 @@
+import { UsageError } from "./errors.ts";
+
+/** One container of `containers get`, reduced to what a deployment check compares. */
+export interface ContainerFacts {
+    name: string;
+    imageId: string | null;
+    state: string | null;
+    running: boolean | null;
+    exitCode: number | null;
+    /** healthy, unhealthy, starting, or no_check when the image defines no health check. */
+    health: string;
+    project: string | null;
+}
+
+export interface SyncFacts {
+    commit: string | null;
+    status: string | null;
+    hasError: boolean;
+    hookConfigured: boolean;
+    hookStatus: string | null;
+    at: string | null;
+}
+
+export interface DeploymentExpectation {
+    project: string;
+    commit: string;
+    /** Long-running containers and their expected Docker image IDs. */
+    services: Record<string, string>;
+    /** One-shot containers that must have exited 0, with their image IDs. */
+    jobs: Record<string, string>;
+    /** Containers whose missing health check is waived explicitly. */
+    noHealth: string[];
+}
+
+export interface DeploymentCheck {
+    check: string;
+    status: "ok" | "failed" | "unknown";
+    container?: string;
+    expected?: string;
+    observed?: unknown;
+    waived?: boolean;
+}
+
+const COMMIT = /^[0-9a-f]{7,40}$/;
+const IMAGE_ID = /^sha256:[0-9a-f]{64}$/;
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+
+/** `deployment check|wait <project> --commit <sha> [--container N=sha256:…] [--job N=sha256:…] [--allow-no-health N] [--timeout s]`. */
+export function parseDeploymentArgs(args: string[]): DeploymentExpectation & { wait: boolean; timeoutS: number } {
+    const [mode, project, ...rest] = args;
+    if (mode !== "check" && mode !== "wait") throw new UsageError("deployment check|wait <project> --commit <sha> [--container NAME=sha256:ID]... [--job NAME=sha256:ID]... [--allow-no-health NAME]... [--timeout seconds]");
+    if (project === undefined || !NAME.test(project)) throw new UsageError("deployment needs a project name");
+    const out: DeploymentExpectation & { wait: boolean; timeoutS: number } = { project, commit: "", services: {}, jobs: {}, noHealth: [], wait: mode === "wait", timeoutS: 600 };
+    for (let i = 0; i < rest.length; i += 2) {
+        const flag = rest[i];
+        const value = rest[i + 1];
+        if (value === undefined) throw new UsageError(`${flag} needs a value`);
+        if (flag === "--commit") {
+            if (!COMMIT.test(value)) throw new UsageError("--commit: a git commit (7 to 40 hex)");
+            out.commit = value;
+        } else if (flag === "--container" || flag === "--job") {
+            const [name, id] = value.split("=");
+            if (!NAME.test(name ?? "") || !IMAGE_ID.test(id ?? "")) throw new UsageError(`${flag} NAME=sha256:<64 hex image id>`);
+            (flag === "--container" ? out.services : out.jobs)[name] = id;
+        } else if (flag === "--allow-no-health") {
+            if (!NAME.test(value)) throw new UsageError("--allow-no-health NAME");
+            out.noHealth.push(value);
+        } else if (flag === "--timeout") {
+            const n = Number(value);
+            if (!Number.isInteger(n) || n < 10 || n > 1800) throw new UsageError("--timeout: 10 to 1800 seconds");
+            out.timeoutS = n;
+        } else {
+            throw new UsageError(`unknown option ${flag}`);
+        }
+    }
+    if (out.commit === "") throw new UsageError("--commit is required");
+    if (Object.keys(out.services).length + Object.keys(out.jobs).length === 0) throw new UsageError("name at least one --container or --job");
+    return out;
+}
+
+/** The rows of an arcane-cli list in JSON: the array itself or the API body's `data`. */
+export function listRows(value: unknown): Record<string, unknown>[] {
+    const list = Array.isArray(value) ? value : (value as { data?: unknown } | null)?.data;
+    return Array.isArray(list) ? list.filter((r): r is Record<string, unknown> => typeof r === "object" && r !== null) : [];
+}
+
+function str(v: unknown): string | null {
+    return typeof v === "string" && v.length > 0 ? v : null;
+}
+
+/** The fields of `containers get <name>` JSON (the API's container detail, inside `data` when wrapped). */
+export function containerFacts(raw: unknown, name: string): ContainerFacts {
+    const top = (raw as { data?: unknown } | null)?.data ?? raw;
+    const c = (top ?? {}) as Record<string, unknown>;
+    const state = (c.state ?? {}) as Record<string, unknown>;
+    const health = state.health as { status?: unknown } | null | undefined;
+    const healthStatus = health === undefined || health === null ? "no_check" : str(health.status) ?? "unknown";
+    const compose = c.composeInfo as { projectName?: unknown } | null | undefined;
+    return {
+        name,
+        imageId: str(c.imageId),
+        state: str(state.status),
+        running: typeof state.running === "boolean" ? state.running : null,
+        exitCode: typeof state.exitCode === "number" ? state.exitCode : null,
+        health: healthStatus === "none" ? "no_check" : healthStatus,
+        project: str(compose?.projectName),
+    };
+}
+
+/** The sync fields a deployment compares, from one row of `gitops list --all`. */
+export function syncFacts(row: Record<string, unknown>): SyncFacts {
+    return {
+        commit: str(row.lastSyncCommit),
+        status: str(row.lastSyncStatus),
+        hasError: Boolean(row.lastSyncError),
+        hookConfigured: Boolean(row.preDeployScriptPath),
+        hookStatus: str(row.preDeployLastRunStatus),
+        at: str(row.lastSyncAt),
+    };
+}
+
+/** The checks of arcane-ops `deployment check`, as one pure comparison. */
+export function deploymentChecks(expect: DeploymentExpectation, sync: SyncFacts, containers: readonly (ContainerFacts | null)[], syncAfter: SyncFacts): { status: "ok" | "failed" | "unknown"; checks: DeploymentCheck[] } {
+    const checks: DeploymentCheck[] = [];
+    const commitOk = sync.commit !== null && (sync.commit.startsWith(expect.commit) || expect.commit.startsWith(sync.commit));
+    checks.push({ check: "commit", status: sync.commit === null ? "unknown" : commitOk ? "ok" : "failed", expected: expect.commit, observed: sync.commit });
+    checks.push({ check: "sync", status: sync.status === "success" && !sync.hasError ? "ok" : sync.status === null ? "unknown" : "failed", observed: sync.status });
+    if (sync.hookConfigured) checks.push({ check: "hook", status: sync.hookStatus === "success" ? "ok" : sync.hookStatus === null ? "unknown" : "failed", observed: sync.hookStatus });
+    const names = [...Object.keys(expect.services), ...Object.keys(expect.jobs)];
+    names.forEach((name, i) => {
+        const c = containers[i];
+        if (!c) {
+            checks.push({ check: "container", status: "failed", container: name, observed: "missing" });
+            return;
+        }
+        const expected = expect.services[name] ?? expect.jobs[name];
+        checks.push({ check: "project", status: c.project === null ? "unknown" : c.project === expect.project ? "ok" : "failed", container: name, observed: c.project });
+        checks.push({ check: "image", status: c.imageId === expected ? "ok" : "failed", container: name, expected, observed: c.imageId });
+        if (name in expect.jobs) {
+            checks.push({ check: "job_exit", status: c.state === "exited" && c.exitCode === 0 ? "ok" : "failed", container: name, observed: { state: c.state, exitCode: c.exitCode } });
+        } else {
+            checks.push({ check: "running", status: c.state === "running" && c.running === true ? "ok" : "failed", container: name, observed: c.state });
+            const waived = c.health === "no_check" && expect.noHealth.includes(name);
+            const status = c.health === "healthy" || waived ? "ok" : c.health === "no_check" || c.health === "unknown" ? "unknown" : "failed";
+            checks.push({ check: "health", status, container: name, observed: c.health, waived });
+        }
+    });
+    const stable = (["commit", "status", "hasError", "hookStatus", "at"] as const).every((k) => syncAfter[k] === sync[k]);
+    if (!stable) checks.push({ check: "stable_snapshot", status: "unknown" });
+    const statuses = new Set(checks.map((c) => c.status));
+    return { status: statuses.has("failed") ? "failed" : statuses.has("unknown") ? "unknown" : "ok", checks };
+}

package/specialists/lib/repo.ts

@@ -54,7 +54,8 @@ function gitEnv(spec: RepoSpec): Record<string, string> {
     };
 }
 
-async function git(spec: RepoSpec, dir: string, args: string[]): Promise<string> {
+/** One git command in a specialist checkout, with its deploy key; for wrappers that commit a fixed change of their own. */
+export async function git(spec: RepoSpec, dir: string, args: string[]): Promise<string> {
     const result = await run("/usr/bin/git", ["-C", dir, ...args], { env: gitEnv(spec), timeoutMs: TIMEOUT_MS });
     if (result.code !== 0) throw new ServiceError(`git ${args[0]} failed: ${result.stderr.trim()}`);
     return result.stdout;

package/specialists/wrappers.test.ts

@@ -5,7 +5,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { refusedPrefix, command as arcaneCommand } from "./arcane/run.ts";
 import { buildBackupRemote, command as backupCommand } from "./backup/run.ts";
 import { parseParams, parseRecordFilters, technitiumRequest, command as dnsCommand } from "./dns/run.ts";
-import { buildVpsRemote, command as edgeCommand, isTransientSshFailure } from "./edge/run.ts";
+import { buildVpsRemote, command as edgeCommand, isTransientSshFailure, PUBLIC_ROUTES, routeProbe } from "./edge/run.ts";
 import { API_PREFIXES, buildDmzRemote, validateApiPath, command as identityCommand } from "./identity/run.ts";
 import { buildInferenceRemote, compactReleases, command as inferenceCommand } from "./inference/run.ts";
 import { MAX_ADD_IDS, buildTrendarrCall, interpretRun, parseImdbIds, trendarrConfig, trendarrError, trendarrWarnings, command as mediaCommand } from "./media/run.ts";
@@ -184,6 +184,24 @@ describe("dns wrapper", () => {
 });
 
 describe("edge wrapper", () => {
+    it("probes public routes by status only, without following redirects", async () => {
+        const seen: string[][] = [];
+        const curl = async (args: string[]) => {
+            seen.push(args);
+            const url = args.at(-1) ?? "";
+            return { stdout: url.includes("/auth/v1/settings") ? "401 0.12" : url.includes("studio") ? "302 0.10" : "200 0.05", code: 0 };
+        };
+        const all = await routeProbe([], curl);
+        expect(all).toHaveLength(Object.keys(PUBLIC_ROUTES).length);
+        expect(all.every((r) => r.ok)).toBe(true);
+        expect(seen.every((a) => !a.includes("--location") && !a.includes("-L") && a.includes("=https"))).toBe(true);
+        const [studio] = await routeProbe(["supabase-studio"], async () => ({ stdout: "200 0.1", code: 0 }));
+        expect(studio).toMatchObject({ route: "supabase-studio", httpCode: 200, ok: false });
+        const [down] = await routeProbe(["mealie-public"], async () => ({ stdout: "000 0", code: 28 }));
+        expect(down).toMatchObject({ httpCode: null, ok: false, curlExit: 28 });
+        await expect(routeProbe(["evil"], curl)).rejects.toThrow(UsageError);
+    });
+
     it("maps vps commands and requires reboot confirmation", () => {
         expect(buildVpsRemote(["status"])).toEqual({ remote: "status", stdin: false });
         expect(buildVpsRemote(["deploy-nginx"])).toEqual({ remote: "deploy-nginx", stdin: true });