@phnx-labs/agents-cli 1.22.6 → 1.22.7

package/CHANGELOG.md

@@ -1,9 +1,95 @@
 # Changelog
 
-## 1.22.6
+## 1.22.7
+
+- **`agents feed --project <name>` scopes the whole feed to one project.** Open
+  blocks, the updates view (`--filter updates`), and the trailing activity lane
+  are all filtered to the requested repo/project using the same worktree-aware
+  project key as `agents perf` (`lib/project-key.ts`). The masthead becomes
+  `<project> needs you` / `<project> updates`. Filtering is applied locally after
+  the fleet fan-out, so older peers that do not recognize `--project` still
+  contribute correctly. Source: `apps/cli/src/commands/feed.ts`,
+  `apps/cli/src/lib/feed-ranking.ts`.
+
+- **Feed blocks are now stamped with their project.** The `feed-publish` hook
+  derives project from the session cwd, and `agents feed post --blocked` stamps it
+  on the declared block. Live-session enrichment backfills `project` onto older
+  blocks that lack it. Source: `apps/cli/src/lib/feed.ts`,
+  `apps/cli/src/lib/feed-outcome.ts`, `apps/cli/src/lib/session/active.ts`.
+
+- **`agents activity` is removed.** The standalone milestone timeline is gone;
+  its stream is now read through `agents feed --filter all` (blocks + updates) or
+  `agents feed --filter updates` (updates only). `activity --project <name>` is
+  replaced by `feed --project <name>`. Source: `apps/cli/src/index.ts`,
+  `apps/cli/src/startup/command-registry.ts`, `apps/cli/src/commands/activity.ts`
+  (deleted), `apps/cli/docs/06-observability.md`,
+  `apps/cli/docs/11-projects.md`.
+
+- **`agents browser start` no longer fails with "Custom binary not found" when the `default` profile came from another OS.** `~/.agents/agents.yaml` syncs across the fleet, so a `default` profile auto-created on macOS carried a `/Applications/Google Chrome.app/...` binary path that doesn't exist on a Linux box — a bare `browser start` there died with `Custom binary not found`, the top browser roadblock (one session burned six commands working around it). `ensureDefaultBrowserProfile` now validates that the resolved default can actually launch on THIS machine and, if its browser/binary is missing, regenerates the `default` from the installed-browser auto-detect instead of handing back the broken profile. A configured default (`profiles set-default`) that can't launch here warns and falls through to auto-detect; remote (`ssh://`) defaults skip the local binary check since their browser lives on the far host. Source: `apps/cli/src/lib/browser/profiles.ts`, `apps/cli/docs/browser.md`.
+
+- **The stray "Agents CLI needs to authenticate to continue" Touch ID sheet now actually heals on an already-hashed machine (SEC-13/#1938 follow-up).** 1.22.5 added a one-time no-ACL re-store for a stale-ACL'd `agents-cli.hmackey` item — the internal HMAC key read *before every hashed keychain lookup*, whose damaged copy pops a generic, context-less Touch ID sheet on nearly any command that touches secrets. But it wired the heal only into `maybeAutoRekey`, which is bypassed for the hmackey and hashed-name lookups themselves (`prepareServiceName` returns early for `HMAC_KEY_ITEM` before `maybeAutoRekey` runs). So the exact hot paths that read the key — the `agents devices list` stats probe a SessionStart hook runs, and every background hashed read — never triggered the heal, and an already-migrated machine prompted forever. The documented `agents secrets rekey` remedy is also a no-op on such a machine: with no cleartext names left to re-key, it returns without re-storing the key. The heal now runs on the read path itself (`readHmacKeyRecord`): the first hashed lookup in the first process re-stores the record no-ACL exactly once (guarded by `healedNoAcl`, so it never churns the keychain afterward) — one last prompt on the read that heals it, then silent forever, on every path. Source: `apps/cli/src/lib/secrets/index.ts`.
+
+- **Add Pi (Oh My Pi, `omp`) as a native harness.** agents-cli now installs, runs, and
+  syncs resources for [Oh My Pi](https://omp.sh) (`@oh-my-pi/pi-coding-agent`, binary
+  `omp`) under id `pi`. Pi is a Bun-based, terminal-first, multi-provider coding agent;
+  its cross-provider model catalog (OpenRouter, OpenAI, Anthropic, xAI, DeepSeek, …)
+  surfaces in `agents view` and `agents models pi` via `omp models --json`. It is
+  Claude-compatible: MCP (`.mcp.json`, stdio + http + headers), skills, file commands, and
+  Claude-shaped subagents all sync into `~/.omp/agent/`. Hooks, allowlist, and plugins are
+  intentionally off (omp's hook/approval/plugin models don't map to agents-cli's).
+  Source: `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/exec.ts`, `apps/cli/src/lib/models.ts`.
+
+- **`agents run <profile> --model <tier>` now resolves the cost tier against the profile's own harness, not its host's.** A custom-harness profile (e.g. a DeepSeek model routed through the `claude` host binary) resolved a tier token (`cheap|default|best|ultra`) by calling `resolveTier(options.agent, ...)` with `options.agent` already overwritten to the HOST agent's id — so `best` resolved against Claude's own catalog and could push a real Claude model id as the `--model` flag, clobbering the profile's own `ANTHROPIC_MODEL` env value. Profiles can now declare a `models:` block (per-tier model ids for the harness's own catalog); a requested tier resolves against it first — clamping an unset tier down to the next cheaper one that IS set — and the concrete id is substituted into both the env and the forwarded `--model` value before exec.ts's native (host-catalog) tier logic ever runs. A profile with no `models:` configured degrades gracefully to today's behavior — the harness's single pinned model, with an informational note instead of an error. Source: `apps/cli/src/lib/profiles.ts`, `apps/cli/src/commands/exec.ts`.
+
+- **`agents projects status` card: host-grouped agents, focus units, and a warnings footer.** Live agents render under `@host` rows so the same harness on two machines is not collapsed into one cell. Focus counts are labeled `file-touches (Nd)` instead of bare integers. Repo drift, dirty trees, missing checkouts, slug mismatch, unmeasurable schedule, and crash piles land at the bottom with 🔴 critical / ⚠️ continue. Local workspace probe always feeds the footer (full fleet table still requires `--fleet`). Source: `apps/cli/src/lib/project-status.ts`, `project-focus.ts`, `project-probe.ts`, `commands/projects.ts`.
+
+- **`agents projects status` and `view`/`show` share one body.** Named form is the full card (every milestone + definition); unnamed is the multi-project rollup. No second implementation to drift. Source: `apps/cli/src/commands/projects.ts`.
+
+- **`agents sessions --help` and `05-sessions.md` now teach one session-lifecycle
+  matrix.** `focus` / `focus --attach-only` / `detach` / `attach` / `resume` are
+  listed as distinct intents (not synonyms), so operators stop guessing among
+  `go` / `focus` / `attach` / `resume`. Source: `apps/cli/src/commands/sessions.ts`,
+  `apps/cli/src/commands/focus.ts`, `apps/cli/docs/05-sessions.md`.
 
 - **Cost tiers are ignored (with a clear warning) for profile runs.** A profile's model comes from its endpoint (e.g. Kimi/DeepSeek/GLM via `agents run <profile>`), not the host harness's catalog — so passing `--model cheap|default|best|ultra` to a profile used to resolve against the *host* harness and forward an incompatible model id to the profile's endpoint. Now a tier on a profile run is discarded with a standout warning and the profile's configured model is used. Concrete `--model <id>` on a profile is unchanged. Source: `apps/cli/src/commands/exec.ts`.
 
+- **`agents view` harness rows now lead with the version number.** Custom harness rows previously showed `via <host> <version>` — the host CLI name came first, which buried the version in the middle of the line. The format is now `<version> (forked from <host>)` for pinned harnesses and `<version> (forked from <host>, tracks default)` for unpinned ones that follow the host's global default. The `tracks default` label is shown in green so it stands out at a glance.
+
+- **Chained fork lineage in harness headers.** When a custom harness is itself a fork of another custom harness (which in turn forks a native host), the block header now shows the full two-hop chain: `custom · forked from <intermediate> -> <native-host>`. Single-hop forks continue to show `custom · forked from <parent>`.
+
+- **BYOK budget bar in `agents view`.** Custom harnesses backed by an OpenRouter key now show a live spend bar (amount used, remaining, and limit) inline on the model/auth row. Keys are deduplicated so multiple harnesses sharing the same keychain entry trigger exactly one API call. The bar is rendered only when a budget is available; harnesses without a BYOK key are unaffected. Source: `apps/cli/src/lib/byok-usage.ts`, `apps/cli/src/commands/view.ts`.
+
+- **`agents run auto` with no prompt no longer silently attaches a dead pane or leaves an orphan session (RUSH-2185 / EXEC-23a).** Three latent bugs combined to produce this failure when `auto` picked a harness like `cursor-agent` that exits immediately without a prompt: (F1) the auto-picker had no gate for whether a harness can open a bare interactive REPL — `cursor-agent` was a valid candidate even though its CLI requires a prompt and exits on `argv = []`; (F2) `surfacePaneFailure` was guarded by `status !== 0`, so a clean exit-0 death produced only a bare `[detached]` line with no diagnostic; (F3) the "pane still alive → keep session" fall-through relied on `paneExitStatus` returning `{dead:false}`, which it also returns on any query error (a race right after the pane-died hook), leaving the session alive as an orphan. Fixed: (F1) a new `interactiveRepl` capability bit in `AgentConfig.capabilities` marks every harness; `auto` now filters to REPL-capable candidates before picking, and fails loud naming the installed harnesses when none qualify; (F2) `shouldRecapDeadPane(status, interactive)` surfaces the pane tail any time the run is interactive, regardless of exit code; (F3) `isPaneKnownAliveFromQueryResult(code, stdout)` is now required as positive proof before keeping a session — an ambiguous result tears the session down via `killSession` instead. Source: `apps/cli/src/lib/exec.ts`, `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/types.ts`, `apps/cli/src/lib/capabilities.ts`, `apps/cli/src/commands/exec.ts`, `apps/cli/docs/specifications.md` (EXEC-23a).
+
+- **`agents run auto` can pick the Pi (`omp`) harness for prompt-less interactive runs again, and `main` builds green.** The `interactiveRepl` capability bit added by the RUSH-2185 / EXEC-23a fix landed at the same time as the new Pi harness, and neither change saw the other — so `pi` was the one agent in `AGENTS` that never declared the bit, and the completeness test that pins the registry to the capability list went red on `main` (`pi missing interactiveRepl`). Pi now declares `interactiveRepl: true`: bare `omp` runs the TUI, and `omp -p` is the one-shot form that answers a prompt and exits.
+
+- **`projects status --fleet` no longer labels this box `@local`.** Local sessions from `getActiveSessions()` lacked `machine`; host-grouped agents stamped remotes only. Locals are now filled with `machineId()` before rollup so the agents roster and fleet lines agree. Source: `apps/cli/src/lib/project-status.ts`, `commands/projects.ts`.
+
+- **`agents sessions stats` — which skills/commands you actually invoke, and which are dead weight.** A cheap, db-backed rollup of `session_resource_usage` (the skill/`Skill`-tool + slash-command tallies already recorded at index time), joined to `sessions` for attribution so `--agent`/`--project`/`--since`/`--machine` narrow the window and `--kind`/`--plugin` narrow the resources. A both-ends view: the most-invoked resources (`--bottom` flips to least-invoked, `--top <n>` caps), and the installed-but-never-invoked ones (cross-referenced against `listResources`/`discoverPlugins`) — the productized form of a manual transcript-scan audit. `--json` emits a versioned `sessions-stats` envelope. The signal captures EXPLICIT invocations only (slash commands + `Skill` tool calls) — an auto-triggered skill emits no event and reads as 0, and only Claude transcripts expose the signal today; both caveats are surfaced in help and output. A new `agents sessions backfill resources` folds historical sessions (indexed before the signal shipped) into the usage index, re-parsing each transcript from byte 0, gated by a new `resource_scan_ledger` (schema v31) so reruns skip completed transcripts — mirroring `agents sessions backfill tools`. Source: `apps/cli/src/commands/sessions-stats.ts`, `apps/cli/src/commands/sessions-backfill.ts`, `apps/cli/src/lib/session/db.ts`, `apps/cli/docs/05-sessions.md`, `apps/cli/docs/specifications.md` (SES-IF-4b).
+
+- **`agents share` serves screenshots and recordings with a real content-type.**
+  Publishing a PNG/JPEG/GIF/WebP/AVIF image, an MP4/MOV/WebM video, or a PDF now
+  sets the matching `content-type` instead of `application/octet-stream`. GitHub's
+  image proxy (camo) only renders an inline `![](url)` when the asset is served as
+  a real image/video type, so this is what lets an agent drop a screenshot or a
+  screen recording straight into a PR body via `agents share <file>`. HTML, SVG,
+  CSS, JS, JSON, and text were already typed correctly. Source:
+  `apps/cli/src/lib/share/publish.ts`.
+
+- **`agents trends tools-per-session` now counts every scanned session, not just `agents teams`
+  runs.** The recipe read `sessions.tool_call_count`, a column nothing populates except the
+  teams summarizer (`apps/cli/src/lib/teams/summarizer.ts`) — the general session indexer never
+  computes it. So every session that did not come from a team was scored 0 or excluded outright
+  by `WHERE tool_call_count IS NOT NULL`, pinning the fleet-wide p50 at 0 however many tools ran
+  and leaving only `claude` in the table. It now reads `tool_scan_ledger.call_count`, the
+  per-session count the tool indexer writes for every session it scans — the same index behind
+  `agents sessions --include tools`, so the two surfaces stop disagreeing. Sessions with
+  genuinely zero tool calls still count as 0 instead of vanishing. On a real 7-day window this
+  took the sample from 400 to 570 sessions and surfaced `grok`, `rush`, `codex`, `kimi`,
+  `droid` and `antigravity`, none of which had ever appeared. Run `agents sessions backfill
+  tools` once if historical sessions were never indexed. Source:
+  `apps/cli/src/lib/analytics/recipes.ts`.
+
 ## 1.22.5
 
 - **`agents events` can now filter by `--session <id>` and `--bundle <name>` — trace which agent/session triggered a secret access.** Every event already carries the provenance `sessionId`, and secrets events carry the `bundle` in their payload, but neither was queryable: you could see *that* the `share` bundle was read, not *which session* read it. `--session` (wired to the engine's existing `sessionId` filter) and `--bundle` (a new payload filter across both the operational log and the activity stream) close that gap. `agents events --module secrets --bundle share --session <id>` answers "which agent read the share bundle" — the attribution the Touch ID storm investigation needed, since the macOS biometric sheet itself emits no event. Source: `apps/cli/src/lib/event-stream.ts`, `apps/cli/src/commands/events.ts`, `apps/cli/docs/06-observability.md`.

package/README.md

@@ -31,6 +31,8 @@
   <a href="https://x.ai" title="Grok Build (xAI)"><strong>Grok</strong></a>
   &nbsp;&nbsp;&nbsp;&nbsp;
   <a href="https://factory.ai" title="Factory AI Droid"><strong>Droid</strong></a>
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://omp.sh" title="Oh My Pi"><strong>Pi</strong></a>
 </p>
 
 https://agents-cli.sh/demo.mp4
@@ -270,6 +272,11 @@ agents sessions --include tools --query 'program:git' --count --fleet --json
 
 # Populate historical tool rows once on each device
 agents sessions backfill tools --fleet
+
+# Which skills/commands you actually invoke -- and which installed ones are dead weight
+agents sessions stats
+agents sessions stats --zero            # only the never-invoked (dead weight)
+agents sessions backfill resources      # fold historical sessions into the usage index
 ```
 
 Interactive picker when you're in a terminal. Structured output (`--json`, `--markdown`, filtered by role or turn count) when piped.

package/dist/commands/exec.js

@@ -1568,7 +1568,7 @@ export function registerRunCommand(program) {
                 await warnUnpushedWork(resumeExec.cwd ?? process.cwd());
             process.exit(resumeExit);
         }
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive, inferredInteractiveWithoutTty }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported }, { splitBundleRef, resolveHostSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES, collectHarnessCandidates, pickHarnessWeighted, classifyHarnessCandidates, formatHarnessPickBanner, formatNoHealthyHarnessError, formatNoHealthyAccountError }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports }, { shareRuntimeEnv },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive, inferredInteractiveWithoutTty }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported }, { splitBundleRef, resolveHostSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES, collectHarnessCandidates, pickHarnessWeighted, classifyHarnessCandidates, formatHarnessPickBanner, formatNoHealthyHarnessError, formatNoHealthyAccountError }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports, capableAgents }, { shareRuntimeEnv },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -1629,9 +1629,24 @@ export function registerRunCommand(program) {
             // — launching a default "because it's there" is how a rotate loop
             // hammers an exhausted account.
             const byHarness = await collectHarnessCandidates();
-            const harnessPick = pickHarnessWeighted(byHarness);
+            // F1 (RUSH-2185 / EXEC-23a): a prompt-less run is interactive; only
+            // harnesses that can open a REPL with no argv are valid candidates.
+            // cursor-agent and similar exit immediately without a prompt, which
+            // leaves a silent [detached] pane and an orphan session.
+            const interactive = prompt === undefined && options.headless !== true;
+            const replCapable = interactive ? new Set(capableAgents('interactiveRepl')) : null;
+            const candidateHarness = replCapable
+                ? new Map([...byHarness].filter(([id]) => replCapable.has(id)))
+                : byHarness;
+            const harnessPick = pickHarnessWeighted(candidateHarness);
             if (!harnessPick) {
-                console.error(chalk.red(formatNoHealthyHarnessError(classifyHarnessCandidates(byHarness))));
+                if (replCapable && byHarness.size > 0 && candidateHarness.size === 0) {
+                    const installed = [...byHarness.keys()].join(', ');
+                    console.error(chalk.red(`No installed harness supports a prompt-less interactive REPL (installed: ${installed}). Pass a prompt (-p) or install claude, codex, or another REPL-capable harness.`));
+                }
+                else {
+                    console.error(chalk.red(formatNoHealthyHarnessError(classifyHarnessCandidates(candidateHarness))));
+                }
                 process.exit(1);
             }
             agent = harnessPick.picked.agent;
@@ -1653,7 +1668,7 @@ export function registerRunCommand(program) {
             // so Chinese models (Kimi, DeepSeek, Qwen, GLM) can run inside
             // Claude Code without a local proxy.
             try {
-                const resolved = resolveProfileForRun(rawAgent);
+                const resolved = resolveProfileForRun(rawAgent, options.model);
                 agent = resolved.agent;
                 if (!version)
                     version = resolved.version;
@@ -1661,6 +1676,22 @@ export function registerRunCommand(program) {
                 profileFallbackModel = resolved.fallbackModel;
                 fromProfile = true;
                 process.stderr.write(chalk.gray(`Resolved profile '${resolved.profileName}' -> ${agent}${version ? `@${version}` : ''}\n`));
+                if (resolved.tierNote) {
+                    process.stderr.write(chalk.gray(`[agents] ${resolved.tierNote}\n`));
+                }
+                // A tier token (cheap/default/best/ultra) already resolved against
+                // this PROFILE's own `models:` map above, when the profile opts in.
+                // Replace the raw --model value here so the tier never reaches the
+                // native, HOST-catalog tier block below. When the profile has no
+                // `models:` opt-in at all, resolvedModel stays undefined and
+                // options.model is left as the raw tier token on purpose — the
+                // "cost tiers don't apply to profile ..." discard guard further
+                // down this function is the canonical fallback for that case, and
+                // this block must not race it with a second, differently-worded
+                // message.
+                if (resolved.resolvedModel !== undefined) {
+                    options.model = resolved.resolvedModel;
+                }
             }
             catch (err) {
                 console.error(chalk.red(err.message));

package/dist/commands/feed.d.ts

@@ -13,7 +13,7 @@
  * `agents feed post`: agent-callable free-text progress into the activity
  * stream (milestone `status.posted`). Session/agent/host/runtime/pid identity
  * is auto-stamped from env + the pid registry — no domain-specific flags.
- * Humans watch via the feed activity lane / `agents activity`.
+ * Humans watch via the feed activity lane.
  */
 import type { Command } from 'commander';
 import { type OpenBlock } from '../lib/feed.js';
@@ -47,6 +47,7 @@ export declare function formatOutcomeHeader(group: OutcomeGroup): string;
 export declare function sessionHintsFromActive(sessions: Array<{
     sessionId?: string;
     agentId?: string;
+    cwd?: string;
     ticket?: {
         id?: string;
     };

package/dist/commands/feed.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified, buildDeclaredBlock, publishBlock, } from '../lib/feed.js';
 import { ensureActivityLogHook, readRecentActivity, formatActivityLine, formatProgressUpdate, mergeActivityEvents, parseActivityPayload, } from '../lib/activity.js';
+import { projectKeyFromCwd } from '../lib/project-key.js';
 import { postFeedStatus } from '../lib/feed-post.js';
 import { parseFeedPostLevel, planFeedBroadcast, runFeedBroadcast, effectiveBroadcastConfig, blockBroadcastContext, blockDeliveryFailure, } from '../lib/feed-broadcast.js';
 import { getSessionById } from '../lib/session/db.js';
@@ -215,6 +216,7 @@ export function sessionHintsFromActive(sessions) {
         prNumber: s.pr?.number,
         prUrl: s.pr?.url,
         worktreeSlug: s.worktree?.slug,
+        project: s.cwd ? projectKeyFromCwd(s.cwd) : undefined,
     }));
 }
 export function registerFeedCommand(program) {
@@ -228,6 +230,7 @@ export function registerFeedCommand(program) {
         .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('--project <name>', 'Scope the feed to one project/repo (matches cwd basename, case-insensitive)')
         .option('--dispatch', 'Run stall suppression + default-on-no-answer policy and urgent notifications')
         .option('--pause <id>', 'Pause a runaway/needy local process (SIGSTOP) or cancel a cloud task')
         .option('--kill <id>', 'Kill a runaway/needy local process (SIGTERM) or cancel a cloud task');
@@ -317,7 +320,13 @@ docs/06-observability.md.
             // it the ask would scroll away like any other update.
             let outcomes;
             if (flags.blocked) {
-                const block = buildDeclaredBlock(event, {
+                const block = buildDeclaredBlock({
+                    sessionId: event.sessionId,
+                    mailboxId: event.mailboxId,
+                    host: event.host,
+                    runtime: event.runtime,
+                    cwd: event.cwd,
+                }, {
                     // Prefer title as the front-loaded ask on the phone; body is detail.
                     text: event.title
                         ? (event.detail ? `${event.title}: ${event.detail}` : event.title)
@@ -399,12 +408,12 @@ docs/06-observability.md.
             if (filter === 'all') {
                 console.log();
                 renderUpdatesView(await gatherStatusPosts({
-                    limit: UPDATES_VIEW_LIMIT, hosts: opts.host, local: opts.local, includeLocal, self,
-                }));
+                    limit: UPDATES_VIEW_LIMIT, hosts: opts.host, local: opts.local, includeLocal, self, project: opts.project,
+                }), opts.project);
                 return;
             }
             if (includeLocal)
-                renderActivityLane();
+                renderActivityLane(opts.project);
         };
         // Updates view: deliberate progress posts only (blocks are decisions, not
         // announcements). Short-circuits the block pipeline — no dispatch policy —
@@ -425,7 +434,7 @@ docs/06-observability.md.
                 console.log(JSON.stringify(updates, null, 2));
                 return;
             }
-            renderUpdatesView(updates);
+            renderUpdatesView(updates, opts.project);
             return;
         }
         // Active sessions feed both the GC sweep and outcome enrichment (ticket/PR).
@@ -487,7 +496,10 @@ docs/06-observability.md.
                 blocks = mergeFeedBlocks(visibleLocalBlocks, remote.items);
             }
         }
-        blocks = rankFeedBlocks(blocks, localSignals);
+        blocks = rankFeedBlocks(blocks, localSignals).filter((b) => blockMatchesProject(b, opts.project));
+        const dispatchBlocksProject = opts.project
+            ? dispatchBlocks.filter((b) => blockMatchesProject(b, opts.project))
+            : dispatchBlocks;
         const digest = suppressionDigest(preparedLocal.filter);
         if (digest && !opts.json) {
             console.log(chalk.dim(digest));
@@ -495,7 +507,7 @@ docs/06-observability.md.
         if (opts.dispatch) {
             const policy = loadPolicy();
             const now = new Date();
-            for (const b of dispatchBlocks) {
+            for (const b of dispatchBlocksProject) {
                 // Wrap per-block policy so one malformed block (e.g. a crafted
                 // mailboxId that throws in mailboxDir) can't abort the whole loop and
                 // strand every remaining block's dispatch.
@@ -540,7 +552,7 @@ docs/06-observability.md.
         }
         // Shared fleet-comms masthead (same family as `agents mailboxes`).
         console.log(masthead({
-            title: 'they need you',
+            title: opts.project ? `${opts.project} needs you` : 'they need you',
             accent: 'amber',
             host: self,
             right: formatFeedMastheadRight(blocks),
@@ -630,6 +642,18 @@ export function resolveFeedFilter(raw) {
         return 'all';
     return 'needs';
 }
+/** True when a block belongs to the requested project (case-insensitive). */
+function blockMatchesProject(block, project) {
+    if (!project)
+        return true;
+    return (block.project ?? '').toLowerCase() === project.toLowerCase();
+}
+/** True when an activity event belongs to the requested project (case-insensitive). */
+function eventMatchesProject(ev, project) {
+    if (!project)
+        return true;
+    return ((ev.project ?? projectKeyFromCwd(ev.cwd) ?? '')).toLowerCase() === project.toLowerCase();
+}
 /**
  * Render one activity event in the lane: deliberate progress posts
  * (`status.posted`) use the rich multi-line {@link formatProgressUpdate}; hook
@@ -668,30 +692,33 @@ function readStatusPosts(limit) {
  * uses; `--local` (or the no-fanout env guard on a peer) keeps it to this box.
  */
 async function gatherStatusPosts(opts) {
-    const local = opts.includeLocal ? readStatusPosts(opts.limit) : [];
+    const local = opts.includeLocal
+        ? readStatusPosts(opts.limit).filter((ev) => eventMatchesProject(ev, opts.project))
+        : [];
     const forceLocal = opts.local === true || process.env[FEED_NO_FANOUT_ENV] === '1';
     if (forceLocal)
-        return local;
+        return local.slice(0, opts.limit);
     const remoteHosts = opts.hosts?.length ? remoteFeedHostsToDial(opts.hosts, opts.self) : undefined;
     if (opts.hosts?.length && (!remoteHosts || remoteHosts.length === 0))
-        return local;
+        return local.slice(0, opts.limit);
     const remote = await gatherRemoteAgentsJson({
         args: ['feed', '--filter', 'updates', '--json'],
         noFanoutEnv: FEED_NO_FANOUT_ENV,
         hosts: remoteHosts,
         parse: parseActivityPayload,
     });
-    return mergeActivityEvents(local, remote.items).slice(0, opts.limit);
+    const merged = mergeActivityEvents(local, remote.items).filter((ev) => eventMatchesProject(ev, opts.project));
+    return merged.slice(0, opts.limit);
 }
 /**
  * Render the **Updates** view: deliberate progress posts only (`status.posted`),
  * recency-ordered, with rich identity chips. Pure `file.edited` / git-hook noise
  * is excluded so operators see announcements, not tool churn.
  */
-function renderUpdatesView(updates) {
+function renderUpdatesView(updates, project) {
     const hosts = new Set(updates.map((e) => e.host).filter(Boolean));
     console.log(masthead({
-        title: 'updates',
+        title: project ? `${project} updates` : 'updates',
         accent: 'cyan',
         host: hosts.size > 1 ? `${hosts.size} machines` : (updates[0]?.host ?? machineId()),
         right: `${updates.length} post${updates.length === 1 ? '' : 's'}`,
@@ -712,16 +739,16 @@ function renderUpdatesView(updates) {
  * activity logs. Read-only tail of the logs -- no transcript re-parsing. Silent
  * when empty.
  */
-function renderActivityLane(limit = 6) {
+function renderActivityLane(project, limit = 6) {
     const events = readRecentActivity({
         sinceMs: Date.now() - 24 * 60 * 60 * 1000,
-        limit,
+        limit: limit * (project ? 4 : 1),
         tier: 'milestone',
-    });
+    }).filter((ev) => eventMatchesProject(ev, project));
     if (events.length === 0)
         return;
-    console.log(chalk.bold('\n  recent activity'));
-    for (const ev of events)
+    console.log(chalk.bold(project ? `\n  recent activity · ${project}` : '\n  recent activity'));
+    for (const ev of events.slice(0, limit))
         renderActivityEntry(ev);
-    console.log(chalk.gray('  → agents activity  for the full stream'));
+    console.log(chalk.gray('  → agents feed --project ' + (project ?? '<project>') + '  for the full stream'));
 }

package/dist/commands/focus.js

@@ -20,8 +20,9 @@ import { runOnPeer } from '../lib/session/remote-list.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { openSurfaces, currentContext, availableBackends, detectCurrentBackend, } from '../lib/terminal/index.js';
 import { isInteractiveTerminal } from './utils.js';
+import { setHelpSections } from '../lib/help.js';
 export function registerFocusCommand(program) {
-    program
+    const cmd = program
         .command('focus')
         .argument('[id]', 'Short/full session id to focus; omit for an interactive picker')
         .option('--local', 'Only this machine (skip the cross-host sweep)')
@@ -30,6 +31,26 @@ export function registerFocusCommand(program) {
         .action(async (id, opts) => {
         await focusAction(id, opts);
     });
+    setHelpSections(cmd, {
+        examples: `
+      # Jump to a live session (attach pane/tab, or open a new tab and resume)
+      agents sessions focus a1b2c3d4
+
+      # Attach only — refuse if nothing is joinable (old sessions go)
+      agents sessions focus a1b2c3d4 --attach-only
+
+      # Pick from live sessions on this machine only
+      agents sessions focus --local
+    `,
+        notes: `
+      Lifecycle siblings (not synonyms):
+        focus              live jump (default "take me there")
+        focus --attach-only  attach only; never fork (replaces go)
+        detach / attach    interactive ↔ headless presence
+        resume             multi-select history → tabs
+        run --resume       single scripted continue
+    `,
+    });
 }
 /**
  * Which fallback fires when a session has no attach rail. `--attach-only` (the old

package/dist/commands/models.js

@@ -16,13 +16,13 @@ import { setTierOverride, clearTierOverride, listTierOverrides } from '../lib/mo
 import { getModelPricing } from '../lib/pricing/index.js';
 import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
 import { wrapJoined } from './inspect.js';
-const MODEL_CAPABLE_AGENTS = ['claude', 'codex', 'opencode', 'cursor', 'openclaw', 'antigravity', 'kimi', 'grok', 'droid'];
+const MODEL_CAPABLE_AGENTS = ['claude', 'codex', 'opencode', 'cursor', 'openclaw', 'antigravity', 'kimi', 'grok', 'droid', 'pi'];
 /**
  * Agents that don't necessarily install under ~/.agents/versions (cursor ships
  * via a curl script). For these, fall back to the PATH binary and synthesize
  * a version label from the install path so cache keys stay stable.
  */
-const PATH_ONLY_AGENTS = new Set(['cursor']);
+const PATH_ONLY_AGENTS = new Set(['cursor', 'pi']);
 /** Derive a version label from the PATH-installed binary location for agents without managed versions. */
 function fallbackPathVersion(agent) {
     const src = locateModelSource(agent, 'unresolved');