@phnx-labs/agents-cli 1.20.90 → 1.20.91

package/dist/commands/sessions-picker.js

@@ -18,6 +18,7 @@ import { extractTodoProgress, WORKTREE_RE } from '../lib/session/state.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { itemPicker } from '../lib/picker.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
+import { extractArtifacts, extractHooks, extractLinks, extractRepos, extractSkills } from '../lib/session/highlights.js';
 /** A session whose transcript lives on another machine (folded in over the live
  * cross-machine fan-out): its `filePath` is on that peer's disk, so the preview
  * can't parse it locally — it shows metadata + a "resume there" note instead.
@@ -417,9 +418,15 @@ function formatCompactPreview(events, session) {
     }
     // Recent activity = directories touched (not raw tool calls). Prefer a
     // parser-supplied dirsTouched when present; else derive from event paths.
+    // Width-capped: a long Dirs line used to wrap and swamp the whole pane.
     const dirs = directoriesTouched(session, events, changes);
     if (dirs.length) {
-        lines.push(chalk.cyan('Dirs:    ') + chalk.white(dirs.join(chalk.gray(' · '))));
+        lines.push(chalk.cyan('Dirs:    ') + joinWidthCapped(dirs, termWidth - 12));
+    }
+    // Repos worked in (basename of each `.git` root under the touched paths).
+    const repos = extractRepos(events, session.cwd);
+    if (repos.length) {
+        lines.push(chalk.cyan('Repos:   ') + chalk.white(repos.slice(0, 4).join(chalk.gray(' · '))));
     }
     const teamLine = formatTeamLineage(session);
     if (teamLine) {
@@ -442,6 +449,41 @@ function formatCompactPreview(events, session) {
     if (activity.length) {
         lines.push(chalk.cyan('Changes:  ') + activity.join(chalk.gray(' · ')));
     }
+    // Documents the session produced (`.agents/artifacts|plans|reports`, other
+    // *.md/*.html creations) — the files a human browses later, named + clickable.
+    const artifacts = extractArtifacts(changes);
+    if (artifacts.length) {
+        const shown = artifacts.slice(0, 5).map(a => linkPath(a.path, a.basename));
+        const more = artifacts.length > 5 ? chalk.gray(` · +${artifacts.length - 5} more`) : '';
+        lines.push(chalk.cyan('Artifacts: ') + shown.join(chalk.gray(' · ')) + more);
+    }
+    // Skills invoked (plugin skills included — they ride the same Skill tool).
+    const skills = extractSkills(events);
+    if (skills.length) {
+        const shown = skills.slice(0, 5).map(s => chalk.white(s.name) + (s.count > 1 ? chalk.gray(` ×${s.count}`) : ''));
+        const more = skills.length > 5 ? chalk.gray(` · +${skills.length - 5} more`) : '';
+        lines.push(chalk.cyan('Skills:  ') + shown.join(chalk.gray(' · ')) + more);
+    }
+    // Hooks fired (Claude transcripts record firings; other harnesses don't).
+    const hooks = extractHooks(events);
+    if (hooks.length) {
+        const shown = hooks.slice(0, 4).map(h => chalk.white(h.name) + (h.count > 1 ? chalk.gray(` ×${h.count}`) : '') + (h.failed ? chalk.red(` (${h.failed} failed)`) : ''));
+        const more = hooks.length > 4 ? chalk.gray(` · +${hooks.length - 4} more`) : '';
+        lines.push(chalk.cyan('Hooks:   ') + shown.join(chalk.gray(' · ')) + more);
+    }
+    // Links mentioned in the conversation — clickable (OSC 8), tracker-classified.
+    const links = extractLinks(events);
+    if (links.length) {
+        const shown = links.slice(0, 5).map(l => chalk.blue(linkUrl(l.url, l.label)));
+        const more = links.length > 5 ? chalk.gray(` · +${links.length - 5} more`) : '';
+        lines.push(chalk.cyan('Links:   ') + shown.join(chalk.gray(' · ')) + more);
+    }
+    // Error tally, mirroring the full summary's Errors section in one line.
+    const errorEvents = events.filter(e => e.type === 'error');
+    if (errorEvents.length) {
+        const first = errorEvents[0].tool || 'unknown';
+        lines.push(chalk.cyan('Errors:  ') + chalk.red(`${errorEvents.length} failure${errorEvents.length === 1 ? '' : 's'}`) + chalk.gray(` — first: ${first}`));
+    }
     const metadata = [
         ...toolTags,
         subAgentCount ? `${subAgentCount} sub-agent${subAgentCount === 1 ? '' : 's'}` : '',
@@ -559,12 +601,39 @@ function encodeClaudeSlug(absPath) {
 }
 /** The `.agents/worktrees/<name>` marker, Claude-slug-encoded (`/.` → `--`). */
 const SLUG_WORKTREE_RE = /--agents-worktrees-(.+)$/;
