@phnx-labs/agents-cli 1.20.91 → 1.20.93

package/dist/commands/activity.js

@@ -1,13 +1,37 @@
 import chalk from 'chalk';
-import { collapseActivity, enrichActivityEvents, ensureActivityLogHook, filterActivityEvents, formatActivityGroupHeader, formatEnrichedActivityLine, formatProgressUpdate, groupActivity, mergeActivityEvents, parseActivityPayload, projectFromCwd, readRecentActivity, styleForEvent, tierForEvent, } from '../lib/activity.js';
+import { ACTIVITY_HOOK_DEFINITIONS, collapseActivity, enrichActivityEvents, capActivityEvents, ensureActivityLogHook, filterActivityByProject, filterActivityEvents, formatActivityGroupMeta, formatEnrichedActivityLine, formatProgressUpdate, groupActivity, mergeActivityEvents, parseActivityPayload, readRecentActivity, styleForEvent, tierForEvent, } from '../lib/activity.js';
 import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
+import { resolveProjectKey } from '../lib/project-key.js';
+import { listProjectDefs, projectNameForCwd, resolveProjectNameForCwd } from '../lib/projects.js';
 import { machineId, normalizeHost } from '../lib/machine-id.js';
 import { shouldIncludeLocalFeed, remoteFeedHostsToDial } from './feed.js';
 import { getActiveSessions } from '../lib/session/active.js';
 /** Recursion guard: a peer answering a fan-out never re-fans-out itself. */
 export const ACTIVITY_NO_FANOUT_ENV = 'AGENTS_ACTIVITY_LOCAL';
+/** `--group-by` values; `none` is the opt-out that `--flat` also selects. */
 const GROUP_BY_VALUES = ['project', 'device', 'agent'];
-/** Wire the activity-log hooks into each hooks-capable version's settings. */
+const GROUP_BY_NONE = 'none';
+/** Grouping when neither `--group-by` nor `--flat` is given. */
+const DEFAULT_GROUP_BY = 'project';
+/**
+ * How much further back than `--limit` the LOCAL log read goes, so routine
+ * churn on this box can't crowd the fleet's milestones out of the window
+ * ({@link capActivityEvents} does the real capping).
+ */
+const LOCAL_READ_HEADROOM = 5;
+/**
+ * Wire the activity-log hooks into each hooks-capable version's settings.
+ *
+ * Only a failure that leaves THIS command's log unwritten is worth a warning.
+ * `registerHooksToSettings` reports every unresolved hook in the manifest — a
+ * missing `inject-session-id` script, someone else's half-installed plugin —
+ * and echoing all of them printed five wrapped lines of unrelated noise above
+ * the timeline on every run. Those belong to `agents doctor`, which exists to
+ * find them; here they are dropped. What still surfaces: an activity-hook
+ * failure, and any error attributable to NO manifest hook — a corrupt
+ * settings.json or an unwritable hooks file aborts registration for the whole
+ * agent, which is exactly a failure that leaves the activity log unwritten.
+ */
 async function installActivityHooks() {
     const warnings = [];
     const hookInstall = ensureActivityLogHook();
@@ -20,22 +44,45 @@ async function installActivityHooks() {
         import('../lib/versions.js'),
     ]);
     const manifest = parseHookManifest({ warn: false });
+    const manifestNames = Object.keys(manifest);
     for (const { agent, version } of iterHooksCapableVersions({ agent: 'claude' })) {
         const result = registerHooksToSettings(agent, getVersionHomePath(agent, version), manifest);
-        if (result.errors.length > 0)
-            warnings.push(`${agent}@${version}: ${result.errors.join('; ')}`);
+        const ours = result.errors.filter((e) => isActivityHookError(e) || !isManifestHookError(e, manifestNames));
+        if (ours.length > 0)
+            warnings.push(`${agent}@${version}: ${ours.join('; ')}`);
     }
     return warnings;
 }
