@phnx-labs/agents-cli 1.20.92 → 1.21.0

package/dist/lib/linear-projects.d.ts

@@ -0,0 +1,62 @@
+/** The minimal Linear project shape the link flow needs (id + name + url). */
+export interface LinearProjectLite {
+    id: string;
+    name: string;
+    /** Project URL, when the `linear` CLI JSON carries one. Never fabricated. */
+    url?: string;
+}
+/**
+ * Collapse a Linear name / repo slug / folder path to one comparison key:
+ * lowercase, keep only the last path segment, strip separators.
+ *   "Agents CLI"            -> "agentscli"
+ *   "phnx-labs/agents-cli"  -> "agentscli"
+ *   "~/src/.../agents-cli"  -> "agentscli"
+ */
+export declare function normalizeProjectKey(s: string): string;
+/**
+ * Find the Linear project that best matches a repo slug or folder name.
+ * Exact normalized match first, then a containment fallback (either direction),
+ * so "agents-cli-web" still suggests "Agents CLI" when no exact peer exists.
+ *
+ * Kept for parity with the Factory original — the `link` command uses
+ * {@link pickLinearProject} instead: this one returns the FIRST match (silent
+ * on duplicate names), which is fine for a UI suggestion but never for a write
+ * path.
+ */
+export declare function matchLinearProject(slugOrName: string, projects: LinearProjectLite[]): LinearProjectLite | undefined;
+/**
+ * Find the local checkout directory a Linear project name refers to, on EXACT
+ * key equality only — never containment. `matchLinearProject`'s containment
+ * fallback is right for suggesting a link a human then confirms; this backs
+ * `projects import --from-linear`, which writes `root`/`repo` with nobody
+ * looking, and "Agents CLI" must not silently bind `agents-cli-web`.
+ *
+ * Returns `undefined` when nothing matches, and also when SEVERAL dirs key to
+ * the same value (`agents-cli` and `agents_cli`) — an ambiguous match is not a
+ * match.
+ */
+export declare function matchLocalCheckoutExact(name: string, dirNames: string[]): string | undefined;
+/** The outcome of picking one Linear project out of the workspace list. */
+export type LinearPick = {
+    kind: 'match';
+    project: LinearProjectLite;
+} | {
+    kind: 'candidates';
+    projects: LinearProjectLite[];
+} | {
+    kind: 'none';
+};
+/**
+ * Pick the Linear project a query refers to. An exact id or exact normalized
+ * name match is confident enough to write; anything weaker (several exact-name
+ * peers, or only containment matches) comes back as a candidate LIST for the
+ * user to disambiguate — the link command never guesses on a weak signal.
+ */
+export declare function pickLinearProject(query: string, projects: LinearProjectLite[]): LinearPick;
+/**
+ * List the workspace's Linear projects via the `linear` CLI on PATH. Throws a
+ * clear error when the binary is missing, errors, or returns a shape we can't
+ * use — this backs an explicit user command, so a silent empty list would send
+ * the user down a wrong "no matches" path.
+ */
+export declare function listLinearProjects(): LinearProjectLite[];

package/dist/lib/linear-projects.js

