@astrofoundry/pi-astro 0.28.0 → 0.29.0

package/extensions/astro-discord/index.ts

@@ -13,6 +13,7 @@ import { ACTIVATION_ENV, type ChannelSettings, type DiscordConfig, allowedSpecia
 import { type ConversationState, type ResolvedConversation, forgetStale, loadState, newConversationId, recordAnswer, resolveConversation, saveState, sessionsRoot, startConversation } from "./conversations.ts";
 import { describeImages, downloadImages, type ImageAttachment, imageAttachments } from "./attachments.ts";
 import { GatewayClient } from "./gateway.ts";
+import { cancelledApprovalText, interruptedTaskText, readOpenWork, type OpenWork, type StopReason, writeOpenWork } from "./open-work.ts";
 import { type Quote, type QuotedMessage, withQuotes } from "./quote.ts";
 import { DiscordRest, type MessageComponent } from "./rest.ts";
 
@@ -86,8 +87,13 @@ interface ActiveTask {
     startedAt: number;
     conversation: ResolvedConversation;
     images: ImageAttachment[];
+    abort?: AbortController;
+    placeholder?: string;
 }
 
+/** How long a shutdown may spend editing Discord messages; launchd kills the job 20 s after the stop signal. */
+const SHUTDOWN_BUDGET_MS = 8000;
+
 function log(line: string): void {
     process.stderr.write(`[astro-discord ${new Date().toISOString()}] ${line}\n`);
 }
@@ -115,6 +121,9 @@ class Bridge {
     private readonly queues = new Map<string, Promise<void>>();
     private readonly active = new Map<string, ActiveTask>();
     private readonly approvalMessages = new Map<string, { channelId: string; messageId: string; userMessage: ActiveTask }>();
+    private gateway: GatewayClient | undefined;
+    private stopping = false;
+    private readonly since = new Date().toISOString();
     private config: DiscordConfig;
     private conversations: ConversationState;
     private botUserId = "";
@@ -146,9 +155,65 @@ class Bridge {
         else log(`config not reloaded: ${loaded.errors.join("; ")}`);
     }
 
+    private openWork(): OpenWork {
+        return {
+            since: this.since,
+            tasks: [...this.active.values()].map((t) => ({ specialist: t.specialist, channelId: t.channelId, messageId: t.messageId, ...(t.placeholder ? { placeholderId: t.placeholder } : {}) })),
+            approvals: [...this.approvalMessages.entries()].map(([ticketId, a]) => ({ ticketId, channelId: a.channelId, messageId: a.messageId, userChannelId: a.userMessage.channelId, userMessageId: a.userMessage.messageId })),
+        };
+    }
+
+    /** Records what is open in Discord, so a restart can wait for it and the next process can close it after a crash. */
+    private saveOpenWork(): void {
+        try {
+            writeOpenWork(this.openWork());
+        } catch (err) {
+            log(`open work not saved: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+
+    /** Tells Discord that open approvals were cancelled and running tasks interrupted, so no button is left dead without a word. */
+    private async closeOpen(work: OpenWork, reason: StopReason): Promise<void> {
+        const edits: Promise<unknown>[] = [];
+        for (const a of work.approvals) {
+            edits.push(this.rest.editMessage(a.channelId, a.messageId, cancelledApprovalText(reason), approvalButtons(a.ticketId, true)).catch(() => undefined));
+            edits.push(this.rest.removeOwnReaction(a.userChannelId, a.userMessageId, REACTION.waiting).catch(() => undefined));
+        }
+        for (const t of work.tasks) {
+            const text = interruptedTaskText(t.specialist, reason);
+            edits.push((t.placeholderId ? this.rest.editMessage(t.channelId, t.placeholderId, text) : this.rest.createMessage(t.channelId, { content: text, replyTo: t.messageId })).catch(() => undefined));
+            edits.push(
+                this.rest
+                    .removeOwnReaction(t.channelId, t.messageId, REACTION.running)
+                    .then(() => this.rest.addReaction(t.channelId, t.messageId, REACTION.failed))
+                    .catch(() => undefined),
+            );
+        }
+        await Promise.race([Promise.all(edits), new Promise((resolve) => setTimeout(resolve, SHUTDOWN_BUDGET_MS).unref())]);
+    }
+
+    /** Called from Pi's session_shutdown, which Pi awaits on SIGTERM before it exits. */
+    async shutdown(): Promise<void> {
+        if (this.stopping) return;
+        this.stopping = true;
+        this.gateway?.stop();
+        const work = this.openWork();
+        for (const task of this.active.values()) task.abort?.abort();
+        if (work.tasks.length > 0 || work.approvals.length > 0) log(`shutdown: cancelling ${work.approvals.length} approval(s), interrupting ${work.tasks.length} task(s)`);
+        await this.closeOpen(work, "restart");
+        this.approvals.close();
+        writeOpenWork({ since: this.since, tasks: [], approvals: [] });
+    }
+
     async start(): Promise<void> {
         const me = await this.rest.currentUser();
         this.botUserId = me.id;
+        const leftover = readOpenWork();
+        if (leftover) {
+            log(`closing what the previous process left open: ${leftover.approvals.length} approval(s), ${leftover.tasks.length} task(s)`);
+            await this.closeOpen(leftover, "crash");
+            writeOpenWork({ since: this.since, tasks: [], approvals: [] });
+        }
         await this.approvals.listen();
         const gateway = new GatewayClient({
             token: this.token,
@@ -159,6 +224,7 @@ class Bridge {
             },
         });
         gateway.start();
+        this.gateway = gateway;
         log(`connected as ${me.username} (${me.id}); channels ${Object.keys(this.config.channels).join(", ")}; specialists ${this.specialists().names.join(", ")}`);
     }
 
@@ -266,12 +332,16 @@ class Bridge {
 
     private async runTask(agent: AgentConfig, taskText: string, task: ActiveTask): Promise<void> {
         task.startedAt = Date.now();
+        task.abort = new AbortController();
         this.active.set(task.specialist, task);
+        this.saveOpenWork();
         await this.rest.addReaction(task.channelId, task.messageId, REACTION.running);
         const placeholder = await this.rest
             .createMessage(task.channelId, { content: `${REACTION.running} **${task.specialist}** is working on your task, please wait…`, replyTo: task.messageId })
             .then((m) => m.id)
             .catch(() => undefined);
+        task.placeholder = placeholder;
+        this.saveOpenWork();
         // Discord clears the typing indicator after about ten seconds; refresh it while the task runs.
         await this.rest.triggerTyping(task.channelId).catch(() => undefined);
         const typing = setInterval(() => void this.rest.triggerTyping(task.channelId).catch(() => undefined), 8000);
@@ -308,6 +378,7 @@ class Bridge {
                 env: { [ACTIVATION_ENV]: "0", [APPROVAL_URL_ENV]: this.approvals.url, [APPROVAL_TOKEN_ENV]: this.approvals.token, ASTRO_CHANNEL: "discord" },
                 extraSystemPrompt: CHANNEL_RULES,
                 session,
+                signal: task.abort.signal,
                 onUpdate: (partial) => {
                     const progress = describeProgress(partial, seen);
                     seen = progress.seen;
@@ -327,9 +398,14 @@ class Bridge {
             output = err instanceof Error ? err.message : String(err);
         } finally {
             clearInterval(typing);
-            this.active.delete(task.specialist);
+            if (!this.stopping) {
+                this.active.delete(task.specialist);
+                this.saveOpenWork();
+            }
             if (images) await fs.rm(images.dir, { recursive: true, force: true }).catch(() => undefined);
         }
+        // During shutdown the interrupted message was already written; an aborted run has nothing else to say.
+        if (this.stopping) return;
         await this.rest.removeOwnReaction(task.channelId, task.messageId, REACTION.running).catch(() => undefined);
         await this.rest.addReaction(task.channelId, task.messageId, failed ? REACTION.failed : REACTION.done).catch(() => undefined);
         const answers = await this.deliver(task, placeholder, `${failed ? "❌" : "✅"} **${task.specialist}**\n${output}`, attachment);
@@ -373,12 +449,14 @@ class Bridge {
         const content = `🔒 **${short}** wants to run ${code(ticket.args.join(" "))} for <@${task.userId}>. ${owners}: approve or deny within ${this.config.approvalTimeoutMinutes} min.`;
         const posted = await this.rest.createMessage(task.channelId, { content, replyTo: task.messageId, components: approvalButtons(ticket.id) });
         this.approvalMessages.set(ticket.id, { channelId: posted.channel_id, messageId: posted.id, userMessage: task });
+        this.saveOpenWork();
     }
 
     private async expireApproval(ticket: Ticket): Promise<void> {
         const posted = this.approvalMessages.get(ticket.id);
         if (!posted) return;
         this.approvalMessages.delete(ticket.id);
+        this.saveOpenWork();
         await this.rest.editMessage(posted.channelId, posted.messageId, `⌛ No decision within ${this.config.approvalTimeoutMinutes} min; ${code(ticket.args.join(" "))} was not run.`).catch(() => undefined);
         await this.rest.removeOwnReaction(posted.userMessage.channelId, posted.userMessage.messageId, REACTION.waiting).catch(() => undefined);
     }
@@ -401,6 +479,7 @@ class Bridge {
         }
         const posted = this.approvalMessages.get(ticket.id);
         this.approvalMessages.delete(ticket.id);
+        this.saveOpenWork();
         const verdict = decision === "approve" ? `✅ Approved by <@${userId}>` : `⛔ Denied by <@${userId}>`;
         await this.rest.updateInteractionMessage(interaction.id, interaction.token, `${verdict}: ${code(ticket.args.join(" "))}`);
         if (posted) await this.rest.removeOwnReaction(posted.userMessage.channelId, posted.userMessage.messageId, REACTION.waiting).catch(() => undefined);
@@ -414,6 +493,10 @@ class Bridge {
  */
 export default function astroDiscord(pi: ExtensionAPI): void {
     if (process.env[ACTIVATION_ENV] !== "1" || process.env[AGENT_ENV]) return;
+    let bridge: Bridge | undefined;
+    pi.on("session_shutdown", async () => {
+        await bridge?.shutdown();
+    });
     pi.on("session_start", async (_event, ctx: ExtensionContext) => {
         const loaded = loadConfig();
         if (!loaded.config) {
@@ -428,7 +511,8 @@ export default function astroDiscord(pi: ExtensionAPI): void {
             return;
         }
         try {
-            await new Bridge(ctx, loaded.config, token).start();
+            bridge = new Bridge(ctx, loaded.config, token);
+            await bridge.start();
         } catch (err) {
             log(`start failed: ${err instanceof Error ? err.message : String(err)}`);
         }

package/extensions/astro-discord/launcher.ts

@@ -0,0 +1,20 @@
+/**
+ * The LaunchAgent's run.sh. Pi's RPC mode exits when stdin closes, so stdin is
+ * a FIFO opened read-write: it never reaches end-of-file. `exec` makes Pi the
+ * job's own process, so launchd's stop signal reaches Pi, whose shutdown lets
+ * the bridge cancel open approvals in Discord before it exits.
+ */
+export function runScriptText(pi: string): string {
+    return [
+        "#!/bin/sh",
+        "# Headless Pi host for the Discord bridge. Pi's RPC mode exits when stdin closes; a FIFO opened read-write never closes.",
+        "# exec makes Pi the job's process, so launchd's stop signal reaches it and the bridge can close open approvals first.",
+        'export PATH="/opt/homebrew/bin:$HOME/.local/bin:/usr/bin:/bin"',
+        "export ASTRO_DISCORD=1",
+        'cd "$HOME"',
+        'fifo="$HOME/.config/astro-discord/stdin.fifo"',
+        '[ -p "$fifo" ] || mkfifo -m 600 "$fifo"',
+        `exec ${pi} --mode rpc --no-session <> "$fifo"`,
+        "",
+    ].join("\n");
+}

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

@@ -0,0 +1,71 @@
+import { spawn } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { runScriptText } from "./launcher.ts";
+import { busyPath, cancelledApprovalText, interruptedTaskText, readOpenWork, writeOpenWork } from "./open-work.ts";
+
+describe("open work record", () => {
+    let dir: string;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), "astro-open-"));
+        process.env.ASTRO_DISCORD_DIR = dir;
+    });
+    afterEach(() => {
+        delete process.env.ASTRO_DISCORD_DIR;
+        rmSync(dir, { recursive: true, force: true });
+    });
+
+    it("exists only while something is open", () => {
+        const work = { since: "t", tasks: [{ specialist: "arcane", channelId: "1", messageId: "2", placeholderId: "3" }], approvals: [] };
+        writeOpenWork(work);
+        expect(readOpenWork()).toEqual(work);
+        writeOpenWork({ since: "t", tasks: [], approvals: [] });
+        expect(existsSync(busyPath())).toBe(false);
+        expect(readOpenWork()).toBeNull();
+        writeFileSync(busyPath(), "not json");
+        expect(readOpenWork()).toBeNull();
+    });
+
+    it("says why an approval was cancelled and a task interrupted", () => {
+        expect(cancelledApprovalText("restart")).toMatch(/bridge restarted before a decision, so nothing was run/);
+        expect(cancelledApprovalText("crash")).toMatch(/stopped unexpectedly/);
+        expect(interruptedTaskText("arcane", "restart")).toMatch(/^❌ \*\*arcane\*\* was interrupted: the bridge restarted\./);
+    });
+});
+
+describe("launcher", () => {
+    let home: string;
+    beforeEach(() => {
+        home = mkdtempSync(join(tmpdir(), "astro-launch-"));
+        mkdirSync(join(home, ".config", "astro-discord"), { recursive: true });
+    });
+    afterEach(() => rmSync(home, { recursive: true, force: true }));
+
+    it("keeps stdin open and hands the stop signal to Pi", async () => {
+        const out = join(home, "events");
+        const fakePi = join(home, "fake-pi.mjs");
+        writeFileSync(
+            fakePi,
+            [
+                "#!/usr/bin/env node",
+                `import { appendFileSync } from "node:fs";`,
+                `const log = (e) => appendFileSync(${JSON.stringify(out)}, e + "\\n");`,
+                `log("args " + process.argv.slice(2).join(" "));`,
+                `process.stdin.on("end", () => log("eof"));`,
+                `process.stdin.resume();`,
+                `process.on("SIGTERM", () => { log("term"); process.exit(0); });`,
+            ].join("\n"),
+        );
+        chmodSync(fakePi, 0o755);
+        const script = join(home, "run.sh");
+        writeFileSync(script, runScriptText(`${process.execPath} ${fakePi}`), { mode: 0o700 });
+        const child = spawn("/bin/sh", [script], { env: { HOME: home, PATH: process.env.PATH ?? "" }, stdio: "ignore" });
+        await new Promise((resolve) => setTimeout(resolve, 1500));
+        child.kill("SIGTERM");
+        const code = await new Promise<number | null>((resolve) => child.once("exit", resolve));
+        expect(code).toBe(0);
+        expect(readFileSync(out, "utf-8").trim().split("\n")).toEqual(["args --mode rpc --no-session", "term"]);
+    }, 15_000);
+});

package/extensions/astro-discord/open-work.ts

@@ -0,0 +1,73 @@
+import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDir } from "./config.ts";
+
+/** A running task as far as Discord shows it: the user's message and the bot's "working" reply. */
+export interface OpenTask {
+    specialist: string;
+    channelId: string;
+    messageId: string;
+    placeholderId?: string;
+}
+
+/** An approval request still waiting for a button. */
+export interface OpenApproval {
+    ticketId: string;
+    channelId: string;
+    messageId: string;
+    /** The user's message that carries the 🔒 reaction. */
+    userChannelId: string;
+    userMessageId: string;
+}
+
+/**
+ * What the bridge has open in Discord. Written to `busy.json` whenever it
+ * changes and removed when nothing is open, so a restart can wait for it and a
+ * new process can close what a crashed one left behind.
+ */
+export interface OpenWork {
+    since: string;
+    tasks: OpenTask[];
+    approvals: OpenApproval[];
+}
+
+export function busyPath(): string {
+    return join(configDir(), "busy.json");
+}
+
+export function writeOpenWork(work: OpenWork): void {
+    const path = busyPath();
+    if (work.tasks.length === 0 && work.approvals.length === 0) {
+        rmSync(path, { force: true });
+        return;
+    }
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(work, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+}
+
+/** The record a previous process left, or null when it closed everything. */
+export function readOpenWork(): OpenWork | null {
+    let raw: unknown;
+    try {
+        raw = JSON.parse(readFileSync(busyPath(), "utf-8"));
+    } catch {
+        return null;
+    }
+    const r = raw as Partial<OpenWork> | null;
+    if (!r || !Array.isArray(r.tasks) || !Array.isArray(r.approvals)) return null;
+    return { since: String(r.since ?? ""), tasks: r.tasks, approvals: r.approvals };
+}
+
+export type StopReason = "restart" | "crash";
+
+export function cancelledApprovalText(reason: StopReason): string {
+    return reason === "restart"
+        ? "🔌 Cancelled: the bridge restarted before a decision, so nothing was run. Ask again."
+        : "🔌 Cancelled: the bridge stopped unexpectedly before a decision, so nothing was run. Ask again.";
+}
+
+export function interruptedTaskText(specialist: string, reason: StopReason): string {
+    const why = reason === "restart" ? "the bridge restarted" : "the bridge stopped unexpectedly";
+    return `❌ **${specialist}** was interrupted: ${why}. Work it had already started may have finished; ask it to check the current state.`;
+}

package/extensions/astro-discord/setup.ts

@@ -14,6 +14,7 @@ import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { Writable } from "node:stream";
 import { type ChannelSettings, configDir, configPath, tokenPath, validateConfig } from "./config.ts";
+import { runScriptText } from "./launcher.ts";
 import { DiscordRest } from "./rest.ts";
 
 const LABEL = "com.astrofoundry.astro-discord";
@@ -180,7 +181,7 @@ async function main(): Promise<void> {
     const logFile = join(homedir(), "Library", "Logs", "astro-discord.log");
     writeFileSync(
         runScript,
-        `#!/bin/sh\n# Headless Pi host for the Discord bridge. Pi's RPC mode exits when stdin closes, so a pipe keeps it open.\nexport PATH="/opt/homebrew/bin:$HOME/.local/bin:/usr/bin:/bin"\nexport ASTRO_DISCORD=1\ncd "$HOME"\ntail -f /dev/null | exec ${pi} --mode rpc --no-session\n`,
+        runScriptText(pi),
         { mode: 0o700 },
     );
     const plist = `<?xml version="1.0" encoding="UTF-8"?>

package/package.json

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

package/skills/arcane/SKILL.md

@@ -36,7 +36,7 @@ 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. 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.
+- Private images (the registry refuses anonymous access, such as our own Grimoire builds) are left out of the table and the counts; the summary line counts them and `privateImages` lists them. Mention them only when the caller asks.
 
 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.
 

package/specialists/AGENTS.md

@@ -54,7 +54,7 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
 - 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.
+- `arcane update-report [--all]` is `lib/image-updates.ts` over `lib/registry.ts`: a fresh `images updates check --all`, then `projects list --all` for the stack and service of each image reference, then the registries' tag lists and manifest digests (anonymous bearer tokens from each registry's challenge; digests by HEAD, which Docker Hub does not count as a pull; lscr.io is read from ghcr.io). A floating or major-series tag is resolved to the release tag whose digest matches the running and the latest build, searching the newest tags of the three commonest release shapes; a fixed tag is compared with the newest tag of the same shape; a digest pin with the newest release. Checks older than one minute before the run count as stale and show as unknown. Private images (anonymous access refused with 401 or 403) are excluded from rows, counts, and table, listed in `privateImages`, and counted in the summary line. The table is fixed-width text for a code block, because Discord renders no Markdown tables.
 - `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

@@ -105,7 +105,7 @@ Check: `sudo -n -u specialist -H /usr/local/bin/specialist-cli arcane --caller t
 
 The `astro-discord` extension gives Discord users access to the specialists from a channel. It runs in a headless Pi host on Cortex (LaunchAgent `com.astrofoundry.astro-discord`, user `cortex`), never in interactive sessions.
 
-- Channels are configured one by one (`channels.<id>`): `trigger` is `always` (every message that names a specialist counts) or `mention` (only messages that start with `@Cortex` or reply to the bot); `specialists` is `*` or a list. A channel with one specialist needs no prefix: every message there is a task for it. In a channel with several, `dns list the zones` names the specialist; an addressed message without a name gets a reply asking for one. Threads inherit their parent channel's entry; unlisted channels are ignored. The bot replies at once with "<specialist> is working on your task" and shows the typing indicator until the answer replaces that reply. Reactions on your message: ⏳ running, 🔒 waiting for an owner's approval, ✅ done, ❌ failed. `help` shows the specialists you may use in that channel and the commands (`status` lists running tasks; owners in the admin channel also see the `config` commands). Each channel and specialist has one conversation: a reply to the bot's answer, or another task for that specialist within 30 minutes, continues it with everything the specialist saw before; otherwise a new one starts, and a task beginning with `new` forces that. Replied-to and forwarded messages (text, embeds, attachment names) travel with the task, so "check this" on a forwarded alert works. Image attachments on the message or on what it quotes (up to 4, 8 MiB each) are downloaded and passed to the specialist, which sees them; other file types are named only. Sessions live under `~/.config/astro-discord/sessions/<specialist>/` and are deleted after 7 days. Long answers arrive as a `.md` attachment.
+- Channels are configured one by one (`channels.<id>`): `trigger` is `always` (every message that names a specialist counts) or `mention` (only messages that start with `@Cortex` or reply to the bot); `specialists` is `*` or a list. A channel with one specialist needs no prefix: every message there is a task for it. In a channel with several, `dns list the zones` names the specialist; an addressed message without a name gets a reply asking for one. Threads inherit their parent channel's entry; unlisted channels are ignored. The bot replies at once with "<specialist> is working on your task" and shows the typing indicator until the answer replaces that reply. Reactions on your message: ⏳ running, 🔒 waiting for an owner's approval, ✅ done, ❌ failed. `help` shows the specialists you may use in that channel and the commands (`status` lists running tasks; owners in the admin channel also see the `config` commands). Each channel and specialist has one conversation: a reply to the bot's answer, or another task for that specialist within 30 minutes, continues it with everything the specialist saw before; otherwise a new one starts, and a task beginning with `new` forces that. Replied-to and forwarded messages (text, embeds, attachment names) travel with the task, so "check this" on a forwarded alert works. Image attachments on the message or on what it quotes (up to 4, 8 MiB each) are downloaded and passed to the specialist, which sees them; other file types are named only. Sessions live under `~/.config/astro-discord/sessions/<specialist>/` and are deleted after 7 days. Long answers arrive as a `.md` attachment. When the bridge restarts, open approval requests are marked cancelled and running tasks interrupted in Discord; ask again.
 - Access: `owners` may use every specialist and decide approvals; `access.<specialist>` lists extra users for that specialist; everyone else gets no reply. Owners change the configuration from the admin channel (`adminChannelId`) without a shell: `config show`, `config channel <#channel> <always|mention> <*|dns,edge>`, `config channel <#channel> remove`, `config access <specialist> add|remove <@user>`; the bot writes `~/.config/astro-discord/config.json` on Cortex, which is also editable by hand and re-read on every message. Deny the bot's role View Channel on channels it must never read; that is the boundary the map cannot provide.
 - Approvals: a risky call (anything with `--confirm`, plus writes such as record or zone deletes, Zitadel changes, Pomerium deploys, Arcane redeploys, service restarts) pauses the specialist and posts Approve/Deny buttons; only owners' clicks count; no decision within `approvalTimeoutMinutes` denies it. The specialist then reports the denial. Ambiguous tasks get a question back instead of an action.
 - Setup, as `cortex`: `d=$(mktemp -d) && cp ~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro/extensions/astro-discord/*.ts "$d" && node --disable-warning=ExperimentalWarning "$d/setup.ts"` (Node does not strip types inside `node_modules`, so the files are copied first) prompts for the bot token and the ids, checks each against Discord, and writes `~/.config/astro-discord/{token,config.json,run.sh}` and the LaunchAgent; it prints the `launchctl bootstrap` line. After a pi-astro update restart the bridge with `launchctl kickstart -k gui/$(id -u)/com.astrofoundry.astro-discord`. Log: `~/Library/Logs/astro-discord.log`.

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

@@ -100,7 +100,7 @@ describe("resolveRef", () => {
     });
 
     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("ghcr.io/astrofoundry/app:main", entry("A1", "A2"), registry, NOW)).toMatchObject({ status: "update", latest: "new build", private: true });
         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" });
@@ -120,17 +120,21 @@ describe("buildUpdateReport", () => {
                 { 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" },
+                { name: "ours", status: "running", updateInfo: { serviceUpdates: { api: { imageRef: "ghcr.io/astrofoundry/app:main" }, worker: { imageRef: "ghcr.io/astrofoundry/app:main" } } } },
             ],
         };
         const check = {
             "lscr.io/linuxserver/prowlarr:latest": entry("D1", "D2"),
             "nginx:1.31.4-alpine": entry("N", "N"),
             "busybox:latest": entry("B", "B"),
+            "ghcr.io/astrofoundry/app:main": entry("A1", "A2"),
         };
         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).toMatch(/^Fresh check 2026-09-25T18:30:00Z: 4 services in 5 stacks, 3 images\. 1 private images \(2 services\) excluded\./);
+        expect(report.privateImages).toEqual(["ghcr.io/astrofoundry/app:main"]);
+        expect(report.rows.some((r) => r.stack === "ours")).toBe(false);
         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 });

package/specialists/lib/image-updates.ts

@@ -34,6 +34,8 @@ export interface UpdateReport {
     checkedAt: string;
     stacks: number;
     images: number;
+    /** Private image references, excluded from `rows`, `counts`, and the table. */
+    privateImages: string[];
     counts: Record<UpdateStatus, number>;
     rows: UpdateRow[];
     table: string;
@@ -150,6 +152,8 @@ interface Resolution {
     action: string;
     note: string;
     latestDigest?: string;
+    /** The registry refused anonymous access: an image of our own, left out of the report. */
+    private?: boolean;
 }
 
 /** Resolves one image reference to running and latest versions from the fresh check and the registry's tags. */
@@ -175,7 +179,8 @@ export async function resolveRef(refText: string, entry: CheckEntry | undefined,
         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));
+        if (status === 401 || status === 403) return { ...digestOnly("private image, the registry needs credentials"), private: true };
+        return digestOnly(err instanceof Error ? err.message : String(err));
     }
 
     const digests = new Map<string, string | null>();