-/** Session facts (project / ticket / execution host) keyed for the read-time join. */
-function activityHintsFromSessions(sessions) {
+/**
+ * Does this hook-registration error concern one of the activity-log hooks?
+ * `registerHooksToSettings` prefixes each error with the manifest hook name
+ * (`<name>: script not found`), so the entry names are the discriminator.
+ */
+export function isActivityHookError(error) {
+    return Object.keys(ACTIVITY_HOOK_DEFINITIONS).some((name) => error.startsWith(`${name}:`));
+}
+/**
+ * Is this error attributable to a named manifest hook at all? Errors that name
+ * no hook — `Failed to parse settings.json`, `Failed to write
+ * agents-cli-hooks.ts: …` — are agent-level aborts, not per-hook noise, and
+ * must never be filtered out.
+ */
+export function isManifestHookError(error, manifestNames) {
+    return manifestNames.some((name) => error.startsWith(`${name}:`));
+}
+/**
+ * Session facts (project / ticket / execution host) keyed for the read-time
+ * join. These sessions are this machine's, so their cwds get the canonical
+ * defined-project-first resolution rather than the bare cwd fold.
+ */
+function activityHintsFromSessions(sessions, resolveProject = resolveProjectKey) {
     return sessions.map((s) => ({
         sessionId: s.sessionId,
         ticket: s.ticket?.id,
         // Where the process actually lives — the SSH-resolved provenance host, else
         // the cross-machine `machine` id. Normalized to match the event `host` form.
         executionHost: s.provenance?.host ? normalizeHost(s.provenance.host) : s.machine,
-        project: projectFromCwd(s.cwd),
+        project: resolveProject(s.cwd),
     }));
 }
 /**
@@ -70,6 +117,23 @@ function renderFlat(events, opts) {
     }
     process.stdout.write('\n');
 }
+/** Max peers named in the unreachable note before the rest collapse to `+N`. */
+const UNREACHABLE_NAME_LIMIT = 4;
+/**
+ * One compact trailing note for peers that didn't answer the fan-out. Now that
+ * every run dials the fleet, an offline box is routine -- but never silent: the
+ * reader has to know the timeline is missing a machine, not that the machine
+ * was idle. Empty string when everything answered.
+ */
+export function formatUnreachableNote(skipped) {
+    if (skipped.length === 0)
+        return '';
+    const named = skipped.slice(0, UNREACHABLE_NAME_LIMIT);
+    const rest = skipped.length - named.length;
+    const list = rest > 0 ? `${named.join(', ')} +${rest}` : named.join(', ');
+    const noun = skipped.length === 1 ? 'device' : 'devices';
+    return chalk.gray(`  · ${skipped.length} ${noun} unreachable: ${list}\n\n`);
+}
 /** Print the bucketed view (`--group-by project|device|agent`). */
 function renderGrouped(events, by, opts) {
     const groups = groupActivity(events, by);
@@ -78,7 +142,11 @@ function renderGrouped(events, by, opts) {
     const showProject = by !== 'project';
     process.stdout.write(chalk.bold(`\n  activity by ${by}\n`));
     for (const group of groups) {
-        process.stdout.write(`\n  ${chalk.bold(formatActivityGroupHeader(group))}\n`);
+        // `▸ <label>  <meta>` -- label leads in cyan so projects scan down the
+        // left edge (mirrors the `agents sessions` overview), the counts and the
+        // machines that touched this project trail behind it in gray.
+        const meta = formatActivityGroupMeta(group, { showDevices: by !== 'device' });
+        process.stdout.write(`\n  ${chalk.cyan('▸')} ${chalk.cyan.bold(group.label)}  ${chalk.gray(meta)}\n`);
         const { milestones, counts, subagentCount } = collapseActivity(group.events);
         const shown = opts.all ? group.events : milestones;
         for (const ev of shown) {
@@ -97,89 +165,168 @@ function renderGrouped(events, by, opts) {
     }
     process.stdout.write('\n');
 }
+/**
+ * Resolve `--group-by` / `--flat` into the grouping dimension, or `undefined`
+ * for a flat stream. Throws on an unknown value so the caller can exit 1 --
+ * a mistyped dimension must not silently fall back to the default.
+ */
+export function resolveActivityGrouping(opts) {
+    if (opts.flat)
+        return undefined;
+    if (opts.groupBy === undefined)
+        return DEFAULT_GROUP_BY;
+    if (opts.groupBy === GROUP_BY_NONE)
+        return undefined;
+    if (!GROUP_BY_VALUES.includes(opts.groupBy)) {
+        throw new Error(`--group-by must be one of: ${[...GROUP_BY_VALUES, GROUP_BY_NONE].join(', ')}`);
+    }
+    return opts.groupBy;
+}
+/**
+ * Decide the read scope. Fleet-wide is the DEFAULT -- agents run on every box,
+ * so "what are my agents doing" is a fleet question -- and three things narrow
+ * it: `--local`, an explicit `--host`/`--device` list, and the recursion guard
+ * a peer answering a fan-out carries (else every peer would re-fan the fleet).
+ * `--devices-all`/`--hosts-all` are kept as explicit no-ops for scripts that
+ * already pass them.
+ */
+export function resolveActivityScope(opts, self, noFanoutEnv = process.env[ACTIVITY_NO_FANOUT_ENV] === '1') {
+    if (opts.local === true || noFanoutEnv)
+        return { includeLocal: true, wantRemote: false };
+    const explicitHosts = opts.host;
+    if (explicitHosts && explicitHosts.length > 0) {
+        const remoteHosts = remoteFeedHostsToDial(explicitHosts, self) ?? [];
+        return {
+            includeLocal: shouldIncludeLocalFeed(explicitHosts, self),
+            wantRemote: remoteHosts.length > 0,
+            remoteHosts,
+        };
+    }
+    return { includeLocal: true, wantRemote: true };
+}
 export function registerActivityCommand(program) {
     program
         .command('activity')
-        .description('Recent agent activity -- plans, PRs, worktrees, sub-agents (newest first)')
+        .description('Recent agent activity across the fleet -- plans, PRs, worktrees, sub-agents, by project')
         .option('--json', 'Emit the (enriched) event list as JSON')
         .option('--all', 'Include routine activity (file edits) inline, not collapsed')
         .option('--milestones', 'Only milestone events (plans, PRs, worktrees, sub-agents)')
-        .option('-n, --limit <n>', 'Cap the number of events shown', (v) => parseInt(v, 10), 40)
+        .option('-n, --limit <n>', 'Cap the milestones shown (routine work rides along as counts); with --all, caps every event', (v) => parseInt(v, 10), 40)
         .option('--since <minutes>', 'Only events within the last N minutes', (v) => parseInt(v, 10))
         .option('--local', 'Only this machine -- skip the cross-machine SSH fan-out')
         .option('-H, --host <target...>', 'Scope to remote machine(s) over SSH; repeatable')
         .option('--device <target...>', 'Alias for --host; repeatable')
-        .option('--devices-all', 'Fan out to every reachable device on the fleet')
+        .option('--devices-all', 'Fan out to every reachable device (the default; kept for scripts)')
         .option('--hosts-all', 'Alias for --devices-all')
-        .option('--group-by <field>', 'Bucket the stream by project | device | agent')
+        .option('--group-by <field>', 'Bucket the stream by project | device | agent | none (default: project)')
+        .option('--flat', 'One newest-first stream instead of project buckets')
+        .option('--project <name>', 'Only items under one project; exact match on the resolved (defined-project-first) label')
         .option('--filter <text>', 'Narrow to items matching a project / device / agent / event / ticket')
         .addHelpText('after', `
 Examples:
-  agents activity                              # this machine, newest first
-  agents activity --devices-all --group-by project   # per project across the fleet
+  agents activity                              # the whole fleet, by project
+  agents activity --local                      # just this machine
+  agents activity --flat                       # one newest-first stream
   agents activity --host yosemite-s1           # one box over SSH
-  agents activity --devices-all --filter RUSH-2100   # one ticket, fleet-wide
-  agents activity --milestones                 # only plans / PRs / worktrees / sub-agents
+  agents activity --project rush               # one defined project, fleet-wide
+  agents activity --filter RUSH-2100           # one ticket, fleet-wide
+  agents activity --group-by device            # by machine instead of project
 
-Each item is enriched by JOINING to live sessions (project, execution host,
-Linear ticket) -- never by re-parsing transcripts. --devices-all runs the same
-'activity --json' on each peer and merges the streams host-tagged.
+Fleet-wide and project-grouped by default: the same 'activity --json' runs on
+every reachable peer and the streams merge host-tagged. Each item is enriched by
+JOINING to live sessions (project, execution host, Linear ticket) -- never by
+re-parsing transcripts. Project labels are canonical: a cwd inside a defined
+project (~/.agents/projects/<name>.yaml) reads as that project's name, so a
+multi-repo project is one bucket; anything else folds to its repository. Each
+project header names the machines its work ran on.
 `)
         .action(async (opts) => {
         if (opts.device?.length)
             opts.host = [...(opts.host ?? []), ...opts.device];
-        const groupBy = opts.groupBy;
-        if (groupBy && !GROUP_BY_VALUES.includes(groupBy)) {
-            process.stderr.write(chalk.red(`--group-by must be one of: ${GROUP_BY_VALUES.join(', ')}\n`));
+        let groupBy;
+        try {
+            groupBy = resolveActivityGrouping(opts);
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`${err.message}\n`));
             process.exitCode = 1;
             return;
         }
-        const self = machineId();
-        const forceLocal = opts.local === true || process.env[ACTIVITY_NO_FANOUT_ENV] === '1';
-        const explicitHosts = opts.host;
-        const wantAll = Boolean(opts.devicesAll || opts.hostsAll);
-        const wantRemote = !forceLocal && (wantAll || (explicitHosts != null && explicitHosts.length > 0));
-        // Local events are included unless an explicit --host list excludes this box.
-        let includeLocal = true;
-        if (wantRemote && explicitHosts && explicitHosts.length > 0) {
-            includeLocal = shouldIncludeLocalFeed(explicitHosts, self);
+        // `parseInt` yields NaN for a non-numeric -n, and every downstream slice
+        // against NaN is empty — an unreadable flag would otherwise render as
+        // "No recent agent activity", which is a lie about the fleet.
+        if (!Number.isFinite(opts.limit) || opts.limit <= 0) {
+            process.stderr.write(chalk.red('--limit must be a positive number\n'));
+            process.exitCode = 1;
+            return;
         }
+        const self = machineId();
+        const { includeLocal, wantRemote, remoteHosts } = resolveActivityScope(opts, self);
         const warnings = includeLocal ? await installActivityHooks() : [];
         const sinceMs = typeof opts.since === 'number' && opts.since > 0
             ? Date.now() - opts.since * 60_000
             : undefined;
+        // Each peer contributes its own newest `-n` window, so the merged pool is
+        // already several times the cap. The local read is the one source that
+        // would otherwise be capped twice, and reading further back costs nothing
+        // (the files are tailed either way) — so it gets the headroom.
         let events = includeLocal
-            ? readRecentActivity({ sinceMs, limit: opts.limit })
+            ? readRecentActivity({ sinceMs, limit: opts.limit * LOCAL_READ_HEADROOM })
             : [];
+        // Peers that were dialed but never answered, reported once at the end
+        // rather than as a line each above the timeline.
+        let unreachable = [];
         if (wantRemote) {
-            // Explicit hosts drop self (it's the local read); --devices-all dials
-            // every online peer (hosts undefined).
-            const remoteHosts = explicitHosts?.length ? remoteFeedHostsToDial(explicitHosts, self) : undefined;
-            if (!explicitHosts?.length || (remoteHosts && remoteHosts.length > 0)) {
-                const remoteArgs = ['activity', '--json', '-n', String(opts.limit)];
-                if (typeof opts.since === 'number' && opts.since > 0)
-                    remoteArgs.push('--since', String(opts.since));
-                const remote = await gatherRemoteAgentsJson({
-                    args: remoteArgs,
-                    noFanoutEnv: ACTIVITY_NO_FANOUT_ENV,
-                    hosts: remoteHosts,
-                    parse: parseActivityPayload,
-                });
-                events = mergeActivityEvents(events, remote.items);
-            }
+            const remoteArgs = ['activity', '--json', '-n', String(opts.limit)];
+            if (typeof opts.since === 'number' && opts.since > 0)
+                remoteArgs.push('--since', String(opts.since));
+            const remote = await gatherRemoteAgentsJson({
+                args: remoteArgs,
+                noFanoutEnv: ACTIVITY_NO_FANOUT_ENV,
+                hosts: remoteHosts?.length ? remoteHosts : undefined,
+                parse: parseActivityPayload,
+                quiet: true,
+            });
+            events = mergeActivityEvents(events, remote.items);
+            unreachable = remote.skipped;
         }
         // Enrich by joining to live LOCAL sessions (ticket/project/execution host).
         // Remote events arrive already enriched by their own peer, so the join only
         // fills local ones; the pure fallbacks (cwd->project, host->device) cover
         // everything either way. Skip the ps/lsof scan when there's nothing to show.
+        // Project labels are canonical: a defined project's name wins over the
+        // repo-level key — including over a stale or def-skewed pre-baked stamp
+        // (the def match is a pure prefix compare; foreign paths just don't match),
+        // so a multi-repo project buckets as one even across version skew.
+        const projectDefs = listProjectDefs();
+        const canonicalProject = (cwd) => projectNameForCwd(cwd ?? undefined, projectDefs);
+        const resolveProject = (cwd) => resolveProjectNameForCwd(cwd, projectDefs);
         const sessions = includeLocal && events.length > 0 ? await getActiveSessions() : [];
-        let enriched = enrichActivityEvents(events, activityHintsFromSessions(sessions));
+        let enriched = enrichActivityEvents(events, activityHintsFromSessions(sessions, resolveProject), resolveProject, canonicalProject);
         if (opts.milestones)
             enriched = enriched.filter((e) => tierForEvent(e.event) === 'milestone');
+        if (opts.project) {
+            const unfiltered = enriched;
+            enriched = filterActivityByProject(enriched, opts.project);
+            // An exact-name flag that matches nothing deserves a useful answer, not
+            // a generic "no activity" that lies about the fleet.
+            if (enriched.length === 0 && unfiltered.length > 0) {
+                const seen = [...new Set(unfiltered.map((e) => e.project).filter((p) => !!p))].sort();
+                const defined = projectDefs.map((d) => d.name);
+                const parts = [
+                    seen.length ? `seen: ${seen.join(', ')}` : '',
+                    defined.length ? `defined: ${defined.join(', ')}` : '',
+                ].filter(Boolean);
+                process.stderr.write(chalk.gray(`  · no events for project "${opts.project}" (exact match)${parts.length ? ` — ${parts.join(' · ')}` : ''}\n`));
+            }
+        }
         if (opts.filter)
             enriched = filterActivityEvents(enriched, opts.filter);
-        enriched = enriched.slice(0, opts.limit);
+        enriched = capActivityEvents(enriched, opts.limit, { all: opts.all || opts.milestones });
         if (opts.json) {
+            // stdout stays clean JSON, but an unanswered peer is never a silent drop.
+            if (unreachable.length > 0)
+                process.stderr.write(formatUnreachableNote(unreachable));
             process.stdout.write(`${JSON.stringify(enriched, null, 2)}\n`);
             return;
         }
@@ -187,11 +334,13 @@ Linear ticket) -- never by re-parsing transcripts. --devices-all runs the same
             process.stderr.write(chalk.yellow(`  ! ${w}\n`));
         if (enriched.length === 0) {
             process.stdout.write(chalk.gray('No recent agent activity. Events appear here as agents create plans, open PRs, and spawn sub-agents.\n'));
+            process.stdout.write(formatUnreachableNote(unreachable));
             return;
         }
         if (groupBy)
             renderGrouped(enriched, groupBy, opts);
         else
             renderFlat(enriched, opts);
+        process.stdout.write(formatUnreachableNote(unreachable));
     });
 }

package/dist/commands/beta.js

@@ -4,6 +4,7 @@ const BETA_DESCRIPTIONS = {
     drive: 'Google Drive integration for reading and writing files',
     factory: 'Cloud-based agent dispatch via Rush Factory',
     'session-sync': 'Cross-machine session transcript sync via R2 (daemon push/pull)',
+    projects: 'Named multi-repo projects with a progress rollup (agents projects)',
 };
 function parseFeatures(values) {
     const valid = new Set(ALL_BETA_FEATURES);

package/dist/commands/doctor.js

@@ -12,7 +12,7 @@ import { getCliVersion } from '../lib/version.js';
 import { resolveHost } from '../lib/hosts/registry.js';
 import { sshExecAsync } from '../lib/ssh-exec.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
-import { machineId } from '../lib/session/sync/config.js';
+import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import chalk from 'chalk';
 import { checkAllClis, collectTeamsDoctorData } from '../lib/teams/agents.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError, getAccountInfo } from '../lib/agents.js';
@@ -101,7 +101,9 @@ async function resolveFleetTargets(opts) {
     const registry = await loadDevices();
     const localName = machineId();
     return Object.values(registry)
-        .filter((d) => d.name.toLowerCase() !== localName)
+        // Normalize names so zion/ZION/zion.local all match machineId() and we never
+        // self-SSH the local box during fleet probes (RUSH-2114).
+        .filter((d) => normalizeHost(d.name) !== localName)
         // Control devices (a cockpit) never run agents — skip them in the fleet
         // fan-out (an explicit --device <name> still resolves above).
         .filter((d) => !isControlDevice(d))

package/dist/commands/events.js

@@ -17,6 +17,8 @@ import chalk from 'chalk';
 import * as fs from 'fs';
 import { getLogsPath } from '../lib/events.js';
 import { readUnifiedEvents } from '../lib/event-stream.js';
+import { ingestBatch } from '../lib/events-ingest.js';
+import { setHelpSections } from '../lib/help.js';
 /**
  * Resolve `--limit` into a record cap. `0` means "no cap" — without it there is
  * no way to read the whole stream, and any aggregation (group-by failure, count
@@ -97,8 +99,93 @@ function renderRow(r) {
     const agent = r.agent ? chalk.gray(` ${r.agent}`) : '';
     return `${time}  ${originLabel(r).padEnd(24)} ${user.padEnd(22)} ${ev.padEnd(26)}${agent}  ${detailFor(r)}`;
 }
+/** Read all of stdin. Returns '' when nothing is piped. */
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return '';
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf-8');
+}
+function registerEmitSubcommand(events) {
+    const emitCmd = events
+        .command('emit')
+        .description('Record events produced outside this process (reads JSONL on stdin)')
+        .requiredOption('--source <name>', 'Producer name; stamped as `module` so `events --module <name>` filters to it')
+        .option('--dry-run', 'Validate and report without writing')
+        .option('--json', 'Report {written, rejected} as JSON')
+        .action(async (opts, cmd) => {
+        // The parent `events` command also declares `--json` (for its read view).
+        // Commander binds a flag declared on BOTH to the parent, so a bare
+        // `events emit … --json` lands on parent.opts().json and the child sees
+        // undefined — the human string would print where a caller expects JSON.
+        // Read both, same as `feed post`.
+        const wantJson = Boolean(opts?.json ?? cmd?.parent?.opts?.().json);
+        const input = await readStdin();
+        if (input.trim() === '') {
+            console.error('events emit: nothing on stdin — pipe one JSON object per line.');
+            process.exitCode = 1;
+            return;
+        }
+        let result;
+        try {
+            result = ingestBatch(input, { source: opts.source, dryRun: opts.dryRun });
+        }
+        catch (err) {
+            console.error(`events emit: ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = 1;
+            return;
+        }
+        if (wantJson) {
+            console.log(JSON.stringify({ written: result.written, rejected: result.rejected, routed: result.routed }, null, 2));
+        }
+        else if (result.rejected.length === 0) {
+            console.log(`${result.written} event(s) recorded${opts.dryRun ? ' (dry run)' : ''}.`);
+        }
+        else {
+            console.log(`${result.written} event(s) recorded${opts.dryRun ? ' (dry run)' : ''}.`);
+            console.error(`rejected ${result.rejected.length} line(s):`);
+            for (const r of result.rejected)
+                console.error(`  line ${r.line}: ${r.reason}`);
+        }
+        // Valid siblings are already written; a non-zero exit reports that the
+        // batch was not fully accepted without pretending nothing landed.
+        if (result.rejected.length > 0)
+            process.exitCode = 1;
+    });
+    setHelpSections(emitCmd, {
+        examples: `
+      # 1. Produce one JSON object per line (this is the whole input format).
+      printf '%s\\n' '{"event":"factory.command","commandId":"agents.newClaude"}' \\
+        | agents events emit --source factory
+
+      # 2. Flush a batch and check what landed.
+      agents events emit --source factory --json < batch.jsonl
+
+      # 3. Read it back. --limit 0 matters whenever you aggregate.
+      agents events --module factory --limit 0 --json
+    `,
+        notes: `
+      \`event\` is required and must be a known kind. \`ts\` (ISO-8601) is optional
+      and defaults to now — pass it so a batched producer records when each event
+      HAPPENED rather than when it flushed.
+
+      Envelope keys: ts, sessionId, mailboxId, terminalId, launchId, tmuxPane,
+      host, runtime, agent, tool, detail, url, project, cwd. Any other key is
+      payload and passes through the usual redaction.
+
+      A milestone kind (e.g. factory.launch) REQUIRES a sessionId — the activity
+      log is one file per session. Milestones route there; everything else goes
+      to the operational log. \`agents events\` reads both.
+
+      Rejection is per line: one bad line never discards the batch. Exit is 1 if
+      any line was rejected.
+    `,
+    });
+}
 export function registerEventsCommand(program) {
-    program
+    const events = program
         .command('events')
         .description('Read the unified event stream (operational + agent activity)')
         .option('--module <name>', 'Only events from this group (e.g. teams, secrets, activity)')
@@ -166,6 +253,9 @@ Examples:
         if (truncated)
             console.log(chalk.yellow(capNote));
     });
+    // `events` both reads (its own action, above) and writes (this subcommand) —
+    // the same shape as `feed` / `feed post`.
+    registerEmitSubcommand(events);
 }
 /** commander repeatable-option collector. */
 function collect(value, previous) {

package/dist/commands/exec.d.ts

@@ -16,6 +16,20 @@ export interface RunAccountPickerRequest {
 /** Distinguish a terminal account-picker marker from an explicit @version pin. */
 export declare function parseRunAccountPickerRequest(agentSpec: string): RunAccountPickerRequest;
 /** Return every option whose routing semantics conflict with a local account choice. */
+/**
+ * The `--host` alias family — the flags that mean "dispatch this run to another
+ * machine over SSH". `--host` is canonical; `--device`/`--on`/`--computer` are
+ * aliases. Returns the values actually given (so callers can both test presence
+ * and read the target). Kept in ONE place because a guard that listed only a
+ * subset silently let `--terminal --device` open a local tab and drop the remote
+ * target — the drift this predicate exists to prevent.
+ */
+export declare function hostTargetGiven(options: {
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+}): string[];
 export declare function runAccountPickerConflicts(options: {
     resume?: string | boolean;
     strategy?: string;