@@ -0,0 +1,144 @@
+// Linear project matching for `agents projects link --linear`.
+//
+// A project's identity shows up three ways — a Linear project name ("Agents CLI"),
+// a GitHub repo slug ("phnx-labs/agents-cli"), and a filesystem folder
+// (".../agents-cli"). normalizeProjectKey() collapses all three to one comparison
+// key so they compare equal, and matchLinearProject() binds a repo/folder to the
+// Linear project the user most likely means.
+//
+// Ported from apps/factory/src/core/linearProjects.ts (no cross-package imports —
+// repo rule); keep the two in sync. The matcher half is PURE so it unit-tests
+// without a live `linear` binary; the `linear projects --json` shell-out lives at
+// the bottom (listLinearProjects) and fails LOUD — it's behind an explicit user
+// command, not a best-effort card enrichment.
+import { execFileSync } from 'child_process';
+/**
+ * Collapse a Linear name / repo slug / folder path to one comparison key:
+ * lowercase, keep only the last path segment, strip separators.
+ *   "Agents CLI"            -> "agentscli"
+ *   "phnx-labs/agents-cli"  -> "agentscli"
+ *   "~/src/.../agents-cli"  -> "agentscli"
+ */
+export function normalizeProjectKey(s) {
+    const last = s.toLowerCase().split('/').filter(Boolean).pop() ?? '';
+    return last.replace(/[-_\s.]/g, '');
+}
+/**
+ * Find the Linear project that best matches a repo slug or folder name.
+ * Exact normalized match first, then a containment fallback (either direction),
+ * so "agents-cli-web" still suggests "Agents CLI" when no exact peer exists.
+ *
+ * Kept for parity with the Factory original — the `link` command uses
+ * {@link pickLinearProject} instead: this one returns the FIRST match (silent
+ * on duplicate names), which is fine for a UI suggestion but never for a write
+ * path.
+ */
+export function matchLinearProject(slugOrName, projects) {
+    const key = normalizeProjectKey(slugOrName);
+    if (!key)
+        return undefined;
+    const exact = projects.find((p) => normalizeProjectKey(p.name) === key);
+    if (exact)
+        return exact;
+    return projects.find((p) => {
+        const pk = normalizeProjectKey(p.name);
+        return pk.length > 0 && (pk.includes(key) || key.includes(pk));
+    });
+}
+/**
+ * Collapse a Linear **display name** or a directory basename to one comparison
+ * key. Deliberately NOT `normalizeProjectKey`: that one keeps only the segment
+ * after the last `/`, which is right for an `owner/repo` slug or a filesystem
+ * path and wrong for a display name, where `/` is ordinary punctuation. Keying
+ * "Rush / Web" the path way yields `web`, which exact-matches an unrelated
+ * `web/` checkout — the precise silent mis-binding this whole match path exists
+ * to prevent.
+ */
+function checkoutMatchKey(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, '');
+}
+/**
+ * Find the local checkout directory a Linear project name refers to, on EXACT
+ * key equality only — never containment. `matchLinearProject`'s containment
+ * fallback is right for suggesting a link a human then confirms; this backs
+ * `projects import --from-linear`, which writes `root`/`repo` with nobody
+ * looking, and "Agents CLI" must not silently bind `agents-cli-web`.
+ *
+ * Returns `undefined` when nothing matches, and also when SEVERAL dirs key to
+ * the same value (`agents-cli` and `agents_cli`) — an ambiguous match is not a
+ * match.
+ */
+export function matchLocalCheckoutExact(name, dirNames) {
+    const key = checkoutMatchKey(name);
+    if (!key)
+        return undefined;
+    const hits = dirNames.filter((d) => checkoutMatchKey(d) === key);
+    return hits.length === 1 ? hits[0] : undefined;
+}
+/**
+ * Pick the Linear project a query refers to. An exact id or exact normalized
+ * name match is confident enough to write; anything weaker (several exact-name
+ * peers, or only containment matches) comes back as a candidate LIST for the
+ * user to disambiguate — the link command never guesses on a weak signal.
+ */
+export function pickLinearProject(query, projects) {
+    const q = query.trim();
+    if (!q)
+        return { kind: 'none' };
+    const byId = projects.find((p) => p.id === q);
+    if (byId)
+        return { kind: 'match', project: byId };
+    const key = normalizeProjectKey(q);
+    if (!key)
+        return { kind: 'none' };
+    const exact = projects.filter((p) => normalizeProjectKey(p.name) === key);
+    if (exact.length === 1)
+        return { kind: 'match', project: exact[0] };
+    if (exact.length > 1)
+        return { kind: 'candidates', projects: exact };
+    const containment = projects.filter((p) => {
+        const pk = normalizeProjectKey(p.name);
+        return pk.length > 0 && (pk.includes(key) || key.includes(pk));
+    });
+    return containment.length > 0 ? { kind: 'candidates', projects: containment } : { kind: 'none' };
+}
+/**
+ * List the workspace's Linear projects via the `linear` CLI on PATH. Throws a
+ * clear error when the binary is missing, errors, or returns a shape we can't
+ * use — this backs an explicit user command, so a silent empty list would send
+ * the user down a wrong "no matches" path.
+ */
+export function listLinearProjects() {
+    let out;
+    try {
+        out = execFileSync('linear', ['projects', '--json'], {
+            encoding: 'utf8',
+            timeout: 8000,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+    }
+    catch {
+        throw new Error('Could not list Linear projects — is the `linear` CLI installed and logged in? (`brew install linear-cli`, `linear auth login`)');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(out);
+    }
+    catch {
+        throw new Error('`linear projects --json` returned invalid JSON');
+    }
+    if (!Array.isArray(parsed))
+        throw new Error('`linear projects --json` did not return a list');
+    return parsed.flatMap((x) => {
+        if (x && typeof x === 'object' && !Array.isArray(x)) {
+            const o = x;
+            if (typeof o.id === 'string' && typeof o.name === 'string') {
+                const p = { id: o.id, name: o.name };
+                if (typeof o.url === 'string')
+                    p.url = o.url;
+                return [p];
+            }
+        }
+        return [];
+    });
+}

package/dist/lib/mailbox-gc.js

@@ -8,9 +8,9 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { getMailboxRootDir } from './state.js';
+import { getFeedDir, getMailboxRootDir } from './state.js';
 import { mailboxDir, isValidMailboxId, readMessage, sweepExpired, } from './mailbox.js';
-import { listBlocks, removeBlock } from './feed.js';
+import { listBlocks, removeBlock, recordMessageReceipt } from './feed.js';
 const DEFAULT_MAX_CONSUMED_AGE_MINUTES = 24 * 60;
 function consumedAgeMinutes(file, now) {
     try {
@@ -31,7 +31,7 @@ function jsonFiles(dir) {
     }
     return names.filter((n) => n.endsWith('.json')).sort();
 }
-function archiveAllPending(boxDir, reason) {
+function archiveAllPending(boxDir, reason, feedRoot) {
     let n = 0;
     for (const dir of [path.join(boxDir, 'inbox'), path.join(boxDir, 'processing')]) {
         for (const name of jsonFiles(dir)) {
@@ -45,6 +45,14 @@ function archiveAllPending(boxDir, reason) {
                     fs.writeFileSync(tmp, JSON.stringify(msg, null, 2), 'utf-8');
                     fs.renameSync(tmp, dest);
                     fs.unlinkSync(src);
+                    if (msg.blockId) {
+                        try {
+                            recordMessageReceipt(msg.blockId, { msgId: msg.msgId, status: reason === 'expired' ? 'expired' : 'dropped', at: new Date().toISOString(), from: msg.from }, feedRoot);
+                        }
+                        catch {
+                            // Receipt surfacing is best-effort; never stall GC.
+                        }
+                    }
                 }
                 else {
                     fs.renameSync(src, dest);
@@ -58,6 +66,16 @@ function archiveAllPending(boxDir, reason) {
     }
     return n;
 }
+function blockAgeMinutes(blockId, feedRoot, now) {
+    const file = path.join(feedRoot ?? getFeedDir(), `${blockId}.json`);
+    try {
+        const stat = fs.statSync(file);
+        return (now.getTime() - stat.mtimeMs) / 60_000;
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
 function pruneConsumed(boxDir, maxAgeMinutes, now) {
     let n = 0;
     const consumed = path.join(boxDir, 'consumed');
@@ -115,7 +133,7 @@ export function gcMailbox(activeBoxIds, options = {}) {
         const boxDir = mailboxDir(name, root);
         if (!activeBoxIds.has(name)) {
             result.deadBoxes++;
-            result.messagesDroppedDead += archiveAllPending(boxDir, 'dead');
+            result.messagesDroppedDead += archiveAllPending(boxDir, 'dead', feedRoot);
             result.consumedPruned += pruneConsumed(boxDir, maxConsumedAgeMinutes, now);
             // Also prune the empty box dir if it is now empty.
             try {
@@ -136,13 +154,18 @@ export function gcMailbox(activeBoxIds, options = {}) {
         else {
             // Live box: archive expired messages (same path as drain/peek) so GC does
             // not leave expired files in inbox/processing while only bumping metrics.
-            result.messagesDroppedExpired += sweepExpired(boxDir, name, now);
+            result.messagesDroppedExpired += sweepExpired(boxDir, name, now, feedRoot);
             result.consumedPruned += pruneConsumed(boxDir, maxConsumedAgeMinutes, now);
         }
     }
     for (const blockId of blocksToRemove) {
-        if (removeBlock(blockId, feedRoot)) {
-            result.blocksRemoved++;
+        // A dead box's block is kept for up to maxConsumedAgeMinutes after a bounce
+        // receipt is written so the operator/sender can see the failure. Stale blocks
+        // (older than the prune window) are removed.
+        if (blockAgeMinutes(blockId, feedRoot, now) >= maxConsumedAgeMinutes) {
+            if (removeBlock(blockId, feedRoot)) {
+                result.blocksRemoved++;
+            }
         }
     }
     return result;

package/dist/lib/mailbox.d.ts

@@ -1,3 +1,13 @@
+/** Default delivery TTL for messages enqueued without an explicit one (24 hours). */
+export declare const DEFAULT_TTL_SECONDS: number;
+/** Env var that overrides {@link DEFAULT_TTL_SECONDS} with a duration like "24h" or "3600". */
+export declare const MAILBOX_TTL_ENV = "AGENTS_MAILBOX_TTL";
+/**
+ * Resolve the default mailbox TTL in seconds. Honors `AGENTS_MAILBOX_TTL`
+ * (parsed by {@link parseDuration}); falls back to 24h. A malformed env value
+ * fails loud instead of silently disabling expiry.
+ */
+export declare function resolveDefaultTtlSeconds(): number;
 /** A single mailbox message. `text` may embed `host:/path` clip tokens. */
 export interface MailboxMessage {
     /** Unique, time-sortable id. Also the on-disk filename stem. */
@@ -54,8 +64,11 @@ export declare function isExpired(msg: MailboxMessage, now?: Date): boolean;
 /**
  * Move expired messages from inbox/ and processing/ into consumed/ with a
  * `dropped: expired` marker. Called by drain/peek before returning messages.
+ *
+ * When a dropped message carries a `blockId`, a failure receipt is surfaced
+ * back to the feed store so the sender sees the bounce.
  */
-export declare function sweepExpired(boxDir: string, boxId?: string, now?: Date): number;
+export declare function sweepExpired(boxDir: string, boxId?: string, now?: Date, feedRoot?: string): number;
 /**
  * Drain the box: return every pending message addressed to it, in FIFO order,
  * removing them from the queue. Claim-first (inbox → processing → consumed) so

package/dist/lib/mailbox.js

@@ -20,6 +20,26 @@ import * as path from 'path';
 import { randomUUID } from 'crypto';
 import { getMailboxRootDir } from './state.js';
 import { recordMessageReceipt } from './feed.js';
+import { parseDuration } from './hooks/cache.js';
+/** Default delivery TTL for messages enqueued without an explicit one (24 hours). */
+export const DEFAULT_TTL_SECONDS = 24 * 60 * 60;
+/** Env var that overrides {@link DEFAULT_TTL_SECONDS} with a duration like "24h" or "3600". */
+export const MAILBOX_TTL_ENV = 'AGENTS_MAILBOX_TTL';
+/**
+ * Resolve the default mailbox TTL in seconds. Honors `AGENTS_MAILBOX_TTL`
+ * (parsed by {@link parseDuration}); falls back to 24h. A malformed env value
+ * fails loud instead of silently disabling expiry.
+ */
+export function resolveDefaultTtlSeconds() {
+    const raw = process.env[MAILBOX_TTL_ENV];
+    if (raw == null || raw === '')
+        return DEFAULT_TTL_SECONDS;
+    const parsed = parseDuration(raw);
+    if (parsed == null || parsed <= 0) {
+        throw new Error(`Invalid ${MAILBOX_TTL_ENV}=${JSON.stringify(raw)}: expected a positive duration (e.g. 24h, 30m, 3600).`);
+    }
+    return parsed;
+}
 /**
  * A mailboxId must be a single, separator-free path segment. Real ids (session
  * UUID / teams agentId / loop runId) already satisfy this; rejecting anything
@@ -78,8 +98,9 @@ export function enqueue(boxDir, msg) {
         text: msg.text,
         blockId: msg.blockId,
     };
-    if (msg.ttlSeconds != null && msg.ttlSeconds > 0) {
-        record.expiresAt = new Date(now.getTime() + msg.ttlSeconds * 1000).toISOString();
+    const ttlSeconds = msg.ttlSeconds ?? resolveDefaultTtlSeconds();
+    if (ttlSeconds > 0) {
+        record.expiresAt = new Date(now.getTime() + ttlSeconds * 1000).toISOString();
     }
     const target = path.join(inboxDir(boxDir), `${msgId}.json`);
     const tmp = `${target}.${process.pid}.tmp`;
@@ -139,8 +160,11 @@ function archiveDropped(boxDir, name, reason) {
 /**
  * Move expired messages from inbox/ and processing/ into consumed/ with a
  * `dropped: expired` marker. Called by drain/peek before returning messages.
+ *
+ * When a dropped message carries a `blockId`, a failure receipt is surfaced
+ * back to the feed store so the sender sees the bounce.
  */
-export function sweepExpired(boxDir, boxId = path.basename(boxDir), now = new Date()) {
+export function sweepExpired(boxDir, boxId = path.basename(boxDir), now = new Date(), feedRoot) {
     ensureDirs(boxDir);
     let n = 0;
     for (const dir of [inboxDir(boxDir), processingDir(boxDir)]) {
@@ -154,6 +178,14 @@ export function sweepExpired(boxDir, boxId = path.basename(boxDir), now = new Da
                     fs.writeFileSync(tmp, JSON.stringify(msg, null, 2), 'utf-8');
                     fs.renameSync(tmp, dest);
                     fs.unlinkSync(path.join(dir, name));
+                    if (msg.blockId) {
+                        try {
+                            recordMessageReceipt(msg.blockId, { msgId: msg.msgId, status: 'expired', at: new Date().toISOString(), from: msg.from }, feedRoot ?? process.env.AGENTS_FEED_DIR);
+                        }
+                        catch {
+                            // Receipt surfacing is best-effort; never stall expiry.
+                        }
+                    }
                     n++;
                 }
                 catch {

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

@@ -34,29 +34,12 @@ export declare function codesignVerifies(appPath: string): boolean;
  * A Developer-ID-signed but un-notarized app is rejected by `spctl --assess`,
  * which macOS surfaces as "the app is damaged" and can crash AppKit during
  * launch. This is separate from `codesign --verify`: a signature can be valid
- * while Gatekeeper still refuses to run it.
+ * while Gatekeeper still refuses to run it. The release notarizes + staples the
+ * helper (menubar/scripts/build.sh, gated by verify-menubar-helper.sh), so a
+ * shipped bundle passes this; the launch guards use it to fail loud rather than
+ * bootstrap a helper macOS would reject.
  */
 export declare function gatekeeperAssesses(appPath: string): boolean;
-/**
- * Guarantee the installed bundle has a signature Gatekeeper will accept on THIS
- * machine.
- *
- * npm's pack/extract strips the ad-hoc/linker signature the release baked into
- * the helper, leaving `code object is not signed at all`. On macOS 26+ the
- * kernel's code-signing monitor SIGKILLs an unsigned/invalid binary at launch
- * (`SIGKILL (Code Signature Invalid)`), so under the launchd `KeepAlive` service
- * an ad-hoc release helper crash-loops forever and its unstable identity makes
- * the Accessibility grant (needed for the clip→paste keystroke in Clip.swift)
- * re-prompt every time. A fresh ad-hoc re-sign gives the on-disk bytes a
- * matching cdhash, which the kernel accepts.
- *
- * A Developer-ID-signed helper survives npm untouched — its embedded signature
- * still verifies — but if the release was not notarized, Gatekeeper rejects it.
- * In that case we strip the quarantine xattr and re-sign ad-hoc so the helper
- * can launch locally. The stable fix is to notarize the release build; this
- * fallback just prevents a crash-loop while the user is on an un-notarized cut.
- */
-export declare function ensureValidSignature(appPath: string): boolean;
 /**
  * Copy the bundled `.app` to the stable user path (idempotent unless forced).
  * Returns the installed executable path, or null if no source bundle ships
@@ -65,6 +48,7 @@ export declare function ensureValidSignature(appPath: string): boolean;
 export declare function ensureMenubarAppInstalled(opts?: {
     forceReinstall?: boolean;
 }): string | null;
+export declare function generateServicePlist(execPath: string): string;
 /**
  * Restart the menu-bar launchd agent from a clean state.
  *

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

@@ -25,6 +25,21 @@ import { getCliVersion, resolveAgentsBin, resolveInstalledLayout } from '../vers
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 const SERVICE_LABEL = 'com.phnx-labs.agents-menubar';
+/**
+ * Minimum seconds between launchd restarts of the helper (`ThrottleInterval`).
+ *
+ * The helper can crash at startup on a loaded machine: `NSApplication.shared`
+ * segfaults inside `SLSNewConnection` when WindowServer is too starved to hand
+ * out a connection. With `KeepAlive` and no throttle, launchd relaunches on its
+ * 10s default, and each attempt spawns a fresh `agents doctor --json` before
+ * dying — so a starved box gets hit harder the worse it gets. 30s bounds that
+ * respawn rate while staying well inside "the menu bar came back on its own".
+ *
+ * This only paces the restarts. What actually stops the pile-up is the helper
+ * bounding and group-killing its own children (menubar/Sources/MenubarHelper/
+ * ChildProcess.swift); the two are complementary, not alternatives.
+ */
+const MENUBAR_THROTTLE_SECONDS = 30;
 function onDarwin() {
     return process.platform === 'darwin';
 }
@@ -181,41 +196,15 @@ export function codesignVerifies(appPath) {
  * A Developer-ID-signed but un-notarized app is rejected by `spctl --assess`,
  * which macOS surfaces as "the app is damaged" and can crash AppKit during
  * launch. This is separate from `codesign --verify`: a signature can be valid
- * while Gatekeeper still refuses to run it.
+ * while Gatekeeper still refuses to run it. The release notarizes + staples the
+ * helper (menubar/scripts/build.sh, gated by verify-menubar-helper.sh), so a
+ * shipped bundle passes this; the launch guards use it to fail loud rather than
+ * bootstrap a helper macOS would reject.
  */
 export function gatekeeperAssesses(appPath) {
     const r = spawnSync('spctl', ['--assess', '--type', 'exec', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
     return r.status === 0;
 }
-/**
- * Guarantee the installed bundle has a signature Gatekeeper will accept on THIS
- * machine.
- *
- * npm's pack/extract strips the ad-hoc/linker signature the release baked into
- * the helper, leaving `code object is not signed at all`. On macOS 26+ the
- * kernel's code-signing monitor SIGKILLs an unsigned/invalid binary at launch
- * (`SIGKILL (Code Signature Invalid)`), so under the launchd `KeepAlive` service
- * an ad-hoc release helper crash-loops forever and its unstable identity makes
- * the Accessibility grant (needed for the clip→paste keystroke in Clip.swift)
- * re-prompt every time. A fresh ad-hoc re-sign gives the on-disk bytes a
- * matching cdhash, which the kernel accepts.
- *
- * A Developer-ID-signed helper survives npm untouched — its embedded signature
- * still verifies — but if the release was not notarized, Gatekeeper rejects it.
- * In that case we strip the quarantine xattr and re-sign ad-hoc so the helper
- * can launch locally. The stable fix is to notarize the release build; this
- * fallback just prevents a crash-loop while the user is on an un-notarized cut.
- */
-export function ensureValidSignature(appPath) {
-    if (codesignVerifies(appPath) && gatekeeperAssesses(appPath))
-        return true;
-    // Drop any quarantine/xattrs the tarball round-trip added (they can break
-    // both codesign and Gatekeeper), then re-sign ad-hoc under the helper's
-    // stable bundle identifier.
-    spawnSync('xattr', ['-cr', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
-    spawnSync('codesign', ['--force', '--sign', '-', '--identifier', SERVICE_LABEL, appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
-    return codesignVerifies(appPath);
-}
 /**
  * Copy the bundled `.app` to the stable user path (idempotent unless forced).
  * Returns the installed executable path, or null if no source bundle ships
@@ -229,13 +218,9 @@ export function ensureMenubarAppInstalled(opts = {}) {
         return null;
     const dest = installedAppPath();
     if (!opts.forceReinstall && fs.existsSync(dest)) {
-        // Self-heal an already-installed bundle whose signature npm stripped on a
-        // prior upgrade (macOS 26+ SIGKILLs it otherwise) without a forced recopy.
-        ensureValidSignature(dest);
         return installedExecutablePath();
     }
     copyAppBundle(src, dest);
-    ensureValidSignature(dest);
     // A fresh copy is exactly when the bundle's icon can be new (first install) or
     // superseded (upgrade) — register it so LaunchServices knows the bundle and can
     // resolve its AppIcon for the left-hand slot of daemon notifications.
@@ -245,7 +230,7 @@ export function ensureMenubarAppInstalled(opts = {}) {
 function xmlEscape(s) {
     return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
-function generateServicePlist(execPath) {
+export function generateServicePlist(execPath) {
     const home = os.homedir();
     const logPath = path.join(getHelpersDir(), 'menubar', 'menubar.log');
     fs.mkdirSync(path.dirname(logPath), { recursive: true });
@@ -281,6 +266,8 @@ function generateServicePlist(execPath) {
   <true/>
   <key>KeepAlive</key>
   <true/>
+  <key>ThrottleInterval</key>
+  <integer>${MENUBAR_THROTTLE_SECONDS}</integer>
   <key>ProcessType</key>
   <string>Interactive</string>
   <key>StandardOutPath</key>
@@ -331,12 +318,15 @@ export function enableMenubarService(opts = { clearOptOut: true }) {
     const exec = ensureMenubarAppInstalled({ forceReinstall: true });
     if (!exec)
         return false;
-    // Never bootstrap a helper the kernel will kill on launch: an invalid
-    // signature under launchd KeepAlive is an infinite crash loop. If the bundle
-    // can't be made valid (re-sign already attempted in ensureMenubarAppInstalled),
-    // skip the service rather than spin the loop.
-    if (!codesignVerifies(installedAppPath())) {
-        process.stderr.write('agents: menu-bar helper has no valid code signature; skipping launch to avoid a crash loop.\n');
+    // Never bootstrap a helper macOS will reject at launch: an invalid signature
+    // under launchd KeepAlive crash-loops forever, and an un-notarized bundle is
+    // rejected by Gatekeeper as "damaged". A shipped helper is Developer-ID signed
+    // AND notarized (release build + the verify-menubar-helper.sh prepack gate), so
+    // this passes; if it ever doesn't, skip the service and point at the upgrade
+    // rather than re-signing over it (an ad-hoc re-sign never satisfies Gatekeeper).
+    if (!(codesignVerifies(installedAppPath()) && gatekeeperAssesses(installedAppPath()))) {
+        process.stderr.write('agents: menu-bar helper is not notarized/valid on this machine; skipping launch. ' +
+            'Upgrade to a notarized build (npm i -g @phnx-labs/agents-cli), then `agents menubar setup`.\n');
         return false;
     }
     if (opts.clearOptOut)
@@ -560,11 +550,12 @@ export function runMenubarSetup() {
         return { steps, configured: false, status: getMenubarStatus() };
     }
     step('bundle', before.installedVersion === getCliVersion() ? 'ok' : 'changed', `${installedAppPath()} (${getCliVersion()})`);
-    if (!codesignVerifies(installedAppPath())) {
-        step('signature', 'failed', 'no valid code signature — refusing to start it (launchd KeepAlive would crash-loop)');
+    if (!(codesignVerifies(installedAppPath()) && gatekeeperAssesses(installedAppPath()))) {
+        step('signature', 'failed', 'not notarized/valid on this machine — refusing to start it (Gatekeeper rejects an ' +
+            'un-notarized helper as "damaged"). Upgrade to a notarized build of agents-cli.');
         return { steps, configured: false, status: getMenubarStatus() };
     }
-    step('signature', 'ok', 'valid');
+    step('signature', 'ok', 'valid + notarized');
     // Clear the sticky opt-out: running `setup` is an explicit request for the
     // menu bar, so a stale `menubar disable` must not silently win.
     clearMenubarOptOut();

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

@@ -4,8 +4,12 @@
  * 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
+ * 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
@@ -32,6 +36,17 @@ export interface DesktopNotification {
      * 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 MenubarHelper one-shot notify mode. Exported for tests. */
 export declare function buildMenubarNotifyArgs(n: DesktopNotification): string[];

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

@@ -4,8 +4,12 @@
  * 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
+ * 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
@@ -35,6 +39,8 @@ export function buildMenubarNotifyArgs(n) {
         args.push('--subtitle', n.subtitle);
     if (n.action)
         args.push('--action', n.action);
+    if (n.agent)
+        args.push('--agent', n.agent);
     return args;
 }
 /** AppleScript for the osascript degradation path. Exported for tests. */

package/dist/lib/migrate.js

@@ -1708,7 +1708,7 @@ function migrateVersionResourcesToPatterns() {
         }
     }
     if (changed) {
-        const META_HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n\n';
+        const META_HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/apps/cli/schema/agents-yaml.schema.json\n\n';
         fs.writeFileSync(metaFile, META_HEADER + yaml.stringify(meta), 'utf-8');
         console.error('Migrated agents.yaml versions: entries to pattern format');
     }