@phnx-labs/agents-cli 1.22.56 → 1.22.57

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.22.57
+
+- **Removed two duplicate commands: `agents list` and `agents trash restore` (PHNX-3391).** `agents list` was a long-deprecated full duplicate of `agents view` (it already printed "agents list is now agents view" before delegating) — `agents view` is now the one version-listing surface. `agents trash restore <target>` was an exact duplicate of the top-level `agents restore <target>` (both call `restoreVersion`); `agents restore` stays, and `agents trash` keeps `trash list`. Both removed names now error as retired top-level commands rather than auto-correcting. Source: `cli/src/commands/versions.ts`, `cli/src/commands/trash.ts`.
+
+- **`agents perf` moved to `agents insights perf` (PHNX-3391).** Performance metrics are an insight, not a top-level noun — latency now sits beside `agents insights cost` / `output` under the one `insights` group. Every subcommand is unchanged (`agents insights perf [hooks|commands|run|friction]`), the disposable warehouse at `~/.agents/.cache/perf/perf.db` is untouched, and bare `agents perf` now errors (retired top-level name) rather than auto-correcting. Source: `cli/src/commands/perf.ts`, `cli/src/commands/insights.ts`, `cli/src/cli/command-registry.ts`.
+
+- **`agents insights mix` is now the one counter surface — the eight per-recipe shortcut commands, `recipes`, and `trends` are gone (PHNX-3391).** `agents insights mix` already printed the whole recipe board, yet each section was *also* a standalone command (`agents insights harness-mix`, `model-mix`, …), *also* reachable as `mix <recipe>`, *also* listed by `agents insights recipes`, and the board was *also* aliased by `agents insights trends` — one query engine wearing five surfaces (each registered twice, under `insights` and `sessions insights`). It collapses to one: `agents insights mix` (board), `agents insights mix <recipe>` (one section, e.g. `mix harness-mix`), and `agents insights mix --list` (the recipe ids). The removed spellings now error and point at `mix`. This is surface removal, not hiding — 20 command registrations deleted. Source: `cli/src/lib/analytics/mix-commands.ts`.
+
+- **Worker boxes now show real Claude usage (S:/W:) bars in `agents view` (PHNX-3392).** A rate limit is metered per account, so the number is identical on every box — but only a headed device (`personal`/`desktop`) can read it, because the usage endpoint needs the `user:profile` scope only the interactive login carries. Headless workers, which have just the `user:inference` setup-token, got a 403 and showed blank bars. A new `usage-sync` daemon service closes the gap: each personal/desktop daemon pushes its per-account usage snapshot to worker peers, which merge it newest-wins (via the hidden `agents __usage-ingest` verb). Role-gated (personal/desktop publish, workers consume), single-executor per destination, and idempotent. A synced bar reads as last-seen, never a live fetch. Source: `cli/src/lib/accounting/usage-sync.ts`, `cli/src/lib/daemon/usage-sync-service.ts`.
+
+- **`agents devices` gains a `desktop` role and stops double-labeling your interactive box (PHNX-3392).** `agents devices role <name>` now accepts a third value — `desktop` — for a headed always-on box (the release/credential home, e.g. a Mac mini): it is excluded from `--device auto` like `personal` (agents never auto-land there), but authenticates from its own interactive login like `personal` rather than a worker setup-token. And `agents devices list` no longer prints both `★ interactive` and `personal` on the same row — a `personal` box IS your interactive seat, so the star is folded into the role (it still shows for a non-personal box pinned as `interactive.host`). Source: `cli/src/lib/device-config.ts`, `cli/src/commands/ssh.ts`.
+
+- **The system DotAgents repo `phnx-labs/.agents-system` was renamed to `phnx-labs/.agents` on GitHub, and both names are now recognized as the system origin (PHNX-3394).** The `-system` suffix was redundant once the layering itself is the role. The clone target stays `gh:phnx-labs/.agents-system` (GitHub's rename redirect makes that resolve fine, so there is no forced cutover), but a checkout under either name is recognized as the system origin across all transport forms (ssh / https / scp-style), via a `RENAMED_REMOTE_ALIASES` fold in `canonicalGitRemote` and the pure `isSystemRepoRemote` behind `isSystemRepoOrigin`. The companion extras repo `phnx-labs/.agents-extras` keeps its name but is now private and opt-in (`agents repo add`, not cloned by default). Source: `cli/src/lib/git.ts`.
+
 ## 1.22.56
 
 - **Scheduled routines claim a durable per-occurrence slot, so a duplicate delivery or a catch-up of the same slot can't double-launch (PHNX-3215).** The forward-timer path keyed its single-fire claim on croner's `currentRun()`, which is the jittered wall-clock fire instant, not the aligned schedule boundary — so two timer callbacks for one occurrence minted different run ids and both launched, and a live fire never collided with its catch-up twin. The scheduler now floors the fire to the aligned `(routine, scheduledFor)` boundary (`fireSlot`/`alignedSlotForFire`), the same derivation catch-up uses, making the atomic slot claim a structural guarantee (SING-15/16, self-overlap SING-13). Source: `cli/src/lib/scheduler.ts`, `cli/src/lib/scheduling/routines.ts`, `cli/src/lib/overdue.ts`.

package/README.md

@@ -11,7 +11,7 @@
   <a href="https://github.com/phnx-labs/agi-cli"><img src="https://img.shields.io/badge/github-phnx--labs%2Fagi--cli-blue?style=flat-square" alt="github" /></a>
 </p>
 
-**A framework for running a distributed agent factory.** Dispatch Claude, Codex, Antigravity, Grok, and more across your own machines, in parallel, on your existing subscriptions. Measure every run with `agents perf` / `agents insights`, fold what you learn back into `AGENTS.md` and skills, then put the loop on a schedule with routines and monitors. Spawn parallel teams in isolated terminals or dispatch to the cloud for a PR. Watch live state across the fleet, nudge stalled runs, and message agents mid-flight. Store secrets behind Touch ID, drive real browsers and Electron apps, and steer the whole fleet from a menu bar — all from one CLI.
+**A framework for running a distributed agent factory.** Dispatch Claude, Codex, Antigravity, Grok, and more across your own machines, in parallel, on your existing subscriptions. Measure every run with `agents insights` (latency lives at `agents insights perf`), fold what you learn back into `AGENTS.md` and skills, then put the loop on a schedule with routines and monitors. Spawn parallel teams in isolated terminals or dispatch to the cloud for a PR. Watch live state across the fleet, nudge stalled runs, and message agents mid-flight. Store secrets behind Touch ID, drive real browsers and Electron apps, and steer the whole fleet from a menu bar — all from one CLI.
 
 <p align="center">
   <a href="https://github.com/anthropics/claude-code" title="Claude Code"><img src="assets/harnesses/anthropic.svg" height="32" alt="Claude Code" /></a>
@@ -110,7 +110,7 @@ agents teams add checkout codex  "Write tests for the new code" --name qa --afte
 agents teams start checkout --watch
 
 # Measure what happened -- latency, friction, dead-weight skills
-agents perf commands --days 7      # slowest CLI entrypoints
+agents insights perf commands --days 7   # slowest CLI entrypoints
 agents insights --since 30d        # friction, harness comparison, ranked actions
 
 # Fold the lesson back into the harness -- every agent picks it up next run
@@ -125,7 +125,7 @@ agents routines add nightly-payments-audit \
 agents menubar setup
 ```
 
-`agents perf` reads a disposable warehouse at `~/.agents/.cache/perf/perf.db` -- hook, command, and run timing rollups, deletable any time. `agents insights` (alias `agents sessions insights`) is deterministic and offline: it caches per-session facets, compares harnesses, and ranks actions by evidence count -- no model call unless you pass `--narrative`. Routines put any of this on a cron ([Routines](#routines)); monitors fire it on a change instead of a clock ([Monitors](#monitors)); the menu bar is the always-on control surface for the fleet these commands drive ([Menu bar](#menu-bar)).
+`agents insights perf` reads a disposable warehouse at `~/.agents/.cache/perf/perf.db` -- hook, command, and run timing rollups, deletable any time. `agents insights` (alias `agents sessions insights`) is deterministic and offline: it caches per-session facets, compares harnesses, and ranks actions by evidence count -- no model call unless you pass `--narrative`. Routines put any of this on a cron ([Routines](#routines)); monitors fire it on a change instead of a clock ([Monitors](#monitors)); the menu bar is the always-on control surface for the fleet these commands drive ([Menu bar](#menu-bar)).
 
 ---
 
@@ -1407,7 +1407,7 @@ Two repos with the same shape, different roles:
 
 | Repo | Role | Owner |
 |---|---|---|
-| `~/.agents-system/` | **System repo** — core/built-in skills, commands, hooks, rules, MCP configs, permissions, and profiles that ship with `agi-cli`. The defaults every install gets. | Maintained upstream at [phnx-labs/.agents-system](https://github.com/phnx-labs/.agents-system) |
+| `~/.agents-system/` | **System repo** — core/built-in skills, commands, hooks, rules, MCP configs, permissions, and profiles that ship with `agi-cli`. The defaults every install gets. | Maintained upstream at [phnx-labs/.agents](https://github.com/phnx-labs/.agents) (formerly `.agents-system`) |
 | `~/.agents/` | **User repo** — your personal additions and overrides. This is what `agents repo push`/`pull` syncs. | You |
 
 **Version pinning:** `agents.yaml` at project root pins which agent version to use (like `.nvmrc` for Node).

package/dist/bootstrap.js

@@ -156,7 +156,9 @@ program.hook('postAction', (_thisCommand, actionCommand) => {
             }).catch(() => { });
         }
         // Disposable perf warehouse — fail-soft spool append (no SQLite on this path).
-        if (durationMs !== undefined && parts[0] !== 'perf') {
+        // Skip the perf reader itself (now `agents insights perf`, PHNX-3391) so it
+        // never records its own latency into the board it prints.
+        if (durationMs !== undefined && !(parts[0] === 'insights' && parts[1] === 'perf')) {
             // sessionId/agent are resolvable here the same way emit() resolves them
             // for command.start/command.end above (the shared provenance floor,
             // event-provenance.ts) — without this, every command.end perf sample

package/dist/cli/command-registry.d.ts

@@ -65,7 +65,6 @@ export declare const loadRefreshRules: ModuleLoader;
 export declare const loadFactory: ModuleLoader;
 export declare const loadInsights: ModuleLoader;
 export declare const loadTrace: ModuleLoader;
-export declare const loadPerf: ModuleLoader;
 export declare const loadPty: ModuleLoader;
 export declare const loadTmux: ModuleLoader;
 export declare const loadWatchdog: ModuleLoader;

package/dist/cli/command-registry.js

@@ -67,7 +67,6 @@ export const loadRefreshRules = async () => (await import('../commands/refresh-r
 export const loadFactory = async () => (await import('../commands/factory.js')).registerFactoryCommands;
 export const loadInsights = async () => (await import('../commands/insights.js')).registerInsightsCommand;
 export const loadTrace = async () => (await import('../commands/sessions-trace.js')).registerTraceCommand;
-export const loadPerf = async () => (await import('../commands/perf.js')).registerPerfCommand;
 export const loadPty = async () => (await import('../commands/pty.js')).registerPtyCommands;
 export const loadTmux = async () => (await import('../commands/tmux.js')).registerTmuxCommands;
 export const loadWatchdog = async () => (await import('../commands/watchdog.js')).registerWatchdogCommand;
@@ -142,7 +141,6 @@ export const COMMAND_LOADERS = {
     workflows: [loadWorkflows],
     add: [loadVersions],
     use: [loadVersions],
-    list: [loadVersions],
     remove: [loadVersions],
     rm: [loadVersions],
     purge: [loadVersions],
@@ -177,7 +175,6 @@ export const COMMAND_LOADERS = {
     // `agents trace` is a top-level alias of `agents sessions trace` (precedent:
     // `agents insights` aliases `agents sessions insights`). One implementation.
     trace: [loadTrace],
-    perf: [loadPerf],
     pty: [loadPty],
     tmux: [loadTmux],
     watchdog: [loadWatchdog],

package/dist/commands/exec.js

@@ -431,7 +431,7 @@ async function handleTerminalHandoff(agentSpec, options, prompt) {
     if (!knownAgent) {
         const probeCwd = options.cwd ?? process.cwd();
         if (!hasProfile && !resolveWorkflowRef(rawTarget, probeCwd)) {
-            console.error(chalk.red(`Unknown agent, profile, or workflow: ${rawTarget}. See \`agents list\` for the installed harnesses.`));
+            console.error(chalk.red(`Unknown agent, profile, or workflow: ${rawTarget}. See \`agents view\` for the installed harnesses.`));
             process.exit(1);
         }
     }

