pi-async-bash 0.1.0

package/src/monitor-session.ts

@@ -0,0 +1,164 @@
+/**
+ * The monitor session lifecycle — the tricky part of the bash_async_watch tool, lifted
+ * out of the tool action so its invariants are unit-testable through a fake
+ * MonitorSource (no real spawning, no real sockets).
+ *
+ * Responsibilities: stream each batch of new log lines as a notification,
+ * rate-limit a firehose, emit exactly one terminal event (on natural exit,
+ * kill, timeout, or firehose), and tear the source down. The tool just
+ * validates, builds a source, and hands it here.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { BackgroundRegistry } from "./state.ts";
+import {
+    DELIVER_FOLLOWUP,
+    EVENT,
+    MONITOR_MAX_LINES_PER_WINDOW,
+    MONITOR_RATE_WINDOW_MS,
+    type Job,
+    type UiContext,
+} from "./types.ts";
+import { renderSidebar } from "./registry.ts";
+import { startBackgroundJob, terminateJobSilently } from "./lifecycle.ts";
+import { followLines, type MonitorFollower } from "./monitor-follow.ts";
+import type { MonitorSource } from "./monitor-source.ts";
+import { completionSummary, sendTaskNotification, type TerminalStatus } from "./notify.ts";
+
+/**
+ * Wire a monitor's source to its event stream, terminal event, deadline, and
+ * teardown. The job must already be in the registry. Returns nothing — the
+ * session runs until the source ends, the deadline fires, or it is killed.
+ */
+export function startMonitorSession(args: {
+    pi: ExtensionAPI;
+    reg: BackgroundRegistry;
+    ctx: UiContext;
+    job: Job;
+    source: MonitorSource;
+    description: string;
+    persistent: boolean;
+    timeoutMs: number;
+}): void {
+    const { pi, reg, ctx, job, source, description, persistent, timeoutMs } = args;
+    const { id, logPath } = job;
+
+    let terminalEmitted = false;
+    let finishing = false;
+    let windowStart = Date.now();
+    let windowLines = 0;
+
+    // Stream events stay live but passive (delivered as a follow-up, no wake) —
+    // they carry data the agent is actively watching and surface on the agent's
+    // next natural turn without spawning an unsolicited one. The terminal
+    // notice (stream ended / stopped / failed) is its own <task-notification>
+    // (see finishMonitor), sent the moment the source ends.
+    const emitEvent = (lines: string[]): void => {
+        if (lines.length === 0) return;
+        pi.sendMessage(
+            {
+                customType: EVENT.monitorEvent,
+                content: `◉ ${description}\n${lines.join("\n")}`,
+                display: true,
+                details: { jobId: id, description, logPath, terminal: false },
+            },
+            DELIVER_FOLLOWUP
+        );
+    };
+
+    const follower: MonitorFollower = followLines(logPath, (lines) => {
+        if (terminalEmitted) return;
+
+        // Sliding-window firehose check.
+        const now = Date.now();
+        if (now - windowStart > MONITOR_RATE_WINDOW_MS) {
+            windowStart = now;
+            windowLines = 0;
+        }
+        windowLines += lines.length;
+
+        emitEvent(lines);
+
+        // Don't trip the firehose guard while draining the final flush.
+        if (!finishing && windowLines > MONITOR_MAX_LINES_PER_WINDOW) {
+            stopMonitor(
+                "killed",
+                `Monitor "${description}" stopped (too many events (>${MONITOR_MAX_LINES_PER_WINDOW}/${MONITOR_RATE_WINDOW_MS / 1000}s) — restart with a tighter filter)`
+            );
+        }
+    });
+
+    // job.stop: transient teardown invoked by the kill path. Tears down the
+    // source (closes the ws socket) — the follower is stopped *and flushed* by
+    // finishMonitor on the exit path (kill → process/socket close → exit →
+    // onExit), so a user-initiated kill stays lossless.
+    job.stop = source.stop;
+
+    /**
+     * Emit exactly one terminal <task-notification> for the monitor. Sent
+     * before the job is marked terminal (onExit runs ahead of completeJob), so
+     * the status/summary are explicit and eviction is left to completeJob.
+     */
+    const finishMonitor = (status: TerminalStatus, summary: string): void => {
+        if (terminalEmitted) return;
+        // Flush remaining lines first (while terminalEmitted is still false so
+        // the follower callback emits them), then the terminal notification.
+        finishing = true;
+        follower.stop(true);
+        terminalEmitted = true;
+        sendTaskNotification({ reg, pi, job, status, summary, evict: false });
+    };
+
+    /** Forced stop (timeout / firehose). Emits a terminal event, then routes
+     *  through the standard silent-kill path (which calls job.stop). */
+    function stopMonitor(status: TerminalStatus, summary: string): void {
+        finishMonitor(status, summary);
+        terminateJobSilently(reg, job);
+        renderSidebar(reg, ctx);
+    }
+
+    // Wire exit → terminal event. shouldNotify:false because the monitor owns
+    // its own terminal event (no double-fire from completeJob). Monitors stream their
+    // own output, so the prompt-stall heuristic is nonsensical here; the oversize
+    // cap is also suppressed for persistent watches (session-length log tails are
+    // expected to grow).
+    const jobAc = startBackgroundJob({
+        reg,
+        pi,
+        ctx,
+        job,
+        exit: source.exit,
+        shouldNotify: false,
+        disablePromptStall: true,
+        disableOversizeKill: persistent,
+        onExit: ({ code, signal }) => {
+            // A signal death (external kill) is the "stopped" summary, never
+            // "stream ended". Natural exits reuse completionSummary — the job
+            // carries name: description, so the summary names the watch.
+            if (job.status === "killed" || signal !== null) {
+                finishMonitor("killed", completionSummary(job, "killed"));
+            } else if (code === 0) {
+                finishMonitor("completed", completionSummary(job, "completed"));
+            } else {
+                // completeJob marks terminal after onExit — set the exit code
+                // now so completionSummary can name it.
+                job.exitCode = code ?? undefined;
+                finishMonitor("failed", completionSummary(job, "failed"));
+            }
+        },
+    });
+
+    // Deadline (skipped for persistent watches). Cleared when the job aborts
+    // (natural exit or kill) so a short monitor doesn't keep a live timer +
+    // closure alive for the whole timeout window.
+    if (!persistent) {
+        const deadline = setTimeout(() => {
+            stopMonitor(
+                "killed",
+                `Monitor "${description}" stopped (timeout after ${Math.round(timeoutMs / 1000)}s)`
+            );
+        }, timeoutMs);
+        (deadline as NodeJS.Timeout).unref();
+        jobAc.signal.addEventListener("abort", () => clearTimeout(deadline), { once: true });
+    }
+}

