@phnx-labs/agents-cli 1.20.76 → 1.20.78

package/dist/lib/hosts/remote-session-id.js

@@ -0,0 +1,84 @@
+/**
+ * Resolve a remote-created session id back to an interactive `--host` launcher.
+ *
+ * A headless `--host` run captures the remote-coined id from the followed log
+ * (the `--emit-session-id` marker — see session-marker.ts). An INTERACTIVE run
+ * has no followed log: the local TTY is wired straight through `sshStream`
+ * (stdio:'inherit'), so nothing can tap the stream for a marker without breaking
+ * the agent's raw-mode TUI. Instead we correlate by AGENT_LAUNCH_ID.
+ *
+ * The launcher forwards a launch id it controls (`--env AGENT_LAUNCH_ID=<id>`);
+ * the remote `agents run` adopts it (exec.ts `resolveLaunchId`), so the remote
+ * SessionStart hook records the agent's REAL session id under that exact key in
+ * `~/.agents/.cache/terminals/sessions/<pid>.json`. After the stream returns we
+ * do ONE ssh read of that dir and pick the record whose `launch_id` matches —
+ * the same launch-id join `agents sessions --active` uses locally
+ * (session/hook-sessions.ts), just across the SSH hop.
+ *
+ * This gives the interactive path a real per-agent id to register in the local
+ * session index and to reconnect against, for Codex/Kimi/Grok/Gemini — closing
+ * the gap RUSH-2033 left for every non-Claude agent (Claude still forces its own
+ * id up front and never reaches here).
+ */
+import { sshExec } from '../ssh-exec.js';
+/**
+ * Pick the real session id for `launchId` from the remote hook records.
+ *
+ * `recordsJson` is the newline-delimited JSON the remote read emits — one record
+ * per line (a `cat` of every `sessions/*.json`). Scan for the record whose
+ * `launch_id` matches and return its `session_id`; when several match (pid reuse,
+ * a lingering file) the NEWEST by `ts` wins, mirroring the local reader's
+ * keep-newest tie-break (session/hook-sessions.ts). Pure so the correlation is
+ * unit-testable from fixtures with no SSH. Returns undefined when no record
+ * carries the launch id (the hook hasn't landed yet, or a hookless harness).
+ */
+export function pickRemoteSessionId(recordsJson, launchId) {
+    if (!launchId)
+        return undefined;
+    let best;
+    for (const line of recordsJson.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(trimmed);
+        }
+        catch {
+            continue; // a partial/garbled line — skip, never throw
+        }
+        if (rec.launch_id !== launchId)
+            continue;
+        if (typeof rec.session_id !== 'string' || !rec.session_id)
+            continue;
+        const ts = typeof rec.ts === 'number' ? rec.ts : 0;
+        // Strict `>` so the FIRST record wins a tie — matches keepNewest (hook-sessions.ts).
+        if (!best || ts > best.ts)
+            best = { sid: rec.session_id, ts };
+    }
+    return best?.sid;
+}
+/**
+ * Read the remote hook-session dir over ssh and resolve the real session id the
+ * remote run recorded under `launchId`. One round-trip, best-effort: any ssh
+ * failure, a missing dir, or an absent record yields undefined — the caller then
+ * keeps the un-mapped run rather than a fabricated id.
+ *
+ * `$HOME` expands on the REMOTE login shell (never the local box). The glob is a
+ * literal path with no user input, so it is injection-safe; a `2>/dev/null` on a
+ * globless dir keeps the command quiet when the dir is empty or absent.
+ */
+export function resolveRemoteSessionId(target, launchId, timeoutMs = 6000) {
+    if (!launchId)
+        return undefined;
+    // `cat` every record onto its own line. `head -c` caps a runaway file; the
+    // trailing `true` keeps the pipeline's exit 0 even when the glob matches nothing.
+    const cmd = 'cat "$HOME"/.agents/.cache/terminals/sessions/*.json 2>/dev/null | head -c 1048576 || true';
+    const res = sshExec(target, cmd, { timeoutMs, multiplex: true });
+    if (res.code !== 0 && !res.stdout)
+        return undefined;
+    // Each record is a single-line JSON object; `cat` may run them together, so
+    // normalise `}{` boundaries onto separate lines before scanning.
+    const normalised = res.stdout.replace(/\}\s*\{/g, '}\n{');
+    return pickRemoteSessionId(normalised, launchId);
+}

package/dist/lib/hosts/run-target.d.ts