package/dist/commands/hooks.js

@@ -594,22 +594,22 @@ Examples:
         .addHelpText('after', `
 Shows aggregated stats for every hook that fired through a generated shim.
 Primary source: disposable SQLite warehouse ~/.agents/.cache/perf/perf.db
-(same data as \`agents perf hooks\`). Falls back to the legacy daily JSONL under
+(same data as \`agents insights perf hooks\`). Falls back to the legacy daily JSONL under
 ~/.agents/.cache/logs/ when the warehouse is empty.
 
 Examples:
   agents hooks profile                # last 7 days, table form
   agents hooks profile --days 30      # roll up the full month
   agents hooks profile --json | jq    # pipe somewhere
-  agents perf hooks                   # same rollup under the perf surface
+  agents insights perf hooks                   # same rollup under the perf surface
 
 A hook whose p99 exceeds --warn-ms gets flagged in the cache column. Add
 'cache: 5m' or 'cache: 5m-bg' to its hooks.yaml entry to fix it.
 `)
-        .option('--project <key>', 'Scope to one project (see agents perf --help)')
+        .option('--project <key>', 'Scope to one project (see agents insights perf --help)')
         .action(async (options) => {
         const { DEFAULT_SLOW_HOOK_WARN_MS } = await import('../lib/hooks/profile.js');
-        // Same rollup as `agents perf hooks` — this command predates the `perf`
+        // Same rollup as `agents insights perf hooks` — this command predates the `perf`
         // surface and is kept as a documented alias; delegate instead of
         // duplicating the SQLite-vs-legacy-JSONL fallback and table rendering.
         const { loadHookProfile, renderHookTable } = await import('./perf.js');

package/dist/commands/insights.d.ts

@@ -7,20 +7,21 @@
  *                                rhythm, edits) — split by Claude account by default
  *   agents insights mix          COUNTERS (sessions index + usage.db recipes:
  *                                harness/model mix, token ratios, secrets, browser)
- *   agents insights <recipe>     One baked mix recipe (harness-mix, tools-per-session, …)
+ *   agents insights mix <recipe> One baked mix recipe (harness-mix, tools-per-session, …)
  *   agents insights query        Raw usage.db rows
  *
- * Sibling observe verbs (stay separate — different questions):
+ * Sibling observe verbs under this same group (different questions):
  *
  *   agents insights cost    what you spent ($ and duration)
  *   agents insights output  what shipped (burn vs PRs and commits)
+ *   agents insights perf    latency (hooks, CLI commands, agent.run) — not popularity
  *   agents view             live quota headroom (per account, with auth state)
- *   agents perf             latency (hooks, CLI commands, agent.run) — not popularity
  *   agents sessions stats   which skills/slash-commands were explicitly invoked
  *
  * Why mix lives here (not a second top-level `trends`): two abstract "analytics"
  * nouns taught agents and humans to guess. One verb, two engines — cheap SQL mix
- * vs transcript facets. Latency stays on `perf` so it is never confused with mix.
+ * vs transcript facets. `perf` (latency) is also nested here now (PHNX-3391) —
+ * performance is an insight, kept a distinct sub-verb so it is never confused with mix.
  *
  * Modelled on Claude Code's `/insights`, with the difference that motivated it: that
  * command reads one account's directory, while `balanced` rotation sprays sessions
@@ -31,7 +32,8 @@
  * the coaching prose by piping the AGGREGATE (never raw transcripts) through a headless
  * `claude -p`.
  *
- * Former top-level `agents trends` is `agents insights mix` / `agents insights trends`.
+ * Former top-level `agents trends` is `agents insights mix` (one section:
+ * `agents insights mix <recipe>`; `--list` names them).
  */
 import type { Command } from 'commander';
 export declare function registerInsightsCommand(program: Command): void;

package/dist/commands/insights.js

@@ -7,20 +7,21 @@
  *                                rhythm, edits) — split by Claude account by default
  *   agents insights mix          COUNTERS (sessions index + usage.db recipes:
  *                                harness/model mix, token ratios, secrets, browser)