@@ -243,7 +248,7 @@ export async function resolveRef(refText: string, entry: CheckEntry | undefined,
         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" : "" };
+    return { kind, running, latest, status: "update", action: "pull", note: majorChange(running, latest) ? "major version change: read its release notes before pulling" : "" };
 }
 
 async function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
@@ -347,7 +352,9 @@ export async function buildUpdateReport(input: { check: unknown; projects: unkno
     await mapLimit(refs, CONCURRENCY, async (ref) => {
         resolved.set(ref, await resolveRef(ref, entries[ref], registry, input.startedAt));
     });
-    const rows: UpdateRow[] = services.map((s) => {
+    const privateImages = refs.filter((ref) => resolved.get(ref)?.private === true);
+    const listed = services.filter((s) => s.ref === null || !privateImages.includes(s.ref));
+    const rows: UpdateRow[] = listed.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("; ");
@@ -359,9 +366,10 @@ export async function buildUpdateReport(input: { check: unknown; projects: unkno
     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 excluded = privateImages.length === 0 ? "" : ` ${privateImages.length} private images (${services.length - listed.length} services) excluded.`;
     const summary =
-        `Fresh check ${checkedAt}: ${services.length} services in ${stacks} stacks, ${refs.length} images. ` +
+        `Fresh check ${checkedAt}: ${listed.length} services in ${stacks} stacks, ${refs.length - privateImages.length} images.${excluded} ` +
         `${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) };
+    return { checkedAt, stacks, images: refs.length - privateImages.length, privateImages, counts, rows: shown, table: renderTable(shown, summary) };
 }