@phnx-labs/agents-cli 1.20.83 → 1.20.85

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 1.20.85
+
+- **`agents feed post` can now be mirrored to the systems you actually watch.**
+  A post was durable but local: an operator away from every terminal never saw
+  it, and the tracker that owns the work heard nothing. Declare sinks under
+  `feed.broadcast` in `agents.yaml` — argv templates, not built-in integrations —
+  and each post is fanned out to them. `--level important` marks a post worth
+  interrupting someone over, so a sink with `minLevel: important` never fires on
+  a routine "CI green"; a template referencing `{ticket}` is skipped when no
+  ticket is known, and the ticket is joined from the session index rather than
+  asked for as a flag. `{message}` composes the human line a messaging sink wants
+  — `<project> · <text>` plus the first attached URL — so an out-of-band ping
+  leads with the project and carries a clickable link. Delivery is best-effort
+  and reported per sink; a mirror that fails never costs you the post. Source:
+  `apps/cli/src/lib/feed-broadcast.ts`, `apps/cli/src/commands/feed.ts`,
+  `apps/cli/docs/06-observability.md`.
+
+- **`agents feed --filter updates` now shows the progress posts agents actually
+  wrote, across the fleet.** The view read the most recent N activity events and
+  *then* kept `status.posted`, so routine `file.edited` churn filled the whole
+  slice — a box with six real posts rendered "0 posts" (and `--json` returned one
+  of six). `readRecentActivity` gained `events` / `tier` filters that apply before
+  the limit, so the limit counts posts; the same fix restores the milestone lane
+  under `agents feed`. The updates view also fans out over SSH like the block view
+  (`-H/--host`, `--device`, `--local` to opt out), because an agent posts on
+  whichever box ran it. Source: `apps/cli/src/lib/activity.ts`,
+  `apps/cli/src/commands/feed.ts`.
+
+- **`agents run --notify` posts a desktop notification when a headless run
+  finishes, and menu-bar quick dispatch now uses it.** The dispatch panel used to
+  post its "finished"/"failed" notice from the MenubarHelper's own
+  process-termination callback, so a helper that restarted mid-run — an upgrade
+  replacing the bundle, a crash — took the callback with it while the run carried
+  on reparented to launchd, and the dispatch could never report back. The run
+  process owns the notice now: armed on its own `exit`, so it covers local,
+  `--host` and `--lease` dispatch alike and survives anything that happens to the
+  launcher. The helper's click actions also accept `url:<https…>` so a completion
+  notification can open the PR or ticket the run produced. Source:
+  `apps/cli/src/lib/run-notify.ts`, `apps/cli/src/commands/exec.ts`,
+  `apps/cli/menubar/Sources/MenubarHelper/AgentsCLI.swift`,
+  `apps/cli/menubar/Sources/MenubarHelper/PromptPanel.swift`.
+
+## 1.20.84
+
+- **Agent onboarding cheat sheet and docs drift guard.** Added
+  `apps/cli/docs/AGENT-CHEATSHEET.md` as a one-page on-ramp for agents, wired it
+  from `apps/cli/AGENTS.md` and `apps/cli/docs/README.md`, and added
+  `scripts/verify-docs.sh` (plus a `verify-docs` npm script and CI job) to catch
+  broken relative links and missing entry-point wiring before merge.
+
+- **Codex can now build, test, and install without escalating to YOLO.** Codex's
+  `workspace-write` sandbox blocks `$HOME`, so `cargo build`, `go build`, `npm/bun install`,
+  `pip install` etc. failed on their out-of-workspace cache writes (`~/.cargo`, `GOCACHE`,
+  `~/.npm`, `~/.cache`, …) — which is what pushed people to `--mode full`
+  (`--dangerously-bypass-approvals-and-sandbox`). agents-cli now writes a platform-resolved
+  baseline of **regenerable toolchain caches** into Codex's `config.toml`
+  (`[sandbox_workspace_write].writable_roots`) on permission sync — `~/.cargo`, `~/.rustup`,
+  `~/.npm`, `~/.bun`, `~/go`, `~/.deno`, `~/.gradle`, `~/.m2`, `~/.gem`, plus `~/Library/Caches`
+  + `~/Library/pnpm` on macOS or `~/.cache` + `~/.local/{share,state}` on Linux. Credential dirs
+  (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.config`, `~/.netrc`) are deliberately excluded, so
+  `--mode auto` stays a real sandbox — far narrower than danger-full-access. Any
+  `writable_roots` you set yourself are preserved (unioned, never clobbered). Source:
+  `apps/cli/src/lib/permissions.ts` (`codexDefaultWritableRoots`, `mergeCodexSandboxWrite`).
+
+- **`agents sessions` team rows now show the team's target and teammate, not just
+  the slug.** Each teammate row reads `<team> · <teammate> · by <orchestrator> ·
+  <live turn | mission>`, where the mission is a one-line summary of the teammate's
+  spawn prompt (`assignedTask`, shown even before it has a transcript). Several
+  teams from one orchestrator stay legible (distinct team names) and each says what
+  it is for. `--active --json` carries `assignedTask`. Source:
+  `apps/cli/src/lib/session/active.ts`, `apps/cli/src/commands/sessions.ts`.
+
 ## 1.20.83
 
 - **Routines now treat date-specific cron schedules as one-shot jobs (RUSH-2074).**

package/dist/commands/exec.js

@@ -367,6 +367,7 @@ export function registerRunCommand(program) {
         .option('--resume [id]', 'Resume a previous conversation. Accepts a full or partial session id (prefix-matched against the index); omit the id to pick from recent sessions interactively. Resumes under the version that started the session. claude/codex resume natively; other agents replay via a /continue first message. Pair with a prompt to continue headlessly.')
         .option('--session-id <id>', 'Force a NEW conversation to use this exact session UUID (Claude only). This CREATES a session — to resume an existing one, use --resume.')
         .option('--name <slug>', 'Name the run — seeds the session label so it shows up as `<name>` in `agents sessions` and resolves by it (and `agents hosts logs <name>` for --host runs) instead of an opaque id. An agent-generated title later refines the label; your name shows until then. Optional.')
+        .option('--notify', 'Post a desktop notification when a headless run finishes. Fired by this process on exit, so it survives whatever launched the run (the menu bar dispatching it, a terminal you closed).')
         .option('--verbose', 'Show detailed execution logs')
         .option('--raw', 'Interactive runs on macOS/Linux launch inside a shared tmux session (for %pane addressing + re-attach). Pass --raw to spawn the agent directly instead. Also disabled by AGENTS_NO_TMUX=1.')
         .option('--no-tmux', 'Spawn the agent directly instead of wrapping it in the shared tmux session. Same effect as --raw / AGENTS_NO_TMUX=1. Use this to see the agent\'s full startup output when a launch is failing.')
@@ -492,6 +493,20 @@ export function registerRunCommand(program) {
             // a native flag, not a prompt. Run interactively.
             prompt = undefined;
         }
+        // --notify: post a desktop notification when this run finishes. Armed on
+        // process exit so it covers EVERY dispatch path below (local, --host,
+        // --lease, the error path) instead of one branch. Only for headless runs
+        // — an interactive run ends in front of the person who started it.
+        if (options.notify && prompt !== undefined) {
+            const { armRunFinishNotification } = await import('../lib/run-notify.js');
+            armRunFinishNotification({
+                agent: agentSpec,
+                name: options.name,
+                prompt,
+                cwd: options.cwd ?? process.cwd(),
+                host: options.host,
+            });
+        }
         // A trailing @ is an explicit request to choose one installed account.
         // Strip only that terminal marker; concrete agent@version pins retain
         // their existing meaning in every dispatch path below.

package/dist/commands/feed.js

@@ -1,7 +1,10 @@
 import chalk from 'chalk';
 import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified } from '../lib/feed.js';
-import { ensureActivityLogHook, readRecentActivity, formatActivityLine, formatProgressUpdate } from '../lib/activity.js';
+import { ensureActivityLogHook, readRecentActivity, formatActivityLine, formatProgressUpdate, mergeActivityEvents, parseActivityPayload, } from '../lib/activity.js';
 import { postFeedStatus } from '../lib/feed-post.js';
+import { parseFeedPostLevel, planFeedBroadcast, runFeedBroadcast, } from '../lib/feed-broadcast.js';
+import { getSessionById } from '../lib/session/db.js';
+import { readMeta } from '../lib/state.js';
 import { enrichBlocksFromSessions, groupBlocksByOutcome, isUnambiguousOutcomeAnswer, openBlocksForOutcome, stampBlockOutcomes, } from '../lib/feed-outcome.js';
 import { classifyBlock, filterBlocksForFeed, suppressionDigest, } from '../lib/ask-classifier.js';
 import { machineId, normalizeHost } from '../lib/machine-id.js';
@@ -234,6 +237,7 @@ export function registerFeedCommand(program) {
         .argument('<text...>', 'What just happened — one short human line')
         .option('--session <id>', 'Session id escape hatch (default: auto from env / pid registry)')
         .option('--attach <path-or-url...>', 'Attach an artifact (local file or URL); repeatable')
+        .option('--level <level>', 'How loudly to broadcast: milestone (default) or important. Configured sinks with minLevel: important only fire on the latter.', 'milestone')
         .option('--json', 'Emit the written event as JSON')
         .addHelpText('after', `
 Examples:
@@ -242,11 +246,19 @@ Examples:
   agents feed post "cover render ready" --attach ./out/cover.png
   agents feed post "ready for review" --json
 
+  # Worth interrupting someone over — reaches sinks gated on minLevel: important:
+  agents feed post "release blocked: npm token expired" --level important
+
   # Outside a run, pass the session explicitly:
   agents feed post "manual note" --session 00998b0e-2d15-4d2f-a58b-974a886c9b47
 
 Identity (session, agent, host, runtime, pid, launchId) is stamped automatically.
-Domain facts (tickets, PRs) are not CLI flags — join them on the session at read time.
+Domain facts (tickets, PRs) are not CLI flags — the ticket is joined from the
+session index at post time, so a broadcast sink can comment on it without the
+agent having to remember it.
+
+Configure where a post is mirrored under feed.broadcast in agents.yaml — see
+docs/06-observability.md.
 `)
         .action((textParts, opts, cmd) => {
         // Parent `feed` also declares `--json` (for the list view). Commander
@@ -255,19 +267,23 @@ Domain facts (tickets, PRs) are not CLI flags — join them on the session at re
         const flags = {
             session: opts?.session ?? cmd?.opts?.()?.session,
             attach: opts?.attach ?? cmd?.opts?.()?.attach,
+            level: opts?.level ?? cmd?.opts?.()?.level,
             json: Boolean(opts?.json ?? cmd?.opts?.()?.json ?? cmd?.parent?.opts?.()?.json),
         };
         try {
+            const level = parseFeedPostLevel(flags.level);
             const { event } = postFeedStatus({
                 text: Array.isArray(textParts) ? textParts.join(' ') : String(textParts ?? ''),
                 sessionId: flags.session,
                 attach: flags.attach,
             });
+            const outcomes = broadcastPostedEvent(event, level);
             if (flags.json) {
-                console.log(JSON.stringify(event, null, 2));
+                console.log(JSON.stringify(outcomes.length ? { ...event, broadcast: outcomes } : event, null, 2));
                 return;
             }
             console.log(formatProgressUpdate(event));
+            reportBroadcast(outcomes);
         }
         catch (err) {
             console.error(chalk.red(err.message));
@@ -305,20 +321,39 @@ Domain facts (tickets, PRs) are not CLI flags — join them on the session at re
                 }
             }
         }
-        // Updates view: deliberate progress posts only, over the local activity
-        // timeline (blocks are decisions, not announcements). Short-circuit the
-        // whole block pipeline — no remote fan-out, no dispatch policy.
+        // Trailing lane under the block views: `--filter all` appends the same
+        // fleet-wide updates section, anything else the compact local lane.
+        const renderTrailingActivity = async () => {
+            if (filter === 'all') {
+                console.log();
+                renderUpdatesView(await gatherStatusPosts({
+                    limit: UPDATES_VIEW_LIMIT, hosts: opts.host, local: opts.local, includeLocal, self,
+                }));
+                return;
+            }
+            if (includeLocal)
+                renderActivityLane();
+        };
+        // Updates view: deliberate progress posts only (blocks are decisions, not
+        // announcements). Short-circuits the block pipeline — no dispatch policy —
+        // but fans out like the block view, because a post lands on whichever box
+        // ran the agent.
         if (filter === 'updates') {
             for (const warning of setupWarnings) {
                 console.error(chalk.yellow(`Feed hook setup warning: ${warning}`));
             }
+            const updates = await gatherStatusPosts({
+                limit: opts.json ? UPDATES_JSON_LIMIT : UPDATES_VIEW_LIMIT,
+                hosts: opts.host,
+                local: opts.local,
+                includeLocal,
+                self,
+            });
             if (opts.json) {
-                const updates = readRecentActivity({ sinceMs: Date.now() - 7 * 24 * 60 * 60 * 1000, limit: 100 })
-                    .filter((e) => e.event === 'status.posted');
                 console.log(JSON.stringify(updates, null, 2));
                 return;
             }
-            renderUpdatesView();
+            renderUpdatesView(updates);
             return;
         }
         // Active sessions feed both the GC sweep and outcome enrichment (ticket/PR).
@@ -428,14 +463,7 @@ Domain facts (tickets, PRs) are not CLI flags — join them on the session at re
         }
         if (blocks.length === 0) {
             console.log(chalk.gray(digest ? 'No open blocks after stall suppression.' : 'No open blocks.'));
-            if (includeLocal) {
-                if (filter === 'all') {
-                    console.log();
-                    renderUpdatesView();
-                }
-                else
-                    renderActivityLane();
-            }
+            await renderTrailingActivity();
             return;
         }
         // Shared fleet-comms masthead (same family as `agents mailboxes`).
@@ -458,16 +486,45 @@ Domain facts (tickets, PRs) are not CLI flags — join them on the session at re
         });
         for (const g of groups)
             renderOutcomeGroup(g, self);
-        if (includeLocal) {
-            if (filter === 'all') {
-                console.log();
-                renderUpdatesView();
-            }
-            else
-                renderActivityLane();
-        }
+        await renderTrailingActivity();
     });
 }
+/**
+ * Mirror a written post to the configured sinks (`feed.broadcast` in
+ * agents.yaml). The ticket is JOINED from the session index rather than asked
+ * for as a flag — it is a domain fact about the session, and an agent that has
+ * to remember a `--ticket` argument is an agent that will forget it. Returns the
+ * per-sink outcomes; an empty array means nothing is configured, which is the
+ * default and is not a failure.
+ */
+function broadcastPostedEvent(event, level) {
+    const config = readMeta().feed?.broadcast;
+    if (!config || Object.keys(config).length === 0)
+        return [];
+    const ticket = getSessionById(event.sessionId)?.ticketId;
+    const planned = planFeedBroadcast(config, {
+        text: event.detail ?? '',
+        level,
+        ticket,
+        project: event.project,
+        agent: event.agent,
+        host: event.host,
+        session: event.sessionId,
+        links: (event.attachments ?? [])
+            .map((a) => a.href)
+            .filter((href) => /^https?:\/\//i.test(href)),
+    });
+    return runFeedBroadcast(planned);
+}
+/** One line per sink that ran. Silent when nothing is configured. */
+function reportBroadcast(outcomes) {
+    for (const o of outcomes) {
+        if (o.ok)
+            console.log(chalk.gray(`  → ${o.name}`));
+        else
+            console.error(chalk.yellow(`  → ${o.name} failed: ${o.error}`));
+    }
+}
 /** Normalize a raw --filter value; unknown/empty falls back to the default. */
 export function resolveFeedFilter(raw) {
     const v = (raw ?? '').trim().toLowerCase();
@@ -490,15 +547,59 @@ function renderActivityEntry(ev) {
         console.log(formatActivityLine(ev, { showHost: true }));
     }
 }
+/** How far back the updates view looks for deliberate progress posts. */
+const UPDATES_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+/** Posts kept per machine in the rendered view / the `--json` payload. */
+const UPDATES_VIEW_LIMIT = 30;
+const UPDATES_JSON_LIMIT = 100;
+/**
+ * The most recent `limit` deliberate progress posts on THIS machine, newest
+ * first. The event filter is pushed into the reader so `limit` counts posts —
+ * slicing first and filtering after returned an empty view on a busy box, where
+ * routine `file.edited` hook events fill the whole slice.
+ */
+function readStatusPosts(limit) {
+    return readRecentActivity({
+        sinceMs: Date.now() - UPDATES_WINDOW_MS,
+        limit,
+        events: ['status.posted'],
+    });
+}
+/**
+ * Progress posts across the fleet, newest first. An agent posts on whichever
+ * box it runs on, so a local-only read shows the operator a fraction of what
+ * the fleet reported. Peers are dialed with the same SSH fan-out the block view
+ * uses; `--local` (or the no-fanout env guard on a peer) keeps it to this box.
+ */
+async function gatherStatusPosts(opts) {
+    const local = opts.includeLocal ? readStatusPosts(opts.limit) : [];
+    const forceLocal = opts.local === true || process.env[FEED_NO_FANOUT_ENV] === '1';
+    if (forceLocal)
+        return local;
+    const remoteHosts = opts.hosts?.length ? remoteFeedHostsToDial(opts.hosts, opts.self) : undefined;
+    if (opts.hosts?.length && (!remoteHosts || remoteHosts.length === 0))
+        return local;
+    const remote = await gatherRemoteAgentsJson({
+        args: ['feed', '--filter', 'updates', '--json'],
+        noFanoutEnv: FEED_NO_FANOUT_ENV,
+        hosts: remoteHosts,
+        parse: parseActivityPayload,
+    });
+    return mergeActivityEvents(local, remote.items).slice(0, opts.limit);
+}
 /**
  * Render the **Updates** view: deliberate progress posts only (`status.posted`),
  * recency-ordered, with rich identity chips. Pure `file.edited` / git-hook noise
  * is excluded so operators see announcements, not tool churn.
  */
-function renderUpdatesView(limit = 30) {
-    const updates = readRecentActivity({ sinceMs: Date.now() - 7 * 24 * 60 * 60 * 1000, limit })
-        .filter((e) => e.event === 'status.posted');
-    console.log(masthead({ title: 'updates', accent: 'cyan', host: machineId(), right: `${updates.length} post${updates.length === 1 ? '' : 's'}` }));
+function renderUpdatesView(updates) {
+    const hosts = new Set(updates.map((e) => e.host).filter(Boolean));
+    console.log(masthead({
+        title: 'updates',
+        accent: 'cyan',
+        host: hosts.size > 1 ? `${hosts.size} machines` : (updates[0]?.host ?? machineId()),
+        right: `${updates.length} post${updates.length === 1 ? '' : 's'}`,
+    }));
     console.log();
     if (updates.length === 0) {
         console.log(chalk.gray('  No progress updates yet. Agents post them with `agents feed post "…"`.'));
@@ -516,8 +617,11 @@ function renderUpdatesView(limit = 30) {
  * when empty.
  */
 function renderActivityLane(limit = 6) {
-    const events = readRecentActivity({ sinceMs: Date.now() - 24 * 60 * 60 * 1000, limit })
-        .filter((e) => e.tier === 'milestone');
+    const events = readRecentActivity({
+        sinceMs: Date.now() - 24 * 60 * 60 * 1000,
+        limit,
+        tier: 'milestone',
+    });
     if (events.length === 0)
         return;
     console.log(chalk.bold('\n  recent activity'));

package/dist/commands/sessions.js

@@ -247,7 +247,13 @@ export function buildSessionDescription(s) {
         return cleanPreview([todo, base].filter(Boolean).join(' · '));
     }
     if (s.context === 'teams') {
+        // A teams row identifies its TEAM, then the teammate within it, then who
+        // spun it up, then what it's working on — so several teams from one
+        // orchestrator stay distinct and each shows its target, not just its slug.
         const parts = [s.teamName];
+        // Teammate name (distinct from the team slug) — which member this row is.
+        if (s.label && s.label !== s.teamName)
+            parts.push(s.label);
         // Lineage: which orchestrator spun up this team. Prefer the resolved label,
         // else the short session id, so "by whom" is answerable at a glance.
         const orch = s.orchestratorLabel || (s.orchestratorSessionId ? s.orchestratorSessionId.slice(0, 8) : '');
@@ -255,12 +261,12 @@ export function buildSessionDescription(s) {
             parts.push(`by ${orch}`);
         if (todo)
             parts.push(todo);
-        if (s.preview)
-            parts.push(s.preview);
-        else if (s.label)
-            parts.push(s.label);
-        else if (s.topic)
-            parts.push(s.topic);
+        // Target: the live latest turn if working, else the assigned mission (the
+        // team's task/target, shown even before the teammate has a transcript), else
+        // the transcript topic.
+        const target = s.preview || s.assignedTask || s.topic;
+        if (target)
+            parts.push(target);
         return cleanPreview(parts.filter(Boolean).join(' · '));
     }
     // Terminal, headless, or sub-agent: todos + live preview, then label, then topic.

package/dist/lib/activity.d.ts

@@ -105,6 +105,14 @@ export interface RecentActivityOptions {
     root?: string;
     /** Per-session tail budget in bytes. */
     maxBytesPerSession?: number;
+    /**
+     * Only include these event names. Applied BEFORE `limit`, so asking for a
+     * rare event (a deliberate `status.posted`) returns that many of it instead
+     * of however many survive a slice dominated by routine `file.edited` churn.
+     */
+    events?: string[];
+    /** Only include events in these tiers. Applied BEFORE `limit`, as `events` is. */
+    tier?: ActivityTier;
 }
 /**
  * Merge recent events across every session's log, newest first. Reads only the

package/dist/lib/activity.js

@@ -194,9 +194,14 @@ export function listActivitySessions(root) {
 export function readRecentActivity(opts = {}) {
     const dir = opts.root ?? getActivityDir();
     const sinceMs = opts.sinceMs ?? 0;
+    const wanted = opts.events && opts.events.length > 0 ? new Set(opts.events) : null;
     const all = [];
     for (const sessionId of listActivitySessions(dir)) {
         for (const ev of readSessionActivity(sessionId, dir, opts.maxBytesPerSession)) {
+            if (wanted && !wanted.has(ev.event))
+                continue;
+            if (opts.tier && ev.tier !== opts.tier)
+                continue;
             const t = Date.parse(ev.ts);
             if (Number.isFinite(t) && t >= sinceMs)
                 all.push(ev);

package/dist/lib/feed-broadcast.d.ts

@@ -0,0 +1,66 @@
+/** How loudly a post asks to be heard. Ordered — `important` implies milestone. */
+export type FeedPostLevel = 'milestone' | 'important';
+/** Parse a `--level` value; anything unrecognized is a usage error, not a default. */
+export declare function parseFeedPostLevel(raw: string | undefined): FeedPostLevel;
+export interface FeedSinkConfig {
+    /**
+     * argv to run, with `{placeholder}` tokens substituted. First element is the
+     * program; it is spawned directly (no shell), so quoting is not a concern and
+     * post text can never become shell syntax.
+     */
+    command: string[];
+    /** Lowest post level that reaches this sink. Defaults to `milestone` (all posts). */
+    minLevel?: FeedPostLevel;
+}
+/** `feed.broadcast` in agents.yaml — sink name → what to run. */
+export type FeedBroadcastConfig = Record<string, FeedSinkConfig>;
+/** Everything a template may interpolate. Absent values skip templates that need them. */
+export interface FeedBroadcastContext {
+    /** The post text, verbatim. */
+    text: string;
+    level: FeedPostLevel;
+    /** Tracker id for the work, e.g. `RUSH-2081`. */
+    ticket?: string;
+    /** Repo/project the post came from. */
+    project?: string;
+    agent?: string;
+    host?: string;
+    session?: string;
+    /** URLs attached to the post — the PR, the ticket, a shared plan. */
+    links?: string[];
+}
+export interface PlannedSink {
+    name: string;
+    argv: string[];
+}
+export interface SinkOutcome {
+    name: string;
+    ok: boolean;
+    /** stderr tail when the sink failed, for the warning line. */
+    error?: string;
+}
+/**
+ * A human-facing one-liner for a messaging sink: what project, what happened,
+ * and the link to go read more. Leading with the project is deliberate — a
+ * message that opens with an agent name tells the reader nothing about which of
+ * their projects just moved.
+ */
+export declare function composeBroadcastMessage(ctx: FeedBroadcastContext): string;
+/**
+ * Substitute `{placeholder}` tokens in an argv template. Returns undefined when
+ * the template needs a value this post does not have — the sink is then skipped
+ * rather than run with an empty argument, which is how a `linear update --comment`
+ * would otherwise comment on nothing.
+ */
+export declare function renderSinkArgv(template: string[], ctx: FeedBroadcastContext): string[] | undefined;
+/**
+ * Which sinks this post reaches, in config order. Pure — the dry-run listing and
+ * the real fan-out plan through here, so what `--dry-run` shows is what runs.
+ */
+export declare function planFeedBroadcast(config: FeedBroadcastConfig | undefined, ctx: FeedBroadcastContext): PlannedSink[];
+/**
+ * Run the planned sinks. Each is a direct spawn with a bounded lifetime; a sink
+ * that fails or is not installed is reported, never thrown — the post is already
+ * written and must not be undone by a mirror that could not be reached.
+ */
+export declare function runFeedBroadcast(planned: PlannedSink[], timeoutMs?: number): SinkOutcome[];

package/dist/lib/feed-broadcast.js

@@ -0,0 +1,131 @@
+/**
+ * Fan an `agents feed post` out to the systems the operator actually watches.
+ *
+ * A post is already durable — it lands in the append-only activity log and shows
+ * up in `agents feed --filter updates`. But an operator who is away from every
+ * terminal never sees it, and the tracker that owns the work (a Linear ticket,
+ * a GitHub issue) hears nothing at all. So a post can also be mirrored outward.
+ *
+ * Sinks are **argv templates from config**, never hardcoded integrations. This
+ * CLI ships Apache-2.0 and must not depend on one person's tracker or messaging
+ * stack; declaring `[linear, update, "{ticket}", --comment, "{text}"]` in
+ * `agents.yaml` keeps the coupling in the operator's config where it belongs,
+ * and lets someone else point the same mechanism at `jira`, `gh issue comment`,
+ * or a webhook script.
+ *
+ * Two rules decide whether a sink runs, both derived from the post itself:
+ *
+ *   - **Level.** `minLevel: important` keeps a sink for the posts worth
+ *     interrupting someone over, so a routine "CI green" does not buzz a phone.
+ *   - **Placeholders.** A template that references `{ticket}` is skipped when no
+ *     ticket is known. The template declares what it needs; nothing has to
+ *     restate it as a flag, and a sink can never fire with a hole in its argv.
+ *
+ * Delivery is best-effort and reported: a sink that fails prints a warning and
+ * the post still stands. Losing a mirror must never cost the operator the post.
+ */
+import { spawnSync } from 'child_process';
+const LEVEL_RANK = { milestone: 0, important: 1 };
+/** Parse a `--level` value; anything unrecognized is a usage error, not a default. */
+export function parseFeedPostLevel(raw) {
+    const v = (raw ?? '').trim().toLowerCase();
+    if (!v || v === 'milestone')
+        return 'milestone';
+    if (v === 'important')
+        return 'important';
+    throw new Error(`Unknown --level '${raw}'. Use milestone or important.`);
+}
+const PLACEHOLDER = /\{([a-z]+)\}/g;
+/**
+ * A human-facing one-liner for a messaging sink: what project, what happened,
+ * and the link to go read more. Leading with the project is deliberate — a
+ * message that opens with an agent name tells the reader nothing about which of
+ * their projects just moved.
+ */
+export function composeBroadcastMessage(ctx) {
+    const head = ctx.project ? `${ctx.project} · ${ctx.text}` : ctx.text;
+    const link = ctx.links?.find((l) => /^https?:\/\//i.test(l));
+    return link ? `${head}\n${link}` : head;
+}
+/** The values a template may reference, resolved once per post. */
+function templateVars(ctx) {
+    return {
+        text: ctx.text,
+        ticket: ctx.ticket,
+        project: ctx.project,
+        agent: ctx.agent,
+        host: ctx.host,
+        session: ctx.session,
+        level: ctx.level,
+        links: ctx.links?.length ? ctx.links.join(' ') : undefined,
+        message: composeBroadcastMessage(ctx),
+    };
+}
+/**
+ * Substitute `{placeholder}` tokens in an argv template. Returns undefined when
+ * the template needs a value this post does not have — the sink is then skipped
+ * rather than run with an empty argument, which is how a `linear update --comment`
+ * would otherwise comment on nothing.
+ */
+export function renderSinkArgv(template, ctx) {
+    const vars = templateVars(ctx);
+    const argv = [];
+    for (const token of template) {
+        let missing = false;
+        const rendered = token.replace(PLACEHOLDER, (whole, key) => {
+            const value = vars[key];
+            if (value === undefined || value === '') {
+                missing = true;
+                return whole;
+            }
+            return value;
+        });
+        if (missing)
+            return undefined;
+        argv.push(rendered);
+    }
+    return argv.length > 0 ? argv : undefined;
+}
+/**
+ * Which sinks this post reaches, in config order. Pure — the dry-run listing and
+ * the real fan-out plan through here, so what `--dry-run` shows is what runs.
+ */
+export function planFeedBroadcast(config, ctx) {
+    if (!config)
+        return [];
+    const planned = [];
+    for (const [name, sink] of Object.entries(config)) {
+        if (!Array.isArray(sink?.command) || sink.command.length === 0)
+            continue;
+        const min = sink.minLevel ?? 'milestone';
+        if (LEVEL_RANK[ctx.level] < LEVEL_RANK[min])
+            continue;
+        const argv = renderSinkArgv(sink.command, ctx);
+        if (!argv)
+            continue;
+        planned.push({ name, argv });
+    }
+    return planned;
+}
+/**
+ * Run the planned sinks. Each is a direct spawn with a bounded lifetime; a sink
+ * that fails or is not installed is reported, never thrown — the post is already
+ * written and must not be undone by a mirror that could not be reached.
+ */
+export function runFeedBroadcast(planned, timeoutMs = 20_000) {
+    return planned.map(({ name, argv }) => {
+        const result = spawnSync(argv[0], argv.slice(1), {
+            encoding: 'utf-8',
+            timeout: timeoutMs,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (result.error) {
+            return { name, ok: false, error: result.error.message };
+        }
+        if (result.status !== 0) {
+            const tail = (result.stderr || result.stdout || '').trim().split('\n').slice(-1)[0];
+            return { name, ok: false, error: tail || `exited ${result.status}` };
+        }
+        return { name, ok: true };
+    });
+}

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

@@ -116,6 +116,11 @@ export const RUN_OPTION_FORWARDING = {
     tailscale: 'local-only', // --tailscale/--no-tailscale gate the lease net mode; never forwarded
     copyCreds: 'local-only', // copies creds TO the host before dispatch — local concern only
     authCheck: 'local-only', // --no-auth-check gates the local interactive login preflight; --host runs skip that preflight entirely
+    // The notification must land on the box the PERSON is at — the one that
+    // dispatched — not on a headless worker with no desktop to post to. The local
+    // process follows the remote run to completion, so its exit handler fires at
+    // the right moment anyway.
+    notify: 'local-only',
     // Deprecated alias for --device auto; resolved on the launching box before SSH.
     smart: 'local-only',
 };

package/dist/lib/permissions.d.ts

@@ -233,6 +233,27 @@ export declare function convertToKimiFormat(set: PermissionSet): {
  * OpenCode uses: { permission: { bash: { "git *": "allow", "rm *": "deny" } } }
  */
 export declare function convertToOpenCodeFormat(set: PermissionSet): OpenCodePermissions;
+/**
+ * Default extra writable roots for Codex's `workspace-write` sandbox: the
+ * regenerable package/toolchain caches that build/test/install write OUTSIDE the
+ * workspace (cargo registry, npm/bun/pnpm caches, GOPATH/GOCACHE, the OS cache
+ * root, …). Without these, a sandboxed `cargo build` / `go build` / `npm install`
+ * fails on its cache write, which is what pushes users to `--mode full` (YOLO).
+ *
+ * Credential dirs (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.config`, `~/.netrc`) are
+ * deliberately EXCLUDED so the sandbox stays meaningful — this is far from
+ * danger-full-access. Resolved per platform + home; each box regenerates its own
+ * Codex config on sync, so the paths always match the box Codex runs on.
+ */
+export declare function codexDefaultWritableRoots(home?: string, platform?: NodeJS.Platform): string[];
+/**
+ * Merge Codex `[sandbox_workspace_write]` config, UNIONing `writable_roots` so a
+ * baseline cache root never clobbers a root the user configured directly (a
+ * plain object spread would overwrite the whole array), while merging scalar
+ * keys (`network_access`) normally. Shared by the user- and version-scoped Codex
+ * config writers so the two can't drift.
+ */
+export declare function mergeCodexSandboxWrite(existing: Record<string, unknown> | undefined, incoming: NonNullable<CodexPermissions['sandbox_workspace_write']>): Record<string, unknown>;
 /**
  * Convert canonical permission set to Codex format.
  * Codex uses coarse-grained modes, so we infer the best fit.

package/dist/lib/permissions.js

@@ -1007,6 +1007,48 @@ export function convertToOpenCodeFormat(set) {
         },
     };
 }
+/**
+ * Default extra writable roots for Codex's `workspace-write` sandbox: the
+ * regenerable package/toolchain caches that build/test/install write OUTSIDE the
+ * workspace (cargo registry, npm/bun/pnpm caches, GOPATH/GOCACHE, the OS cache
+ * root, …). Without these, a sandboxed `cargo build` / `go build` / `npm install`
+ * fails on its cache write, which is what pushes users to `--mode full` (YOLO).
+ *
+ * Credential dirs (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.config`, `~/.netrc`) are
+ * deliberately EXCLUDED so the sandbox stays meaningful — this is far from
+ * danger-full-access. Resolved per platform + home; each box regenerates its own
+ * Codex config on sync, so the paths always match the box Codex runs on.
+ */
+export function codexDefaultWritableRoots(home = HOME, platform = process.platform) {
+    const shared = ['.cargo', '.rustup', '.npm', '.bun', 'go', '.deno', '.gradle', '.m2', '.gem'];
+    const roots = shared.map((d) => path.join(home, d));
+    if (platform === 'darwin') {
+        roots.push(path.join(home, 'Library', 'Caches'), path.join(home, 'Library', 'pnpm'));
+    }
+    else {
+        // Linux/XDG: ~/.cache covers pip, uv, go-build, ms-playwright, etc.
+        roots.push(path.join(home, '.cache'), path.join(home, '.local', 'share'), path.join(home, '.local', 'state'));
+    }
+    return roots;
+}
+/**
+ * Merge Codex `[sandbox_workspace_write]` config, UNIONing `writable_roots` so a
+ * baseline cache root never clobbers a root the user configured directly (a
+ * plain object spread would overwrite the whole array), while merging scalar
+ * keys (`network_access`) normally. Shared by the user- and version-scoped Codex
+ * config writers so the two can't drift.
+ */
+export function mergeCodexSandboxWrite(existing, incoming) {
+    const existingRoots = Array.isArray(existing?.writable_roots)
+        ? existing.writable_roots
+        : [];
+    const unionRoots = [...new Set([...existingRoots, ...(incoming.writable_roots ?? [])])];
+    return {
+        ...existing,
+        ...incoming,
+        ...(unionRoots.length > 0 ? { writable_roots: unionRoots } : {}),
+    };
+}
 /**
  * Convert canonical permission set to Codex format.
  * Codex uses coarse-grained modes, so we infer the best fit.
@@ -1042,6 +1084,15 @@ export function convertToCodexFormat(set, cwd) {
             network_access: true,
         };
     }
+    // Baseline (unconditional): always grant the regenerable build/test/install
+    // caches as writable roots so `agents run codex` in workspace-write can build,
+    // test, and install without escalating to danger-full-access. Merged with
+    // network_access above when set; applyCodexPermissions unions these with any
+    // writable_roots the user configured directly.
+    result.sandbox_workspace_write = {
+        ...result.sandbox_workspace_write,
+        writable_roots: codexDefaultWritableRoots(),
+    };
     return result;
 }
 // ============================================================================
@@ -1333,8 +1384,10 @@ function applyCodexPermissions(set, scope = 'user', cwd, merge = true) {
         }
         if (newPermissions.sandbox_workspace_write) {
             const existing = config.sandbox_workspace_write;
+            // merge=false is a deliberate full replace (drops any user-custom roots);
+            // production sync always passes merge=true, taking the union path.
             config.sandbox_workspace_write = merge
-                ? { ...existing, ...newPermissions.sandbox_workspace_write }
+                ? mergeCodexSandboxWrite(existing, newPermissions.sandbox_workspace_write)
                 : newPermissions.sandbox_workspace_write;
         }
         fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');
@@ -1450,8 +1503,10 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             }
             if (newPermissions.sandbox_workspace_write) {
                 const existing = config.sandbox_workspace_write;
+                // merge=false is a deliberate full replace (drops any user-custom roots);
+                // production sync always passes merge=true, taking the union path.
                 config.sandbox_workspace_write = merge
-                    ? { ...existing, ...newPermissions.sandbox_workspace_write }
+                    ? mergeCodexSandboxWrite(existing, newPermissions.sandbox_workspace_write)
                     : newPermissions.sandbox_workspace_write;
             }
             fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');

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

@@ -0,0 +1,27 @@
+import { type DesktopNotification } from './menubar/notify-desktop.js';
+export interface RunNotifyContext {
+    /** Agent that ran, e.g. `claude`. */
+    agent: string;
+    /** `--name` slug when the caller named the run; falls back to the agent. */
+    name?: string;
+    /** The prompt, used for a one-line reminder of what the run was about. */
+    prompt?: string;
+    /** Working directory the run was scoped to; its basename names the project. */
+    cwd?: string;
+    /** Machine the run executed on, when it was dispatched off-box. */
+    host?: string;
+    /** Clickable target — a PR/ticket URL the caller already knows. */
+    url?: string;
+}
+/**
+ * The finish notification for one run. Pure — the exit handler and the tests
+ * both build through here, so what ships is what is asserted.
+ */
+export declare function buildRunFinishNotification(ctx: RunNotifyContext, exitCode: number): DesktopNotification;
+/**
+ * Post the finish notification when this process exits. Best-effort by
+ * construction: `notifyDesktop` swallows its own failures, and a run killed
+ * outright (SIGKILL) never reaches an exit handler — that is the documented
+ * limit, not a case to paper over.
+ */
+export declare function armRunFinishNotification(ctx: RunNotifyContext): void;

