@astrofoundry/pi-astro 0.27.0 → 0.28.0

package/agents/arcane.md

@@ -20,5 +20,6 @@ Rules:
 - 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.
+- Before a major version update, read its notes with `release-notes`, summarise breaking changes and manual steps, then ask for one go. Never ask the caller to read release notes for you.
 - 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.27.0",
+  "version": "0.28.0",
   "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"

package/skills/arcane/SKILL.md

@@ -35,11 +35,23 @@ The output is JSON with `counts`, `rows`, and `table`. Answer with the `table` f
 
 - `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.
+- A note "major version change" or "newer major ... available" means the update crosses a major version. Read its release notes yourself before asking anything (next section).
 - 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.
 
+## Release notes
+
+`["release-notes", "<stack>/<service>"]` (the service may be left out when the stack has one) finds the image's source repository through its `org.opencontainers.image.source` label and returns the GitHub releases after the running version up to the latest: `repository`, `releases` (`tag`, `name`, `published`, `url`, `notes`, `omittedSections`), `omitted` (older releases dropped for length), `reason` (why there are none, or that the running version was unknown). Long notes are condensed by section: the introduction and upgrade-relevant sections (breaking changes, migration, Docker, configuration) are kept first; `omittedSections` names what was left out, and the full text is at `url`. For linuxserver images the repository is their packaging repository, whose releases carry the upstream changes.
+
+For every update that crosses a major version, and whenever the caller asks what changed:
+
+1. Run `release-notes` for that service and read every release it returns.
+2. Summarise in a few lines: breaking changes, manual steps (database or data migrations, new, renamed, or removed settings and environment variables, changed volumes or ports), and what the Docker or upgrade sections require. Say plainly when the notes show none, and name the sections that were omitted.
+3. Ask the caller for one go for that stack, with the summary. Do not apply a major update without it.
+
+Minor and patch updates need no notes unless the caller asks. When `release-notes` reports no source, a source outside GitHub, or no releases, say so and ask for the go with that caveat; never guess the changes.
+
 ## 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.

package/specialists/AGENTS.md

@@ -55,6 +55,7 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
 - 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.
+- `arcane release-notes <stack>[/<service>]` is `lib/releases.ts`: a single-image check and `resolveRef` give the running and latest versions, `HttpRegistry.labels` reads `org.opencontainers.image.source` from the latest image (index to linux/amd64 manifest to config blob), and the anonymous GitHub releases API (60 requests an hour, up to 3 pages of 100) gives the releases in between, oldest first. `condenseNotes` keeps each release under 12,000 characters by section priority; `capTotal` drops the oldest releases past 40,000 characters in total.
 
 ## 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`; `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.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); `release-notes <stack>/<service>` (GitHub notes between the two 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,10 +4,11 @@ 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 { buildUpdateReport } from "../lib/image-updates.ts";
+import { buildUpdateReport, parseTag, resolveRef, stackServices, type CheckEntry } 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 { HttpRegistry, parseImageRef } from "../lib/registry.ts";
+import { releaseNotesFor } from "../lib/releases.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";
@@ -71,6 +72,9 @@ const HELP = `arcane specialist
   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.