+/**
+ * Join display tokens with ` · `, stopping before the line exceeds `maxWidth`
+ * and appending `… +N more` for the rest. Keeps the Dirs line on one row.
+ */
+function joinWidthCapped(items, maxWidth) {
+    const sep = ' · ';
+    let out = '';
+    let shown = 0;
+    for (const item of items) {
+        const next = shown === 0 ? item : out + sep + item;
+        if (shown > 0 && next.length > maxWidth)
+            break;
+        out = next;
+        shown++;
+    }
+    const remaining = items.length - shown;
+    const suffix = remaining > 0 ? ` … +${remaining} more` : '';
+    return chalk.white(out) + (suffix ? chalk.gray(suffix) : '');
+}
 /** Relativize a file path to its parent dir, short enough for one preview line. */
 export function relativizeDir(filePath, cwd) {
     const norm = filePath.replace(/\\/g, '/');
     if (!norm || norm.includes('node_modules') || norm.includes('/.git/') || norm.includes('/plans/')) {
         return undefined;
     }
+    // agents-cli internals — version homes, session/run archives, the bare
+    // worktree container/root — are never meaningful "directories the user works
+    // in". Cwd is exempt: a session running inside such a dir keeps its own paths.
+    const normBase = cwd?.replace(/\\/g, '/').replace(/\/$/, '');
+    const underCwd = normBase && (norm === normBase || norm.startsWith(normBase + '/'));
+    if (!underCwd && (norm.includes('/.agents/.history/') || /\/\.agents\/worktrees(\/[^/]+)?\/?$/.test(norm))) {
+        return undefined;
+    }
     let dir = path.posix.dirname(norm);
     // Claude project-slug form: a leading `-`-segment (`-home-me-…`) that carries
     // the cwd, lossily encoded. Handle it in SLUG SPACE — never lossy-decode to a

package/dist/index.js

@@ -94,7 +94,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadHq, loadFeed, loadActivity, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadPerf, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadHq, loadFeed, loadActivity, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
@@ -173,11 +173,24 @@ program.hook('postAction', (_thisCommand, actionCommand) => {
         if (parts.length === 0)
             return;
         const started = auditStarts.get(actionCommand);
+        const durationMs = started !== undefined ? Date.now() - started : undefined;
+        const command = parts.join(' ');
         emit('command.end', {
             module: parts[0],
-            command: parts.join(' '),
-            ...(started !== undefined ? { durationMs: Date.now() - started } : {}),
+            command,
+            ...(durationMs !== undefined ? { durationMs } : {}),
         });
+        // Disposable perf warehouse — fail-soft spool append (no SQLite on this path).
+        if (durationMs !== undefined && parts[0] !== 'perf') {
+            void import('./lib/perf/spool.js').then(({ recordSample }) => {
+                recordSample({
+                    kind: 'command.end',
+                    label: command,
+                    durationMs,
+                    cwd: process.cwd(),
+                });
+            }).catch(() => { });
+        }
     }
     catch {
         // Best-effort completion record; the start line is the durable audit fact.
@@ -269,6 +282,7 @@ Credentials and profiles:
 Diagnostics:
   doctor [agent[@version]]        Diagnose CLI availability, sync status, and resource divergence; --check for the CI drift gate
   usage [agent]                   Show rate-limit and quota usage per agent
+  perf                            Latency rollups (hooks, commands, runs) from the disposable perf warehouse
 
 Config sync:
   drive                           Sync session history across machines via rsync
@@ -885,6 +899,7 @@ async function registerAllEagerCommands() {
     await reg(loadFactory);
     await reg(loadUsage);
     await reg(loadCost);
+    await reg(loadPerf);
     await reg(loadOutput);
     await reg(loadBudget);
     await reg(loadAlias);

package/dist/lib/activity.d.ts

@@ -2,7 +2,17 @@ import type { EventRecord } from './events.js';
 /** Recognizable milestone events, ordered first in any activity lane. */
 export type MilestoneEvent = 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created'
 /** Deliberate agent-authored progress post (`agents feed post`). */
- | 'status.posted';
+ | 'status.posted'
+/**
+ * The same post, but the agent is STUCK (`agents feed post --blocked`).
+ *
+ * A distinct event rather than a flag on `status.posted` because it is a
+ * different kind of thing in the stream: a benign update is history the
+ * moment it lands, while a blocked post stays open until someone answers it.
+ * Readers that show "what needs a human" select on this; readers that show
+ * "what happened" get both.
+ */
+ | 'status.blocked';
 /** Routine activity events, collapsed to counts by readers. */
 export type ActivityKind = 'file.edited';
 export type ActivityEventKind = MilestoneEvent | ActivityKind;

package/dist/lib/activity.js

@@ -38,6 +38,7 @@ export const MILESTONE_EVENTS = [
     'task.completed',
     'checklist.created',
     'status.posted',
+    'status.blocked',
 ];
 const MILESTONE_SET = new Set(MILESTONE_EVENTS);
 export function tierForEvent(event) {

package/dist/lib/catchup.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Catch-up: run a routine whose scheduled fire this device missed.
+ *
+ * Fires are in-process croner timers, and croner only ever schedules forward
+ * from "now". A daemon that is down, asleep, or wedged when a routine comes due
+ * therefore loses that fire outright — `loadAll()` rebuilds every Cron looking
+ * only at the future (scheduler.ts), so nothing replays it. Detection has always
+ * existed (`detectOverdueJobs`), but it ran once at daemon startup and only
+ * logged plus popped a notification; the routine still never ran.
+ *
+ * This module closes that loop. A missed fire is:
+ *
+ *   1. CLAIMED — `claimMissedFire` writes a real run with status `missed`,
+ *      stamped at the time the fire was DUE, so `agents routines runs <name>`
+ *      shows the gap instead of the listing showing a weeks-old `completed` as
+ *      though it were current. The write is an atomic claim (see below), and
+ *      only the claimant proceeds to step 2.
+ *   2. RUN — unless the routine sets `catchup: false`, it is executed late via
+ *      the same `executeJobDetached` path `agents routines catchup` already used.
+ *
+ * The `missed` record is also what makes this idempotent, so there is no
+ * separate ledger to keep in sync. `detectOverdueJobs` compares the most recent
+ * expected fire against `getLatestRun(...).startedAt`; a `missed` record stamped
+ * at `expectedAt` advances that comparison, so the same missed fire is never
+ * reconsidered — across ticks, daemon restarts, or a restart storm. (A job that
+ * is overdue by definition has no run later than `expectedAt`, so the
+ * back-stamped record always sorts last in `listRuns`.)
+ *
+ * That comparison alone is not enough when two callers overlap, because both
+ * can read the same overdue set before either writes. The claim in
+ * `claimMissedFire` closes that: the record's directory is created with a
+ * non-recursive `mkdir`, an atomic test-and-set, and only the caller that wins
+ * it runs the routine. This holds across processes — the daemon's timer and a
+ * human running `agents routines catchup` — which neither an in-process flag
+ * nor `withFileLock` (synchronous; this pass awaits a spawn) can cover.
+ */
+import { type JobConfig, type RunMeta } from './routines.js';
+import { type OverdueJob } from './overdue.js';
+/** What happened to one overdue routine on a catch-up pass. */
+export interface CatchupOutcome {
+    name: string;
+    /** The fire that was missed. */
+    expectedAt: Date;
+    /**
+     * `ran` — re-run late. `recorded` — miss logged, not re-run (`catchup: false`
+     * or a dry run). `claimed-elsewhere` — a concurrent pass or process already
+     * owns this fire. `error` — could not start the late run.
+     */
+    result: 'ran' | 'recorded' | 'claimed-elsewhere' | 'error';
+    /** Run id of the late run, when one was started. */
+    runId?: string;
+    /** Why the late run could not be started. */
+    error?: string;
+}
+/**
+ * Is this routine allowed to run late? Default true — a routine you scheduled
+ * is one you expect to have run, so losing a fire silently is never the helpful
+ * default. `catchup: false` opts out a routine whose worth expires with its slot.
+ */
+export declare function shouldCatchUp(job: Pick<JobConfig, 'catchup'>): boolean;
+/** The run id a missed fire is recorded under — derived from when it was DUE. */
+export declare function missedRunId(expectedAt: Date): string;
+/**
+ * CLAIM a missed fire: atomically record that it never happened, and report
+ * whether this caller is the one that recorded it.
+ *
+ * Returns the run on a successful claim, or `null` when another caller already
+ * claimed the same (routine, expected-fire) pair. That return value is the
+ * concurrency control for the whole module — only the claimant runs the routine
+ * late, so a fire can never be spawned twice.
+ *
+ * The atomicity is the non-recursive `mkdir` of the run directory: on every
+ * POSIX filesystem that is a single test-and-set, failing with EEXIST if the
+ * directory is already there. It therefore holds between the daemon's timer and
+ * a human running `agents routines catchup` in a separate process — which an
+ * in-process re-entrancy flag cannot cover, and which a lock cannot cover either
+ * (`withFileLock` is synchronous and this pass awaits a spawn).
+ *
+ * The run id is derived from `expectedAt` rather than "now" so the same missed
+ * fire always maps to the same directory — that is what makes the claim
+ * meaningful — and so the record sorts into `listRuns` (lexical over ISO run
+ * ids) at the point the gap actually occurred.
+ *
+ * Deliberately at-most-once: a process that dies between claiming and spawning
+ * leaves the fire un-run. That is the right trade for something that starts
+ * agent processes — a double spawn costs real work and money, while the miss is
+ * still on the record for a human to see and re-run.
+ */
+export declare function claimMissedFire(job: JobConfig, expectedAt: Date): RunMeta | null;
+export interface CatchupOptions {
+    /** Record misses but start no late runs. Powers `catchup --dry-run`. */
+    dryRun?: boolean;
+    /** Clock injection seam for tests. */
+    now?: Date;
+    /** Overdue set to act on. Defaults to detecting it. Lets a caller reuse a scan. */
+    overdue?: OverdueJob[];
+}
+/**
+ * Record — and, unless opted out, re-run — every routine this device missed.
+ *
+ * Device scoping is already enforced upstream: `detectOverdueJobs` skips a job
+ * pinned elsewhere (overdue.ts), so a fleet of machines never all catch up the
+ * same routine.
+ */
+export declare function runCatchup(opts?: CatchupOptions): Promise<CatchupOutcome[]>;

package/dist/lib/catchup.js

@@ -0,0 +1,160 @@
+/**
+ * Catch-up: run a routine whose scheduled fire this device missed.
+ *
+ * Fires are in-process croner timers, and croner only ever schedules forward
+ * from "now". A daemon that is down, asleep, or wedged when a routine comes due
+ * therefore loses that fire outright — `loadAll()` rebuilds every Cron looking
+ * only at the future (scheduler.ts), so nothing replays it. Detection has always
+ * existed (`detectOverdueJobs`), but it ran once at daemon startup and only
+ * logged plus popped a notification; the routine still never ran.
+ *
+ * This module closes that loop. A missed fire is:
+ *
+ *   1. CLAIMED — `claimMissedFire` writes a real run with status `missed`,
+ *      stamped at the time the fire was DUE, so `agents routines runs <name>`
+ *      shows the gap instead of the listing showing a weeks-old `completed` as
+ *      though it were current. The write is an atomic claim (see below), and
+ *      only the claimant proceeds to step 2.
+ *   2. RUN — unless the routine sets `catchup: false`, it is executed late via
+ *      the same `executeJobDetached` path `agents routines catchup` already used.
+ *
+ * The `missed` record is also what makes this idempotent, so there is no
+ * separate ledger to keep in sync. `detectOverdueJobs` compares the most recent
+ * expected fire against `getLatestRun(...).startedAt`; a `missed` record stamped
+ * at `expectedAt` advances that comparison, so the same missed fire is never
+ * reconsidered — across ticks, daemon restarts, or a restart storm. (A job that
+ * is overdue by definition has no run later than `expectedAt`, so the
+ * back-stamped record always sorts last in `listRuns`.)
+ *
+ * That comparison alone is not enough when two callers overlap, because both
+ * can read the same overdue set before either writes. The claim in
+ * `claimMissedFire` closes that: the record's directory is created with a
+ * non-recursive `mkdir`, an atomic test-and-set, and only the caller that wins
+ * it runs the routine. This holds across processes — the daemon's timer and a
+ * human running `agents routines catchup` — which neither an in-process flag
+ * nor `withFileLock` (synchronous; this pass awaits a spawn) can cover.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { readJob, writeRunMeta, getRunDir, } from './routines.js';
+import { detectOverdueJobs } from './overdue.js';
+import { executeJobDetached } from './runner.js';
+/**
+ * Is this routine allowed to run late? Default true — a routine you scheduled
+ * is one you expect to have run, so losing a fire silently is never the helpful
+ * default. `catchup: false` opts out a routine whose worth expires with its slot.
+ */
+export function shouldCatchUp(job) {
+    return job.catchup !== false;
+}
+/** The run id a missed fire is recorded under — derived from when it was DUE. */
+export function missedRunId(expectedAt) {
+    return expectedAt.toISOString().replace(/[:.]/g, '-');
+}
+/**
+ * CLAIM a missed fire: atomically record that it never happened, and report
+ * whether this caller is the one that recorded it.
+ *
+ * Returns the run on a successful claim, or `null` when another caller already
+ * claimed the same (routine, expected-fire) pair. That return value is the
+ * concurrency control for the whole module — only the claimant runs the routine
+ * late, so a fire can never be spawned twice.
+ *
+ * The atomicity is the non-recursive `mkdir` of the run directory: on every
+ * POSIX filesystem that is a single test-and-set, failing with EEXIST if the
+ * directory is already there. It therefore holds between the daemon's timer and
+ * a human running `agents routines catchup` in a separate process — which an
+ * in-process re-entrancy flag cannot cover, and which a lock cannot cover either
+ * (`withFileLock` is synchronous and this pass awaits a spawn).
+ *
+ * The run id is derived from `expectedAt` rather than "now" so the same missed
+ * fire always maps to the same directory — that is what makes the claim
+ * meaningful — and so the record sorts into `listRuns` (lexical over ISO run
+ * ids) at the point the gap actually occurred.
+ *
+ * Deliberately at-most-once: a process that dies between claiming and spawning
+ * leaves the fire un-run. That is the right trade for something that starts
+ * agent processes — a double spawn costs real work and money, while the miss is
+ * still on the record for a human to see and re-run.
+ */
+export function claimMissedFire(job, expectedAt) {
+    const runId = missedRunId(expectedAt);
+    const runDir = getRunDir(job.name, runId);
+    fs.mkdirSync(path.dirname(runDir), { recursive: true });
+    try {
+        fs.mkdirSync(runDir); // non-recursive: throws EEXIST if already claimed
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return null;
+        throw err;
+    }
+    const at = expectedAt.toISOString();
+    const meta = {
+        jobName: job.name,
+        runId,
+        agent: job.agent,
+        workflow: job.workflow,
+        command: job.command,
+        pid: null,
+        status: 'missed',
+        startedAt: at,
+        completedAt: at,
+        exitCode: null,
+        errorMessage: 'scheduled fire missed — the scheduler was not running when it came due',
+        actor: job.actor,
+    };
+    writeRunMeta(meta);
+    return meta;
+}
+/**
+ * Record — and, unless opted out, re-run — every routine this device missed.
+ *
+ * Device scoping is already enforced upstream: `detectOverdueJobs` skips a job
+ * pinned elsewhere (overdue.ts), so a fleet of machines never all catch up the
+ * same routine.
+ */
+export async function runCatchup(opts = {}) {
+    const overdue = opts.overdue ?? detectOverdueJobs(opts.now ?? new Date());
+    const outcomes = [];
+    for (const entry of overdue) {
+        const config = readJob(entry.name);
+        if (!config) {
+            outcomes.push({
+                name: entry.name,
+                expectedAt: entry.expectedAt,
+                result: 'error',
+                error: 'config not found',
+            });
+            continue;
+        }
+        // Claim first. Losing the claim means another pass (or another process)
+        // already owns this fire — say so rather than running it a second time.
+        if (claimMissedFire(config, entry.expectedAt) === null) {
+            outcomes.push({ name: entry.name, expectedAt: entry.expectedAt, result: 'claimed-elsewhere' });
+            continue;
+        }
+        if (!shouldCatchUp(config) || opts.dryRun) {
+            outcomes.push({ name: entry.name, expectedAt: entry.expectedAt, result: 'recorded' });
+            continue;
+        }
+        try {
+            const meta = await executeJobDetached(config);
+            outcomes.push({
+                name: entry.name,
+                expectedAt: entry.expectedAt,
+                result: 'ran',
+                runId: meta.runId,
+            });
+        }
+        catch (err) {
+            outcomes.push({
+                name: entry.name,
+                expectedAt: entry.expectedAt,
+                result: 'error',
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return outcomes;
+}

package/dist/lib/channels/providers/desktop.d.ts

@@ -0,0 +1,49 @@
+import type { ChannelProvider } from '../registry.js';
+/**
+ * Split one message into the notification's title and body.
+ *
+ * A broadcast sink hands us `composeBroadcastMessage`'s shape — `<project> · <text>`
+ * with any link on a second line — so honouring the newline puts the human
+ * sentence in the title and the URL underneath, which is how the existing
+ * daemon notifications already read.
+ *
+ * Notification banners show roughly two lines before an ellipsis, so a long
+ * single-line message is split at the title boundary rather than truncated away:
+ * the head becomes the title and the remainder still arrives in the body.
+ */
+export declare function splitDesktopMessage(text: string): {
+    title: string;
+    body: string;
+};
+/**
+ * Which native notifier this platform wires, or undefined when it wires none.
+ *
+ * macOS always ships `osascript`, and `notifyDesktop` prefers the branded
+ * MenubarHelper when installed and degrades to osascript otherwise — either way
+ * something delivers. Linux depends on `notify-send`, which is NOT guaranteed
+ * (a headless box typically lacks it), so the platform answer alone is not proof
+ * there — see `desktopDeliverable`. Every other platform has no wired notifier at
+ * all (`notifyDesktop` is a documented no-op), so sending there must fail loud.
+ *
+ * Pure and platform-injectable so the gate is testable without spawning.
+ */
+export declare function desktopNotifier(platform?: NodeJS.Platform): string | undefined;
+/**
+ * Whether a notification sent right now would actually arrive.
+ *
+ * On Linux the notifier is a separate binary that is frequently absent, and
+ * `notifyDesktop` spawns it detached — an ENOENT surfaces asynchronously and is
+ * swallowed. Reporting `ok` off the platform name alone would therefore mark an
+ * undelivered notification as delivered, which is the same silent failure this
+ * provider exists to remove, just relocated. So probe for the binary.
+ *
+ * macOS needs no probe: `osascript` is part of the OS, so the degrade path is
+ * always available even when MenubarHelper is not installed.
+ */
+export declare function desktopDeliverable(platform?: NodeJS.Platform): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare const desktopProvider: ChannelProvider;

package/dist/lib/channels/providers/desktop.js

@@ -0,0 +1,132 @@
+/**
+ * Desktop provider — the local machine's native notification centre.
+ *
+ * The only channel with no external dependency: no network, no login, no vendor
+ * CLI. On the Mac the operator is sitting at it works when every other channel is
+ * dead, which is exactly when a blocked agent most needs to reach them.
+ *
+ * Delivery reuses `notifyDesktop` (lib/menubar/notify-desktop.ts), so a message
+ * sent here is attributed to MenubarHelper.app and carries the agents-cli mark —
+ * the same path that produces the "agents-cli / <title> / <body>" entries already
+ * in Notification Center.
+ *
+ * WHY THIS ISN'T A THIN PASSTHROUGH: `notifyDesktop` is deliberately
+ * fire-and-forget — it spawns detached and swallows every failure so a hiccup can
+ * never take the daemon down. A channel provider cannot inherit that: a sink that
+ * always reports `ok: true` would make an undelivered notification look delivered,
+ * which is the precise class of silent failure this whole subsystem exists to
+ * kill. So the provider resolves *deliverability* up front — is there a notifier
+ * on this platform at all — and fails loud when there is not. It reports what it
+ * can actually know: on a platform with no notifier, nothing will arrive.
+ */
+import * as os from 'os';
+import { spawnSync } from 'child_process';
+import { notifyDesktop } from '../../menubar/notify-desktop.js';
+const NAME = 'desktop';
+/** Longest title before macOS truncates it in the banner. Keeps the ask readable. */
+const TITLE_MAX = 64;
+/**
+ * Split one message into the notification's title and body.
+ *
+ * A broadcast sink hands us `composeBroadcastMessage`'s shape — `<project> · <text>`
+ * with any link on a second line — so honouring the newline puts the human
+ * sentence in the title and the URL underneath, which is how the existing
+ * daemon notifications already read.
+ *
+ * Notification banners show roughly two lines before an ellipsis, so a long
+ * single-line message is split at the title boundary rather than truncated away:
+ * the head becomes the title and the remainder still arrives in the body.
+ */
+export function splitDesktopMessage(text) {
+    const trimmed = text.trim();
+    const newline = trimmed.indexOf('\n');
+    if (newline !== -1) {
+        return {
+            title: trimmed.slice(0, newline).trim().slice(0, TITLE_MAX),
+            body: trimmed.slice(newline + 1).trim(),
+        };
+    }
+    if (trimmed.length <= TITLE_MAX) {
+        return { title: trimmed, body: '' };
+    }
+    // Break on the last word boundary inside the limit so the title doesn't end
+    // mid-word; fall back to a hard cut when there is no space to break on.
+    const head = trimmed.slice(0, TITLE_MAX);
+    const cut = head.lastIndexOf(' ');
+    const at = cut > TITLE_MAX / 2 ? cut : TITLE_MAX;
+    return { title: trimmed.slice(0, at).trim(), body: trimmed.slice(at).trim() };
+}
+/**
+ * Which native notifier this platform wires, or undefined when it wires none.
+ *
+ * macOS always ships `osascript`, and `notifyDesktop` prefers the branded
+ * MenubarHelper when installed and degrades to osascript otherwise — either way
+ * something delivers. Linux depends on `notify-send`, which is NOT guaranteed
+ * (a headless box typically lacks it), so the platform answer alone is not proof
+ * there — see `desktopDeliverable`. Every other platform has no wired notifier at
+ * all (`notifyDesktop` is a documented no-op), so sending there must fail loud.
+ *
+ * Pure and platform-injectable so the gate is testable without spawning.
+ */
+export function desktopNotifier(platform = os.platform()) {
+    if (platform === 'darwin')
+        return 'menubar-or-osascript';
+    if (platform === 'linux')
+        return 'notify-send';
+    return undefined;
+}
+/**
+ * Whether a notification sent right now would actually arrive.
+ *
+ * On Linux the notifier is a separate binary that is frequently absent, and
+ * `notifyDesktop` spawns it detached — an ENOENT surfaces asynchronously and is
+ * swallowed. Reporting `ok` off the platform name alone would therefore mark an
+ * undelivered notification as delivered, which is the same silent failure this
+ * provider exists to remove, just relocated. So probe for the binary.
+ *
+ * macOS needs no probe: `osascript` is part of the OS, so the degrade path is
+ * always available even when MenubarHelper is not installed.
+ */
+export function desktopDeliverable(platform = os.platform()) {
+    const notifier = desktopNotifier(platform);
+    if (!notifier) {
+        return { ok: false, reason: `no desktop notifier on ${platform} — nothing would be delivered` };
+    }
+    if (platform === 'linux') {
+        const probe = spawnSync('which', ['notify-send'], { stdio: 'ignore' });
+        if (probe.status !== 0) {
+            return { ok: false, reason: 'notify-send not on PATH — nothing would be delivered' };
+        }
+    }
+    return { ok: true };
+}
+export const desktopProvider = {
+    name: NAME,
+    async send(text, opts) {
+        // `target` is meaningless for a local notification — the recipient is whoever
+        // is at this machine — but it is echoed for --json parity with every other
+        // provider, and `agents notify` still requires notify.owner.to to be set.
+        const id = opts.target || os.hostname();
+        // Order matters, and CI caught it: validate the CALLER first, then honour
+        // dry-run, and only then probe the platform.
+        //
+        // An empty message is a caller error on every platform, so it must not be
+        // masked by "this box has no notifier" — the specific, actionable error wins.
+        // And `--dry-run` means "resolve + build but do not send", so it must not
+        // depend on the ability to send; the sibling rush provider likewise returns
+        // ok for a dry run before its own `which rush` check (providers/rush.ts).
+        const { title, body } = splitDesktopMessage(text);
+        if (!title) {
+            return { ok: false, channel: NAME, id, error: 'refusing to send an empty notification' };
+        }
+        if (opts.dryRun) {
+            return { ok: true, channel: NAME, id };
+        }
+        const deliverable = desktopDeliverable();
+        if (!deliverable.ok) {
+            return { ok: false, channel: NAME, id, error: deliverable.reason };
+        }
+        notifyDesktop({ title, body });
+        return { ok: true, channel: NAME, id };
+    },
+};

package/dist/lib/channels/providers/index.js

@@ -7,6 +7,7 @@ import { registerChannelProvider } from '../registry.js';
 import { mailboxProvider } from './mailbox.js';
 import { rushProviders } from './rush.js';
 import { openclawTelegramProvider } from './openclaw-telegram.js';
+import { desktopProvider } from './desktop.js';
 let registered = false;
 /** Register all built-in providers once (idempotent). */
 export function registerBuiltinProviders() {
@@ -17,4 +18,5 @@ export function registerBuiltinProviders() {
     for (const p of rushProviders)
         registerChannelProvider(p);
     registerChannelProvider(openclawTelegramProvider);
+    registerChannelProvider(desktopProvider);
 }