@astrofoundry/pi-astro 0.28.1 → 0.29.1

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/extensions/specialist-gate/approvals.test.ts

@@ -13,8 +13,15 @@ describe("approvals", () => {
         expect(isRisky("identity", ["zitadel", "DELETE", "/v2/users/1"])).toBe(true);
         expect(isRisky("identity", ["dmz", "deploy-config"])).toBe(true);
         expect(isRisky("arcane", ["projects", "list"])).toBe(false);
-        expect(isRisky("arcane", ["projects", "redeploy", "mealie"])).toBe(true);
-        expect(isRisky("arcane", ["gitops", "sync", "arcane", "--yes"])).toBe(true);
+        expect(isRisky("arcane", ["projects", "redeploy", "mealie"])).toBe(false);
+        expect(isRisky("arcane", ["projects", "upgrade", "media", "sonarr", "--yes"])).toBe(false);
+        expect(isRisky("arcane", ["gitops", "sync", "arcane", "--yes"])).toBe(false);
+        expect(isRisky("arcane", ["projects", "upgrade", "--help"])).toBe(false);
+        expect(isRisky("arcane", ["projects", "down", "media"])).toBe(true);
+        expect(isRisky("arcane", ["--json", "projects", "delete", "media"])).toBe(true);
+        expect(isRisky("arcane", ["volumes", "remove", "mealie_mealie-pgdata"])).toBe(true);
+        expect(isRisky("arcane", ["system", "upgrade"])).toBe(true);
+        expect(isRisky("edge", ["vps", "reboot", "--confirm", "--help"])).toBe(false);
         expect(isRisky("proxmox", ["guests"])).toBe(false);
         expect(isRisky("proxmox", ["set", "107", "memory=768"])).toBe(true);
         expect(isRisky("proxmox", ["shutdown", "107", "--confirm"])).toBe(true);

package/extensions/specialist-gate/index.ts

@@ -20,12 +20,13 @@ export const APPROVAL_TOKEN_ENV = "ASTRO_APPROVAL_TOKEN";
  * the writes that do not need `--confirm` in a terminal session.
  */
 export const RISKY: Readonly<Record<string, readonly RegExp[]>> = {
+    // Destructive or hard to undo only: upgrades, redeploys, restarts, and syncs are routine and run on the caller's request.
     arcane: [
-        /^(projects|stacks)\s+(up|down|redeploy|restart|stop|delete|remove|rm|destroy|upgrade)\b/,
-        /^containers\s+(stop|restart|kill|remove|rm|delete)\b/,
+        /^(projects|stacks)\s+(down|delete|remove|rm|destroy)\b/,
+        /^containers\s+(remove|rm|delete)\b/,
         /^(images|volumes|networks)\s+(prune|remove|rm|delete)\b/,
         /^system\s+(prune|upgrade)\b/,
-        /^gitops\s+(sync|delete|update|import)\b/,
+        /^gitops\s+delete\b/,
     ],
     identity: [/^zitadel\s+(DELETE|POST|PUT|PATCH)\b/, /^dmz\s+(deploy-config|pomerium-restart|render|lego-renew)\b/],
     network: [/^unifi\s+policy-(create|update|delete)\b/],
@@ -37,8 +38,11 @@ export const RISKY: Readonly<Record<string, readonly RegExp[]>> = {
 };
 
 export function isRisky(service: string, args: readonly string[]): boolean {
+    // A help lookup prints usage and changes nothing, whatever command it names.
+    if (args.includes("--help") || args.includes("-h")) return false;
     if (args.includes("--confirm")) return true;
-    const joined = args.join(" ");
+    // Flags placed before the command (`--json projects delete x`) must not hide it from the patterns.
+    const joined = args.filter((a) => !a.startsWith("-")).join(" ");
     return (RISKY[service] ?? []).some((pattern) => pattern.test(joined));
 }
 

package/package.json

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

package/specialists/AGENTS.md

@@ -73,7 +73,7 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
 
 ## Chat bridges
 
-`extensions/astro-discord/` runs specialists for Discord messages through `runAgent` and passes `ASTRO_APPROVAL_URL`/`ASTRO_APPROVAL_TOKEN` to the child. The gate consults `RISKY` in `extensions/specialist-gate/index.ts` and blocks on a ticket until an owner decides; keep `RISKY` in step with the wrappers when a new interrupting or destructive command appears (every `--confirm` command is covered by construction).
+`extensions/astro-discord/` runs specialists for Discord messages through `runAgent` and passes `ASTRO_APPROVAL_URL`/`ASTRO_APPROVAL_TOKEN` to the child. The gate consults `RISKY` in `extensions/specialist-gate/index.ts` and blocks on a ticket until an owner decides (`--help`/`-h` never counts; flags are ignored when matching, so they cannot hide a command; Arcane lists only destructive actions since 2026-09-26, because a routine upgrade the caller asked for made them approve the same thing twice); keep `RISKY` in step with the wrappers when a new interrupting or destructive command appears (every `--confirm` command is covered by construction).
 
 ## Next
 

package/specialists/README.md

@@ -105,9 +105,9 @@ 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.
+- Approvals: a risky call (anything with `--confirm`, plus writes such as record or zone deletes, Zitadel changes, Pomerium deploys, service restarts, and on Arcane only destructive actions: `down`, deletes, prunes, image, volume, or network removal, `system upgrade`, `gitops delete`; help lookups never ask) pauses the specialist and posts Approve/Deny buttons; only owners' clicks count; no decision within `approvalTimeoutMinutes` denies it. The specialist then reports the denial. Ambiguous tasks get a question back instead of an action.
 - Setup, as `cortex`: `d=$(mktemp -d) && cp ~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro/extensions/astro-discord/*.ts "$d" && node --disable-warning=ExperimentalWarning "$d/setup.ts"` (Node does not strip types inside `node_modules`, so the files are copied first) prompts for the bot token and the ids, checks each against Discord, and writes `~/.config/astro-discord/{token,config.json,run.sh}` and the LaunchAgent; it prints the `launchctl bootstrap` line. After a pi-astro update restart the bridge with `launchctl kickstart -k gui/$(id -u)/com.astrofoundry.astro-discord`. Log: `~/Library/Logs/astro-discord.log`.
 - Discord side: application `Cortex` with a bot, Message Content Intent enabled, invited with scopes `bot` and `applications.commands` and permissions View Channel, Send Messages, Attach Files, Read Message History, Add Reactions.