@phnx-labs/agents-cli 1.20.91 → 1.20.92

package/CHANGELOG.md

@@ -1,5 +1,149 @@
 # Changelog
 
+## 1.20.92
+
+- **`agents sessions` rows show creation time as well as last activity (RUSH-2107).**
+  The trailing time cell used to carry one unlabeled "X ago" — last activity — so a
+  row could not say when the session began or how long it had been alive. It now
+  reads `3d → 1 hour ago`: the compact creation age, then the last-activity label the
+  listing sorts by. Both the interactive picker and the flat/tree listings render it.
+  A session that ran for under a minute keeps a single field (the two halves would
+  name the same moment), and a terminal too narrow for both drops the creation age
+  rather than squeezing the topic below its floor, so rows never wrap. The picker's
+  detail pane spells the same facts out as `created X ago · last active Y ago ·
+  lasted Z`, and now derives them from the indexed session metadata when no local
+  transcript exists — so **remote** and not-yet-indexed sessions report their timing
+  instead of showing none. Source: `apps/cli/src/lib/session/relative-time.ts`,
+  `apps/cli/src/commands/sessions.ts`, `apps/cli/src/commands/sessions-picker.ts`.
+
+- **Stop fleet health probes from orphaning remote processes on timeout (RUSH-2114).** `sshExecAsync` now uses a direct ssh connection whenever a `timeoutMs` is set, because a control-master outlives the local client and keeps the remote command running after we kill it. `agents doctor` also normalizes host names before excluding the local machine, so `zion.local` can no longer be self-SSH'd. Source: `apps/cli/src/lib/ssh-exec.ts`, `apps/cli/src/commands/doctor.ts`.
+- **Harden menubar install against Gatekeeper rejection.** `ensureValidSignature` now checks `spctl --assess`; a Developer-ID-signed but un-notarized bundle is stripped of quarantine and re-signed ad-hoc so the launchd service does not crash-loop with "app is damaged". The release build script gained optional notarization via `MENUBAR_HELPER_NOTARIZE` and `MENUBAR_HELPER_NOTARIZE_KEYCHAIN_PROFILE`. Source: `apps/cli/src/lib/menubar/install-menubar.ts`, `apps/cli/menubar/scripts/build.sh`.
+
+- **`agents activity` now shows the whole fleet, grouped by project.** The
+  question the command answers is "what are my agents doing", and agents run on
+  every box — but it read only the local logs unless you remembered
+  `--devices-all`, and printed one flat newest-first stream. Both defaults are
+  inverted: every run fans `activity --json` out to each reachable device and
+  merges the peers' streams host-tagged, then buckets them by project, one level,
+  no sub-grouping. `--local` scopes back to this machine, `-H/--host` to named
+  boxes, and `--flat` (or `--group-by none`) restores the single stream;
+  `--devices-all`/`--hosts-all` remain accepted so existing scripts keep working.
+  A peer answering the fan-out still carries the recursion guard, so it never
+  re-fans the fleet.
+
+- **Each project header names the machines its work ran on.** A bucket reads
+  `▸ agents-cli  12 events · 4 milestones · zion, yosemite-s0` — up to three
+  machines by name plus a `+N` tail, so a project touched by a dozen boxes stays
+  one scannable line; individual rows keep their own `[host]` tag. Peers that
+  never answered are reported once at the end (`· 2 devices unreachable: …`)
+  rather than a line each above the timeline, so a missing machine is visible but
+  not noisy.
+
+- **A project is now the repository, not whatever directory the agent sat in.**
+  A cwd resolves to the git repository containing it, so `<repo>/apps/cli` files
+  under `<repo>` instead of `cli`, and a worktree under
+  `<repo>/.agents/worktrees/<slug>` folds back into the repo it branched from.
+  A directory in no repo groups as itself, and a dotfiles repo at `$HOME` is not
+  treated as a project. The `agents sessions` overview and `agents feed post` now
+  share this one resolver (`lib/project-key.ts`), so a project reads identically
+  everywhere instead of each view folding cwds its own way.
+
+- **`--limit` is spent on milestones, not on collapsed churn.** The default view
+  rolls routine `file.edited` work up to a count, so a plain slice let one busy
+  machine's 40 file edits hide every other device's PRs behind a single
+  `file edited ×40` line. The cap now bounds the milestones shown, with the
+  routine events inside that window riding along for the counts. `--all` still
+  shows routine work inline and caps every event.
+
+- **The activity header no longer carries other subsystems' hook warnings.**
+  Registering the activity-log hooks surfaced every unresolved entry in the hook
+  manifest — a missing `inject-session-id` script, someone else's half-installed
+  plugin — printing five wrapped yellow lines above the timeline on every run.
+  Those are `agents doctor`'s job; only a failure that would leave the activity
+  log unwritten is reported here.
+
+- **The menu bar's New Session opens in the terminal you actually work in.** It
+  hardcoded AppleScript at Terminal.app, so a Ghostty or iTerm user got a
+  Terminal.app window every time. It now shells `agents run <agent> --terminal`,
+  and the CLI resolves the terminal from the user's own live sessions — the host
+  app `agents sessions --active` already attributes every session to
+  (`ActiveSession.host`). Order: the terminal the caller is in, then the host of
+  the most recent live session, then the first available backend. Hosts map to
+  backends only where the engine can really drive them, so an undrivable host
+  (Warp, kitty, Cursor) falls through instead of opening the wrong app. A
+  tmux-hosted session (every interactive `agents run`) resolves to the app its
+  attached tmux client is in, via the same resolver behind
+  `agents sessions`' "viewing in Ghostty tab 2" — without that it would name the
+  multiplexer and no terminal at all. Source:
+  `apps/cli/src/lib/terminal/preferred.ts`,
+  `apps/cli/src/lib/terminal/backends/terminal-app.ts`,
+  `apps/cli/menubar/Sources/MenubarHelper/AgentsCLI.swift`.
+
+- **`agents run <agent> --terminal` opens a run in a real terminal tab.** For a
+  caller that cannot host a TUI (the menu bar, a script). Without a value the
+  terminal is detected as above; `--terminal <backend>` forces one
+  (`iterm | ghostty | terminal | tmux | vscodium-agent`) and errors on an unknown
+  id rather than silently auto-detecting. The tab re-invokes the same argv with
+  the flag stripped, so `--mode`, `--cwd`, and a `--` passthrough ride along.
+  Cannot combine with `--host`. Source: `apps/cli/src/lib/terminal/run-surface.ts`,
+  `apps/cli/src/commands/exec.ts`.
+
+- **Terminal.app is a real launch backend now (`terminal`).** Registered last, so
+  it is the every-Mac floor without outranking a terminal the user chose to
+  install, and reported unavailable over SSH where `osascript` cannot reach the
+  GUI login. It has no scriptable split, so a split request opens a tab, and
+  `agents sessions resume --splits` now says so instead of quietly producing
+  tabs. `detectCurrentBackend` also recognizes `TERM_PROGRAM=Apple_Terminal`.
+  Source: `apps/cli/src/lib/terminal/backends/terminal-app.ts`.
+
+- **`agents sessions resume` / `sessions focus` reach Terminal.app too.** Adding
+  it to the backend registry changes both: on a Mac with neither iTerm, Ghostty,
+  nor VSCodium installed they used to fall back to resuming in the current
+  process, and now open a Terminal.app tab; `resume`'s interactive picker gains a
+  Terminal row, and `--terminal-app` forces it (named apart from
+  `run --terminal`, which means something different). Source:
+  `apps/cli/src/commands/sessions-resume.ts`, `apps/cli/src/commands/focus.ts`.
+
+- **New Task… in the menu bar.** A row above New Session that opens the
+  quick-dispatch bar — the same panel as `Cmd-Shift-O`, now reachable without the
+  chord (and without the Accessibility grant the chord needs). The status item
+  owns the one panel instance, so an interrupted capture is restored whichever
+  entry point you return through. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/StatusItemController.swift`.
+
+- **Activity, feed posts, and the sessions overview now speak defined project
+  names.** One resolver (`resolveProjectNameForCwd`, `lib/projects.ts`) backs all
+  three: a cwd inside a defined project (`~/.agents/projects/<name>.yaml`) reads
+  as the project's name — a multi-repo project is a single bucket in `agents
+  activity`, not one per repo — and anything else falls back to the
+  repository-level key, so nothing changes without definitions. Each peer
+  resolves its own cwds against its synced definitions before events cross the
+  wire. Source: `apps/cli/src/lib/projects.ts`, `apps/cli/src/commands/activity.ts`.
+
+- **`agents activity --project <name>`** narrows the fleet stream to one project,
+  exact-matched on the resolved label — one project's PRs, plans, and worktrees
+  across every box without the rest of the fleet's noise. Source:
+  `apps/cli/src/lib/activity.ts` (`filterActivityByProject`).
+
+- **`agents projects` — named multi-repo projects with a project progress rollup (beta).**
+  Define a project once in `~/.agents/projects/<name>.yaml` (name, home-relative
+  root/defaultPath, multiple repos with monorepo subpaths, described `contexts[]`
+  starting points, external `integrations[]`, Linear link) and `agents run --project
+  <name>` resolves the definition before the old `<root>/<slug>` convention — undefined
+  slugs behave exactly as before. The headline is `agents projects status`: instead of a
+  per-agent activity line, it renders one card per project — live agents by state, plan
+  completion, open **and** recently-merged PRs, tickets in flight, and the artifacts
+  agents produced — by rolling up signals already on disk (live agents matched to a project
+  by this machine's session cwd; the merged-PR count is repo-global via `gh`). `--window
+  <days>` and `--no-remote`
+  tune the PR/artifact lookup. Also `list` / `add` (infers root + origin slug) / `show` /
+  `edit` / `import --from-factory` (absorbs the Factory `projects.json` registry) / `rm`.
+  Enable with `agents beta enable projects`. Source: `apps/cli/src/lib/projects.ts`,
+  `apps/cli/src/lib/project-status.ts`, `apps/cli/src/commands/projects.ts`,
+  `apps/cli/src/lib/project-root.ts`.
+
+- **The cross-fleet session sweep no longer hides sessions on manually-registered devices.** `agents sessions` fan-out (and therefore `--resolve`, cross-machine resume, and `--active`) picked peers with a strict `tailscale.online === true` test. A device registered with `address.via: "manual"` never gets a Tailscale peer entry at all, so its `online` stayed `undefined` and the sweep skipped it **permanently** — every session on that box was invisible and could not be resolved or resumed from any other machine. Peer selection is now `isDialableDevice`, a union of both liveness signals: a device with no Tailscale block is unknown-not-offline (the rule `ssh.ts` `renderDeviceTable` and Factory's `isDeviceOnline` already used, so the picker and the sweep finally agree on who exists), and a positive live SSH probe (`DeviceProfile.reachability`, RUSH-1965) additionally rescues a device whose snapshot says offline. A **failed** probe deliberately does not remove a peer — the probe runs on a short SSH budget and returns false negatives on a congested tailnet (observed calling the local machine unreachable), and letting that shrink the sweep would hide sessions on healthy boxes. Applied to both sweeps that share this shape. Source: `apps/cli/src/lib/devices/registry.ts` (`isDialableDevice`), `apps/cli/src/lib/session/remote-list.ts`, `apps/cli/src/lib/remote-agents-json.ts`.
+
 ## 1.20.91
 
 - **An agent can now say it is stuck: `agents feed post --blocked` (RUSH-2110).** The
@@ -123,6 +267,17 @@
 
 ## 1.20.90
 
+- **Bash commands are now parsed and classified for richer activity summaries.** The
+  `11-activity-log.py` hook tokenizes every Bash tool call and emits a structured
+  `bash.executed` activity record with `category`, `bashTool`, and `bashAction`.
+  High-signal commands also raise milestones: `video.rendered`/`video.converted`
+  for `ffmpeg`, `image.upscaled` for `realesrgan`/`waifu2x`/`swin2sr`, and
+  `metadata.edited` for `exiftool`/`id3v2`/`metaflac`/`vorbiscomment`. The session
+  renderer and digest use the shared `lib/session/bash-command.ts` classifier.
+  Source: `apps/cli/src/lib/session/bash-command.ts`,
+  `apps/cli/src/lib/activity.ts`, `apps/cli/src/lib/session/digest.ts`,
+  `apps/cli/src/lib/session/render.ts`.
+
 - **`agents sessions --active` now shows one row per agent, not one per directory.**
   A live tmux agent pane whose durable identity records were missing (the common case
   once meta/pid-registry entries age out) was dropped, then re-surfaced by the ps-scan

package/README.md

@@ -288,7 +288,7 @@ Filters **stack** (they AND together), the active set shows in the header, and t
 
 Each live session resolves to `working`, `waiting_input` (with why -- a question, a plan review, or a permission prompt), or `idle`, alongside badges for the PR it opened, the worktree it sits in, and the ticket it's working. `agents sessions focus [id]` attaches the live pane in place -- the tmux split locally or over SSH, or its Ghostty tab -- and falls back to a fresh tab + resume when the terminal is gone.
 
-Landing on a session cold? `agents sessions <id>` prints a catch-up digest: an inferred title, files changed grouped by directory (created / modified / deleted), a histogram of which tools did the work, and the last test verdict -- the signals to reload a task in seconds.
+Landing on a session cold? `agents sessions <id>` prints a catch-up digest: an inferred title, files changed grouped by directory (created / modified / deleted), a histogram of which tools did the work (including parsed Bash commands -- `git`, `npm`, `ffmpeg`, `ssh`, and so on), and the last test verdict -- the signals to reload a task in seconds.
 
 ### Resume anywhere — and stay resumed
 

package/dist/commands/activity.d.ts

@@ -8,14 +8,80 @@
  * it tails the logs and collapses routine work to counts, surfacing milestones
  * individually and newest-first.
  *
- * Fleet-wide by opt-in: `--devices-all` (or `--host <box>`) fans the same
- * `activity --json` payload out across the fleet the way `agents feed` does,
- * merges every peer's stream host-tagged, and joins each item to live sessions
- * (project / ticket / execution host) so `--group-by project` shows, per
- * project, what each agent did, where, and for which ticket -- progress at a
- * glance. Local-only stays the default.
+ * Fleet-wide and project-grouped BY DEFAULT: the question this command answers
+ * is "what are my agents doing", and agents run on every box, so a local-only
+ * flat stream answered a narrower question than anyone asked. Each run fans the
+ * same `activity --json` payload out across the fleet the way `agents feed`
+ * does, merges every peer's stream host-tagged, joins each item to live sessions
+ * (project / ticket / execution host), and buckets it by project -- one level,
+ * no sub-grouping, with the machines named in each project's header.
+ *
+ * `--local` scopes back to this machine, `--host <box>` to named peers, and
+ * `--flat` (or `--group-by none`) restores the single newest-first stream.
  */
 import type { Command } from 'commander';
+import { type ActivityGroupBy } from '../lib/activity.js';
 /** Recursion guard: a peer answering a fan-out never re-fans-out itself. */
 export declare const ACTIVITY_NO_FANOUT_ENV = "AGENTS_ACTIVITY_LOCAL";
+interface ActivityOpts {
+    json?: boolean;
+    all?: boolean;
+    milestones?: boolean;
+    limit: number;
+    since?: number;
+    local?: boolean;
+    host?: string[];
+    device?: string[];
+    devicesAll?: boolean;
+    hostsAll?: boolean;
+    groupBy?: string;
+    flat?: boolean;
+    project?: string;
+    filter?: string;
+}
+/**
+ * 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 declare function isActivityHookError(error: string): boolean;
+/**
+ * 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 declare function isManifestHookError(error: string, manifestNames: string[]): boolean;
+/**
+ * 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 declare function formatUnreachableNote(skipped: string[]): string;
+/**
+ * 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 declare function resolveActivityGrouping(opts: Pick<ActivityOpts, 'groupBy' | 'flat'>): ActivityGroupBy | undefined;
+/** Which machines an invocation reads from. Pure -- no SSH, no device registry. */
+export interface ActivityScope {
+    /** Read this box's own activity logs. */
+    includeLocal: boolean;
+    /** Dial peers over SSH. */
+    wantRemote: boolean;
+    /** Peers to dial; `undefined` means "every reachable device". */
+    remoteHosts?: string[];
+}
+/**
+ * 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 declare function resolveActivityScope(opts: Pick<ActivityOpts, 'local' | 'host'>, self: string, noFanoutEnv?: boolean): ActivityScope;
 export declare function registerActivityCommand(program: Command): void;
+export {};

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);