package/src/monitor-source.ts

@@ -0,0 +1,62 @@
+/**
+ * A monitor's event source, behind one seam.
+ *
+ * Both kinds of monitor produce the same thing the session needs: a log file
+ * whose appended lines are events, a promise that resolves when the source
+ * ends, and a teardown hook. Naming that contract lets the session (see
+ * monitor-session.ts) treat command and WebSocket monitors identically, and
+ * makes a third source (named pipe, file replay, …) a drop-in later.
+ */
+
+import { spawnWithFileOutput, type SpawnExit } from "./spawn.ts";
+import { openWsSource, type WsSpec } from "./monitor-ws.ts";
+
+export interface MonitorSource {
+    /** File the follower reads; appended lines become events. */
+    logPath: string;
+    /** OS pid backing the source, or 0 when there is no process (ws). */
+    pid: number;
+    /** Human-readable label shown in the sidebar / bash_async_list list. */
+    label: string;
+    /** Resolves when the source ends (process exit, or ws close as code-only). */
+    exit: Promise<SpawnExit>;
+    /** Teardown beyond the standard process kill (closes the ws socket). */
+    stop: () => void;
+}
+
+/** Command source: a shell child whose stdout is the event stream and whose
+ *  stderr is captured separately (readable, never emitted). */
+export function spawnCommandSource(args: {
+    command: string;
+    cwd: string;
+    logPath: string;
+    errPath: string;
+}): MonitorSource {
+    const spawned = spawnWithFileOutput({
+        command: args.command,
+        cwd: args.cwd,
+        logPath: args.logPath,
+        errPath: args.errPath,
+    });
+    return {
+        logPath: args.logPath,
+        pid: spawned.pid,
+        label: args.command,
+        exit: spawned.exit,
+        // The process group is killed by the standard kill path; nothing extra.
+        stop: () => {},
+    };
+}
+
+/** WebSocket source: each text frame is appended to the log as a line. */
+export function openWsMonitorSource(spec: WsSpec, logPath: string): MonitorSource {
+    const ws = openWsSource(spec, logPath);
+    return {
+        logPath,
+        pid: 0,
+        label: `ws ${spec.url}`,
+        // A socket has no signal — the close code maps to the code half.
+        exit: ws.exit.then((code) => ({ code, signal: null })),
+        stop: ws.close,
+    };
+}