+  release-notes <stack>[/<service>]
+                              GitHub release notes between the running and the latest version of one service's image,
+                              found through the image's org.opencontainers.image.source label
 ${REPO_HELP}
 Refused: ${REFUSED_PREFIXES.join(", ")}. GitOps-managed projects (gitOpsManagedBy set) change in the repository, then sync.`;
 
@@ -177,6 +181,34 @@ async function updateReport(config: ArcaneConfig, args: string[]): Promise<numbe
     });
 }
 
+async function releaseNotes(config: ArcaneConfig, args: string[]): Promise<number> {
+    if (args.length !== 1 || !/^[A-Za-z0-9_.-]+(\/[A-Za-z0-9_.-]+)?$/.test(args[0])) throw new UsageError("release-notes <stack>[/<service>]");
+    const [stack, service] = args[0].split("/");
+    const startedAt = Date.now();
+    return withCli(config, async (cli) => {
+        const all = stackServices(await cliJson(cli, ["projects", "list", "--all"]));
+        const matches = all.filter((s) => s.stack === stack && (service === undefined || s.service === service));
+        if (matches.length === 0) throw new UsageError(`no service ${args[0]}; stacks: ${[...new Set(all.map((s) => s.stack))].join(", ")}`);
+        if (matches.length > 1) throw new UsageError(`${stack} has several services (${matches.map((s) => s.service).join(", ")}); name one as ${stack}/<service>`);
+        const target = matches[0];
+        if (target.ref === null) throw new ServiceError(`Arcane lists no image for ${args[0]}`);
+        const ref = parseImageRef(target.ref);
+        const entry = ref.digest ? undefined : ((await cliJson(cli, ["images", "updates", "check", target.ref])) as CheckEntry);
+        const registry = new HttpRegistry();
+        const resolved = await resolveRef(target.ref, entry, registry, startedAt);
+        const latest = parseTag(resolved.latest) ? resolved.latest : null;
+        const running = parseTag(resolved.running) ? resolved.running : null;
+        const base = { stack: target.stack, service: target.service, ref: target.ref, running: resolved.running, latest: resolved.latest, status: resolved.status };
+        if (latest === null) {
+            printJson({ ...base, releases: [], reason: `no release version names the latest build (${resolved.latest}); nothing to compare` });
+            return 0;
+        }
+        const notes = await releaseNotesFor(target.ref, running, latest, ref.tag ?? latest, registry);
+        printJson({ ...base, ...notes });
+        return 0;
+    });
+}
+
 export async function command(args: string[]): Promise<number> {
     if (args.length === 0 || args[0] === "--help" || args[0] === "help") {
         printRaw(HELP);
@@ -185,6 +217,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));
+    if (args[0] === "release-notes") return releaseNotes(config, args.slice(1));
     return passthrough(config, args);
 }
 

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

@@ -1,6 +1,7 @@
 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";
+import { capTotal, condenseNotes, githubRepo, releaseNotesFor, releasesBetween, type GithubRelease } from "./releases.ts";
 
 const NOW = Date.parse("2026-09-25T18:30:00Z");
 const FRESH = "2026-09-25T18:30:05Z";
@@ -17,6 +18,9 @@ class FakeRegistry implements Registry {
         if (repo === undefined || repo === "private") throw new RegistryError(`${ref.repository}: private or not found`, 401);
         return repo.tags;
     }
+    async labels(): Promise<Record<string, string>> {
+        return {};
+    }
     async digest(ref: ImageRef, tag: string): Promise<string | null> {
         this.heads++;
         const repo = this.repos[ref.repository];
@@ -142,6 +146,7 @@ describe("buildUpdateReport", () => {
                 return ["17.1", "18.1"];
             },
             digest: async () => null,
+            labels: async () => ({}),
         };
         const registry = cachingRegistry(inner);
         await Promise.all([registry.tags(parseImageRef("postgres:17")), registry.tags(parseImageRef("postgres:18"))]);
@@ -188,3 +193,67 @@ describe("HttpRegistry", () => {
         expect(nextLink(null)).toBeNull();
     });
 });
+
+describe("release notes", () => {
+    const release = (tag: string, extra: Partial<GithubRelease> = {}): GithubRelease => ({ tag_name: tag, name: `Release ${tag}`, body: `notes ${tag}`, published_at: "2026-09-01T00:00:00Z", html_url: `https://github.com/o/r/releases/tag/${tag}`, draft: false, prerelease: false, ...extra });
+
+    it("reads GitHub repositories from source labels", () => {
+        expect(githubRepo("https://github.com/Stirling-Tools/Stirling-PDF")).toBe("Stirling-Tools/Stirling-PDF");
+        expect(githubRepo("https://github.com/linuxserver/docker-radarr.git")).toBe("linuxserver/docker-radarr");
+        expect(githubRepo("git@github.com:o/r.git")).toBe("o/r");
+        expect(githubRepo("https://gitlab.com/o/r")).toBeNull();
+    });
+
+    it("keeps published releases after the running version up to the latest, oldest first", () => {
+        const all = [release("v3.1.0"), release("v3.0.0"), release("v3.0.0-rc1", { prerelease: true }), release("v2.15.0"), release("v2.14.3"), release("v2.14.2"), release("draft", { draft: true })];
+        expect(releasesBetween(all, "2.14.3", "3.0.0").map((r) => r.tag)).toEqual(["v2.15.0", "v3.0.0"]);
+        expect(releasesBetween(all, null, "3.0.0").map((r) => r.tag)).toEqual(["v2.14.2", "v2.14.3", "v2.15.0", "v3.0.0"]);
+        expect(releasesBetween([release("2.6.5.5623-ls162"), release("2.6.5.5623-ls161")], "2.6.5.5623-ls161", "2.6.5.5623-ls162").map((r) => r.tag)).toEqual(["2.6.5.5623-ls162"]);
+        expect(releasesBetween(all, "2.14.3", "latest")).toEqual([]);
+        const long = releasesBetween([release("1.1.0", { body: "x".repeat(13_000) })], "1.0.0", "1.1.0")[0];
+        expect(long.notes.startsWith("x".repeat(12_000))).toBe(true);
+        expect(long.truncated).toBe(true);
+        expect(long.omittedSections).toEqual(["rest of introduction (13000 chars)"]);
+    });
+
+    it("keeps upgrade-relevant sections of long notes first", () => {
+        const body = ["V3 is live, read the upgrade guide.\n", "## What's Changed\n", `### Bug Fixes\n${"b".repeat(8000)}\n`, `### Enhancements\n${"e".repeat(20_000)}\n`, `### Docker Updates\n${"d".repeat(3000)}\n`, `## New Contributors\n${"c".repeat(1500)}\n`].join("");
+        const { notes, omitted } = condenseNotes(body, 12_000);
+        expect(notes).toContain("V3 is live");
+        expect(notes).toContain("### Docker Updates");
+        expect(notes).toContain("### Bug Fixes");
+        expect(notes.indexOf("Bug Fixes")).toBeLessThan(notes.indexOf("Docker Updates"));
+        expect(omitted).toEqual(["Enhancements (20018 chars)", "New Contributors (1521 chars)"]);
+        expect(condenseNotes("short")).toEqual({ notes: "short", omitted: [] });
+    });
+
+    it("drops the oldest notes first when the total is too long", () => {
+        const notes = Array.from({ length: 10 }, (_, i) => ({ tag: `1.${i}.0`, name: "", published: "", url: "", notes: "x".repeat(6000), truncated: false, omittedSections: [] }));
+        const capped = capTotal(notes);
+        expect(capped.notes.map((n) => n.tag)).toEqual(["1.4.0", "1.5.0", "1.6.0", "1.7.0", "1.8.0", "1.9.0"]);
+        expect(capped.omitted).toEqual(["1.0.0", "1.1.0", "1.2.0", "1.3.0"]);
+    });
+
+    it("finds the source through the image labels and reports why when it cannot", async () => {
+        const labelled: Registry = { tags: async () => [], digest: async () => null, labels: async () => ({ "org.opencontainers.image.source": "https://github.com/o/r" }) };
+        const fetchImpl = (async () => new Response(JSON.stringify([release("v1.1.0"), release("v1.0.0")]), { status: 200 })) as unknown as typeof fetch;
+        expect(await releaseNotesFor("o/r:latest", "1.0.0", "1.1.0", "latest", labelled, fetchImpl)).toMatchObject({ repository: "o/r", releases: [{ tag: "v1.1.0" }], reason: "" });
+        const bare: Registry = { ...labelled, labels: async () => ({}) };
+        expect(await releaseNotesFor("o/r:latest", "1.0.0", "1.1.0", "latest", bare, fetchImpl)).toMatchObject({ repository: null, reason: expect.stringContaining("declares no") });
+        const elsewhere: Registry = { ...labelled, labels: async () => ({ "org.opencontainers.image.source": "https://gitlab.com/o/r" }) };
+        expect(await releaseNotesFor("o/r:latest", "1.0.0", "1.1.0", "latest", elsewhere, fetchImpl)).toMatchObject({ reason: "the source repository is not on GitHub" });
+    });
+});
+
+describe("HttpRegistry labels", () => {
+    it("walks the index to the amd64 image config", async () => {
+        const fetchImpl = (async (input: string | URL | Request) => {
+            const url = String(input);
+            if (url.endsWith("/manifests/latest")) return new Response(JSON.stringify({ manifests: [{ digest: "sha256:arm", platform: { os: "linux", architecture: "arm64" } }, { digest: "sha256:amd", platform: { os: "linux", architecture: "amd64" } }] }), { status: 200 });
+            if (url.endsWith("/manifests/sha256:amd")) return new Response(JSON.stringify({ config: { digest: "sha256:cfg" } }), { status: 200 });
+            if (url.endsWith("/blobs/sha256:cfg")) return new Response(JSON.stringify({ config: { Labels: { "org.opencontainers.image.source": "https://github.com/o/r" } } }), { status: 200 });
+            return new Response("", { status: 404 });
+        }) as typeof fetch;
+        expect(await new HttpRegistry(fetchImpl).labels(parseImageRef("o/r:latest"), "latest")).toEqual({ "org.opencontainers.image.source": "https://github.com/o/r" });
+    });
+});

