@phnx-labs/agents-cli 1.21.0 → 1.21.2

package/dist/lib/linear-cache.js

@@ -0,0 +1,146 @@
+/**
+ * Disk TTL cache for the Linear answers behind the `agents projects` card.
+ *
+ * Linear meters two budgets independently, and only one of them binds. Observed
+ * on this account's response headers:
+ *
+ *   x-ratelimit-requests-limit:   2500      remaining: 2
+ *   x-ratelimit-complexity-limit: 3000000   remaining: 2999987
+ *
+ * Requests are scarce; complexity is 99.999% untouched. So the thing to
+ * optimize is the NUMBER of calls, not their cost — and the way to spend 2500
+ * of them is an agent (or a watch loop) running `projects status` repeatedly.
+ * A human typing it is not the exhauster.
+ *
+ * The CLI is a short-lived process, so an in-memory memo would only help within
+ * one invocation, which is the case that never needed help. This caches to disk.
+ *
+ * **One file per key, written by atomic rename.** A single JSON document holding
+ * every entry has to be read, modified, and written back, and that sequence is
+ * not atomic across processes — measured on this machine, two concurrent writers
+ * of 40 distinct keys each left **8 of 80** surviving. This box routinely runs a
+ * dozen agent sessions, so that is the normal case, not a corner. Per-key files
+ * remove the shared mutable document entirely: two processes caching different
+ * projects never touch the same path, and two caching the SAME project race only
+ * to write identical data. `writeFileSync` to a temp path followed by `rename`
+ * makes each file appear whole or not at all, so a reader never sees a partial
+ * write.
+ *
+ * The load-bearing behavior is what happens on FAILURE: a stale entry keeps
+ * being served, marked stale, instead of the line vanishing. That rule is
+ * borrowed from `mergeAuthHealthEntries` — one 8s timeout must not flip a
+ * populated chip to empty — and it is the fix for the card silently losing its
+ * Linear line mid-session when the request budget ran out.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from './state.js';
+/** Matches `SKILL_INDEX_TTL_MS` (`lib/registry.ts`) — the repo's TTL convention. */
+export const LINEAR_CACHE_TTL_MS = 10 * 60_000;
+const CACHE_SUBDIR = 'linear-projects';
+/** Sits beside the per-project files; its own file, so it cannot be clobbered by them. */
+const RATE_LIMIT_FILE = 'rate-limit.json';
+/**
+ * Where the snapshot lives. `AGENTS_LINEAR_CACHE_PATH` overrides the directory,
+ * mirroring `AGENTS_FACTORY_PROJECTS_PATH` (`auto-dispatch.ts`) — `getCacheDir()`
+ * resolves `HOME` once at module load, so a test that swaps `process.env.HOME`
+ * afterwards would otherwise read and WRITE the developer's real cache.
+ */
+function cacheDir() {
+    return process.env.AGENTS_LINEAR_CACHE_PATH ?? path.join(getCacheDir(), CACHE_SUBDIR);
+}
+/**
+ * One file per project id. Linear ids are UUIDs, but this is a filename built
+ * from external input, so anything outside the safe set is encoded rather than
+ * trusted — a `/` or `..` must never escape the cache directory.
+ */
+function entryPath(projectId) {
+    return path.join(cacheDir(), `${projectId.replace(/[^a-zA-Z0-9._-]/g, '_')}.json`);
+}
+/** Parse a cache file, treating absent/corrupt/wrong-shaped as simply absent. */
+function readJson(file, valid) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return valid(raw) ? raw : undefined;
+    }
+    catch {
+        return undefined; // absent or corrupt — an empty cache is always a valid answer
+    }
+}
+/**
+ * Write whole-or-not-at-all: a temp file in the same directory (so `rename`
+ * stays on one filesystem and is therefore atomic) swapped into place. A reader
+ * concurrent with this never observes a half-written document.
+ */
+function writeJson(file, value) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(value), 'utf8');
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        /* best-effort: an unwritable cache degrades to no cache, never to an error */
+    }
+}
+function isEntry(raw) {
+    return (!!raw &&
+        typeof raw === 'object' &&
+        typeof raw.at === 'number' &&
+        'value' in raw);
+}
+/** Look up a project's cached answer. Returns stale entries too — the caller decides. */
+export function readCached(projectId, nowMs) {
+    const entry = readJson(entryPath(projectId), isEntry);
+    if (!entry)
+        return undefined;
+    const ageMs = nowMs - entry.at;
+    return { value: entry.value, ageMs, stale: ageMs > LINEAR_CACHE_TTL_MS };
+}
+/** Store a freshly fetched answer. */
+export function writeCached(projectId, value, nowMs) {
+    writeJson(entryPath(projectId), { at: nowMs, value });
+}
+/** Drop one project's entry — used when `projects link` re-points a definition. */
+export function invalidateCached(projectId) {
+    try {
+        fs.rmSync(entryPath(projectId), { force: true });
+    }
+    catch {
+        /* already gone is the desired state */
+    }
+}
+function isRateLimitFile(raw) {
+    return !!raw && typeof raw === 'object' && typeof raw.until === 'number';
+}
+/** True when a prior 429 said the budget is exhausted and has not yet reset. */
+export function isRateLimited(nowMs) {
+    const f = readJson(path.join(cacheDir(), RATE_LIMIT_FILE), isRateLimitFile);
+    return !!f && f.until > nowMs;
+}
+/**
+ * Read a 429's `x-ratelimit-requests-reset` header into an epoch-ms instant.
+ * Linear sends epoch milliseconds; anything absent, non-numeric, or already in
+ * the past is not usable and the caller backs off a TTL instead. Pure, so the
+ * parsing is testable without a live 429.
+ */
+export function parseRateLimitReset(header, nowMs) {
+    if (!header)
+        return undefined;
+    const n = Number(header);
+    if (!Number.isFinite(n) || n <= nowMs)
+        return undefined;
+    return n;
+}
+/**
+ * Record a 429 so the next runs don't spend a request learning the same thing.
+ * `resetAtMs` comes from {@link parseRateLimitReset}; without it, back off one TTL.
+ */
+export function noteRateLimited(resetAtMs, nowMs) {
+    // The invariant this owns: `until` is always in the future. A reset already
+    // elapsed would record a window that is over before it is written, which
+    // reads as "not rate limited" and sends the next run straight back into the
+    // 429 it just took.
+    const until = resetAtMs && resetAtMs > nowMs ? resetAtMs : nowMs + LINEAR_CACHE_TTL_MS;
+    writeJson(path.join(cacheDir(), RATE_LIMIT_FILE), { until });
+}