package/src/monitor-ws.ts

@@ -0,0 +1,132 @@
+/**
+ * WebSocket source for the bash_async_watch tool.
+ *
+ * A ws monitor has no child process. Instead of spawning, it opens a WebSocket
+ * and appends each incoming frame as a line to the same `<jobId>.log` the
+ * line-follower reads — so ws and command monitors share one emitter path and
+ * the existing jobs-list / attach / Read surface works unchanged.
+ *
+ * Compatibility: uses the runtime's global `WebSocket` (stable since Node 22).
+ * When absent, isWsSupported() is false and the tool rejects the ws source with
+ * an actionable error rather than crashing.
+ */
+
+import { closeSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface WsSpec {
+    url: string;
+    protocols?: string[];
+}
+
+export interface WsSource {
+    /** Resolves when the socket closes (0 = clean close, 1 = error/abnormal). */
+    exit: Promise<number>;
+    /** Close the socket. Idempotent. */
+    close: () => void;
+}
+
+/** True when the runtime provides a global WebSocket constructor. */
+export function isWsSupported(): boolean {
+    return typeof (globalThis as { WebSocket?: unknown }).WebSocket === "function";
+}
+
+/**
+ * Open `spec.url`, appending each event as a line to `logPath`. The log file is
+ * created (truncated) up front so the follower has something to stat. Returns
+ * an exit promise (resolved on close) and a close handle.
+ *
+ * Throws synchronously if WebSocket is unsupported or construction fails — the
+ * caller surfaces that as a tool error.
+ */
+export function openWsSource(spec: WsSpec, logPath: string): WsSource {
+    if (!isWsSupported()) {
+        throw new Error(
+            "WebSocket is not available in this runtime (needs Node 22+). " +
+                "Use a command source instead, e.g. " +
+                `command: 'websocat ${spec.url}' or 'wscat -c ${spec.url}'.`
+        );
+    }
+
+    // Ensure the log dir exists (a ws monitor may be the first background job of
+    // the session, so LOG_DIR may not have been created by a spawn yet), then
+    // hold one appendable fd open for the socket's lifetime — one writeSync per
+    // frame instead of an open/write/close trio.
+    mkdirSync(dirname(logPath), { recursive: true });
+    const logFd = openSync(logPath, "w");
+    let fdClosed = false;
+    const closeFd = (): void => {
+        if (fdClosed) return;
+        fdClosed = true;
+        try {
+            closeSync(logFd);
+        } catch {
+            /* already closed */
+        }
+    };
+
+    const append = (line: string): void => {
+        if (fdClosed) return;
+        try {
+            writeSync(logFd, line.endsWith("\n") ? line : `${line}\n`);
+        } catch {
+            /* best-effort: a vanished log dir shouldn't take down the socket */
+        }
+    };
+
+    const WS = (globalThis as { WebSocket: typeof WebSocket }).WebSocket;
+    const ws = new WS(spec.url, spec.protocols);
+
+    let settled = false;
+    let resolveExit!: (code: number) => void;
+    const exit = new Promise<number>((resolve) => {
+        resolveExit = resolve;
+    });
+    const settle = (code: number): void => {
+        if (settled) return;
+        settled = true;
+        closeFd();
+        resolveExit(code);
+    };
+
+    ws.addEventListener("message", (ev: MessageEvent) => {
+        const data: unknown = ev.data;
+        if (typeof data === "string") {
+            append(data);
+        } else if (data instanceof ArrayBuffer) {
+            append(`[binary frame, ${data.byteLength} bytes]`);
+        } else if (data && typeof (data as { byteLength?: number }).byteLength === "number") {
+            append(`[binary frame, ${(data as { byteLength: number }).byteLength} bytes]`);
+        } else {
+            append("[non-text frame]");
+        }
+    });
+
+    ws.addEventListener("error", () => {
+        append("[websocket error]");
+        // Some implementations fire error without a following close.
+        try {
+            ws.close();
+        } catch {
+            /* already closing */
+        }
+        settle(1);
+    });
+
+    ws.addEventListener("close", (ev: CloseEvent) => {
+        append(`[socket closed: code ${ev.code}${ev.reason ? ` ${ev.reason}` : ""}]`);
+        settle(ev.code === 1000 || ev.code === 1005 ? 0 : 1);
+    });
+
+    return {
+        exit,
+        close() {
+            try {
+                ws.close();
+            } catch {
+                /* already closed */
+            }
+            settle(0);
+        },
+    };
+}

package/src/monitoring.ts

@@ -0,0 +1,170 @@
+/**
+ * Stall detection for background jobs.
+ *
+ * Watches a job's log file and warns the agent when output stops growing while
+ * the tail looks like an interactive prompt, or kills the job when output
+ * exceeds the size cap. Progress streaming lives in output.ts (pollFileTail).
+ */
+
+import { openSync, readSync, closeSync, statSync as fsStatSync } from "node:fs";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+    DELIVER_FOLLOWUP,
+    DELIVER_STEER,
+    EVENT,
+    MAX_LOG_BYTES,
+    STALL_CHECK_INTERVAL_MS,
+    STALL_TAIL_BYTES,
+    STALL_THRESHOLD_MS,
+} from "./types.ts";
+import { buildTaskNotification } from "./notify.ts";
+import { describeJob } from "./format.ts";
+
+// --- Stall watcher -------------------------------------------------------
+
+/**
+ * Detect a stalled job. When the output file:
+ *   1. exceeds MAX_LOG_BYTES, call onOversize and report the job terminated;
+ *   2. has not grown for STALL_THRESHOLD_MS and its tail matches an interactive
+ *      prompt pattern, send a bg-stall warning.
+ *
+ * Callers MUST invoke the returned cancel on completion to clear the interval.
+ */
+export function watchStalls(args: {
+    jobId: string;
+    command: string;
+    /** Job name (bash/bash_async `description`); falls back to the command. */
+    name?: string;
+    logPath: string;
+    pi: ExtensionAPI;
+    onOversize?: () => void;
+    /** Skip the interactive-prompt stall heuristic (used for monitors). */
+    disablePromptStall?: boolean;
+    /** Skip the oversize auto-kill (used for persistent monitors). */
+    disableOversizeKill?: boolean;
+}): () => void {
+    let lastSize = 0;
+    let lastGrowth = Date.now();
+    let lastPromptCheckSize = -1;
+    let cancelled = false;
+
+    const tick = () => {
+        if (cancelled) return;
+        try {
+            const { size } = fsStatSync(args.logPath);
+
+            if (size > MAX_LOG_BYTES && !args.disableOversizeKill) {
+                cancelled = true;
+                if (args.onOversize) args.onOversize();
+                args.pi.sendMessage(
+                    {
+                        customType: EVENT.stall,
+                        content: `⚠️ Background job ${args.jobId} exceeded ${MAX_LOG_BYTES / (1024 * 1024)} MiB output. Terminated.`,
+                        display: true,
+                        details: { jobId: args.jobId, logPath: args.logPath, command: args.command },
+                    },
+                    DELIVER_FOLLOWUP
+                );
+                return;
+            }
+
+            if (size > lastSize) {
+                lastSize = size;
+                lastGrowth = Date.now();
+            } else if (
+                !args.disablePromptStall &&
+                Date.now() - lastGrowth >= STALL_THRESHOLD_MS &&
+                size !== lastPromptCheckSize
+            ) {
+                // Output is static and past the stall threshold. Read the tail
+                // once per size — re-reading identical bytes every tick is pure
+                // waste, since the prompt verdict cannot change until it grows.
+                lastPromptCheckSize = size;
+                const fd = openSync(args.logPath, "r");
+                try {
+                    const readStart = Math.max(0, size - STALL_TAIL_BYTES);
+                    const toRead = Math.min(size, STALL_TAIL_BYTES);
+                    const buf = Buffer.alloc(toRead);
+                    readSync(fd, buf, 0, toRead, readStart);
+                    const tail = buf.toString("utf-8", 0, toRead);
+                    if (looksLikePrompt(tail)) {
+                        cancelled = true;
+                        sendStallPrompt(args.pi, args.jobId, describeJob(args.name, args.command), args.logPath, tail);
+                        return;
+                    }
+                } finally {
+                    closeSync(fd);
+                }
+            }
+        } catch {
+            /* File may not exist yet — retry next tick. */
+        }
+        schedule();
+    };
+    // Re-arm with a fresh timer each tick (rather than refresh()) so the
+    // watcher also works under node:test mock timers. Global setTimeout —
+    // a node:timers named import is snapshotted before mock.timers.enable.
+    let timer: NodeJS.Timeout;
+    const schedule = () => {
+        timer = setTimeout(tick, STALL_CHECK_INTERVAL_MS);
+        timer.unref();
+    };
+    schedule();
+
+    return () => {
+        cancelled = true;
+        clearTimeout(timer);
+    };
+}
+
+// --- Prompt pattern matching ---------------------------------------------
+
+/** Patterns that identify an interactive prompt. */
+export const PROMPT_PATTERNS = [
+    /\(y\/n\)/i,
+    /\[y\/n\]/i,
+    /\(yes\/no\)/i,
+    /\b(?:Do you|Would you|Shall I|Are you sure|Ready to)\b.*\? *$/i,
+    /Press (any key|Enter)/i,
+    /Continue\?/i,
+    /Overwrite\?/i,
+];
+
+/** True when the last line of the tail matches a prompt pattern. */
+export function looksLikePrompt(tail: string): boolean {
+    const lastLine = tail.trimEnd().split("\n").pop() ?? "";
+    return PROMPT_PATTERNS.some((p) => p.test(lastLine));
+}
+
+/**
+ * Send the interactive-prompt stall warning: Claude Code's <task-notification>
+ * shape WITHOUT a <status> tag (CC omits it deliberately — the job is still
+ * running), followed by the output tail and remediation guidance as plain
+ * text, all as ONE message content. Delivered like a completion (steer +
+ * triggerTurn). Does NOT touch the job's `notified` latch — a later real
+ * completion must still notify.
+ */
+function sendStallPrompt(
+    pi: ExtensionAPI,
+    jobId: string,
+    description: string,
+    logPath: string,
+    tail: string
+): void {
+    const summary = `Async command "${description}" appears to be waiting for interactive input`;
+    const content =
+        buildTaskNotification({ taskId: jobId, outputFile: logPath, summary }) +
+        `\nLast output:\n${tail.trimEnd()}\n\n` +
+        `The command is likely blocked on an interactive prompt. Kill this task and re-run ` +
+        `with piped input (e.g., \`echo y | command\`) or a non-interactive flag if one exists.`;
+
+    pi.sendMessage(
+        {
+            customType: EVENT.taskNotification,
+            content,
+            display: true,
+            details: { jobId, logPath, summary },
+        },
+        DELIVER_STEER
+    );
+}