- *   agents insights <recipe>     One baked mix recipe (harness-mix, tools-per-session, …)
+ *   agents insights mix <recipe> One baked mix recipe (harness-mix, tools-per-session, …)
  *   agents insights query        Raw usage.db rows
  *
- * Sibling observe verbs (stay separate — different questions):
+ * Sibling observe verbs under this same group (different questions):
  *
  *   agents insights cost    what you spent ($ and duration)
  *   agents insights output  what shipped (burn vs PRs and commits)
+ *   agents insights perf    latency (hooks, CLI commands, agent.run) — not popularity
  *   agents view             live quota headroom (per account, with auth state)
- *   agents perf             latency (hooks, CLI commands, agent.run) — not popularity
  *   agents sessions stats   which skills/slash-commands were explicitly invoked
  *
  * Why mix lives here (not a second top-level `trends`): two abstract "analytics"
  * nouns taught agents and humans to guess. One verb, two engines — cheap SQL mix
- * vs transcript facets. Latency stays on `perf` so it is never confused with mix.
+ * vs transcript facets. `perf` (latency) is also nested here now (PHNX-3391) —
+ * performance is an insight, kept a distinct sub-verb so it is never confused with mix.
  *
  * Modelled on Claude Code's `/insights`, with the difference that motivated it: that
  * command reads one account's directory, while `balanced` rotation sprays sessions