@@ -45,6 +45,8 @@ export interface HostPromptRun {
     name?: string;
     /** Resume an existing session on the host by concrete id. */
     resume?: string;
+    /** Explicit id for a new Claude session. */
+    sessionId?: string;
     /** Working directory on the host, already made remote-portable by the caller. */
     remoteCwd?: string;
     /** Stream progress and block until completion (default true). */
@@ -74,6 +76,8 @@ export interface HostPromptRun {
     /** Copy runtime credentials to the host before the run and shred them after. */
     copyCreds?: HostCredentials;
 }
+/** Resolve the id the remote host will adopt for a fresh Claude session. */
+export declare function resolveHostSessionId(agent: string, resume?: string, sessionId?: string): string | undefined;
 /**
  * Dispatch a headless prompt run onto a resolved host, then relate the run's
  * session id back to this launcher for EVERY agent — not just Claude.

package/dist/lib/hosts/run-target.js

@@ -53,6 +53,10 @@ export async function resolveHostRunTarget(name, opts = {}) {
         throw new HostResolutionError(`Unknown host "${name}". List hosts: agents hosts list`);
     return host;
 }
+/** Resolve the id the remote host will adopt for a fresh Claude session. */
+export function resolveHostSessionId(agent, resume, sessionId) {
+    return agent === 'claude' && !resume ? sessionId ?? randomUUID() : undefined;
+}
 /**
  * Dispatch a headless prompt run onto a resolved host, then relate the run's
  * session id back to this launcher for EVERY agent — not just Claude.
@@ -69,7 +73,7 @@ export async function resolveHostRunTarget(name, opts = {}) {
  * while the run continues).
  */
 export async function dispatchPromptToHost(host, opts) {
-    const forcedSessionId = opts.agent === 'claude' && !opts.resume ? randomUUID() : undefined;
+    const forcedSessionId = resolveHostSessionId(opts.agent, opts.resume, opts.sessionId);
     // Ask the remote to print its resolved id whenever we did NOT force one (every
     // non-Claude agent, and Claude-on-resume where the id is already known). No-op
     // when the run isn't followed — nothing tails the log to catch the marker.

package/dist/lib/hosts/session-index.js

@@ -14,7 +14,7 @@
  */
 import * as fs from 'fs';
 import { upsertSession } from '../session/db.js';
-import { SESSION_AGENTS } from '../session/types.js';
+import { isSessionTrackedAgent } from '../session/types.js';
 import { localLogPath, updateTask } from './tasks.js';
 import { parseSessionIdMarker } from './session-marker.js';
 import { deriveShortId } from '../session/short-id.js';
@@ -27,7 +27,7 @@ export function hostSessionMeta(task, ctx) {
     const id = task.sessionId;
     if (!id)
         return null;
-    if (!SESSION_AGENTS.includes(task.agent))
+    if (!isSessionTrackedAgent(task.agent))
         return null;
     return {
         id,
@@ -99,7 +99,7 @@ export function captureRemoteSessionId(task) {
  * surface and resume it by id.
  */
 export function registerInteractiveHostSession(ctx) {
-    if (!SESSION_AGENTS.includes(ctx.agent))
+    if (!isSessionTrackedAgent(ctx.agent))
         return;
     try {
         upsertSession({

package/dist/lib/menubar/MenubarHelper.app/Contents/Info.plist

@@ -8,6 +8,8 @@
     <string>com.phnx-labs.agents-menubar</string>
     <key>CFBundleName</key>
     <string>Agents Menu Bar</string>
+    <key>CFBundleIconFile</key>
+    <string>AppIcon</string>
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>

package/dist/lib/menubar/MenubarHelper.app/Contents/_CodeSignature/CodeResources

@@ -3,9 +3,22 @@
 <plist version="1.0">
 <dict>
 	<key>files</key>
-	<dict/>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<data>
+		Vd5nfogg74zSRNspluv4uvDecUA=
+		</data>
+	</dict>
 	<key>files2</key>
-	<dict/>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			DznVe0VgYOux7+B/aiHNgGYLCvSJKzgXDTPJn2jNkNg=
+			</data>
+		</dict>
+	</dict>
 	<key>rules</key>
 	<dict>
 		<key>^Resources/</key>

package/dist/lib/menubar/install-menubar.d.ts

@@ -14,6 +14,15 @@
  * migration (`installMenubarLaunchAgent` in migrate.ts) honors, so a disabled
  * menu bar never silently comes back on the next release.
  */
+/**
+ * Absolute path to the installed MenubarHelper executable if it exists on disk,
+ * else null. The desktop notifier (notify-desktop.ts) routes daemon
+ * notifications through this one-shot (`MenubarHelper --notify ...`) so they
+ * carry the agents-cli mark rather than the generic osascript icon. Null on
+ * non-darwin or when the helper is not installed (menu bar disabled, a Linux
+ * package, or a dev checkout without a built bundle).
+ */
+export declare function resolveInstalledMenubarExecutable(): string | null;
 /** True if the user explicitly disabled the menu bar (don't auto-enable on upgrade). */
 export declare function menubarDisabledByUser(): boolean;
 /** True if the launchd plist for the menu-bar service is installed. */

package/dist/lib/menubar/install-menubar.js

@@ -57,6 +57,20 @@ function readInstalledMenubarVersion() {
 function installedExecutablePath() {
     return path.join(installedAppPath(), 'Contents', 'MacOS', 'MenubarHelper');
 }
+/**
+ * Absolute path to the installed MenubarHelper executable if it exists on disk,
+ * else null. The desktop notifier (notify-desktop.ts) routes daemon
+ * notifications through this one-shot (`MenubarHelper --notify ...`) so they
+ * carry the agents-cli mark rather than the generic osascript icon. Null on
+ * non-darwin or when the helper is not installed (menu bar disabled, a Linux
+ * package, or a dev checkout without a built bundle).
+ */
+export function resolveInstalledMenubarExecutable() {
+    if (!onDarwin())
+        return null;
+    const exec = installedExecutablePath();
+    return fs.existsSync(exec) ? exec : null;
+}
 /** ~/Library/LaunchAgents/com.phnx-labs.agents-menubar.plist */
 function servicePlistPath() {
     return path.join(os.homedir(), 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);

package/dist/lib/menubar/notify-desktop.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 `MenubarHelper --notify` invocation —
+ * so the notification is attributed to that bundle and carries the agents-cli /
+ * Agentialized mark instead of the generic AppleScript icon. 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).
+ */
+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;
+}
+/** Argv for the MenubarHelper 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[];
+/**
+ * Fire a native desktop notification, branded via the MenubarHelper 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;

package/dist/lib/menubar/notify-desktop.js

@@ -0,0 +1,78 @@
+/**
+ * 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 `MenubarHelper --notify` invocation —
+ * so the notification is attributed to that bundle and carries the agents-cli /
+ * Agentialized mark instead of the generic AppleScript icon. 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 { spawn } from 'child_process';
+import * as os from 'os';
+import { resolveInstalledMenubarExecutable } from './install-menubar.js';
+/** Argv for the MenubarHelper one-shot notify mode. Exported for tests. */
+export function buildMenubarNotifyArgs(n) {
+    const args = ['--notify', '--title', n.title, '--body', n.body];
+    if (n.subtitle)
+        args.push('--subtitle', n.subtitle);
+    if (n.action)
+        args.push('--action', n.action);
+    return args;
+}
+/** AppleScript for the osascript degradation path. Exported for tests. */
+export function buildOsascriptNotifyArgs(n) {
+    const esc = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    let script = `display notification "${esc(n.body)}" with title "${esc(n.title)}"`;
+    if (n.subtitle)
+        script += ` subtitle "${esc(n.subtitle)}"`;
+    return ['-e', script];
+}
+/** Spawn one detached, best-effort notifier process; swallow async ENOENT. */
+function spawnDetachedQuiet(command, args) {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    // A missing binary (headless box with no osascript/notify-send, or a helper
+    // that vanished) arrives as an async 'error' event. Without this listener Node
+    // re-throws it as an uncaught exception and crashes the daemon — swallow it.
+    child.on('error', () => { });
+    child.unref();
+}
+/**
+ * Fire a native desktop notification, branded via the MenubarHelper companion on
+ * macOS. Best-effort — any failure is swallowed so a notification hiccup never
+ * blocks or crashes the daemon.
+ */
+export function notifyDesktop(n) {
+    const platform = os.platform();
+    try {
+        if (platform === 'darwin') {
+            const exec = resolveInstalledMenubarExecutable();
+            if (exec) {
+                // Branded path: the notification is attributed to MenubarHelper.app, so it
+                // shows the agents-cli mark and its click action is handled by the running
+                // helper's UNUserNotificationCenter delegate.
+                spawnDetachedQuiet(exec, buildMenubarNotifyArgs(n));
+                return;
+            }
+            // Companion app absent — degrade to osascript so delivery is preserved
+            // (generic icon; no click action). See the module header.
+            spawnDetachedQuiet('osascript', buildOsascriptNotifyArgs(n));
+            return;
+        }
+        if (platform === 'linux') {
+            spawnDetachedQuiet('notify-send', [n.title, n.body]);
+        }
+        // Other platforms: no native desktop notifier wired — no-op.
+    }
+    catch {
+        // Notification is best-effort; nothing to do.
+    }
+}

package/dist/lib/overdue.d.ts

@@ -22,10 +22,9 @@ export interface OverdueJob {
  *  missed. One-shot jobs are excluded — they fire at most once. */
 export declare function detectOverdueJobs(now?: Date): OverdueJob[];
 /**
- * Fire a native desktop notification. Best-effort — failures (missing
- * `osascript`/`notify-send`, no display, headless box) are swallowed so a
- * notification attempt can never take the daemon down.
+ * Fire a branded desktop notification listing the overdue jobs. Routed through
+ * the MenubarHelper companion (notify-desktop.ts) so it carries the agents-cli
+ * mark; clicking opens the runs folder (~/.agents/.history/runs). Best-effort —
+ * a missing notifier or absent display is swallowed and never crashes the daemon.
  */
-export declare function notifyDesktop(title: string, body: string): void;
-/** Fire a native desktop notification listing the overdue jobs. Best-effort. */
 export declare function notifyOverdue(jobs: OverdueJob[]): void;

package/dist/lib/overdue.js

@@ -12,9 +12,8 @@
  * `agents routines catchup` command that runs them on demand.
  */
 import { Cron } from 'croner';
-import * as os from 'os';
-import { spawn } from 'child_process';
 import { listJobs, getLatestRun, jobRunsOnThisDevice } from './routines.js';
+import { notifyDesktop } from './menubar/notify-desktop.js';
 // Tolerance between "expected fire" and "recorded run start" — accounts for
 // the small gap between the cron tick and when the runner writes meta.json.
 const GRACE_MS = 60_000;
@@ -77,50 +76,18 @@ export function detectOverdueJobs(now = new Date()) {
     return overdue;
 }
 /**
- * Fire a native desktop notification. Best-effort — failures (missing
- * `osascript`/`notify-send`, no display, headless box) are swallowed so a
- * notification attempt can never take the daemon down.
+ * Fire a branded desktop notification listing the overdue jobs. Routed through
+ * the MenubarHelper companion (notify-desktop.ts) so it carries the agents-cli
+ * mark; clicking opens the runs folder (~/.agents/.history/runs). Best-effort —
+ * a missing notifier or absent display is swallowed and never crashes the daemon.
  */
-export function notifyDesktop(title, body) {
-    const platform = os.platform();
-    try {
-        if (platform === 'darwin') {
-            const safeTitle = title.replace(/"/g, '\\"');
-            const safeBody = body.replace(/"/g, '\\"');
-            const child = spawn('osascript', ['-e', `display notification "${safeBody}" with title "${safeTitle}"`], { detached: true, stdio: 'ignore' });
-            // A missing binary surfaces as an async 'error' event, NOT a synchronous
-            // throw the try/catch would catch. Without a listener Node re-throws it as
-            // an uncaught exception and takes the whole daemon down. Swallow it — the
-            // notification is best-effort.
-            child.on('error', () => { });
-            child.unref();
-        }
-        else if (platform === 'linux') {
-            const child = spawn('notify-send', [title, body], {
-                detached: true,
-                stdio: 'ignore',
-            });
-            // Headless Linux boxes have no `notify-send` (libnotify-bin); its ENOENT
-            // arrives as an async 'error' event, not a throw. Without this listener
-            // the daemon crashes on every overdue routine and systemd restart-loops it
-            // (which also tears down the browser IPC socket). Swallow — best-effort.
-            child.on('error', () => { });
-            child.unref();
-        }
-    }
-    catch {
-        // Notification is best-effort; nothing to do.
-    }
-}
-/** Fire a native desktop notification listing the overdue jobs. Best-effort. */
 export function notifyOverdue(jobs) {
     if (jobs.length === 0)
         return;
-    const title = jobs.length === 1
-        ? `Routine overdue: ${jobs[0].name}`
-        : `${jobs.length} routines overdue`;
+    const title = jobs.length === 1 ? 'Routine overdue' : `${jobs.length} routines overdue`;
+    const subtitle = jobs.length === 1 ? jobs[0].name : undefined;
     const body = jobs.length === 1
         ? `Missed ${jobs[0].expectedAt.toLocaleString()}. Run: agents routines catchup`
         : `${jobs.map((j) => j.name).join(', ')} — agents routines catchup`;
-    notifyDesktop(title, body);
+    notifyDesktop({ title, subtitle, body, action: 'routines:list' });
 }

package/dist/lib/routine-notify.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Routine lifecycle desktop notifications (RUSH-2030).
+ *
+ * The daemon fires a branded notification when a scheduled routine starts and
+ * when it finishes (success or failure), routed through the MenubarHelper
+ * companion (notify-desktop.ts) so it carries the agents-cli mark.
+ *
+ * Anti-spam threshold (Acceptance Criteria #4 — "define a sensible threshold so
+ * users are not spammed"):
+ *   - Agent / workflow routines: notify on BOTH start and finish. These are the
+ *     runs whose output a user actually wants surfaced.
+ *   - Command routines (deterministic housekeeping — version checks, `git pull`,
+ *     notify shims that can fire every minute): notify only on FAILURE. A green
+ *     housekeeping run is noise; a broken one is worth a ping. No start ping.
+ *   - "Notable output" is folded into the single finish notification rather than
+ *     sent as a third message: on failure the error reason, on success the first
+ *     line of the run's report (the user-facing result) when the routine produced
+ *     one. One start + one finish per run — never a stream.
+ *
+ * The pure builders (`routineStartNotification` / `routineFinishNotification`)
+ * return `null` when the threshold says "don't notify", and are unit-tested; the
+ * `notifyRoutine*` wrappers do the filesystem read + dispatch for the daemon.
+ */
+import type { JobConfig, RunMeta } from './routines.js';
+import { type DesktopNotification } from './menubar/notify-desktop.js';
+type RoutineKind = 'agent' | 'workflow' | 'command';
+/** Which flavor of routine a config/meta describes — drives the notify threshold. */
+export declare function routineKind(r: Pick<JobConfig, 'agent' | 'workflow' | 'command'>): RoutineKind;
+/** "1m 20s" / "45s" / "2h 3m" from a millisecond duration, or null when unknown. */
+export declare function formatDuration(ms: number | undefined): string | null;
+/**
+ * First non-empty line of a run report, trimmed to a notification-sized snippet.
+ * This is the "notable output" surfaced on a successful finish — the routine's
+ * own user-facing result. Returns null for an empty/whitespace report so the
+ * caller falls back to a plain "Completed" body.
+ */
+export declare function notableSnippet(report: string | null | undefined, maxLen?: number): string | null;
+/**
+ * Notification for a routine START, or null when the threshold suppresses it
+ * (command-mode housekeeping). Clicking opens the runs folder
+ * (~/.agents/.history/runs).
+ */
+export declare function routineStartNotification(config: Pick<JobConfig, 'name' | 'agent' | 'workflow' | 'command'>): DesktopNotification | null;
+/**
+ * Notification for a routine that failed to even START — `executeJobDetached`
+ * threw before the child was spawned, so no run record and no finish will ever
+ * exist. The daemon fires the START notification unconditionally, so this closes
+ * the "exactly one start + one finish" invariant: the orphaned start gets its
+ * matching failure banner (RUSH-2030). Unlike a green finish this is never
+ * suppressed — a broken start is worth a ping for every routine kind, including
+ * command housekeeping. Clicking opens the runs folder (~/.agents/.history/runs)
+ * since there is no run report to open.
+ */
+export declare function routineStartFailedNotification(config: Pick<JobConfig, 'name' | 'agent' | 'workflow' | 'command'>, error: string): DesktopNotification;
+/**
+ * Notification for a routine FINISH, or null when the threshold suppresses it
+ * (a successful command-mode housekeeping run). Success carries the report's
+ * first line when present (the notable output); failure carries the reason.
+ * Clicking opens the run report/log when one is available, else the runs folder
+ * (~/.agents/.history/runs).
+ */
+export declare function routineFinishNotification(meta: Pick<RunMeta, 'jobName' | 'status' | 'exitCode' | 'errorMessage' | 'duration' | 'agent' | 'workflow' | 'command'>, opts?: {
+    report?: string | null;
+    artifactPath?: string | null;
+}): DesktopNotification | null;
+/** Daemon glue: fire the START notification for a triggered routine. Best-effort. */
+export declare function notifyRoutineStart(config: JobConfig): void;
+/**
+ * Daemon glue: fire the "failed to start" notification when a routine trigger
+ * threw before spawning a child. Pairs with the unconditional START ping so a
+ * pre-spawn failure never leaves an orphaned "Routine started". Best-effort.
+ */
+export declare function notifyRoutineStartFailed(config: JobConfig, error: string): void;
+/** Daemon glue: fire the FINISH notification for a completed run. Best-effort. */
+export declare function notifyRoutineFinish(meta: RunMeta): void;
+export {};