package/src/notify.ts

@@ -0,0 +1,140 @@
+/**
+ * Task-completion notifications — Claude Code's <task-notification> engine.
+ *
+ * Every backgrounded job that reaches a terminal state enqueues its OWN
+ * <task-notification> XML message, exactly once, the moment it exits. There
+ * is no hold-and-flush and no coalescing window: pi's steer delivery queues
+ * the message while the agent is streaming and delivers it at the next
+ * tool-call boundary (CC's 'next' priority), or starts a turn when the agent
+ * is idle (triggerTurn: true).
+ *
+ * Exactly-once is enforced by the job's `notified` latch — a check-and-set
+ * done BEFORE the send, so any path that already surfaced the outcome (a
+ * bash_async_list output/attach read, a deliberate kill) suppresses the notification.
+ * A terminal job that has been notified is evicted from the live registry;
+ * its output log stays on disk and the notification carries the path.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DELIVER_STEER, EVENT, type Job } from "./types.ts";
+import type { BackgroundRegistry } from "./state.ts";
+import { forget } from "./registry.ts";
+import { describeJob } from "./format.ts";
+
+/** Terminal statuses a <task-notification> can carry. */
+export type TerminalStatus = "completed" | "failed" | "killed";
+
+/** Escape the XML special characters CC escapes inside element text. */
+export function escapeXml(s: string): string {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/**
+ * Build Claude Code's exact <task-notification> XML block. The <tool_use_id>
+ * line is included only when a toolUseId is present; the <status> line is
+ * omitted deliberately for stall warnings (CC parity).
+ */
+export function buildTaskNotification(args: {
+    taskId: string;
+    toolUseId?: string;
+    outputFile: string;
+    status?: TerminalStatus;
+    summary: string;
+}): string {
+    const lines = [
+        "<task-notification>",
+        `<task_id>${escapeXml(args.taskId)}</task_id>`,
+        ...(args.toolUseId ? [`<tool_use_id>${escapeXml(args.toolUseId)}</tool_use_id>`] : []),
+        `<output_file>${escapeXml(args.outputFile)}</output_file>`,
+        ...(args.status ? [`<status>${args.status}</status>`] : []),
+        `<summary>${escapeXml(args.summary)}</summary>`,
+        "</task-notification>",
+    ];
+    return lines.join("\n");
+}
+
+/**
+ * Claude Code's exact completion summary for a terminal job. `status`
+ * overrides job.status for callers that notify before the job is marked
+ * terminal (the monitor exit path).
+ */
+export function completionSummary(job: Job, status?: TerminalStatus): string {
+    const s = status ?? (job.status as TerminalStatus);
+    const desc = describeJob(job.name, job.command);
+    if (job.kind === "monitor") {
+        if (s === "killed") return `Monitor "${desc}" stopped`;
+        if (s === "failed") return `Monitor "${desc}" script failed (exit ${job.exitCode ?? "unknown"})`;
+        return `Monitor "${desc}" stream ended`;
+    }
+    if (s === "killed") return `Async command "${desc}" was stopped`;
+    if (s === "failed") return `Async command "${desc}" failed with exit code ${job.exitCode ?? "unknown"}`;
+    return `Async command "${desc}" completed${job.exitCode != null ? ` (exit code ${job.exitCode})` : ""}`;
+}
+
+/**
+ * Set the notified latch (Claude Code's markTaskNotified). Idempotent. Called
+ * by every path that surfaces a job's outcome WITHOUT the notification: kill
+ * paths (before the kill, so the exit handler skips notifying) and terminal
+ * reads (bash_async_list output / attach).
+ */
+export function markNotified(job: Job): void {
+    job.notified = true;
+}
+
+/**
+ * Send a terminal job's <task-notification>, exactly once. The latch is set
+ * BEFORE the send, so a concurrent consumer can never produce a duplicate;
+ * if the send itself throws, the notification is lost rather than retried
+ * (exactly-once), and the terminal+notified job lingers until the lazy sweep
+ * in `bash_async_list list`.
+ *
+ * On success the job is evicted from the live registry (terminal + notified)
+ * unless `evict: false` — the monitor path sends before the job is marked
+ * terminal and lets completeJob evict instead.
+ *
+ * Returns true when the notification was sent.
+ */
+export function sendTaskNotification(args: {
+    reg: BackgroundRegistry;
+    pi: ExtensionAPI;
+    job: Job;
+    /** Explicit terminal status when the job isn't marked terminal yet. */
+    status?: TerminalStatus;
+    /** Explicit summary (monitors compose their own). */
+    summary?: string;
+    evict?: boolean;
+}): boolean {
+    const { reg, pi, job } = args;
+    if (job.notified) return false;
+    job.notified = true;
+    const status = args.status ?? (job.status as TerminalStatus);
+    const summary = args.summary ?? completionSummary(job, status);
+
+    try {
+        pi.sendMessage(
+            {
+                customType: EVENT.taskNotification,
+                content: buildTaskNotification({
+                    taskId: job.id,
+                    toolUseId: job.toolCallId || undefined,
+                    outputFile: job.logPath,
+                    status,
+                    summary,
+                }),
+                display: true,
+                details: {
+                    jobId: job.id,
+                    status,
+                    summary,
+                    outputFile: job.logPath,
+                },
+            },
+            DELIVER_STEER
+        );
+    } catch (err) {
+        console.error("[bg-tasks] task notification failed:", err);
+        return false;
+    }
+    if (args.evict !== false) forget(reg, job);
+    return true;
+}