package/dist/lib/run-notify.js

@@ -0,0 +1,54 @@
+/**
+ * Desktop notification when a headless `agents run` finishes (`--notify`).
+ *
+ * The notifying process is the one that OWNS the run. That is the whole point:
+ * the menu bar's quick dispatch used to post its completion notice from the
+ * dispatching MenubarHelper's process-termination callback, so a helper that
+ * restarted (an upgrade, a crash) took the callback with it — the run kept
+ * going, reparented to launchd, and no notification could ever fire. Posting
+ * from the run process instead means the notice survives anything that happens
+ * to the menu bar, and `notifyDesktop` spawns a FRESH one-shot notifier, so it
+ * does not need a helper to have been running at dispatch time either.
+ *
+ * Armed once via `process.on('exit')` so it covers every way the run command
+ * terminates — local spawn, `--host` dispatch, `--lease` box, the error path —
+ * rather than being sprinkled over ~50 `process.exit` call sites where the next
+ * new exit path would silently miss it.
+ */
+import * as path from 'path';
+import { notifyDesktop } from './menubar/notify-desktop.js';
+/** Notification body cap: a banner truncates anyway, and a wall of text is noise. */
+const BODY_MAX = 120;
+function shorten(text, max = BODY_MAX) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/**
+ * The finish notification for one run. Pure — the exit handler and the tests
+ * both build through here, so what ships is what is asserted.
+ */
+export function buildRunFinishNotification(ctx, exitCode) {
+    const label = ctx.name?.trim() || ctx.agent;
+    const project = ctx.cwd ? path.basename(ctx.cwd) : undefined;
+    const where = [project, ctx.host].filter(Boolean).join(' · ');
+    const n = {
+        title: exitCode === 0 ? `${label} finished` : `${label} failed`,
+        body: shorten(ctx.prompt?.trim() || `${ctx.agent} run`),
+    };
+    if (where)
+        n.subtitle = where;
+    if (ctx.url)
+        n.action = `url:${ctx.url}`;
+    return n;
+}
+/**
+ * Post the finish notification when this process exits. Best-effort by
+ * construction: `notifyDesktop` swallows its own failures, and a run killed
+ * outright (SIGKILL) never reaches an exit handler — that is the documented
+ * limit, not a case to paper over.
+ */
+export function armRunFinishNotification(ctx) {
+    process.on('exit', (code) => {
+        notifyDesktop(buildRunFinishNotification(ctx, code));
+    });
+}

