/**
 * Branded desktop notifications for daemon-originated events (RUSH-2030).
 *
 * The one place the daemon (overdue routines, heal, routine start/finish/output)
 * emits a native desktop notification. On macOS it routes through the installed
 * `MenubarHelper.app` companion — a one-shot `"AGI Menu" --notify` invocation —
 * so the notification is attributed to that bundle and carries the agents-cli
 * mark instead of the generic AppleScript icon. A banner carries two images: the
 * agents-cli app icon on the LEFT (the sender) and, when the event belongs to one
 * harness, that agent's avatar on the RIGHT (`agent`, rendered by
 * AgentAvatar.swift) — the same layout macOS gives a YouTube notification, app on
 * the left and the channel on the right. When the companion
 * app is not installed (menu bar disabled, a Linux package, a dev checkout), it
 * degrades to `osascript` so an overdue/heal notice is never silently lost — the
 * generic icon is the acceptable cost of preserving delivery, not a bug hidden by
 * a fallback. On Linux it uses `notify-send`; every other platform is a no-op.
 *
 * All delivery is best-effort and fully detached: a missing binary surfaces as an
 * async 'error' event (not a synchronous throw), so every spawn attaches an
 * 'error' listener — without it Node re-throws ENOENT as an uncaught exception and
 * takes the whole daemon down (the exact crash overdue.test.ts guards).
 */
import { type ChildProcess } from 'child_process';
export interface DesktopNotification {
    /** Bold first line. */
    title: string;
    /** Notification body text. */
    body: string;
    /** Secondary line under the title (macOS only). */
    subtitle?: string;
    /**
     * Deep-link the companion app runs when the notification is clicked. Encoded
     * as `<verb>:<arg>` — `open:/abs/path` opens a file (a run report or log) in the
     * default app; `routines:list` opens the runs folder (~/.agents/.history/runs)
     * in Finder. Best-effort and
     * macOS-only (osascript / notify-send have no click target). See routine-notify.ts.
     */
    action?: string;
    /**
     * Harness the notification is ABOUT (`claude`, `codex`, … — an `AgentId`).
     * macOS draws two images on a banner: the sending bundle's app icon on the
     * LEFT and `contentImage` on the RIGHT. The companion renders this id as the
     * right-hand avatar (AgentAvatar.swift), so a banner reads "agents-cli, about
     * Claude" the way a YouTube notification reads "YouTube, from this channel".
     * Omit it when no single harness owns the event (a daemon heal, a fan-out
     * across several agents) — the right slot then stays empty rather than
     * repeating the left one. macOS-only; osascript / notify-send carry no image.
     */
    agent?: string;
}
/** Argv for the "AGI Menu" one-shot notify mode. Exported for tests. */
export declare function buildMenubarNotifyArgs(n: DesktopNotification): string[];
/** AppleScript for the osascript degradation path. Exported for tests. */
export declare function buildOsascriptNotifyArgs(n: DesktopNotification): string[];
/**
 * Spawn one detached, best-effort notifier process with a bounded lifetime.
 *
 * The child is detached + unref'd so it never blocks the daemon, but — unlike a
 * pure fire-and-forget — it is supervised: a watchdog SIGKILLs it after
 * `timeoutMs` so a stalled notifier can never linger (the pile-up this fixes).
 * The common path (a sub-second post + self-exit) clears the watchdog on the
 * child's own 'exit', so the kill only ever fires for a genuinely hung child.
 *
 * `timeoutMs` is injectable so the bounded-lifetime behaviour is testable against
 * a real long-running child without a multi-second wait. Returns the child so a
 * caller/test can observe it; callers in this module ignore it.
 */
export declare function spawnDetachedQuiet(command: string, args: string[], timeoutMs?: number): ChildProcess;
/**
 * Fire a native desktop notification, branded via the "AGI Menu" companion on
 * macOS. Best-effort — any failure is swallowed so a notification hiccup never
 * blocks or crashes the daemon.
 */
export declare function notifyDesktop(n: DesktopNotification): void;
