@phnx-labs/agents-cli 1.20.91 → 1.20.93

package/CHANGELOG.md

@@ -1,5 +1,270 @@
 # Changelog
 
+## 1.20.93
+
+- **`agents send` is a real delivery envelope; `notify` is just `--to owner` (RUSH-2123).** Flag-first form: `--to`, `--text`, `--channel`, `--attach`, `--url`. `--to owner` expands from `notify.owner` in agents.yaml. Positional text still works. Help names the three planes (deliver / record / control) so send is not confused with `feed post`, `activity`, or `message`/`sessions inject`. Source: `apps/cli/src/commands/send.ts`, `apps/cli/src/lib/channels/send.ts`.
+
+- **`agents events emit` — record events produced outside the CLI.** In-process code
+  calls `emit()` directly, but the producers that most need to record events are not
+  agents-cli processes: the Factory VS Code extension host, shell guards, external
+  tools. They now pipe JSONL on stdin —
+  `… | agents events emit --source factory`. `--source` is stamped as `module`, so
+  `agents events --module factory` filters to one producer. Routing is forced by the
+  stores rather than chosen: a milestone kind requires a `sessionId` and lands in that
+  session's activity log, everything else lands in the operational log. A milestone
+  with no `sessionId` is rejected, not quietly written elsewhere. Rejection is per
+  line, so one bad line never discards a batch, and the exit code is 1 if any line was
+  rejected. `--dry-run` validates without writing.
+  Source: `apps/cli/src/lib/events-ingest.ts`, `apps/cli/src/commands/events.ts`,
+  `apps/cli/docs/06-observability.md`.
+
+- **Four `factory.*` event kinds.** `factory.command`, `factory.action`, `factory.uri`
+  and `factory.launch` describe what a user did in the Factory VS Code extension.
+  `factory.launch` is a milestone — it carries the `sessionId` and `terminalId` that
+  later events join through — and `factory.uri` is audit-level, since an external
+  process driving the user's editor is a "who reached in from outside" fact.
+  Source: `apps/cli/src/lib/events.ts`, `apps/cli/src/lib/activity.ts`.
+
+- **`emit()` accepts a caller-supplied timestamp.** A batched producer records when
+  each event *happened* and flushes later; without this, every event in a flush was
+  stamped at flush time, collapsing their order and corrupting `--since` boundaries.
+  `ts` stays reserved against payload injection — only the explicit override can set
+  it. Source: `apps/cli/src/lib/events.ts`.
+
+- **Fixed: `agents _internal friction` recorded its own invocation.** The command
+  exists precisely because shell guards run before any `agents` process exists and so
+  cannot emit in-process, but it still fired the `command.start` / `command.end` audit
+  hooks, writing two records on top of every friction record. Recorder commands are now
+  exempt. Source: `apps/cli/src/index.ts`.
+
+- **Desktop notifications now show the agent on the right, not a second copy of
+  the app icon.** macOS draws two images on a banner: the sending app's icon on
+  the left and `contentImage` on the right (a YouTube notification uses the slots
+  for "YouTube" plus the channel avatar). agents-cli was putting its own lime mark
+  in the right slot, so both slots said the same thing. The right slot now carries
+  the harness the notification is *about* — a brand-colored tile with a two-letter
+  mark (`CL` claude, `CX` codex, `GK` grok, …), two letters because four harnesses
+  start with `c` and two with `g`. `agents run --notify` and agent/workflow
+  routines pass their harness through; a daemon heal, an overdue sweep, a command
+  routine, or a fan-out across several agents has no single agent and leaves the
+  right slot empty. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/AgentAvatar.swift`,
+  `apps/cli/src/lib/menubar/notify-desktop.ts`, `apps/cli/src/lib/run-notify.ts`,
+  `apps/cli/src/lib/routine-notify.ts`, `apps/cli/docs/menubar.md`.
+
+- **`MenubarHelper --notify` gains `--agent <id>`.** The one-shot notifier accepts
+  the harness id that drives the right-hand avatar; omitting it is how a caller
+  says "no single agent owns this event".
+
+- **`agents projects status --fleet` — per-device workspace drift (beta).**
+  Projects are natively multi-device; `--fleet` adds a `fleet` line to the status
+  card showing, for each project, whether its workspace repos are present on every
+  fleet device, on which branch, ahead/behind their upstream (`↑`/`↓`), and how
+  many uncommitted changes they carry — plus a hidden `agents projects probe
+  --json <path...>` subcommand that is the peer half of the fan-out. One parallel
+  SSH call per device (12s timeout), **no `git fetch`** — drift is measured
+  against each peer's last-fetched upstream, and a repo with no upstream reports
+  no drift rather than zero. Peers that are unreachable or run an older CLI are
+  named once in a trailing note; `probe` itself is not beta-gated so peers answer
+  whenever their binary carries it. The schema gains `repos[].path` (home-relative
+  local checkout) to opt additional repos into probing beyond the primary `root`,
+  and `--json` gains per-project `workspaces[]` with the host-tagged probe rows.
+  The card's `live` line also counts agents on every box under `--fleet` via the
+  existing sessions fan-out. Source: `apps/cli/src/lib/project-probe.ts`,
+  `apps/cli/src/commands/projects.ts`, `apps/cli/src/lib/projects.ts`.
+
+- **`agents projects` outcomes on the card — agent×project members, releases,
+  Linear counts, and `projects link --linear` (beta).** The status card gains an
+  `agents` line under `live` naming WHICH harness is on each project
+  (`claude · running · RUSH-2107 @zion`, sorted running-first, capped at 6 with a
+  `+N more` tail; under `--fleet` remote agents carry their peer's hostname), a
+  latest-release tag on the `ships` line (primary repo only, best-effort
+  `gh release list`), and a `linear` line counting the bound Linear project's
+  issues by state type (`12/30 done · 5 in progress`) — best-effort with an 8s
+  budget, skipped by `--no-remote`, and omitted when the def has no
+  `linear.projectId`. The new `agents projects link <name> --linear [query]`
+  writes that binding: no query auto-suggests from the def name + repo slug via
+  the normalized-key matcher (ported from Factory's `linearProjects.ts`),
+  ambiguous/none prints the candidate list and exits 1. `--json` gains
+  `members[]`, `latestRelease`, and `linear`. Source:
+  `apps/cli/src/lib/project-status.ts`, `apps/cli/src/lib/linear-projects.ts`,
+  `apps/cli/src/lib/linear-project-counts.ts`, `apps/cli/src/commands/projects.ts`.
+
+- **Project sync no longer spams a warning per file it left alone.** Syncing a
+  project whose `.claude/commands/` you wrote yourself printed one wrapped
+  `Skipping project resource target …: already exists and is user-owned` line
+  per file — six hand-authored commands meant twelve lines of terminal noise in
+  the middle of `agents view claude`. Those files are the normal steady state,
+  not a warning, so the sync now reports them once, grouped, in plain words:
+  `Kept 6 of your own files in .claude/commands: debug.md, doc-gaps.md,
+  image-nbp.md, +3 more`. The list also rides out on `SyncResult.projectSkipped`
+  for callers that want it. Source: `apps/cli/src/lib/project-resources.ts`.
+
+- **`agents secrets` now tracks per-bundle usage and surfaces it.** Every secret
+  lifecycle/access event — create, import, export, view, access (a value read for
+  injection), unlock — funnels through the one `emitSecretAudit` chokepoint, which
+  writes to BOTH the append-only `~/.agents/events.jsonl` audit log AND a derived,
+  value-free read-model at `~/.agents/secrets/secrets.db` (never a secret value —
+  bundle name, event kind, key count, resolving agent/host, status only).
+  `agents secrets view <bundle>` now shows whether the bundle is currently
+  **unlocked** (held by the secrets-agent, so reads are prompt-free), a **usage**
+  summary ("accessed 42× (last 2h ago) · exported 3× (last 1d ago)"), and
+  **per-agent** attribution, and nudges when a bundle has no description (also at
+  `create` time). `agents secrets list` gains **`--sort uses`** (most frequently
+  accessed) alongside the existing `--sort used`, and the `--json` payloads carry
+  `uses`, `usage`, and `heldExpiresAt`. A new **`agents secrets activity [bundle]`**
+  prints the recent value-free event timeline (bounded to 90 days). Naming guidance
+  is taught in the help and skill: name a website bundle after its domain
+  (`stripe.com`, `openai.ai`), a desktop-app bundle after its binary suffix
+  (`slack.app`, `photoshop.exe`). Recording is best-effort and
+  `AGENTS_NO_USAGE_TRACK=1` disables it. Source:
+  `apps/cli/src/lib/secrets/usage-db.ts`, `apps/cli/src/lib/secrets/audit.ts`,
+  `apps/cli/src/commands/secrets.ts`, `apps/cli/src/lib/secrets/list-filter.ts`.
+
+## 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 +388,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 {};