package/specialists/lib/image-updates.ts

@@ -330,6 +330,7 @@ export function cachingRegistry(inner: Registry): Registry {
             if (!digests.has(k)) digests.set(k, inner.digest(ref, tag));
             return digests.get(k) as Promise<string | null>;
         },
+        labels: (ref, tag) => inner.labels(ref, tag),
     };
 }
 

package/specialists/lib/registry.ts

@@ -46,6 +46,14 @@ 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>;
+    /** Image labels and index annotations of one tag (linux/amd64 when the tag is multi-platform). */
+    labels(ref: ImageRef, tag: string): Promise<Record<string, string>>;
+}
+
+interface ManifestJson {
+    manifests?: { digest: string; platform?: { os?: string; architecture?: string } }[];
+    config?: { digest?: string };
+    annotations?: Record<string, string>;
 }
 
 export class RegistryError extends ServiceError {
@@ -117,6 +125,26 @@ export class HttpRegistry implements Registry {
         return res.headers.get("docker-content-digest");
     }
 
+    async labels(ref: ImageRef, tag: string): Promise<Record<string, string>> {
+        const top = await this.getJson<ManifestJson>(ref, `/v2/${ref.repository}/manifests/${encodeURIComponent(tag)}`, MANIFEST_ACCEPT);
+        let manifest = top;
+        if (Array.isArray(top.manifests)) {
+            const pick = top.manifests.find((m) => m.platform?.os === "linux" && m.platform.architecture === "amd64") ?? top.manifests.find((m) => m.platform?.os !== "unknown");
+            if (!pick) return { ...top.annotations };
+            manifest = await this.getJson<ManifestJson>(ref, `/v2/${ref.repository}/manifests/${pick.digest}`, MANIFEST_ACCEPT);
+        }
+        const configDigest = manifest.config?.digest;
+        // Blobs redirect to a signed CDN URL; fetch drops the bearer token on that cross-origin hop.
+        const config = configDigest ? await this.getJson<{ config?: { Labels?: Record<string, string> | null } }>(ref, `/v2/${ref.repository}/blobs/${configDigest}`, "application/json") : {};
+        return { ...top.annotations, ...manifest.annotations, ...(config.config?.Labels ?? {}) };
+    }
+
+    private async getJson<T>(ref: ImageRef, path: string, accept: string): Promise<T> {
+        const res = await this.request(ref, path, "GET", accept);
+        if (!res.ok) throw new RegistryError(`${apiHost(ref.registry)}/${ref.repository}: ${path.split("/").slice(-2).join("/")} returned ${res.status}`, res.status);
+        return (await res.json()) as T;
+    }
+
     private async request(ref: ImageRef, path: string, method: string, accept: string): Promise<Response> {
         const host = apiHost(ref.registry);
         const key = `${host}/${ref.repository}`;

package/specialists/lib/releases.ts

@@ -0,0 +1,144 @@
+import { compareVersions, parseTag, type TagVersion } from "./image-updates.ts";
+import { parseImageRef, type Registry } from "./registry.ts";
+
+/** OCI label that names the repository an image was built from. */
+export const SOURCE_LABEL = "org.opencontainers.image.source";
+const NOTES_LIMIT = 12_000;
+/** Section headings that matter for running an upgrade; they are kept before anything else. */
+const PRIORITY = /breaking|upgrad|migrat|docker|deploy|config|important|notice|deprecat|remov|security|action required|environment|database/i;
+/** Sections that never matter for an upgrade decision; they go last. */
+const LOW = /new contributors|development tools|dependenc|chore|full changelog|contributors/i;
+const TOTAL_LIMIT = 40_000;
+const PAGES = 3;
+/** Releases shown when the running version is unknown. */
+const RECENT = 5;
+
+export interface GithubRelease {
+    tag_name: string;
+    name: string | null;
+    body: string | null;
+    published_at: string | null;
+    html_url: string;
+    draft: boolean;
+    prerelease: boolean;
+}
+
+export interface ReleaseNote {
+    tag: string;
+    name: string;
+    published: string;
+    url: string;
+    notes: string;
+    truncated: boolean;
+    /** Sections left out of `notes`, with their size; the full text is at `url`. */
+    omittedSections: string[];
+}
+
+/**
+ * Shortens long release notes by section: the introduction and upgrade-relevant
+ * sections (breaking changes, migration, Docker, configuration) first, the rest
+ * in their original order while space remains, contributor lists last.
+ */
+export function condenseNotes(body: string, limit = NOTES_LIMIT): { notes: string; omitted: string[] } {
+    if (body.length <= limit) return { notes: body, omitted: [] };
+    const sections = body.split(/^(?=#{1,4} )/m).filter((s) => s.trim().length > 0);
+    const title = (s: string) => (s.startsWith("#") ? s.split("\n")[0].replace(/^#+\s*/, "").trim() : "introduction");
+    const rank = (s: string) => (!s.startsWith("#") ? 0 : PRIORITY.test(title(s)) ? 1 : LOW.test(title(s)) ? 3 : 2);
+    const order = sections.map((s, i) => ({ s, i, r: rank(s) })).sort((a, b) => a.r - b.r || a.i - b.i);
+    const kept = new Map<number, string>();
+    const omitted: string[] = [];
+    let used = 0;
+    for (const { s, i, r } of order) {
+        if (used + s.length <= limit) {
+            kept.set(i, s);
+            used += s.length;
+        } else if (r <= 1 && limit - used > 200) {
+            kept.set(i, `${s.slice(0, limit - used)}\n[... section cut]\n`);
+            used = limit;
+            omitted.push(`rest of ${title(s)} (${s.length} chars)`);
+        } else {
+            omitted.push(`${title(s)} (${s.length} chars)`);
+        }
+    }
+    return { notes: [...kept.entries()].sort((a, b) => a[0] - b[0]).map(([, s]) => s).join(""), omitted };
+}
+
+/** `owner/name` of a GitHub source URL such as `https://github.com/Stirling-Tools/Stirling-PDF.git`, or null for other hosts. */
+export function githubRepo(source: string): string | null {
+    const m = /^(?:https?:\/\/|git@)github\.com[/:]([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?(?:[/#?].*)?$/.exec(source.trim());
+    return m ? `${m[1]}/${m[2]}` : null;
+}
+
+/** A release tag as a version, with a leading `v` or `release-` ignored. */
+function releaseVersion(tag: string): TagVersion | null {
+    return parseTag(tag.replace(/^(release-|version-)/i, ""));
+}
+
+/**
+ * Published releases after `running` up to and including `latest`, oldest
+ * first. When the running version is unknown, the last few up to `latest`.
+ */
+export function releasesBetween(releases: GithubRelease[], running: string | null, latest: string): ReleaseNote[] {
+    const to = releaseVersion(latest);
+    const from = running === null ? null : releaseVersion(running);
+    if (!to) return [];
+    const picked = releases
+        .filter((r) => !r.draft && !r.prerelease)
+        .map((r) => ({ r, v: releaseVersion(r.tag_name) }))
+        .filter((x): x is { r: GithubRelease; v: TagVersion } => x.v !== null && compareVersions(x.v, to) <= 0 && (from === null || compareVersions(x.v, from) > 0))
+        .sort((a, b) => compareVersions(a.v, b.v));
+    const chosen = from === null ? picked.slice(-RECENT) : picked;
+    return chosen.map(({ r }) => {
+        const { notes, omitted } = condenseNotes(r.body ?? "");
+        return { tag: r.tag_name, name: r.name ?? r.tag_name, published: r.published_at ?? "", url: r.html_url, notes, truncated: omitted.length > 0, omittedSections: omitted };
+    });
+}
+
+/** Keeps the newest notes whole and drops the oldest once the total passes the limit. */
+export function capTotal(notes: ReleaseNote[]): { notes: ReleaseNote[]; omitted: string[] } {
+    let total = 0;
+    const kept: ReleaseNote[] = [];
+    for (const n of [...notes].reverse()) {
+        if (total + n.notes.length > TOTAL_LIMIT && kept.length > 0) break;
+        total += n.notes.length;
+        kept.unshift(n);
+    }
+    return { notes: kept, omitted: notes.slice(0, notes.length - kept.length).map((n) => n.tag) };
+}
+
+export async function fetchReleases(repo: string, fetchImpl: typeof fetch = fetch): Promise<GithubRelease[]> {
+    const all: GithubRelease[] = [];
+    for (let page = 1; page <= PAGES; page++) {
+        const res = await fetchImpl(`https://api.github.com/repos/${repo}/releases?per_page=100&page=${page}`, {
+            headers: { accept: "application/vnd.github+json", "user-agent": "pi-astro-arcane-release-notes" },
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (!res.ok) throw new Error(`GitHub answered ${res.status} for ${repo} releases`);
+        const batch = (await res.json()) as GithubRelease[];
+        all.push(...batch);
+        if (batch.length < 100) break;
+    }
+    return all;
+}
+
+export interface ReleaseNotesResult {
+    source: string | null;
+    repository: string | null;
+    releases: ReleaseNote[];
+    omitted: string[];
+    reason: string;
+}
+
+/** Finds the image's source repository from its labels, then the GitHub releases between the two versions. */
+export async function releaseNotesFor(refText: string, running: string | null, latest: string, labelTag: string, registry: Registry, fetchImpl: typeof fetch = fetch): Promise<ReleaseNotesResult> {
+    const ref = parseImageRef(refText);
+    const labels = await registry.labels(ref, labelTag);
+    const source = labels[SOURCE_LABEL] ?? null;
+    if (!source) return { source: null, repository: null, releases: [], omitted: [], reason: `the image declares no ${SOURCE_LABEL} label` };
+    const repository = githubRepo(source);
+    if (!repository) return { source, repository: null, releases: [], omitted: [], reason: "the source repository is not on GitHub" };
+    const between = releasesBetween(await fetchReleases(repository, fetchImpl), running, latest);
+    const { notes, omitted } = capTotal(between);
+    const reason = between.length === 0 ? "GitHub lists no published release between the two versions" : running === null ? `running version unknown: the last ${notes.length} releases up to ${latest}` : "";
+    return { source, repository, releases: notes, omitted, reason };
+}