package/dist/lib/linear-project-counts.d.ts

@@ -43,12 +43,21 @@ export interface LinearMilestone {
      * than printing a meaningless `0/0`.
      */
     total: number;
+    /** True when Linear itself flags this as the project's next milestone. */
+    isNext?: boolean;
 }
 /** A milestone as the project declares it, independent of any issue. */
 export interface LinearMilestoneNode {
     id?: string;
     name?: string;
     targetDate?: string | null;
+    /**
+     * Linear's own marker. Observed values: `"next"` (it flags exactly one) and
+     * `"unstarted"`. Treated as an opaque string and only compared to `"next"` —
+     * the enum is not documented as closed, so switching exhaustively on it would
+     * break the day Linear adds a value.
+     */
+    status?: string | null;
 }
 /** The counts the card renders. `total` counts every issue in the project. */
 export interface LinearProjectCounts {
@@ -64,10 +73,22 @@ export interface LinearProjectCounts {
      */
     truncated?: boolean;
     /**
-     * The next unfinished milestone, when the project has one. Derived from the
-     * SAME paged issue fetch as the counts — a milestone is only ever a grouping
-     * of these issues, so asking Linear again would spend a second round trip to
-     * learn what the first already said.
+     * True when this answer came from the cache after a failed or skipped fetch.
+     * The card labels it rather than dropping the line — a populated Linear row
+     * that silently vanishes on one timeout is the defect this replaces.
+     */
+    stale?: boolean;
+    /**
+     * Every milestone the project declares, in the order the card shows them:
+     * unfinished first by target date, then the finished ones. A project with
+     * three checkpoints has three; showing only the next one hides the shape of
+     * the plan, which is what `projects view` exists to show.
+     */
+    milestones?: LinearMilestone[];
+    /**
+     * The one the project is working toward — `milestones[0]` when there is an
+     * unfinished one. Kept as its own field because the compact card shows only
+     * this, while `view` shows the whole list.
      */
     nextMilestone?: LinearMilestone;
 }
@@ -118,6 +139,15 @@ export declare function countsFromIssuesResponse(data: LinearIssuesResponse): Li
  * issues counts as unfinished (it is upcoming work, not completed work). Undated
  * milestones sort last, ties break by declaration order, so the answer is stable.
  */
+export declare function orderedMilestones(declared: LinearMilestoneNode[], nodes: LinearIssueNode[]): LinearMilestone[];
+/**
+ * The milestone the project is working toward next.
+ *
+ * Linear flags one itself (`status: "next"`), and that is the answer the user
+ * sees in Linear's own UI, so it wins when present. Only when nothing is
+ * flagged does this fall back to "earliest-dated unfinished", which is a
+ * reasonable guess but still a guess.
+ */
 export declare function nextMilestone(declared: LinearMilestoneNode[], nodes: LinearIssueNode[]): LinearMilestone | undefined;
 /**
  * Fetch issue counts for one Linear project, paging `issues` filtered by
@@ -126,4 +156,4 @@ export declare function nextMilestone(declared: LinearMilestoneNode[], nodes: Li
  * card just omits the line. `fetchPage` is injectable for tests — the
  * accumulator (cursor hand-off, cap) is the risky logic, not the HTTP.
  */
-export declare function fetchLinearProjectCounts(projectId: string, fetchPage?: (projectId: string, after: string | undefined, signal: AbortSignal) => Promise<LinearIssuesResponse | undefined>): Promise<LinearProjectCounts | undefined>;
+export declare function fetchLinearProjectCounts(projectId: string, fetchPage?: (projectId: string, after: string | undefined, signal: AbortSignal) => Promise<LinearIssuesResponse | undefined>, nowMs?: number): Promise<LinearProjectCounts | undefined>;

package/dist/lib/linear-project-counts.js

@@ -28,6 +28,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { resolveLinearApiKey } from './auto-dispatch-linear.js';
+import { isRateLimited, noteRateLimited, parseRateLimitReset, readCached, writeCached } from './linear-cache.js';
 const LINEAR_API = 'https://api.linear.app/graphql';
 /** Overall budget across all pages — the card must never hang on Linear. */
 const TIMEOUT_MS = 8_000;
@@ -51,7 +52,11 @@ export function countsFromIssuesResponse(data) {
             inProgress++;
     }
     const counts = { done, total: nodes.length, inProgress };
-    const next = nextMilestone(data.project?.projectMilestones?.nodes ?? [], nodes);
+    const declared = data.project?.projectMilestones?.nodes ?? [];
+    const ordered = orderedMilestones(declared, nodes);
+    if (ordered.length)
+        counts.milestones = ordered;
+    const next = nextMilestone(declared, nodes);
     if (next)
         counts.nextMilestone = next;
     return counts;
@@ -70,7 +75,7 @@ export function countsFromIssuesResponse(data) {
  * issues counts as unfinished (it is upcoming work, not completed work). Undated
  * milestones sort last, ties break by declaration order, so the answer is stable.
  */
-export function nextMilestone(declared, nodes) {
+export function orderedMilestones(declared, nodes) {
     // Progress per milestone id, from whatever issues do carry one.
     const progress = new Map();
     for (const n of nodes) {
@@ -83,7 +88,7 @@ export function nextMilestone(declared, nodes) {
             p.done++;
         progress.set(id, p);
     }
-    const candidates = declared
+    const all = declared
         .map((d, order) => {
         if (!d?.id || typeof d.name !== 'string' || !d.name)
             return undefined;
@@ -91,14 +96,18 @@ export function nextMilestone(declared, nodes) {
         const m = { name: d.name, done: p.done, total: p.total, order };
         if (d.targetDate)
             m.targetDate = d.targetDate;
+        if (d.status === 'next')
+            m.isNext = true;
         return m;
     })
-        .filter((m) => m !== undefined)
-        // total 0 means "declared, nothing filed yet" — unfinished, not done.
-        .filter((m) => m.total === 0 || m.done < m.total);
-    if (candidates.length === 0)
-        return undefined;
-    candidates.sort((a, b) => {
+        .filter((m) => m !== undefined);
+    // total 0 means "declared, nothing filed yet" — unfinished, not done.
+    const open = (m) => m.total === 0 || m.done < m.total;
+    all.sort((a, b) => {
+        // Unfinished before finished: what is still ahead is what a reader is
+        // scanning for.
+        if (open(a) !== open(b))
+            return open(a) ? -1 : 1;
         if (a.targetDate && b.targetDate)
             return a.targetDate < b.targetDate ? -1 : a.targetDate > b.targetDate ? 1 : a.order - b.order;
         if (a.targetDate)
@@ -107,8 +116,20 @@ export function nextMilestone(declared, nodes) {
             return 1;
         return a.order - b.order;
     });
-    const { order: _order, ...m } = candidates[0];
-    return m;
+    return all.map(({ order: _order, ...m }) => m);
+}
+/**
+ * The milestone the project is working toward next.
+ *
+ * Linear flags one itself (`status: "next"`), and that is the answer the user
+ * sees in Linear's own UI, so it wins when present. Only when nothing is
+ * flagged does this fall back to "earliest-dated unfinished", which is a
+ * reasonable guess but still a guess.
+ */
+export function nextMilestone(declared, nodes) {
+    const ordered = orderedMilestones(declared, nodes);
+    const open = ordered.filter((m) => m.total === 0 || m.done < m.total);
+    return open.find((m) => m.isNext) ?? open[0];
 }
 /** $LINEAR_API_KEY → macOS Keychain → ~/.linear-cli/config.json. Null if none. */
 function resolveApiKey() {
@@ -130,7 +151,17 @@ function resolveApiKey() {
  * card just omits the line. `fetchPage` is injectable for tests — the
  * accumulator (cursor hand-off, cap) is the risky logic, not the HTTP.
  */
-export async function fetchLinearProjectCounts(projectId, fetchPage = fetchLinearIssuesPage) {
+export async function fetchLinearProjectCounts(projectId, fetchPage = fetchLinearIssuesPage, nowMs = Date.now()) {
+    // Requests are the scarce budget (2500/hr; complexity is untouched), and this
+    // pages up to 10 of them per project per call. Serve a fresh snapshot without
+    // spending any.
+    const cached = readCached(projectId, nowMs);
+    if (cached && !cached.stale)
+        return cached.value;
+    // A prior 429 said there is nothing left to spend — don't spend one finding
+    // that out again. Fall through to the stale snapshot rather than no line.
+    if (isRateLimited(nowMs))
+        return cached ? { ...cached.value, stale: true } : undefined;
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
     try {
@@ -141,8 +172,12 @@ export async function fetchLinearProjectCounts(projectId, fetchPage = fetchLinea
         let truncated = false;
         for (let page = 0;; page++) {
             const data = await fetchPage(projectId, after, ctrl.signal);
+            // A failed fetch keeps the last good answer on screen, marked stale,
+            // instead of the line vanishing. One 8s timeout must not blank a chip
+            // that was populated a minute ago — the rule `mergeAuthHealthEntries`
+            // already encodes for account health.
             if (!data)
-                return undefined;
+                return cached ? { ...cached.value, stale: true } : undefined;
             if (page === 0)
                 declared = data.project?.projectMilestones?.nodes ?? [];
             all.push(...(data.issues?.nodes ?? []));
@@ -156,16 +191,18 @@ export async function fetchLinearProjectCounts(projectId, fetchPage = fetchLinea
             }
             after = pi.endCursor;
         }
-        return {
+        const counts = {
             ...countsFromIssuesResponse({
                 issues: { nodes: all },
                 project: { projectMilestones: { nodes: declared } },
             }),
             ...(truncated ? { truncated } : {}),
         };
+        writeCached(projectId, counts, nowMs);
+        return counts;
     }
     catch {
-        return undefined;
+        return cached ? { ...cached.value, stale: true } : undefined;
     }
     finally {
         clearTimeout(timer);
@@ -182,7 +219,7 @@ async function fetchLinearIssuesPage(projectId, after, signal) {
     const issuesSelection = 'issues(filter:{ project:{ id:{ eq:$p } } }, first:' +
         PAGE_SIZE +
         ', after:$after){ nodes{ state{ type } projectMilestone{ id } } pageInfo{ hasNextPage endCursor } }';
-    const milestonesSelection = 'project(id:$pid){ projectMilestones(first:50){ nodes{ id name targetDate } } }';
+    const milestonesSelection = 'project(id:$pid){ projectMilestones(first:50){ nodes{ id name targetDate status } } }';
     const first = after === undefined;
     const res = await fetch(LINEAR_API, {
         method: 'POST',
@@ -197,6 +234,14 @@ async function fetchLinearIssuesPage(projectId, after, signal) {
         }),
         signal,
     });
+    if (res.status === 429) {
+        // Record when the budget refills so later runs skip the call entirely
+        // rather than spending one of the zero remaining requests to be told so.
+        // The header is epoch milliseconds; absent or unparseable, back off a TTL.
+        const now = Date.now();
+        noteRateLimited(parseRateLimitReset(res.headers.get('x-ratelimit-requests-reset'), now), now);
+        return undefined;
+    }
     if (!res.ok)
         return undefined;
     const json = (await res.json());

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

@@ -7,7 +7,9 @@
     <key>CFBundleIdentifier</key>
     <string>com.phnx-labs.agents-menubar</string>
     <key>CFBundleName</key>
-    <string>Agents Menu Bar</string>
+    <string>AGI Menu</string>
+    <key>CFBundleDisplayName</key>
+    <string>AGI Menu</string>
     <key>CFBundleIconFile</key>
     <string>AppIcon</string>
     <key>CFBundlePackageType</key>

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

@@ -40,10 +40,17 @@ export declare function codesignVerifies(appPath: string): boolean;
  * bootstrap a helper macOS would reject.
  */
 export declare function gatekeeperAssesses(appPath: string): boolean;
+/** True when the bundle carries a Developer ID TeamIdentifier (not ad-hoc). */
+export declare function hasDeveloperIdSignature(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
  * with this install (e.g. Linux package, or a build without the helper).
+ *
+ * Also heals an older install that was ad-hoc re-signed over a Developer ID
+ * source: that unstable identity made Accessibility re-prompt on every upgrade.
+ * When the shipped source is Developer ID and the installed copy is only
+ * ad-hoc, replace it — even without forceReinstall.
  */
 export declare function ensureMenubarAppInstalled(opts?: {
     forceReinstall?: boolean;

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

@@ -205,10 +205,25 @@ export function gatekeeperAssesses(appPath) {
     const r = spawnSync('spctl', ['--assess', '--type', 'exec', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
     return r.status === 0;
 }
+/** True when the bundle carries a Developer ID TeamIdentifier (not ad-hoc). */
+export function hasDeveloperIdSignature(appPath) {
+    const r = spawnSync('codesign', ['-dv', '--verbose=4', appPath], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+    });
+    const out = `${r.stderr || ''}${r.stdout || ''}`;
+    const team = out.match(/TeamIdentifier=([A-Z0-9]+)/)?.[1];
+    return Boolean(team && team !== 'not set');
+}
 /**
  * Copy the bundled `.app` to the stable user path (idempotent unless forced).
  * Returns the installed executable path, or null if no source bundle ships
  * with this install (e.g. Linux package, or a build without the helper).
+ *
+ * Also heals an older install that was ad-hoc re-signed over a Developer ID
+ * source: that unstable identity made Accessibility re-prompt on every upgrade.
+ * When the shipped source is Developer ID and the installed copy is only
+ * ad-hoc, replace it — even without forceReinstall.
  */
 export function ensureMenubarAppInstalled(opts = {}) {
     if (!onDarwin())
@@ -218,7 +233,11 @@ export function ensureMenubarAppInstalled(opts = {}) {
         return null;
     const dest = installedAppPath();
     if (!opts.forceReinstall && fs.existsSync(dest)) {
-        return installedExecutablePath();
+        const sourceIsDevId = hasDeveloperIdSignature(src);
+        const destIsDevId = hasDeveloperIdSignature(dest);
+        if (!(sourceIsDevId && !destIsDevId)) {
+            return installedExecutablePath();
+        }
     }
     copyAppBundle(src, dest);
     // A fresh copy is exactly when the bundle's icon can be new (first install) or
@@ -325,7 +344,7 @@ export function enableMenubarService(opts = { clearOptOut: true }) {
     // 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. ' +
+        process.stderr.write('agents: AGI Menu 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;
     }
@@ -472,8 +491,10 @@ export function installMenubarLaunchAgentOnUpgrade() {
         }
         // Re-enable (recopy helper + rewrite plist) when the version drifted OR the
         // plist's baked interpreter/entry no longer point at the install now running
-        // `agents` — the dual-install skew a version bump alone can't catch.
-        if (menubarSetupStale() || menubarSetupNeedsRepoint()) {
+        // `agents` — the dual-install skew a version bump alone can't catch — OR the
+        // installed copy is still ad-hoc while the shipped source is Developer ID
+        // (older heal path; Accessibility re-prompts until the identity is restored).
+        if (menubarSetupStale() || menubarSetupNeedsRepoint() || installedNeedsDevIdHeal()) {
             enableMenubarService({ clearOptOut: false });
         }
     }
@@ -481,6 +502,15 @@ export function installMenubarLaunchAgentOnUpgrade() {
         /* never block startup on the menu bar */
     }
 }
+/** True when App Support still has an ad-hoc copy but the npm bundle is Developer ID. */
+function installedNeedsDevIdHeal() {
+    const src = sourceAppPath();
+    if (!src || !fs.existsSync(installedAppPath()))
+        return false;
+    if (hasDeveloperIdSignature(installedAppPath()))
+        return false;
+    return hasDeveloperIdSignature(src);
+}
 /**
  * Decide which live helper processes must be ended so exactly one status item
  * survives. Pure so the choice is unit-testable without a live menu bar.
@@ -521,12 +551,12 @@ export function runMenubarSetup() {
         steps.push({ name, outcome, detail });
     };
     if (!onDarwin()) {
-        step('platform', 'failed', `the menu bar helper is macOS only (this is ${process.platform})`);
+        step('platform', 'failed', `AGI Menu is macOS only (this is ${process.platform})`);
         return { steps, configured: false, status: getMenubarStatus() };
     }
     const before = getMenubarStatus();
     if (!sourceAppPath()) {
-        step('bundle', 'failed', 'no menu-bar helper bundle ships with this install');
+        step('bundle', 'failed', 'no AGI Menu bundle ships with this install');
         return { steps, configured: false, status: before };
     }
     // 3 before 1: end the running copies BEFORE swapping the bundle underneath

package/dist/lib/monitors/config.d.ts

@@ -80,7 +80,7 @@ export interface ActionConfig {
     timeout?: string;
     /** routine: name of an existing routine to fire. */
     routine?: string;
-    /** notify: channel for the notification (default `telegram`). */
+    /** notify: override the owner channel (defaults to `notify.owner.channel`). */
     notifyChannel?: string;
     /** webhook-out: URL to POST the event to. */
     url?: string;

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

@@ -5,8 +5,12 @@
  * action goes through the *same* detached spawn cron and webhook fires use
  * (executeJobDetached, lib/runner.ts) — a monitor never duplicates spawn logic,
  * it synthesizes a JobConfig and hands it to the one dispatch seam. `notify`
- * reuses the openclaw Telegram path (lib/notify.ts); `webhook-out` POSTs the event.
+ * routes the owner through the one channel seam (sendToOwner → lookupTransport,
+ * lib/notify.ts) — recipient from notify.owner, no hardcoded chat id, and an
+ * unresolvable channel comes back as `ok: false` instead of exiting the daemon;
+ * `webhook-out` POSTs the event.
  */
+import type { Meta } from '../types.js';
 import type { ActionConfig, MonitorConfig, MonitorEvent } from './config.js';
 /** Outcome of a dispatched action. */
 export interface DispatchResult {
@@ -25,4 +29,4 @@ export declare function injectEvent(prompt: string, event: MonitorEvent): string
  * use. `routine` fires an existing routine with the event injected. `notify` and
  * `webhook-out` are terminal side-effects.
  */
-export declare function dispatchAction(monitor: MonitorConfig, event: MonitorEvent): Promise<DispatchResult>;
+export declare function dispatchAction(monitor: MonitorConfig, event: MonitorEvent, meta?: Meta): Promise<DispatchResult>;

package/dist/lib/monitors/dispatch.js

@@ -5,14 +5,14 @@
  * action goes through the *same* detached spawn cron and webhook fires use
  * (executeJobDetached, lib/runner.ts) — a monitor never duplicates spawn logic,
  * it synthesizes a JobConfig and hands it to the one dispatch seam. `notify`
- * reuses the openclaw Telegram path (lib/notify.ts); `webhook-out` POSTs the event.
+ * routes the owner through the one channel seam (sendToOwner → lookupTransport,
+ * lib/notify.ts) — recipient from notify.owner, no hardcoded chat id, and an
+ * unresolvable channel comes back as `ok: false` instead of exiting the daemon;
+ * `webhook-out` POSTs the event.
  */
-import { execFile } from 'child_process';
-import { promisify } from 'util';
 import { executeJobDetached } from '../runner.js';
 import { readJob } from '../routines.js';
-import { buildOpenClawNotifyArgs } from '../notify.js';
-const execFileAsync = promisify(execFile);
+import { sendToOwner } from '../notify.js';
 /** Replace `{event}` in a prompt with the fired event summary. */
 export function injectEvent(prompt, event) {
     return prompt.replace(/\{event\}/g, event.summary);
@@ -24,7 +24,7 @@ export function injectEvent(prompt, event) {
  * use. `routine` fires an existing routine with the event injected. `notify` and
  * `webhook-out` are terminal side-effects.
  */
-export async function dispatchAction(monitor, event) {
+export async function dispatchAction(monitor, event, meta) {
     const action = monitor.action;
     if (action.type === 'run') {
         const job = {
@@ -63,16 +63,11 @@ export async function dispatchAction(monitor, event) {
         }
     }
     if (action.type === 'notify') {
-        const args = buildOpenClawNotifyArgs(event.summary, {
-            channel: action.notifyChannel ?? 'telegram',
+        const result = await sendToOwner(event.summary, {
+            ...(meta ? { meta } : {}),
+            ...(action.notifyChannel ? { channel: action.notifyChannel } : {}),
         });
-        try {
-            await execFileAsync('openclaw', args);
-            return { kind: 'notify', ok: true };
-        }
-        catch (err) {
-            return { kind: 'notify', ok: false, error: err.message };
-        }
+        return { kind: 'notify', ok: result.ok, ...(result.ok ? {} : { error: result.error }) };
     }
     // webhook-out
     if (!action.url)

package/dist/lib/notify.d.ts

@@ -1,9 +1,29 @@
+/**
+ * Owner notifier — the one seam for "ping the human" messages.
+ *
+ * Every human-facing owner notification (feed urgent-block dispatch, monitor
+ * `notify` action, `agents notify`) funnels through the single channel seam:
+ * `lookupTransport(channel, meta).provider.send(text, opts)`. The recipient comes
+ * from `notify.owner` in agents.yaml — never a hardcoded chat id — so changing the
+ * owner is honoured by every path at once. `notify.transports` picks the actual
+ * provider per host (rush telegram on zion, openclaw-telegram on mac-mini).
+ * Best-effort: a delivery failure is returned to the caller, never thrown, so a
+ * notification hiccup never blocks the agent. That is why this module resolves
+ * with `lookupTransport` and not the `die()`-capable `resolveTransport` — the
+ * monitor daemon and the feed-dispatch loop call in here, and `process.exit()`
+ * would take them down on a typo'd channel name, bypassing their try/catch.
+ */
 import type { OpenBlock } from './feed.js';
-export interface NotifyOptions {
+import type { Meta } from './types.js';
+import type { SendResult } from './channels/registry.js';
+export interface OwnerNotifyOptions {
+    /** Config source (defaults to `readMeta()`); lets callers/tests inject it. */
+    meta?: Meta;
+    /** Override the owner channel from `notify.owner.channel`. */
     channel?: string;
-    account?: string;
-    /** OpenClaw destination (Telegram chat id). Defaults to Muqsit's chat. */
+    /** Override the owner target from `notify.owner.to`. */
     target?: string;
+    /** Resolve + build the delivery but do not actually send. */
     dryRun?: boolean;
 }
 export interface NotifyResult {
@@ -12,6 +32,22 @@ export interface NotifyResult {
     error?: string;
 }
 export declare function formatUrgentBlockMessage(block: OpenBlock): string;
-/** Build openclaw argv for urgent notify (exported for tests). */
-export declare function buildOpenClawNotifyArgs(text: string, options?: Pick<NotifyOptions, 'channel' | 'account' | 'target'>): string[];
-export declare function notifyUrgentBlock(block: OpenBlock, options?: NotifyOptions): Promise<NotifyResult>;
+/**
+ * Build openclaw argv for a Telegram send (used by the openclaw-telegram
+ * provider and its tests). `target` is required — the recipient is always
+ * resolved by the caller, never defaulted to a hardcoded number here.
+ */
+export declare function buildOpenClawNotifyArgs(text: string, opts: {
+    target: string;
+    channel?: string;
+    account?: string;
+}): string[];
+/**
+ * Deliver a message to the configured owner through the one channel seam.
+ * `channel`/`target` default to `notify.owner.{channel,to}`; `notify.transports`
+ * selects the provider per host. A missing owner config or a delivery failure
+ * (e.g. openclaw not on PATH) returns a clean `SendResult` error — never a raw
+ * ENOENT — so callers surface a consistent, best-effort failure.
+ */
+export declare function sendToOwner(text: string, options?: OwnerNotifyOptions): Promise<SendResult>;
+export declare function notifyUrgentBlock(block: OpenBlock, options?: OwnerNotifyOptions): Promise<NotifyResult>;