package/dist/lib/session/active.d.ts

@@ -158,6 +158,15 @@ export interface ActiveSession {
     /** Display label for the orchestrator (its topic/label), resolved when the
      * orchestrator is itself present in the active set. Display-only. */
     orchestratorLabel?: string;
+    /**
+     * For a teams teammate: a one-line summary of the mission it was spawned with
+     * (the `prompt` stored on the teammate record — the team's task/target), so the
+     * listing answers "what is this team working on", not just its name. Survives
+     * before the teammate has produced any transcript (a pending/staged teammate
+     * still shows its target). Distinct from `topic`, which is derived from the
+     * teammate's own transcript once it starts.
+     */
+    assignedTask?: string;
     agentId?: string;
     cloudProvider?: string;
     cloudTaskId?: string;
@@ -338,6 +347,12 @@ interface LiveSignals {
  * {@link resolveFallbackStatus} reports the honest live floor (`running`).
  */
 export declare function computeLiveSignals(kind: string, sessionFile: string | undefined, cwd: string | undefined, pidAlive: boolean): LiveSignals;
+/**
+ * One-line summary of a teammate's spawn prompt — the team's task/target. Takes
+ * the first non-empty line, strips a leading `MISSION:`/`CONTEXT:`/`TASK:` label,
+ * and truncates. Exported for tests.
+ */
+export declare function summarizeMission(prompt: string | null | undefined): string | undefined;
 /** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
 export declare function listTeamsActive(): Promise<ActiveSession[]>;
 /** Live editor-terminal agents across every IDE window. */

package/dist/lib/session/active.js

@@ -576,6 +576,22 @@ function quickExtractTopic(sessionFile) {
     }
     return undefined;
 }
+/**
+ * One-line summary of a teammate's spawn prompt — the team's task/target. Takes
+ * the first non-empty line, strips a leading `MISSION:`/`CONTEXT:`/`TASK:` label,
+ * and truncates. Exported for tests.
+ */
+export function summarizeMission(prompt) {
+    if (!prompt)
+        return undefined;
+    const firstLine = prompt.split('\n').map((l) => l.trim()).find(Boolean);
+    if (!firstLine)
+        return undefined;
+    const cleaned = firstLine.replace(/^(MISSION|CONTEXT|TASK|GOAL|OBJECTIVE)\s*[:\-—]\s*/i, '').trim();
+    if (!cleaned)
+        return undefined;
+    return cleaned.length > 80 ? `${cleaned.slice(0, 79)}…` : cleaned;
+}
 /** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
 export async function listTeamsActive() {
     const mgr = new AgentManager();
@@ -607,6 +623,7 @@ export async function listTeamsActive() {
             startedAtMs: a.startedAt.getTime(),
             lastActivityMs: sessionFileTimes(sessionFile).mtimeMs,
             teamName: a.taskName,
+            assignedTask: summarizeMission(a.prompt),
             agentId: a.agentId,
             // The frozen actor stamped on the teammate record (RUSH-2028) — who ran
             // this teammate, surfaced as the owner in --active (RUSH-2018); sidecar

package/dist/lib/types.d.ts

@@ -6,6 +6,7 @@
  * formats for each supported agent.
  */
 import type { CloudProviderId } from './cloud/types.js';
+import type { FeedBroadcastConfig } from './feed-broadcast.js';
 /** Unique identifier for a current or legacy AI coding agent. */
 export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
@@ -762,6 +763,15 @@ export interface Meta {
     };
     /** Spend guardrails (issue #346). User-global caps; project agents.yaml overrides. */
     budget?: BudgetConfig;
+    /**
+     * `agents feed post` fan-out. `broadcast` maps a sink name to the argv template
+     * run for each post, so mirroring to a tracker or a messaging CLI is the
+     * operator's config rather than an integration compiled into this CLI. See
+     * lib/feed-broadcast.ts and docs/06-observability.md.
+     */
+    feed?: {
+        broadcast?: FeedBroadcastConfig;
+    };
     beta?: {
         enabled?: BetaFeatureName[];
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.83",
+  "version": "1.20.85",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
@@ -55,6 +55,7 @@
     "start": "node dist/index.js",
     "test": "node ./node_modules/vitest/vitest.mjs run",
     "test:remote": "scripts/sandbox.sh 'bun install && bun run build && bun run test'",
+    "verify-docs": "scripts/verify-docs.sh",
     "test:watch": "node ./node_modules/vitest/vitest.mjs"
   },
   "keywords": [