@phnx-labs/agents-cli 1.20.76 → 1.20.77

package/dist/lib/heal.js

@@ -30,7 +30,7 @@ import { repairPluginManifestFile } from './plugin-marketplace.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { spawn } from 'child_process';
+import { notifyDesktop } from './menubar/notify-desktop.js';
 // ─── diff → selection mapping ────────────────────────────────────────────────
 // Which ResourceSelection key each healable diff kind writes through. `rules`
 // re-syncs via the whole-memory channel (not name-scoped); `promptcuts` is not
@@ -68,10 +68,13 @@ export function summarizeHeal(r) {
     return parts.length > 0 ? parts.join(', ') : 'nothing to heal';
 }
 /**
- * Fire a native desktop notification when a background heal did something
- * noteworthy. Best-effort — missing `osascript`/`notify-send` or no display is
- * swallowed. Silent when the pass auto-fixed everything and nothing needs the
- * operator (no point pinging them for routine self-healing).
+ * Fire a branded desktop notification when a background heal did something
+ * noteworthy. Routed through the MenubarHelper companion (notify-desktop.ts) so
+ * it carries the agents-cli mark; clicking opens the runs folder
+ * (~/.agents/.history/runs, via the `routines:list` action the companion
+ * understands). Best-effort — a missing
+ * notifier or no display is swallowed. Silent when the pass auto-fixed everything
+ * and nothing needs the operator (no point pinging them for routine self-healing).
  */
 export function notifyHeal(r) {
     const needsAttention = r.skippedPlugins.length;
@@ -79,27 +82,12 @@ export function notifyHeal(r) {
     if (needsAttention === 0 && healed === 0)
         return;
     const title = needsAttention > 0
-        ? `agents: ${needsAttention} plugin${needsAttention === 1 ? '' : 's'} need attention`
+        ? `${needsAttention} plugin${needsAttention === 1 ? '' : 's'} need attention`
         : 'agents: auto-healed config gaps';
     const body = needsAttention > 0
         ? `${summarizeHeal(r)}. Run: agents doctor --fix`
         : summarizeHeal(r);
-    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' });
-            child.unref();
-        }
-        else if (platform === 'linux') {
-            const child = spawn('notify-send', [title, body], { detached: true, stdio: 'ignore' });
-            child.unref();
-        }
-    }
-    catch {
-        // Notification is best-effort; nothing to do.
-    }
+    notifyDesktop({ title, body, action: 'routines:list' });
 }
 // ─── central plugin layer (version-independent, runs once per heal) ──────────
 /**

package/dist/lib/hosts/dispatch.d.ts

@@ -20,6 +20,15 @@ import { type HostCredentials } from './credentials.js';
  * remainder. Any other path (absolute or relative) is quoted verbatim.
  */
 export declare function remoteCdPrefix(remoteCwd?: string): string;
