@fitchmultz/pi-subagents 0.52.4 → 0.52.6

package/dist/pi-intercom/broker/parked.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "crypto";
 import { nativePeerId } from "../session-targets.js";
-import { writeMessage } from "./framing.js";
+import { isRecord } from "../../shared/unknown.js";
+import { validateIntercomMessageSize, writeMessage } from "./framing.js";
 export function reachable(target) {
     const socket = target?.socket;
     return socket !== undefined && !socket.destroyed && socket.writable && !socket.writableEnded;
@@ -8,6 +9,17 @@ export function reachable(target) {
 function requested(id) {
     return typeof id === "string" && /^[a-zA-Z0-9_-]{8,80}$/.test(id) ? id : undefined;
 }
+function wakeResponse(msg) {
+    if (typeof msg.requestId === "string" && isRecord(msg.result)) {
+        if (msg.result.status === "requested") {
+            return { id: msg.requestId, result: { status: "requested" } };
+        }
+        if (msg.result.status === "failed" && typeof msg.result.reason === "string") {
+            return { id: msg.requestId, result: { status: "failed", reason: msg.result.reason } };
+        }
+    }
+    throw new Error("Invalid wake response");
+}
 /** A fenced child keeps its identity and queued input; it never departs while parked. */
 export class ParkedSessions {
     sessions;
@@ -16,6 +28,20 @@ export class ParkedSessions {
         this.sessions = sessions;
         this.deliver = deliver;
     }
+    handle(socket, id, msg) {
+        if (msg.type === "park" || msg.type === "unpark") {
+            this.park(socket, id, msg.type === "park");
+            return true;
+        }
+        if (msg.type === "wake_result") {
+            const owner = this.sessions.get(id);
+            if (owner) {
+                this.respond(owner, msg);
+            }
+            return true;
+        }
+        return false;
+    }
     park(socket, id, on) {
         const session = this.sessions.get(id);
         if (on && session?.parking === true) {
@@ -57,6 +83,7 @@ export class ParkedSessions {
     }
     /** Flushes a restored child's input and re-sends wakes owed to a (re)registered main. */
     registered(id, previous) {
+        this.registeredWake(previous);
         this.flush(id, previous?.parked?.retained ?? []);
         for (const child of this.sessions.values()) {
             if (nativePeerId(child.info.rootSessionId ?? "") === id) {
@@ -64,6 +91,26 @@ export class ParkedSessions {
             }
         }
     }
+    registeredWake(previous) {
+        const main = previous && this.main(previous);
+        const attempt = previous?.parked?.attempt;
+        if (reachable(main) && attempt?.owner === main.socket) {
+            writeMessage(main.socket, { type: "wake_registered", requestId: attempt.id });
+        }
+    }
+    capabilities(msg) {
+        return {
+            ...(msg.wakeResults === 1 ? { wakeResults: 1 } : {}),
+            ...(msg.wakeNotices === 1 ? { wakeNotices: 1 } : {}),
+        };
+    }
+    features(msg) {
+        return {
+            parking: msg.parking === true,
+            wakeResults: msg.wakeResults === 1,
+            wakeNotices: msg.wakeNotices === 1,
+        };
+    }
     /** A transport handoff, not a departure: no session_left and queued input stays. */
     closed(session) {
         const { parked } = session;
@@ -81,12 +128,21 @@ export class ParkedSessions {
         return [...this.sessions.values()].every(({ parked }) => parked?.closed === true && parked.retained.length === 0);
     }
     retain(target, from, message) {
-        target?.parked?.retained.push({ from, message });
-        if (target) {
+        target?.parked?.retained.push({ from, message, sender: this.sessions.get(from.id)?.socket });
+        if (target && this.waking(message)) {
             this.wake(target);
         }
         return target?.parked !== undefined;
     }
+    queueReason(target, messageId) {
+        const last = target?.parked?.lastFailure;
+        const reason = last === undefined
+            ? "Queued for a parked child; delivery awaits its return."
+            : `Queued for a parked child; the last wake failed: ${last} The message may still arrive after a later wake.`;
+        return validateIntercomMessageSize({ type: "delivery_queued", messageId, reason }) === null
+            ? reason
+            : "Queued for a parked child; its last wake failed. Inspect the agent run for details.";
+    }
     /** Reads of an exited parked child go to its main, which answers from captured history. */
     reader(id) {
         const child = this.sessions.get(id);
@@ -95,10 +151,71 @@ export class ParkedSessions {
     // Passive breadcrumbs and topic updates wait for a genuine wake; they never spawn the child.
     wake(child) {
         const main = this.main(child);
-        const wakes = child.parked?.retained.some(({ message }) => message.passive !== true && message.delivery !== "passive" && message.topic === undefined);
-        if (main && child.parked?.closed === true && wakes === true) {
+        const parked = child.parked;
+        if (!reachable(main) ||
+            parked?.closed !== true ||
+            !parked.retained.some(({ message }) => this.waking(message))) {
+            return;
+        }
+        if (!main.wakeResults) {
             writeMessage(main.socket, { type: "wake", sessionId: child.info.id });
+            return;
+        }
+        if (parked.attempt?.owner === main.socket) {
+            parked.attempt.retry = true;
+            return;
+        }
+        const attempt = {
+            id: randomUUID(),
+            owner: main.socket,
+            count: parked.retained.length,
+            retry: false,
+        };
+        parked.attempt = attempt;
+        writeMessage(main.socket, { type: "wake", sessionId: child.info.id, requestId: attempt.id });
+    }
+    waking(message) {
+        return (message.passive !== true && message.delivery !== "passive" && message.topic === undefined);
+    }
+    /** Only the main sent this request can report it, and only while that child stays parked. */
+    respond(owner, msg) {
+        const { id, result } = wakeResponse(msg);
+        const child = [...this.sessions.values()].find((peer) => peer.parked?.attempt?.id === id &&
+            peer.parked.attempt.owner === owner.socket &&
+            this.main(peer) === owner);
+        const parked = child?.parked;
+        const attempt = parked?.attempt;
+        if (!child || !parked || !attempt) {
+            return;
+        }
+        parked.attempt = undefined;
+        if (result.status === "failed") {
+            parked.lastFailure = result.reason;
+            for (const retained of parked.retained.slice(0, attempt.count)) {
+                this.notify(child, retained, result.reason);
+            }
+        }
+        if (attempt.retry) {
+            this.wake(child);
+        }
+    }
+    notify(child, { from, sender, message }, reason) {
+        const origin = this.sessions.get(from.id);
+        if (message.expectsReply !== true ||
+            origin?.wakeNotices !== true ||
+            origin.socket !== sender ||
+            !reachable(origin)) {
+            return;
         }
+        const frame = {
+            type: "wake_failed",
+            sessionId: child.info.id,
+            messageId: message.id,
+            reason,
+        };
+        writeMessage(origin.socket, validateIntercomMessageSize(frame) === null
+            ? frame
+            : { ...frame, reason: "Wake failed; inspect the agent run for details." });
     }
     main(child) {
         const main = this.sessions.get(nativePeerId(child.info.rootSessionId ?? ""));

package/dist/pi-intercom/broker/spawn.js

@@ -44,9 +44,13 @@ export function getBrokerSpawnOptions() {
 function toError(error) {
     return error instanceof Error ? error : new Error(errorMessage(error));
 }
-export async function spawnBrokerIfNeeded(brokerCommand, brokerArgs) {
+export async function spawnBrokerIfNeeded(brokerCommand, brokerArgs, warning = (message) => {
+    if (message !== undefined) {
+        console.warn(message);
+    }
+}) {
     prepareBrokerSocketPath();
-    await warnPreviousBroker();
+    warning(await previousBrokerWarning());
     if (await isBrokerRunning()) {
         return;
     }
@@ -130,20 +134,20 @@ function readLivePid(pidPath) {
     }
     return isBrokerPidReused(pid, raw) ? null : pid;
 }
-async function warnPreviousBroker() {
+async function previousBrokerWarning() {
     const previousSockets = getPreviousBrokerSocketPaths();
     for (const socketPath of previousSockets) {
         // Migration probes are sequential and never register or send to old peers.
         // oxlint-disable-next-line no-await-in-loop
         if (isOwnedBrokerSocket(socketPath) && (await checkOneSocket(socketPath))) {
-            console.warn("An older agent-directory Intercom broker is still running. Its peers are not part of shared same-user discovery until they reload with the updated extension. Existing sessions and accepted work are untouched; no legacy fallback is used.");
-            return;
+            return "An older agent-directory Intercom broker is still running. Its peers are not part of shared same-user discovery until they reload with the updated extension. Existing sessions and accepted work are untouched; no legacy fallback is used.";
         }
     }
     const previousPid = readLivePid(join(getPiAgentDir(), "intercom", "broker.pid"));
     if (previousPid !== null) {
-        console.warn(`Older Intercom broker PID ${previousPid} may still own accepted work. Its peers need to reload with the updated extension to join shared same-user discovery. Nothing was stopped or replaced; no legacy fallback is used.`);
+        return `Older Intercom broker PID ${previousPid} may still own accepted work. Its peers need to reload with the updated extension to join shared same-user discovery. Nothing was stopped or replaced; no legacy fallback is used.`;
     }
+    return undefined;
 }
 export async function stopUnhealthyBrokerBeforeSpawn() {
     if (await checkSocketConnectable()) {

package/dist/pi-intercom/config.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { getPiAgentDir } from "./agent-dir.js";
 import { isRecord, isUnknownArray } from "./validation.js";
+import { errorMessage } from "../shared/unknown.js";
 const defaults = {
     brokerCommand: process.execPath,
     brokerArgs: [],
@@ -65,7 +66,7 @@ function configuredTimeout(parsed, key) {
     }
     return value;
 }
-export function loadConfig() {
+export function loadConfig(report = console.error) {
     const configPath = join(getPiAgentDir(), "intercom", "config.json");
     if (!existsSync(configPath)) {
         return { ...defaults };
@@ -87,7 +88,7 @@ export function loadConfig() {
         };
     }
     catch (error) {
-        console.error(`Failed to load intercom config at ${configPath}:`, error);
+        report(`Failed to load intercom config at ${configPath}: ${errorMessage(error)}. Using defaults.`);
         return { ...defaults };
     }
 }

package/dist/pi-intercom/connection.js

@@ -17,10 +17,13 @@ export class IntercomConnection {
     lifecycle;
     config;
     hooks;
-    constructor(lifecycle, config, hooks) {
+    wakes = new Map();
+    reporter;
+    constructor(lifecycle, config, hooks, reporter) {
         this.lifecycle = lifecycle;
         this.config = config;
         this.hooks = hooks;
+        this.reporter = reporter;
     }
     get active() {
         return this.client;
@@ -157,6 +160,17 @@ export class IntercomConnection {
             next.respondLast(request.requestId, { error: asError(error).message });
         }
     }
+    receive(next, from, message) {
+        const ctx = this.lifecycle.live();
+        if (this.client !== next || !ctx) {
+            return;
+        }
+        const owner = `inbound:${from.id}:${message.id}`;
+        this.hooks
+            .incoming(ctx, from, message)
+            .then(() => this.reporter.recover(owner))
+            .catch((error) => this.reporter.report(owner, `Intercom inbound ${message.id} from ${from.id} failed: ${asError(error).message}`));
+    }
     createClient() {
         const next = new IntercomClient({
             sendTimeoutMs: this.config.sendTimeoutMs,
@@ -167,17 +181,48 @@ export class IntercomConnection {
             this.answerLast(next, request);
         });
         next.on("message", (from, message) => {
-            const ctx = this.lifecycle.live();
-            if (this.client !== next || !ctx) {
-                return;
-            }
-            this.hooks.incoming(ctx, from, message).catch((error) => {
-                console.error("Intercom inbound delivery failed:", error);
-            });
+            this.receive(next, from, message);
         });
         next.on("wake", (peer) => {
             if (this.client === next) {
-                this.hooks.wake(peer);
+                void this.hooks.wake(peer).catch(() => {
+                    // Old brokers cannot receive wake outcomes.
+                });
+            }
+        });
+        next.on("wake_request", (peer, requestId) => {
+            if (this.client === next) {
+                const registered = new AbortController();
+                this.wakes.set(requestId, registered);
+                void this.hooks
+                    .wake(peer, registered.signal)
+                    .catch((error) => ({
+                    status: "failed",
+                    reason: asError(error).message,
+                }))
+                    .then((result) => {
+                    if (this.client === next && !registered.signal.aborted) {
+                        next.wakes.respond(requestId, result);
+                    }
+                })
+                    .finally(() => {
+                    if (this.wakes.get(requestId) === registered) {
+                        this.wakes.delete(requestId);
+                    }
+                })
+                    .catch(() => {
+                    // A lost broker transport retains the input for the next registration.
+                });
+            }
+        });
+        next.on("wake_registered", (requestId) => {
+            if (this.client === next) {
+                this.wakes.get(requestId)?.abort();
+            }
+        });
+        next.on("wake_failed", (peer, messageId, reason) => {
+            if (this.client === next) {
+                this.hooks.wakeFailed(peer, messageId, reason);
             }
         });
         next.on("session_left", (id) => {
@@ -191,6 +236,7 @@ export class IntercomConnection {
                 return;
             }
             this.hooks.disconnected(error);
+            this.cancelWakes();
             this.client = null;
             this.lifecycle.transport(null);
             this.clearReconnect();
@@ -204,7 +250,14 @@ export class IntercomConnection {
     async connect(ctx, generation, sessionId) {
         const next = this.createClient();
         try {
-            await spawnBrokerIfNeeded(this.config.brokerCommand, this.config.brokerArgs);
+            await spawnBrokerIfNeeded(this.config.brokerCommand, this.config.brokerArgs, (message) => {
+                if (message === undefined) {
+                    this.reporter.recover("older-broker");
+                }
+                else {
+                    this.reporter.report("older-broker", message, "warning");
+                }
+            });
             await next.connect(await this.lifecycle.registration(this.hooks.pendingAsks()), nativePeerId(sessionId));
             if (!this.lifecycle.live(ctx, generation)) {
                 await next.disconnect();
@@ -214,6 +267,7 @@ export class IntercomConnection {
             this.lifecycle.transport(next.sessionId, next.supportsGuardedDelivery);
             this.syncIdentity(ctx.sessionManager.getSessionId());
             this.attempt = 0;
+            this.reporter.recover("connection-cleanup");
             return next;
         }
         catch (error) {
@@ -222,7 +276,7 @@ export class IntercomConnection {
             }
             // A failed registration still owns its socket.
             await next.disconnect().catch((cleanupError) => {
-                console.error("Intercom failed connection cleanup:", cleanupError);
+                this.reporter.report("connection-cleanup", `Intercom failed connection cleanup: ${asError(cleanupError).message}`);
             });
             throw asError(error);
         }
@@ -275,6 +329,7 @@ export class IntercomConnection {
     }
     async shutdown() {
         this.clearTimers();
+        this.cancelWakes();
         // The bounded launcher attempt is joined before socket shutdown.
         await Promise.allSettled([this.connecting]);
         if (this.client) {
@@ -282,6 +337,12 @@ export class IntercomConnection {
             this.client = null;
         }
     }
+    cancelWakes() {
+        for (const wake of this.wakes.values()) {
+            wake.abort();
+        }
+        this.wakes.clear();
+    }
 }
 export async function resolveConnectedTarget(active, name) {
     const sessions = await active.listSessions();

package/dist/pi-intercom/inbound-delivery.js

@@ -1,5 +1,6 @@
 import { requestedDelivery } from "./inbound-record.js";
 import { runCooperatively } from "../shared/cooperative.js";
+import { asError } from "./validation.js";
 /** Owns cooperative inbound batches, restoration and the flush timer. */
 export class InboundDeliveryOwner {
     timer = null;
@@ -74,9 +75,7 @@ export class InboundDeliveryOwner {
         this.clearTimer();
         this.timer = setTimeout(() => {
             this.timer = null;
-            this.flush(generation)?.catch((error) => {
-                console.error("Intercom inbound delivery failed:", error);
-            });
+            this.flush(generation)?.catch((error) => this.hooks.reporter.report("inbound-delivery", `Intercom inbound delivery failed: ${asError(error).message}`));
         }, delayMs);
         this.timer.unref();
     }
@@ -105,9 +104,15 @@ export class InboundDeliveryOwner {
                 this.journal.queued().length > 0) {
                 this.schedule(0);
             }
+            this.hooks.reporter.recover("inbound-cleanup");
         };
-        task.then(finish, finish).catch((error) => {
-            console.error("Intercom inbound cleanup failed:", error);
+        task
+            .then(() => {
+            this.hooks.reporter.recover("inbound-delivery");
+            finish();
+        }, finish)
+            .catch((error) => {
+            this.hooks.reporter.report("inbound-cleanup", `Intercom inbound cleanup failed: ${asError(error).message}`);
         });
         return task;
     }

package/dist/pi-intercom/index.js

@@ -13,6 +13,7 @@ import { IntercomTools } from "./tools.js";
 import { IntercomSessionEvents } from "./session-events.js";
 import { registerIntercomTools } from "./tool-registration.js";
 import { isParkRequest, PARK, PARKED_HISTORY, WAKE } from "../shared/parking.js";
+import { BackgroundReporter } from "../shared/background-reporting.js";
 /** The agent runtime answers for its exited parked child from the captured native session. */
 function parkedHistory(pi, peer) {
     let history;
@@ -24,9 +25,43 @@ function parkedHistory(pi, peer) {
     });
     return history ?? Promise.reject(new Error("No agent runtime owns parked history."));
 }
-export default function piIntercomExtension(pi) {
-    const config = loadConfig();
+function wakeParked(pi, peer, signal) {
+    let result;
+    pi.events.emit(WAKE, {
+        peer,
+        signal,
+        reply: (outcome) => {
+            result = outcome;
+        },
+    });
+    return (result ??
+        Promise.resolve({ status: "failed", reason: "No agent runtime owns this parked child." }));
+}
+function setupReporting(pi) {
+    let configError;
+    const config = loadConfig((message) => {
+        configError = message;
+    });
     const lifecycle = new IntercomLifecycle(pi, config, readIntercomLineage());
+    const reporter = new BackgroundReporter(() => lifecycle.live());
+    let pendingConfigError = configError;
+    pi.on("session_start", (_event, ctx) => {
+        reporter.start();
+        if (pendingConfigError !== undefined) {
+            if (ctx.hasUI) {
+                ctx.ui.notify(pendingConfigError, "warning");
+            }
+            else {
+                console.error(pendingConfigError);
+            }
+            pendingConfigError = undefined;
+        }
+    });
+    pi.on("session_shutdown", () => reporter.shutdown());
+    return { config, lifecycle, reporter };
+}
+export default function piIntercomExtension(pi) {
+    const { config, lifecycle, reporter } = setupReporting(pi);
     const replies = new ReplyTracker(config.askTimeoutMs);
     const journal = new InboundJournal(pi, lifecycle, replies);
     const wait = new ReplyWait(lifecycle, config.askTimeoutMs);
@@ -43,13 +78,13 @@ export default function piIntercomExtension(pi) {
             wait.reject(new Error(`Disconnected while waiting for reply: ${error.message}`, { cause: error }));
         },
         parkedHistory: (peer) => parkedHistory(pi, peer.id),
-        wake: (peer) => {
-            pi.events.emit(WAKE, peer);
-        },
-    });
+        wake: (peer, signal) => wakeParked(pi, peer, signal),
+        wakeFailed: (peer, messageId, reason) => wait.wakeFailed(peer, messageId, reason),
+    }, reporter);
     const delivery = new InboundDeliveryOwner(pi, lifecycle, journal, {
         replies,
         syncStatus: () => connection.syncStatus(),
+        reporter,
     });
     lifecycle.registerContextEvents(() => connection.syncStatus());
     const inbound = new IntercomInbound(lifecycle, config, {

package/dist/pi-intercom/outbound.js

@@ -3,7 +3,7 @@ import { resolveConnectedTarget, resolvePeerHealth, } from "./connection.js";
 import { RECIPIENT_TURN_FAILED_ATTACHMENT, } from "./runtime-types.js";
 import { errorMessage } from "./validation.js";
 import { formatAttachments } from "./message-format.js";
-import { AskDeliveryError, failureDetails, RecoveryError, } from "./tool-results.js";
+import { AskDeliveryError, failureDetails, RecoveryError, WakeFailedError, } from "./tool-results.js";
 import { sendOptions, toolError, toolText } from "./tool-arguments.js";
 export class IntercomOutbound {
     owners;
@@ -142,6 +142,15 @@ export class IntercomOutbound {
         return toolText(`**Reply from ${to}:**\n${text}${attachments !== undefined && attachments.length > 0 ? formatAttachments(attachments) : ""}`);
     }
     askFailure(error, to, questionId) {
+        if (error instanceof WakeFailedError) {
+            return toolError(`The parked child could not be woken: ${error.message} Your ask is still queued and may arrive after a later wake. Check the recipient before sending it again.`, failureDetails("wake_failed", [{ action: "list" }, { action: "status" }], {
+                error: true,
+                messageId: questionId,
+                accepted: true,
+                delivered: false,
+                queued: true,
+            }));
+        }
         if (error instanceof AskDeliveryError) {
             const result = this.deliveryFailure(to, error.result);
             return { ...result, details: { ...result.details, error: true } };
@@ -272,17 +281,25 @@ export class IntercomOutbound {
             this.owners.replies.markReplied(target.message.id);
             this.markActivity();
             this.recordSent(sender, { text: body, replyTo: target.message.id }, result);
-            return toolText(`Reply sent to ${sender}`, {
-                messageId: result.id,
-                delivered: true,
-                replyTo: target.message.id,
-                reasonCode: "reply_sent",
-            });
+            return this.replySent(sender, target.message.id, result);
         }
         catch (error) {
             return this.replyFailure(error, replyTo);
         }
     }
+    replySent(sender, replyTo, result) {
+        const queued = result.queued === true;
+        return toolText(queued
+            ? `Reply queued for ${sender} (${result.reason ?? "queued"})`
+            : `Reply sent to ${sender}`, {
+            messageId: result.id,
+            accepted: result.accepted,
+            delivered: result.delivered,
+            queued,
+            replyTo,
+            reasonCode: queued ? "message_queued" : "reply_sent",
+        });
+    }
     replyFailure(error, replyTo) {
         const reason = error instanceof RecoveryError ? error.code : "reply_failed";
         const actions = reason === "no_pending_reply"

package/dist/pi-intercom/reply-wait.js

@@ -1,5 +1,5 @@
 import { asError } from "./validation.js";
-import { AskDeliveryError, RecoveryError } from "./tool-results.js";
+import { AskDeliveryError, RecoveryError, WakeFailedError } from "./tool-results.js";
 /** One correlated blocking wait; admitted before send so a fast reply cannot race it. */
 export class ReplyWait {
     waiter = null;
@@ -23,6 +23,11 @@ export class ReplyWait {
             this.reject(new Error(`Reply peer disconnected before answering: ${id}`));
         }
     }
+    wakeFailed(peer, messageId, reason) {
+        if (this.waiter?.from === peer && this.waiter.replyTo === messageId) {
+            this.reject(new WakeFailedError(reason));
+        }
+    }
     receive(sender, message, onMatch) {
         const waiter = this.waiter;
         if (!waiter || sender.id !== waiter.from || message.replyTo !== waiter.replyTo) {

package/dist/pi-intercom/tool-results.js

@@ -27,6 +27,8 @@ export class AskDeliveryError extends Error {
         this.result = result;
     }
 }
+export class WakeFailedError extends Error {
+}
 export function throwIfToolError(result) {
     if (result.isError !== true) {
         return result;

package/dist/pi-intercom/types.d.ts

@@ -1,3 +1,9 @@
+export type WakeResult = {
+    readonly status: "requested";
+} | {
+    readonly status: "failed";
+    readonly reason: string;
+};
 export interface SessionInfo {
     readonly id: string;
     readonly name?: string;

package/dist/shared/background-reporting.js

@@ -0,0 +1,72 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getPiAgentDir } from "../pi-intercom/agent-dir.js";
+/** One active failure per owner. Recovery is established by the owner, not by the reporter. */
+export class BackgroundReporter {
+    episodes = new Map();
+    context;
+    shuttingDown = false;
+    headless = false;
+    constructor(context) {
+        this.context = context;
+    }
+    start() {
+        this.shuttingDown = false;
+    }
+    shutdown() {
+        try {
+            this.headless = this.context()?.hasUI === false;
+        }
+        catch {
+            this.headless = false;
+        }
+        this.shuttingDown = true;
+    }
+    recover(owner) {
+        this.episodes.delete(owner);
+    }
+    published(owner, message) {
+        if (owner !== undefined) {
+            this.episodes.set(owner, message);
+        }
+    }
+    repeated(owner, message) {
+        return owner !== undefined && this.episodes.get(owner) === message;
+    }
+    report(owner, message, severity = "error") {
+        if (this.repeated(owner, message)) {
+            return;
+        }
+        if (this.shuttingDown && this.headless) {
+            console.error(message);
+            this.published(owner, message);
+            return;
+        }
+        try {
+            const ctx = this.context();
+            if (!this.shuttingDown && ctx) {
+                if (ctx.hasUI) {
+                    ctx.ui.notify(message, severity);
+                }
+                else {
+                    console.error(message);
+                }
+                this.published(owner, message);
+                return;
+            }
+        }
+        catch {
+            // A context may be invalidated between its owner's check and notification.
+        }
+        // Pi may have already stopped its renderer during session_shutdown. Never write to the terminal.
+        try {
+            const dir = path.join(getPiAgentDir(), "intercom");
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+            fs.appendFileSync(path.join(dir, "background-errors.log"), `${new Date().toISOString()} ${message}\n`, { mode: 0o600 });
+            this.published(owner, message);
+        }
+        catch {
+            // No terminal write is safe here; the diagnostic store itself may be unavailable.
+        }
+    }
+}