@phnx-labs/agents-cli 1.20.90 → 1.20.92

package/CHANGELOG.md

@@ -1,7 +1,283 @@
 # 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
+  feed carried benign progress but had no way to signal "I cannot proceed", so agents
+  hand-rolled it into the status text (`NEEDS MUQSIT: …`) and it reached nobody. A
+  blocked post writes `status.blocked` to the shared activity stream *and* opens an
+  answerable block in the ledger, so the ask stays open until someone resolves it
+  instead of scrolling away. It is a flag on the existing verb, not a new command —
+  one thing for an agent to learn, and one stream where most posts are benign and
+  some need a human. Blocked is a state, not a volume: it always broadcasts at
+  `important`, so passing `--level` too is a usage error rather than a silent
+  override. Pair it with `--option` for an answerable choice or `--default` for a
+  safe fallback policy may apply. Source: `apps/cli/src/commands/feed.ts`,
+  `apps/cli/src/lib/feed.ts`.
+- **Feed blocks are actually delivered.** `publishBlock` wrote every "needs you"
+  record to the ledger and stopped there — `broadcastPostedEvent` ran only for
+  `feed post`, so a block was durable and invisible at the same time. Blocks now
+  reach the configured `feed.broadcast` sinks, carrying the ask and the literal
+  `agents focus <id>` command that unblocks it, and a block that reaches nobody
+  exits non-zero instead of looking like a success. Source:
+  `apps/cli/src/lib/feed-broadcast.ts`.
+- **New `desktop` channel provider.** `agents send --channel desktop` (and
+  `notify.owner.channel: desktop`) posts a native notification through the branded
+  menu-bar helper. It is the only channel with no external dependency — no network,
+  no login, no vendor CLI — so it still reaches you at your Mac when a messaging
+  gateway is down. It reports real deliverability rather than always succeeding:
+  on Linux it probes for `notify-send` instead of trusting the platform name.
+  Source: `apps/cli/src/lib/channels/providers/desktop.ts`.
+
+- **`agents perf` — disposable SQLite latency warehouse.** Indexed p50/p99
+  rollups for hooks, CLI commands, and `agent.run` timings without scanning the
+  audit JSONL. Warehouse lives at `~/.agents/.cache/perf/perf.db` (safe to wipe);
+  identity columns reuse sessions/events string shapes (`session_id`, `agent`,
+  `machine`, …) for soft cross-reference — no foreign keys. Hook shims spool
+  into the same DB; `agents hooks profile` reads it first. Source:
+  `apps/cli/src/lib/perf/db.ts`, `apps/cli/src/commands/perf.ts`.
+
+- **A routine that misses its fire now runs late instead of being silently lost.** Fires
+  are in-process croner timers, and croner only ever schedules forward from "now" — so a
+  daemon that was down, asleep, or wedged when a routine came due dropped that fire
+  outright, and `loadAll()` rebuilt every timer looking only at the future. Detection
+  existed but ran **once, at daemon startup**, and only logged a warning plus a
+  notification; catching up was a manual `agents routines catchup`. Observed cost: zion's
+  daemon was down from 02:03Z to 08:23Z while the laptop slept, `weekly-fleet-retro` was
+  armed for exactly 04:00Z, never ran, and the restart logged `2 routine(s) overdue` and
+  did nothing. The daemon now re-scans every 5 minutes as well as at startup and runs each
+  missed routine via the same detached path `catchup` already used. Source:
+  `apps/cli/src/lib/catchup.ts`, `apps/cli/src/lib/daemon.ts`.
+- **New `catchup:` routine field, and `agents routines add --no-catchup`.** Defaults to
+  true — a routine you scheduled is one you expect to have run. Set `catchup: false` for a
+  routine whose worth expires with its slot (a 9am brief is useless at 3pm); the miss is
+  still recorded, it just is not re-run. `agents routines list --json` reports the
+  effective value as `catchup`.
+- **New `missed` run status.** A missed fire previously left no trace anywhere — no run
+  record, no log line in the routine's history — so `agents routines list` kept showing the
+  previous run's `completed` as though it were current, sometimes for weeks. A miss is now
+  written as a real run stamped at the moment the fire was due, so `agents routines runs
+  <name>` shows the gap, and the listing renders it distinctly from `failed` (a miss is an
+  infrastructure problem, not a task failure). That record is also what makes catch-up
+  idempotent: it advances the overdue comparison, so the same missed fire is never
+  reconsidered across ticks or a daemon restart storm, and its directory is created with a
+  non-recursive `mkdir` — an atomic claim, so if the daemon's timer and a manual
+  `agents routines catchup` overlap, only one of them runs the routine. Source: `apps/cli/src/lib/routines.ts` (`RunMeta`),
+  `apps/cli/src/commands/routines.ts`.
+- **A routine is never caught up for a fire that predates it.** `detectOverdueJobs` walks back
+  a week for the most recent expected occurrence, and a routine with no runs is overdue by
+  definition — so before this, `agents routines add` on any daily or weekly schedule whose slot
+  had already passed made the routine instantly "overdue". That was cosmetic while catch-up was
+  a manual command; with the daemon now catching up automatically it would have run every newly
+  created routine once, within five minutes of creating it. Routines gain a `createdAt` stamp
+  (written once, like `actor`), and overdue detection floors the expected fire at it — falling
+  back to the routine file's mtime for routines written before the field existed. Observed on
+  the live fleet: `agents-cli-updates`, created Aug 1 and never run, was flagged overdue for a
+  Jul 27 fire. Source: `apps/cli/src/lib/overdue.ts` (`routineEffectiveStart`),
+  `apps/cli/src/lib/routines.ts` (`writeJob`).
+
+- **`agents secrets list` can be filtered.** It had no filtering at all —
+  `--host` picks a machine and `--json` picks a format, but nothing selected over
+  the bundles themselves, so "which of these read with no Touch ID?", "which
+  still store a raw value inline?", "what have I not touched in three months?"
+  meant piping the table through `grep` or went unanswered. There is now an axis
+  per question: a `[query]` positional over name and description, `--policy`,
+  `--backend`, `--type`, `--kind`, `--held`/`--not-held`, `--expired`,
+  `--expiring [days]`, `--unused <duration>`, plus `--sort` and `-n/--limit`.
+  Every axis narrows independently, so they compose. Following the `agents
+  sessions` house style, an unknown value is a loud error naming the valid set
+  rather than an empty list, filters apply before `--json` so the payload is the
+  exact twin of the table, and they are forwarded over `--host` so a remote list
+  narrows the same way. `--held`/`--not-held` read live broker state and so
+  refuse to run off macOS instead of reporting every bundle as unheld. An empty
+  result names the filters that emptied it and the total it started from. Source:
+  `apps/cli/src/lib/secrets/list-filter.ts`, `apps/cli/src/commands/secrets.ts`.
+
+- **The EXPIRING column no longer hides keys that have already expired.**
+  `countExpiringSoon` counted only keys due in the next 30 days — the guard is
+  `d >= 0` — so a bundle whose token died last month rendered `-`, identical to
+  one with no expiry at all. The only places a lapsed key surfaced were
+  `agents secrets view` and a hard abort at inject time, i.e. after it had already
+  broken a run. The column now counts lapsed and upcoming together and turns red
+  once anything has lapsed, and `secrets list --json` gains an `expired` count
+  alongside the existing `expiringSoon`. Source: `apps/cli/src/commands/secrets.ts`.
+
+- **`agents secrets list` now states the hold window instead of the bare word
+  `hold`.** The `hold` tier is a duration — prompt once, then stay silent for
+  `secrets.agent.holdMs` (7 days by default) — but the POLICY column printed only
+  the tier name, so a reader could not tell it meant a window, let alone which
+  one; finding out meant running `agents secrets status`. The column now reads
+  `hold 7d`, and `hold 7d · held 6d` while the broker is actually caching the
+  bundle. It follows the configured window, so a 24-hour hold reads `hold 1d`.
+  `always` and `never` are unchanged — neither has a window, and annotating one
+  would repeat the mistake the `daily` rename fixed. Two adjacent bugs go with
+  it: `agents secrets view` printed "7d by default" as a string literal and so
+  misstated the window for anyone who had configured `holdMs`, and a stale broker
+  entry past its expiry rendered as `hold · held expired` because the column
+  tested the entry for presence rather than liveness. `secrets list --json` and
+  `secrets view --json` gain an additive `holdMs` field (null on `always`/`never`)
+  so a machine caller gets the window too. Source:
+  `apps/cli/src/commands/secrets.ts`.
+
+- **Richer session previews: skills, hooks, links, artifacts, repos, todo status.** The `agents sessions` quick preview and full summary now show the skills a session invoked (with counts), the hooks that fired (Claude transcripts, with repeat counts and failures), a clickable Links section (Linear/Jira/GitHub/GitLab URLs harvested from the conversation), the documents the session produced (`.agents/artifacts|plans|reports` and other `*.md`/`*.html` creations), the repos it worked in (via `.git` walk-up), and an error tally in the picker. The full summary's Plan section now marks checklist items `[x]`/`[>]`/`[ ]` and renders the checklist alongside the ExitPlanMode text instead of hiding it. Changes/Dirs lines collapse `.agents/worktrees/<slug>` prefixes to `⧉ <slug>/…`, are width-capped, and no longer list shell junk (`2>&1`, `$VAR` paths), `node_modules`, or agents-cli internal archives. Source: `apps/cli/src/lib/session/highlights.ts`, `apps/cli/src/lib/session/parse.ts`, `apps/cli/src/lib/session/render.ts`, `apps/cli/src/commands/sessions-picker.ts`.
+
 ## 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 {};