+/**
+ * Merge the resolved actor's provenance env UNDER a caller-supplied env, so every
+ * remote `agents …` invocation forwards `AGENTS_ACTOR*` / `GIT_*` across the SSH
+ * hop. Without it the remote re-resolves the actor from the ORIGINATING box's
+ * `SSH_CONNECTION` (the wrong IP) and mis-credits the run to the shared machine or
+ * `UNRESOLVED@<host>` (RUSH-2028). A caller-supplied value wins on any key
+ * collision, mirroring `buildExecEnv`'s `...options.env` precedence (exec.ts).
+ */
+export declare function withActorEnv(env?: Record<string, string>): Record<string, string>;
 /**
  * Launch a detached login-shell command in its own Unix session/process group.
  *

package/dist/lib/hosts/dispatch.js

@@ -12,8 +12,9 @@ import { randomUUID } from 'crypto';
 import { sshExec, sshStream, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from './types.js';
 import { ensureHostReady } from './ready.js';
-import { remoteShellFor } from './remote-cmd.js';
+import { remoteShellFor, posixEnvExports } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
+import { resolveActor, actorEnv } from '../actor.js';
 import { saveTask, updateTask, terminalPatch } from './tasks.js';
 import { followHostTask } from './progress.js';
 import { wrapHostCommandWithCredentials } from './credentials.js';
@@ -56,6 +57,17 @@ export function remoteCdPrefix(remoteCwd) {
         return `cd "$HOME"/${shellQuote(rest)} && `;
     return `cd ${shellQuote(remoteCwd)} && `;
 }
+/**
+ * Merge the resolved actor's provenance env UNDER a caller-supplied env, so every
+ * remote `agents …` invocation forwards `AGENTS_ACTOR*` / `GIT_*` across the SSH
+ * hop. Without it the remote re-resolves the actor from the ORIGINATING box's
+ * `SSH_CONNECTION` (the wrong IP) and mis-credits the run to the shared machine or
+ * `UNRESOLVED@<host>` (RUSH-2028). A caller-supplied value wins on any key
+ * collision, mirroring `buildExecEnv`'s `...options.env` precedence (exec.ts).
+ */
+export function withActorEnv(env) {
+    return { ...actorEnv(resolveActor()), ...(env ?? {}) };
+}
 /**
  * Launch a detached login-shell command in its own Unix session/process group.
  *
@@ -174,10 +186,14 @@ async function launchDetached(host, target, opts) {
     const id = randomUUID().slice(0, 8);
     const remoteLog = `${REMOTE_DIR}/${id}.log`;
     const remoteExit = `${REMOTE_DIR}/${id}.exit`;
-    // Inner command run under a login shell so PATH resolves `agents`.
+    // Inner command run under a login shell so PATH resolves `agents`. Export the
+    // resolved actor provenance first so the detached remote run inherits it
+    // instead of re-resolving from this box's SSH_CONNECTION (RUSH-2028).
     const invocation = ['agents', ...opts.forwardedArgs].map(shellQuote).join(' ');
     const cwd = remoteCdPrefix(opts.remoteCwd);
-    let inner = `${cwd}${invocation} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
+    const actorExports = posixEnvExports(withActorEnv());
+    const prelude = actorExports ? `${actorExports}; ` : '';
+    let inner = `${prelude}${cwd}${invocation} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
     if (opts.copyCreds) {
         inner = wrapHostCommandWithCredentials(inner, opts.copyCreds);
     }
@@ -370,7 +386,11 @@ export async function runInteractiveOnHost(host, opts) {
         process.stderr.write(`[hosts] warning: ${w}\n`);
     const invocation = ['agents', ...buildInteractiveRunForwardedArgs(opts)].map(shellQuote).join(' ');
     const cwd = remoteCdPrefix(opts.remoteCwd);
-    let remoteCmd = `${cwd}${invocation}`;
+    // Forward actor provenance so the interactive remote run inherits it rather
+    // than re-resolving from this box's SSH_CONNECTION (RUSH-2028).
+    const actorExports = posixEnvExports(withActorEnv());
+    const prelude = actorExports ? `${actorExports}; ` : '';
+    let remoteCmd = `${prelude}${cwd}${invocation}`;
     if (opts.copyCreds) {
         remoteCmd = wrapHostCommandWithCredentials(remoteCmd, opts.copyCreds);
     }

package/dist/lib/hosts/passthrough.js

@@ -20,7 +20,7 @@ import chalk from 'chalk';
 import { assertValidSshTarget, sshStream } from '../ssh-exec.js';
 import { resolveHost, resolveHostByCap } from './registry.js';
 import { sshTargetFor } from './types.js';
-import { dispatchAgentsCommand } from './dispatch.js';
+import { dispatchAgentsCommand, withActorEnv } from './dispatch.js';
 import { stripRoutingFlags, buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { machineId } from '../session/sync/config.js';
@@ -267,9 +267,14 @@ export async function maybeRunOnHost(command, allArgs) {
     // profile, and single-quoted env values would not expand $HOME/$PATH.
     const isDoctorCommand = command === 'doctor' || (command === 'teams' && forwarded[1] === 'doctor');
     const remoteOs = resolveRemoteOsSync(host.name);
-    const env = isDoctorCommand && !/^win/i.test((remoteOs ?? '').trim())
+    const doctorPath = isDoctorCommand && !/^win/i.test((remoteOs ?? '').trim())
         ? { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' }
         : undefined;
+    // Forward actor provenance (AGENTS_ACTOR*/GIT_*) across the SSH hop, merged
+    // UNDER the doctor PATH so that PATH still wins — without this the remote
+    // re-resolves the actor from THIS box's SSH_CONNECTION and mis-credits it
+    // (RUSH-2028). Flows to both POSIX (export) and Windows ($env:) dialects.
+    const env = withActorEnv(doctorPath);
     const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd, remoteOs, env);
     const code = sshStream(target, remoteCmd, { tty: interactive, multiplex: true });
     if (code === 255) {

package/dist/lib/hosts/remote-cmd.d.ts

@@ -68,6 +68,17 @@ export declare const RUN_OPTION_REJECT_MESSAGES: Record<string, string>;
  * POSIX form, so linux/macos are byte-for-byte unchanged.
  */
 export declare function buildRemoteAgentsInvocation(forwardedArgs: string[], remoteCwd?: string, os?: string, env?: Record<string, string>): string;
+/**
+ * Build a POSIX `export K=V; …` prefix from an env map — empty string when the
+ * map is missing or empty. Values are rendered as shell LITERALS by default
+ * (single-quoted via {@link shellQuote}), so a `$(...)` or backtick in a value
+ * can never execute on the SSH target. Only {@link EXPAND_KEYS} (`PATH`) keep the
+ * expanding double-quote form (`\` and `"` escaped) so the remote `$HOME`/`$PATH`
+ * still resolve. Shared by {@link buildRemoteAgentsInvocation} and the
+ * detached/interactive dispatch builders (dispatch.ts) so every remote path
+ * exports env identically.
+ */
+export declare function posixEnvExports(env?: Record<string, string>): string;
 /** The two remote shell dialects we build commands for. */
 export type RemoteShell = 'posix' | 'powershell';
 /**

package/dist/lib/hosts/remote-cmd.js

@@ -144,18 +144,41 @@ export function buildRemoteAgentsInvocation(forwardedArgs, remoteCwd, os, env) {
     }
     const inner = ['agents', ...forwardedArgs].map(shellQuote).join(' ');
     const withCwd = remoteCwd ? `cd ${shellQuote(remoteCwd)} && ${inner}` : inner;
-    if (!env || Object.keys(env).length === 0) {
-        return `bash -lc ${shellQuote(withCwd)}`;
-    }
     // Prepend env exports so the remote command sees the shims dir even when the
     // login shell hasn't sourced the interactive rc files that usually add it.
-    // Values are double-quoted (not single-quoted) so remote variables like
-    // $HOME and $PATH are expanded by the login shell.
-    const exports = Object.entries(env)
-        .map(([k, v]) => `export ${shellQuote(k)}="${v.replace(/[\\"]/g, '\\$&')}"`)
-        .join('; ');
+    const exports = posixEnvExports(env);
+    if (!exports) {
+        return `bash -lc ${shellQuote(withCwd)}`;
+    }
     return `bash -lc ${shellQuote(`${exports}; ${withCwd}`)}`;
 }
+/**
+ * Keys whose values are trusted-static and legitimately need remote shell
+ * expansion — `PATH` references the remote `$HOME`/`$PATH`. Every other key is
+ * rendered as a shell literal, so an attacker-influenceable value (notably actor
+ * provenance, whose name/email can come from a tailnet peer's whois or an
+ * unvalidated `AGENTS_ACTOR_*` env var) can never inject shell into a dispatch.
+ */
+const EXPAND_KEYS = new Set(['PATH']);
+/**
+ * Build a POSIX `export K=V; …` prefix from an env map — empty string when the
+ * map is missing or empty. Values are rendered as shell LITERALS by default
+ * (single-quoted via {@link shellQuote}), so a `$(...)` or backtick in a value
+ * can never execute on the SSH target. Only {@link EXPAND_KEYS} (`PATH`) keep the
+ * expanding double-quote form (`\` and `"` escaped) so the remote `$HOME`/`$PATH`
+ * still resolve. Shared by {@link buildRemoteAgentsInvocation} and the
+ * detached/interactive dispatch builders (dispatch.ts) so every remote path
+ * exports env identically.
+ */
+export function posixEnvExports(env) {
+    if (!env || Object.keys(env).length === 0)
+        return '';
+    return Object.entries(env)
+        .map(([k, v]) => EXPAND_KEYS.has(k)
+        ? `export ${shellQuote(k)}="${v.replace(/[\\"]/g, '\\$&')}"`
+        : `export ${shellQuote(k)}=${shellQuote(v)}`)
+        .join('; ');
+}
 /**
  * Pick the remote shell dialect from a recorded OS/platform string. A Windows
  * host (device-registry `platform: 'windows'`, or an enrolled `HostEntry.os`

package/dist/lib/hosts/remote-session-id.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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).
+ */
+/**
+ * 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 declare function pickRemoteSessionId(recordsJson: string, launchId: string): string | undefined;
+/**
+ * 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 declare function resolveRemoteSessionId(target: string, launchId: string, timeoutMs?: number): string | undefined;

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/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;