@@ -31,7 +32,8 @@
  * the coaching prose by piping the AGGREGATE (never raw transcripts) through a headless
  * `claude -p`.
  *
- * Former top-level `agents trends` is `agents insights mix` / `agents insights trends`.
+ * Former top-level `agents trends` is `agents insights mix` (one section:
+ * `agents insights mix <recipe>`; `--list` names them).
  */
 import * as fs from 'fs';
 import chalk from 'chalk';
@@ -47,6 +49,7 @@ import { formatUsd } from '../lib/pricing/index.js';
 import { formatDuration } from '../lib/session/render.js';
 import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
 import { registerMixCommands } from '../lib/analytics/mix-commands.js';
+import { registerPerfSubcommand } from './perf.js';
 import { registerCostCommand } from './cost.js';
 import { registerOutputCommand } from './output.js';
 const execFileAsync = promisify(execFile);
@@ -570,7 +573,7 @@ function configureInsightsCommand(cmd) {
       # Counter mix board (harness/model/token/secrets recipes) — former agents trends
       agents insights mix
       agents insights mix --days 30
-      agents insights harness-mix --json
+      agents insights mix harness-mix --json
       agents insights query --kind secret --days 7
 
       # One account only, all of its history
@@ -586,10 +589,10 @@ function configureInsightsCommand(cmd) {
       Two paths under one verb:
         bare \`agents insights\`     — transcript behaviour (tools, friction, rhythm, by account)
         \`agents insights mix\`      — cheap counters from sessions.db + usage.db
-      Latency is \`agents perf\` (not mix). Quota is \`agents view\`. Spend is
+      Latency is \`agents insights perf\` (not mix). Quota is \`agents view\`. Spend is
       \`agents insights cost\`; shipped output is \`agents insights output\`. Skill/slash popularity
-      is \`agents sessions stats\`. Former top-level \`agents trends\` is \`agents insights mix\`
-      (also \`agents insights trends\`).
+      is \`agents sessions stats\`. Former top-level \`agents trends\` is \`agents insights mix\`.
+      One recipe is \`agents insights mix <recipe>\` (e.g. \`harness-mix\`); \`--list\` names them.
 
       The behavioural report parses in-scope transcripts once and caches facets; later runs
       re-read only files that changed. \`--refresh\` forces a full re-read.
@@ -606,6 +609,10 @@ export function registerInsightsCommand(program) {
     configureInsightsCommand(cmd);
     registerCostCommand(cmd);
     registerOutputCommand(cmd);
+    // Latency rollups (former top-level `agents perf` → `agents insights perf`,
+    // PHNX-3391). A sibling observe verb of cost/output, so it lives on the
+    // top-level insights group beside them, not under `sessions insights`.
+    registerPerfSubcommand(cmd);
 }
 export function registerSessionsInsightsCommand(sessions) {
     configureInsightsCommand(sessions.command('insights'));

package/dist/commands/perf.d.ts

@@ -1,12 +1,13 @@
 /**
- * `agents perf` — latency rollups over the disposable perf SQLite warehouse.
+ * `agents insights perf` — latency rollups over the disposable perf SQLite
+ * warehouse (former top-level `agents perf`, moved under insights in PHNX-3391).
  *
  * Subcommands:
- *   agents perf              multi-section summary (commands + hooks + runs)
- *   agents perf hooks        per-hook p50/p99 + cache hit rates
- *   agents perf commands     slowest CLI command paths (from command.end)
- *   agents perf run          agent.run / perf.timing labels
- *   agents perf friction     sessions stuck repeatedly hitting the same guard
+ *   agents insights perf              multi-section summary (commands + hooks + runs)
+ *   agents insights perf hooks        per-hook p50/p99 + cache hit rates
+ *   agents insights perf commands     slowest CLI command paths (from command.end)
+ *   agents insights perf run          agent.run / perf.timing labels
+ *   agents insights perf friction     sessions stuck repeatedly hitting the same guard
  *
  * Soft-joins sessions.db via shared string keys (session_id, agent, machine) —
  * no foreign keys. Warehouse lives at ~/.agents/.cache/perf/perf.db (safe to wipe).
@@ -49,5 +50,13 @@ export declare function loadHookProfile(days: number, project?: string): HookPro
  * exit 2 — see lib/friction-heuristics.ts for the grouping.
  */
 export declare function frictionAction(opts: PerfGlobalOpts): void;
-export declare function registerPerfCommand(program: Command): void;
+/**
+ * Attach the `perf` latency-rollup command under a parent (the top-level
+ * `insights` group). Performance is an insight, not a top-level noun — `agents
+ * perf` was retired in favour of `agents insights perf` (PHNX-3391). It is a
+ * sibling of `agents insights cost` / `output`, registered in
+ * `registerInsightsCommand` beside them (top-level insights only, not
+ * `sessions insights`).
+ */
+export declare function registerPerfSubcommand(parent: Command): void;
 export {};

package/dist/commands/perf.js

@@ -1,12 +1,13 @@
 /**
- * `agents perf` — latency rollups over the disposable perf SQLite warehouse.
+ * `agents insights perf` — latency rollups over the disposable perf SQLite
+ * warehouse (former top-level `agents perf`, moved under insights in PHNX-3391).
  *
  * Subcommands:
- *   agents perf              multi-section summary (commands + hooks + runs)
- *   agents perf hooks        per-hook p50/p99 + cache hit rates
- *   agents perf commands     slowest CLI command paths (from command.end)
- *   agents perf run          agent.run / perf.timing labels
- *   agents perf friction     sessions stuck repeatedly hitting the same guard
+ *   agents insights perf              multi-section summary (commands + hooks + runs)
+ *   agents insights perf hooks        per-hook p50/p99 + cache hit rates
+ *   agents insights perf commands     slowest CLI command paths (from command.end)
+ *   agents insights perf run          agent.run / perf.timing labels
+ *   agents insights perf friction     sessions stuck repeatedly hitting the same guard
  *
  * Soft-joins sessions.db via shared string keys (session_id, agent, machine) —
  * no foreign keys. Warehouse lives at ~/.agents/.cache/perf/perf.db (safe to wipe).
@@ -190,7 +191,7 @@ export function frictionAction(opts) {
     // --cwd flag — so silently accepting the flag here would look like it
     // filtered when it did nothing. Fail loud instead of no-op.
     if (opts.project) {
-        console.error(chalk.red("agents perf friction does not support --project yet — friction events carry no cwd to filter on."));
+        console.error(chalk.red("agents insights perf friction does not support --project yet — friction events carry no cwd to filter on."));
         process.exitCode = 1;
         return;
     }
@@ -224,7 +225,7 @@ function summaryAction(opts) {
         }, null, 2));
         return;
     }
-    console.log(chalk.bold(`agents perf — last ${days} day${days === 1 ? '' : 's'}${project ? ` — project ${project}` : ''}`));
+    console.log(chalk.bold(`agents insights perf — last ${days} day${days === 1 ? '' : 's'}${project ? ` — project ${project}` : ''}`));
     console.log(chalk.gray(`warehouse: ${perfDbPath()}  (disposable; soft-join sessions via session_id/agent/machine)`));
     console.log('');
     console.log(chalk.bold('Commands (slowest by p99)'));
@@ -246,7 +247,7 @@ function attachSharedOptions(cmd) {
 }
 /**
  * Commander binds a flag declared on both parent and child to the *parent*.
- * Merge so `agents perf commands --json` still sees json:true on the leaf.
+ * Merge so `agents insights perf commands --json` still sees json:true on the leaf.
  */
 function leafOpts(cmd) {
     const parent = cmd.parent && typeof cmd.parent.opts === 'function'
@@ -254,8 +255,16 @@ function leafOpts(cmd) {
         : {};
     return { ...parent, ...cmd.opts() };
 }
-export function registerPerfCommand(program) {
-    const perf = program
+/**
+ * Attach the `perf` latency-rollup command under a parent (the top-level
+ * `insights` group). Performance is an insight, not a top-level noun — `agents
+ * perf` was retired in favour of `agents insights perf` (PHNX-3391). It is a
+ * sibling of `agents insights cost` / `output`, registered in
+ * `registerInsightsCommand` beside them (top-level insights only, not
+ * `sessions insights`).
+ */
+export function registerPerfSubcommand(parent) {
+    const perf = parent
         .command('perf')
         .description('Latency rollups from the disposable perf warehouse (hooks, commands, runs)')
         .addHelpText('after', `
@@ -264,16 +273,16 @@ Identity columns reuse sessions/events string shapes (session_id, agent, machine
 for soft cross-reference; there are no foreign keys.
 
 Examples:
-  agents perf                        # summary: commands + hooks + runs
-  agents perf hooks                  # per-hook p50/p95/p99 + cache hit rate
-  agents perf commands --days 30     # slowest CLI entrypoints
-  agents perf run --json             # agent.run timings as JSON
-  agents perf hooks --warn-ms 500
-  agents perf hooks --project agents-cli  # scope to one repo's samples
-  agents perf friction               # sessions stuck retrying the same guard block
+  agents insights perf                        # summary: commands + hooks + runs
+  agents insights perf hooks                  # per-hook p50/p95/p99 + cache hit rate
+  agents insights perf commands --days 30     # slowest CLI entrypoints
+  agents insights perf run --json             # agent.run timings as JSON
+  agents insights perf hooks --warn-ms 500
+  agents insights perf hooks --project agents-cli  # scope to one repo's samples
+  agents insights perf friction               # sessions stuck retrying the same guard block
 `);
-    // Options live on the parent so `agents perf --json` and
-    // `agents perf commands --json` both work (see leafOpts).
+    // Options live on the parent so `agents insights perf --json` and
+    // `agents insights perf commands --json` both work (see leafOpts).
     attachSharedOptions(perf).action(function summary() {
         summaryAction(this.opts());
     });

package/dist/commands/rules.js

@@ -538,7 +538,7 @@ Examples:
             }
             const version = resolveVersionAlias(agentId, rawVersion);
             if (!version) {
-                console.log(chalk.red(`Pass a version: ${agentId}@<version>. Try 'default' or 'agents list ${agentId}'.`));
+                console.log(chalk.red(`Pass a version: ${agentId}@<version>. Try 'default' or 'agents view ${agentId}'.`));
                 process.exit(1);
             }
             const installed = listInstalledVersions(agentId);

package/dist/commands/ssh.js

@@ -79,10 +79,14 @@ function deviceSummary(d, isSelf = false, stats, isInteractive = false, roles) {
     const marker = isSelf ? chalk.cyan('▸ ') : '  ';
     const name = isSelf ? chalk.bold.cyan(d.name.padEnd(16)) : chalk.bold(d.name.padEnd(16));
     const here = isSelf ? chalk.cyan('  ← this machine') : '';
-    const interactive = isInteractive ? chalk.yellow('  ★ interactive') : '';
     // `roles` defaults to a single-device roster so a fleet-wide `role` default
     // still reaches this device even when it has no per-device doc of its own.
-    const role = roleTag(d.name, roles ?? listConfiguredDeviceRoles([d.name]));
+    const roleMap = roles ?? listConfiguredDeviceRoles([d.name]);
+    // `personal` already means "the interactive box you sit at", so the star would
+    // just repeat it — show it only when the interactive host is NOT a personal box
+    // (e.g. an unmarked or worker box deliberately pinned as the artifact target).
+    const interactive = isInteractive && roleMap[d.name] !== 'personal' ? chalk.yellow('  ★ interactive') : '';
+    const role = roleTag(d.name, roleMap);
     return `${marker}${name} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}${here}${interactive}${role}`;
 }
 /** The fleet-wide role mark, rendered for a device row. Empty when unmarked —
@@ -95,7 +99,9 @@ function roleTag(name, roles) {
         return chalk.green('  worker');
     if (role === 'personal')
         return chalk.yellow('  personal');
-    return chalk.gray('  control');
+    if (role === 'desktop')
+        return chalk.cyan('  desktop');
+    return '';
 }
 const HEADROOM_BADGE = {
     idle: chalk.green('○ idle'),
@@ -257,7 +263,9 @@ export function renderDeviceTable(reg, names, self, statsMap, full = false, inte
             : '';
         const badge = HEADROOM_BADGE[headroom(stats)];
         const here = isSelf ? chalk.cyan('  ← this machine') : '';
-        const interactive = name === interactiveHost ? chalk.yellow('  ★ interactive') : '';
+        // A `personal` role already conveys "your interactive seat"; don't double-
+        // render the star on it. Keep it for a non-personal pinned interactive host.
+        const interactive = name === interactiveHost && deviceRoles[name] !== 'personal' ? chalk.yellow('  ★ interactive') : '';
         lines.push(fitDeviceRow(`${marker}${label}${plat} ${specCell(stats, specWidth)}${load}${mem}${disk}${freeTotal}  ${badge}${relay}${here}${interactive}`, role, desc, width));
     }
     // Fleet capacity summary — total cores, how much RAM is free right now, and
@@ -1449,12 +1457,12 @@ function registerDevicesCommands(program) {
      *
      * A role written here lands in that device's tracked per-device doc
      * (`devices/<name>/agents.yaml` `config.role`) and syncs with repo
-     * push/pull. The vocabulary is deliberately `worker | personal` only.
+     * push/pull. The vocabulary is `worker | personal | desktop`.
      */
     const runDevicesRole = async (name, role, opts) => {
         if (!name) {
             if (role)
-                throw new Error('Name a device: agents devices role <name> <worker|personal>');
+                throw new Error('Name a device: agents devices role <name> <worker|personal|desktop>');
             const reg = await loadDevices();
             // The full registered roster, not just online — a fleet-wide `role`
             // default must reach a registered device even when it has no per-device
@@ -1475,14 +1483,14 @@ function registerDevicesCommands(program) {
             }
             else {
                 for (const [device, r] of marked) {
-                    const tint = r === 'worker' ? chalk.green : r === 'personal' ? chalk.yellow : chalk.gray;
+                    const tint = r === 'worker' ? chalk.green : r === 'personal' ? chalk.yellow : r === 'desktop' ? chalk.cyan : chalk.gray;
                     console.log(`  ${device.padEnd(20)} ${tint(r)}`);
                 }
             }
             console.log();
             console.log(chalk.bold('--device auto picks from: ') + (pool.length > 0 ? pool.join(', ') : chalk.red('nothing — no eligible device')));
             if (mode === 'all')
-                console.log(chalk.gray('auto.pool=all — worker marks are ignored (a personal device is still excluded).'));
+                console.log(chalk.gray('auto.pool=all — worker marks are ignored (personal and desktop devices are still excluded).'));
             return;
         }
         await mustGetDevice(name);
@@ -1669,7 +1677,8 @@ function registerDevicesCommands(program) {
     });
     const roleCmd = devicesCmd
         .command('role [name] [role]')
-        .description('Show or set what a device is for: worker (agents run here) or personal (you sit here — never picked automatically). ' +
+        .description('Show or set what a device is for: worker (agents run here), personal (you sit here), or desktop (a headed ' +
+        'always-on box — the release/credential home). Personal and desktop are never picked automatically. ' +
         'Marking any device worker makes `--device auto` an allowlist over the marked workers.')
         .option('--clear', 'remove the mark, returning the device to unmarked')
         .option('--json', 'output machine-readable JSON')
@@ -1688,6 +1697,7 @@ function registerDevicesCommands(program) {
       agents devices role yosemite-s0 worker       # agents spin up here
       agents devices role yosemite-s1 worker       # …and here; auto now rotates over these two only
       agents devices role zion personal            # your laptop — keep automatic placement off it
+      agents devices role mac-mini desktop         # headed always-on box — also kept out of auto placement
       agents devices role yosemite-s0 --clear      # unmark
       agents devices role --json                   # machine-readable
     `,
@@ -1699,12 +1709,12 @@ function registerDevicesCommands(program) {
 
       Effect on '--device auto' (agents run, teams, agents ssh auto, and the AGI
       EXT launch commands, which all resolve placement through the CLI):
-        no device marked  -> every online device, as before
-        any worker marked -> ONLY the marked workers
-        personal          -> never picked, under either state
+        no device marked   -> every online device, as before
+        any worker marked  -> ONLY the marked workers
+        personal / desktop -> never picked, under either state
 
-      Turn the allowlist off with 'agents config set auto.pool all'; a personal
-      box stays excluded, since that is what the mark is for.
+      Turn the allowlist off with 'agents config set auto.pool all'; personal and
+      desktop boxes stay excluded, since that is what the mark is for.
     `,
     });
     const describeCmd = devicesCmd

package/dist/commands/trash.d.ts

@@ -9,13 +9,13 @@
 import type { Command } from 'commander';
 /**
  * Restore a soft-deleted version back into ~/.agents/.history/versions/.
- * Shared by `agents trash restore` and the top-level `agents restore` alias.
+ * Backs the top-level `agents restore` command.
  * Exits the process with a non-zero code on any failure.
  */
 export declare function restoreVersion(target: string): void;
 /**
  * Register the top-level `agents restore` command — a shorthand for
- * `agents trash restore` so users can undo a `remove`/`prune` directly.
+ * `agents restore` so users can undo a `remove`/`prune` directly.
  */
 export declare function registerRestoreCommand(program: Command): void;
 export declare function registerTrashCommands(program: Command): void;

package/dist/commands/trash.js

@@ -112,7 +112,7 @@ function humanSize(bytes) {
 }
 /**
  * Restore a soft-deleted version back into ~/.agents/.history/versions/.
- * Shared by `agents trash restore` and the top-level `agents restore` alias.
+ * Backs the top-level `agents restore` command.
  * Exits the process with a non-zero code on any failure.
  */
 export function restoreVersion(target) {
@@ -157,7 +157,7 @@ export function restoreVersion(target) {
 }
 /**
  * Register the top-level `agents restore` command — a shorthand for
- * `agents trash restore` so users can undo a `remove`/`prune` directly.
+ * `agents restore` so users can undo a `remove`/`prune` directly.
  */
 export function registerRestoreCommand(program) {
     program
@@ -196,8 +196,4 @@ export function registerTrashCommands(program) {
         console.log();
         console.log(chalk.gray('Restore with: agents restore <agent>@<version>'));
     });
-    trash
-        .command('restore <target>')
-        .description('Restore a soft-deleted version (e.g. "claude@2.1.110") back to ~/.agents/.history/versions/')
-        .action((target) => restoreVersion(target));
 }

package/dist/commands/versions.d.ts

@@ -2,10 +2,10 @@
  * Version management commands for installing, switching, and removing agent CLIs.
  *
  * Implements `agents add`, `agents prune`, `agents remove` (alias),
- * `agents use`, and the deprecated `agents list`. Handles npm-based installation,
+ * and `agents use`. Handles npm-based installation,
  * shim creation, config symlink
  * switching, resource sync prompts, and project-level version pinning.
  */
 import type { Command } from 'commander';
-/** Register `agents add`, `agents prune`, `agents remove`, `agents use`, and `agents list` (deprecated). */
+/** Register `agents add`, `agents prune`, `agents remove`, and `agents use`. */
 export declare function registerVersionsCommands(program: Command): void;

package/dist/commands/versions.js

@@ -1,4 +1,3 @@
-import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
@@ -6,7 +5,6 @@ import * as path from 'path';
 import { select, confirm, checkbox } from '@inquirer/prompts';
 import { AGENTS, MANAGED_AGENT_IDS, accountOrgBadge, getAccountEmail, getAccountInfo, agentLabel, warnAgentDeprecated, isAgentHardDeprecated, hardDeprecationError, isSelfUpdatingAgent, } from '../lib/agents.js';
 import { formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, isUsageHeadlessScopeError, } from '../lib/accounting/usage.js';
-import { viewAction } from './view.js';
 import { resolveConfiguredModel, formatAgentIdentity } from '../lib/models.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
 import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, isOldestInstalled, getGlobalDefault, setGlobalDefault, markVersionIsolated, setIsolatedDefault, isVersionIsolated, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, printTrashFooter, } from '../lib/installations/versions.js';
@@ -288,7 +286,7 @@ function configureVersionPruneCommand(cmd, commandName) {
     });
     cmd.action((specs, options) => versionPruneAction(specs, options, commandName));
 }
-/** Register `agents add`, `agents prune`, `agents remove`, `agents use`, and `agents list` (deprecated). */
+/** Register `agents add`, `agents prune`, `agents remove`, and `agents use`. */
 export function registerVersionsCommands(program) {
     const addCmd = program
         .command('add <specs...>')
@@ -943,11 +941,4 @@ export function registerVersionsCommands(program) {
             throw err;
         }
     });
-    // Deprecated: use `agents view` instead
-    addHostOption(program.command('list [agent]'))
-        .description('List installed agent CLI versions')
-        .action(async (agentArg) => {
-        console.log(chalk.red('Deprecated: "agents list" is now "agents view"\n'));
-        await viewAction(agentArg);
-    });
 }

package/dist/commands/view.d.ts

@@ -72,8 +72,8 @@ export declare function renderHarnessBlocks(harnesses: ProfileSummary[], install
 /**
  * The USAGE-READ-2 decision, isolated from its runtime inputs so it can be
  * tested directly: a usage read may fall through to the interactive OAuth login
- * ONLY for a foreground human render on a `personal` device. Both conditions are
- * required — role alone is not sufficient.
+ * ONLY for a foreground human render on a headed device (`personal` or
+ * `desktop`). Both conditions are required — role alone is not sufficient.
  */
 export declare function allowInteractiveUsageLogin(role: ConfiguredDeviceRole | undefined, isTTY: boolean): boolean;
 /** Build the set of resource sections to include in `--json` from the