@phnx-labs/agents-cli 1.22.75 → 1.22.77

package/CHANGELOG.md

@@ -1,5 +1,126 @@
 # Changelog
 
+## 1.22.77
+
+- **`agents repo pull` / `agents sync` no longer wedge on a CLI-regenerated `~/.agents/agents.yaml` (PHNX-3968).** The shared central config was rewritten by config commands without being committed, so between the daemon's publish ticks the tree sat dirty on `agents.yaml`; an incoming peer commit that also touched it made the pull refuse with *"incoming changes touch uncommitted paths: agents.yaml"*, forcing manual autostash gymnastics on the fleet. Central config edits are now committed synchronously by the command that makes them (after the meta lock releases, skipped for the daemon whose own publish tick owns its commits), so the tree is clean at rest and the trip cannot occur. A genuinely dirty-and-differing central file now *refuses* the pull (data-safe, self-heals on the next commit) rather than silently taking the remote copy. The user-repo `CHANGELOG.md` (a duplicate of the shipped one) is de-tracked via `.git/info/exclude` so it stops churning the tree. Source: `cli/src/lib/state.ts`, `cli/src/lib/git.ts`, `cli/src/lib/browser/registry.ts`, `cli/src/lib/project-resources.ts`.
+
+## 1.22.76
+
+- **Per-session summarizer: bound the mirror publish (PHNX-3939 follow-up).** The fleet session mirror now caps `checkpoints`/`summaryChecklist` on the **publish** side (50/100 items, 400-char text) exactly as it already did on consume, so a box's own summarizer output can never ride unbounded into the git-synced `daemon-state.json` every peer fetches — matching the `snippet()` cap already applied to `goal`. Source: `cli/src/lib/session/mirror.ts`.
+
+- **Per-session summarizer on the session stream (PHNX-3939).** A new opt-in daemon
+  service computes a 1–2 line **goal**, progress **checkpoints**, and a detailed
+  **checklist** for each running session and delivers them on `agents sessions watch`
+  / `agents feed watch --json` (as `goal` / `checkpoints` / `summaryChecklist` /
+  `summaryState`), so the AGI extension sidebar can render them. It is **off by
+  default and never on the request path**: the model call runs only in the
+  background `session-summarizer` service, reader-gated and bounded per tick, and a
+  computed summary is cached in the transcript-keyed `session_summaries` table so it
+  never recomputes on unchanged bytes and `agents sessions <id>` timing is unchanged.
+  Enable it with `agents config set summarizer.enabled on` plus a local
+  Anthropic-wire endpoint — `agents config set summarizer.baseUrl http://localhost:11434`
+  and `agents config set summarizer.model qwen2.5:3b` (env overrides:
+  `AGENTS_SUMMARIZER_ENABLED` / `AGENTS_SUMMARIZER_BASEURL` / `AGENTS_SUMMARIZER_MODEL`).
+  Summaries ride the fleet session mirror, so a peer's sessions carry them too. When
+  disabled or unconfigured, zero model calls are made and rows read
+  `summaryState: "skipped"`. Source: `cli/src/lib/summarizer/`,
+  `cli/src/lib/daemon/session-summarizer-service.ts`, `cli/src/lib/session/db.ts`.
+
+- **`agents config unset project.root` now actually clears it.** `projectRoot` is a
+  machine-local key persisted to the device doc, which `writeMeta` only clears when
+  the key is present-but-falsy; the unset path dropped the key entirely, so
+  `agents config get project.root` still returned the old value afterward. Source:
+  `cli/src/commands/config.ts`.
+
+---
+type: fixed
+---
+
+Keep fleet account and device routing consistent: poolless teams now use the active worker pool, remote readiness rejects stale account evidence, removed devices lose cached stats, partial device writes preserve unrelated metadata, paths are passed without shell reparsing, and harness forks can translate across native hosts.
+
+- **Managed share: collision recovery, race-safe republish, and OAuth avatars
+  (PHNX-3942, folding PHNX-3547 + PHNX-3579).** Three correctness gaps on the
+  artifact-sharing path are closed. (1) A same-local-part account move no longer
+  dead-ends on the permanent 409: the Worker's `__handles/<handle>` claim now records
+  the verified email, and a request whose verified email matches the claim but whose
+  userId differs (the same human re-authenticated under a new account id) transfers
+  the claim and re-stamps the old account's objects instead of refusing; when the
+  handle genuinely belongs to someone else, `agents artifacts share --handle <name>`
+  publishes under an alternate first-writer-claimed namespace (new `x-share-handle`
+  Worker header). (2) A concurrent republish no longer silently discards a body: the
+  Worker's read → archive-revision → overwrite sequence is now a bounded
+  compare-and-swap loop (`onlyIf.etagMatches`, the primitive PATCH and the usage
+  ledger already used) — a conflicting write 409s the put, the loser re-reads,
+  archives the winner's body as a revision, and lands its own as canonical, so every
+  accepted body survives as canonical or revision. (3) Share attribution prefers the
+  hosted OAuth profile image: the Phoenix session now carries `avatarUrl` (captured
+  at login and refreshed from `/api/v1/auth/me`), and publish stamps it before
+  falling back to the email Gravatar. Also, publish failures stop appending
+  'Check the write token' to quota/rate rejections (413/429) — the Worker's actual
+  reason is surfaced, and only 401/403 mention the token (or `agents auth login` on
+  the managed endpoint). Source: `cli/src/lib/share/worker-template.ts`,
+  `cli/src/lib/share/publish.ts`, `cli/src/lib/identity/client.ts`,
+  `cli/src/lib/identity/index.ts`, `cli/src/commands/auth.ts`,
+  `cli/src/commands/share.ts`.
+
+- **Release recovery and exclusion now hold under rebases, interruption, and concurrent releasers (PHNX-3945).** A retry validates the merged target version and the recorded/fetched release PR identity, then tags and promotes the exact attested PR head even when the merge tree differs. Attestation fallback is capped at 45 seconds total (15-second optional fetch plus a 30-second poll), content-addressed records publish through a same-directory atomic rename, and release-lease acquisition/reclamation uses one expected-old-ref compare-and-swap instead of overwritable custom-ref pushes or a delete/create gap.
+
+---
+type: changed
+---
+
+- **`agents watchdog` uses the standard `enable`/`disable` verbs (PHNX-3949).**
+  The device-local daemon watchdog pass is now toggled with
+  `agents watchdog enable` / `agents watchdog disable`, matching the
+  `enable`/`disable` shape `menubar` and `daemon` already use for the same
+  concept. The old `on` / `off` spellings keep working as aliases, so no existing
+  invocation or script breaks. Source: `cli/src/commands/watchdog.ts`.
+
+---
+type: changed
+---
+
+- **CLI verb vocabulary unified behind one canonical alias table (PHNX-3949).**
+  A new `cli/src/lib/verbs.ts` defines the standard short-form aliases
+  (`list`→`ls`, `remove`→`rm`, `view`→`show`, `rename`→`mv`) and a `withAliases`
+  helper, applied uniformly across `skills`, `hooks`, `commands`, `rules`,
+  `permissions`, `mcp`, `subagents`, `workflows`, and `memory` so every resource
+  group answers to the same shortcuts. No primary command name changes. Source:
+  `cli/src/lib/verbs.ts`.
+- **`agents route` now uses the standard verbs and pluralizes its noun (PHNX-3949).**
+  The router command group matches the shape `harness` already set: read-one is
+  `route view <name>` (old `show` kept as an alias), create is `route add <name>`
+  (old `create` kept as an alias), `list` gains the `ls` short alias, and the
+  whole tree resolves under the plural noun `agents routes ...`. New
+  `route rename <old> <new>` re-keys a user-layer router in place, preserving
+  every field (harness allowlists, weights, linked accounts, hijack flag); it
+  fails loud on a missing source, a name collision in any layer, or a router
+  that resolves from a non-user layer. Source: `cli/src/commands/route.ts`,
+  `cli/src/lib/routers.ts`.
+- **`plugins` moves to the canonical `view`/`add` verbs, and `monitors` gains an
+  `rm` alias (PHNX-3949).** `agents plugins info` is now `agents plugins view`
+  and `agents plugins install` is now `agents plugins add`; the old names keep
+  working as aliases, so no existing invocation breaks. `plugins list` gains an
+  `ls` alias and `plugins remove` gains `rm`. `agents monitors remove <name>`
+  gains the `rm` alias. Source: `cli/src/commands/plugins.ts`,
+  `cli/src/commands/monitors.ts`.
+- **`agents open` is now the machine-only `_callback` verb; handler setup moved under `agents setup url-scheme` (PHNX-3949).**
+  `agents open <url>` was never a user command — it is the OS callback the
+  `agents://` deep-link handler invokes when you click a session link in a
+  rendered artifact. It is now hidden as the machine-only `agents _callback`
+  verb (humans resume with `agents sessions resume`), and the register /
+  unregister / status plumbing moved to a visible `agents setup url-scheme`
+  group. Nothing breaks: `agents open <url>` stays a hidden alias so OS handlers
+  written by older CLIs keep resolving until `agents setup url-scheme register`
+  re-writes them to the new verb, and `agents open register|unregister|status`
+  still work as hidden back-compat subcommands. Source:
+  `cli/src/commands/open.ts`, `cli/src/commands/setup.ts`,
+  `cli/src/lib/deeplink/register.ts`.
+
+- **One canonical Comet: attach-only browser profiles + closed port-squat (PHNX-3967).** A browser profile now carries a `launchPolicy` (`attach-only` | `launch`) and a durable `--user-data-dir`. An attach-only profile (`agents browser profiles create <name> --browser comet --attach-only`, and Arc always) NEVER spawns a rival window — agents attach to the browser you already started with remote debugging, else fail loud with the exact `open -a <app> --args --remote-debugging-port=<port> --user-data-dir=<durable>` relaunch. Before adopting an endpoint the local driver now verifies ownership beyond browser family: it compares the running instance's `--user-data-dir` to the profile's durable dir and rejects a foreign port-squatter (e.g. a logged-out `/tmp` Comet on the canonical port) instead of driving it — and if an occupant is serving CDP but its `--user-data-dir` can't be read, the guard refuses to attach to the unverified instance (fail loud) rather than driving it silently, with `profiles doctor` surfacing the same unverified state instead of a green check. The durable dir lives under `~/.agents/.history/browser-profiles/<name>/` (outside `.cache`), so a one-time sign-in survives quit+relaunch and `profiles remove`. `agents browser profiles doctor` flags a foreign-user-data-dir Comet on the canonical port. Source: `apps/cli/src/lib/browser/drivers/local.ts`, `apps/cli/src/lib/browser/{profiles,chrome,types}.ts`, `apps/cli/src/commands/browser.ts`.
+
+- **`agents doctor` is now diagnose-only; `agents sync` is the single fixer.** `doctor --fix` is removed — running it prints a one-line redirect to `agents sync` and exits non-zero — and every `doctor` remediation now points at `agents sync`. `sync` gains the repairs `doctor --fix` used to own: managed-hook-runtime-shim repair (the "source mismatch" fixer), hook re-wiring, and full home-rot heal, running on **every** sync path — the umbrella, agent-scoped, single-version, and the `agents sync status` / menu-bar drift path — so one `agents sync` now converges a version that `doctor` flags, instead of two commands that could disagree. Repair failures surface in `--json` output and the process exit code. The machine-wide stale-CLI purge no longer runs on a routine sync; it is now the explicit `agents sync --prune-clis` flag. Source: `cli/src/lib/reconcile-and-repair.ts`, `cli/src/commands/sync.ts`, `cli/src/commands/doctor.ts`, `cli/src/lib/drift-sync.ts`.
+
 ## 1.22.75
 
 - **Account labels are per-harness, and survive a daemon publish (PHNX-3887).** One

package/README.md

@@ -493,6 +493,18 @@ Slack). Owner delivery attempts every selected channel, reports partial
 failures, and safely forwards Rush-backed channels from headless workers to a
 capable Mac; ordinary milestone posts remain record-only unless configured.
 
+An optional **per-session summarizer** (off by default) adds a daemon-computed
+`goal`, progress `checkpoints`, and a detailed `summaryChecklist` to each session
+row on the `feed watch` / `sessions watch` stream. It never runs on a request
+path — the model call lives in a background daemon service, cached per transcript
+so it never recomputes on unchanged bytes. Turn it on with a local model endpoint:
+
+```bash
+agents config set summarizer.enabled on
+agents config set summarizer.baseUrl http://localhost:11434   # Ollama / vLLM / LiteLLM
+agents config set summarizer.model qwen2.5:3b
+```
+
 Top-level questions and waiting notifications publish one atomic open-block record per session, including the mailbox id, host, runtime, and every answer option. The default view collapses agents under the **outcome** they serve (Linear ticket, PR, worktree slug, or Unassigned) so a 1,100-agent fleet reads as dozens of deliverables. Answered, resumed, and stopped blocks clear automatically; Task subagents are excluded. The rendered reply command uses the same mailbox id with `agents message`, so the decision routes back to the agent that asked it.
 
 ### Auto-nudge stalls
@@ -504,7 +516,7 @@ agents watchdog --nudge    # actually inject "Continue." into the stalled split
 agents watchdog --watch    # daemon loop: a tick every --interval
 ```
 
-`agents watchdog` detects a stalled session, resolves the *exact* terminal split it lives in (tmux, iTerm, VSCodium, or a raw pty), and injects a nudge -- `Continue.` by default, or set `--text`. Its timestamped default output shows attention-worthy sessions with their agent, host app, machine, project, activity, age, path, latest preview, and decision reason; `--verbose` restores healthy/non-actionable inspections. It's dry by default; `--nudge` acts on a single tick. `agents watchdog on|off` controls the device-local daemon pass, which runs once every three minutes. Steer a single run with `agents watchdog policy <id> off | keep | handsoff`.
+`agents watchdog` detects a stalled session, resolves the *exact* terminal split it lives in (tmux, iTerm, VSCodium, or a raw pty), and injects a nudge -- `Continue.` by default, or set `--text`. Its timestamped default output shows attention-worthy sessions with their agent, host app, machine, project, activity, age, path, latest preview, and decision reason; `--verbose` restores healthy/non-actionable inspections. It's dry by default; `--nudge` acts on a single tick. `agents watchdog enable|disable` controls the device-local daemon pass, which runs once every three minutes. Steer a single run with `agents watchdog policy <id> off | keep | handsoff`.
 
 A stalled session whose tail shows a hard account limit ("You've hit your weekly limit · resets …") is **rotated in place** instead of nudged: the watchdog gates on the same healthy-account selection `agents run auto` makes (zero healthy → one skip event per cooldown window, terminal untouched), injects the harness's exit sequence, relaunches `agents run auto --interactive --session-id <uuid>` in the *same* tab, then replays the old session's resume once the new TUI is live. Default on; `agents watchdog rotate off` disables it (nudging stays on).
 
@@ -623,7 +635,7 @@ A **router** is a reusable, task-typed allowlist -- which harnesses, which model
 
 ```bash
 # Scope a router to two harnesses, capped at a tier
-agents route create research --harness gemini,kimi --tier cheap,default
+agents route add research --harness gemini,kimi --tier cheap,default   # alias: create
 
 # Narrow one harness's model set
 agents route allow research kimi kimi-k2
@@ -632,11 +644,12 @@ agents route allow research kimi kimi-k2
 agents route link-account research gemini personal
 agents route link-account research kimi work
 
-agents route show research
+agents route view research        # alias: show
+agents route rename research prod  # rename a router, preserving its config
 agents route list --json
 ```
 
-Router YAML has no secrets -- safe to `agents repo push` to a shared repo. Harness ids and model/tier tokens are validated on `create`/`allow`: an unknown harness or an unverifiable model id fails loud and writes nothing. Routers resolve as a layered resource (project > user > system, same as profiles).
+Router YAML has no secrets -- safe to `agents repo push` to a shared repo. Harness ids and model/tier tokens are validated on `add`/`allow`: an unknown harness or an unverifiable model id fails loud and writes nothing. Routers resolve as a layered resource (project > user > system, same as profiles). The old verbs `create`/`show` remain as aliases.
 
 ---
 
@@ -903,9 +916,8 @@ Resolution is project > user > system: a `<repo>/.agents/workflows/<name>/` over
 Bundle skills, commands, hooks, MCP servers, settings, and permissions under a single manifest. One source dir at `~/.agents/plugins/<name>/`, mirrored into every installed Claude / OpenClaw version automatically.
 
 ```bash
-# Install from a git URL or local path
-agents plugins install hivemind@https://github.com/activeloopai/hivemind.git
-agents plugins install ./my-plugin
+# Add (install) from a git URL or local path — `install` is an alias for `add`
+agents plugins add hivemind@https://github.com/activeloopai/hivemind.git
 agents plugins add ./my-plugin
 
 # Apply to one agent (default version) or all supported
@@ -934,7 +946,7 @@ Plugins that ship `hooks/`, `.mcp.json`, `bin/`, `scripts/`, `settings.json` (no
 
 ```bash
 # Hooks-bearing plugins copy in but stay disabled by default
-agents plugins install hivemind@https://github.com/activeloopai/hivemind.git \
+agents plugins add hivemind@https://github.com/activeloopai/hivemind.git \
   --allow-exec-surfaces
 
 # Same gate on re-sync (e.g., after upstream updates)

package/dist/bootstrap.js

@@ -265,15 +265,15 @@ function maybeWarnMultiInstall() {
     for (const info of inventory) {
         console.error(chalk.gray(`  ${info.packageRoot}  ${info.version}  (${info.note})`));
     }
-    // RUSH-2705/2713: only advertise `agents doctor --fix` for copies it will
-    // really delete. A duplicate --fix won't auto-purge (a healthy >=1.22.30 peer,
-    // OR a pre-1.22.30 copy left alone only because no fixed peer exists — the
-    // latter is genuinely vulnerable, not healthy) makes --fix a remedy that
-    // no-ops forever — name the manual removal command instead.
+    // RUSH-2705/2713: only advertise the `agents sync --prune-clis` purge for copies it
+    // will really delete. A duplicate sync won't auto-purge (a healthy >=1.22.30
+    // peer, OR a pre-1.22.30 copy left alone only because no fixed peer exists — the
+    // latter is genuinely vulnerable, not healthy) makes it a remedy that no-ops
+    // forever — name the manual removal command instead.
     const peers = inventory.filter((info) => !info.running);
     console.error(chalk.gray('Upgrades apply to the running copy.'));
     if (peers.some((info) => info.autoPurgeable)) {
-        console.error(chalk.gray('Purge npx-cache / legacy / pre-1.22.30 copies with: agents doctor --fix'));
+        console.error(chalk.gray('Purge npx-cache / legacy / pre-1.22.30 copies with: agents sync --prune-clis'));
     }
     for (const peer of peers.filter((info) => !info.autoPurgeable)) {
         console.error(chalk.gray(`Remove the ${peer.version} copy at ${peer.packageRoot} with: ${manualUninstallCommand(peer.packageRoot)}`));
@@ -731,7 +731,7 @@ async function runUpgrade(version, options) {
                 console.log(chalk.gray(`Purged ${purge.removed.length} stale agents-cli install${purge.removed.length === 1 ? '' : 's'} (npx-cache / legacy / pre-1.22.30).`));
             }
             if (purge.failed.length > 0) {
-                console.log(chalk.yellow(`Could not purge ${purge.failed.length} stale install${purge.failed.length === 1 ? '' : 's'}; re-run agents doctor --fix.`));
+                console.log(chalk.yellow(`Could not purge ${purge.failed.length} stale install${purge.failed.length === 1 ? '' : 's'}; re-run agents sync --prune-clis.`));
             }
             // RUSH-2705/2713: duplicates --fix won't auto-purge (a healthy
             // >=1.22.30 peer, or a pre-1.22.30 copy with no fixed peer to fall back

package/dist/cli/command-registry.js

@@ -157,6 +157,10 @@ export const COMMAND_LOADERS = {
     monitors: [loadMonitors],
     projects: [loadProjects],
     run: [loadRun],
+    // `_callback` is the machine-only agents:// deep-link verb; `open` is its
+    // hidden back-compat alias (OS handlers written by older CLIs call it). Both
+    // tokens must lazy-load the same module so either resolves. See commands/open.ts.
+    _callback: [loadOpen],
     open: [loadOpen],
     reconnect: [loadReconnect],
     fork: [loadFork],
@@ -167,6 +171,7 @@ export const COMMAND_LOADERS = {
     restore: [loadRestore],
     doctor: [loadDoctor],
     route: [loadRoute],
+    routes: [loadRoute],
     harness: [loadHarness],
     harnesses: [loadHarness],
     secrets: [loadSecrets],

package/dist/commands/artifacts-setup.js

@@ -98,7 +98,7 @@ export async function runShareWizard() {
     }
     const { input } = await import('@inquirer/prompts');
     const baseUrl = await input({
-        message: 'Endpoint base URL (e.g. https://share.agents-cli.sh)',
+        message: 'Endpoint base URL (e.g. https://share.getrush.ai)',
         validate: (v) => (v.trim().startsWith('http') ? true : 'Enter the full https:// URL of the endpoint.'),
     });
     await runShareJoin(baseUrl.trim());

package/dist/commands/artifacts.js

@@ -31,7 +31,7 @@ export function registerArtifactsCommands(program) {
 
       # Or provision your own Cloudflare endpoint (or join a teammate's)
       agents artifacts setup
-      agents artifacts share join https://share.agents-cli.sh
+      agents artifacts share join https://share.getrush.ai
 
       # What's live in your namespace, and taking one down
       agents artifacts share list

package/dist/commands/auth.js

@@ -26,7 +26,13 @@ async function login() {
         await sleep(interval);
         const poll = await pollDeviceToken(grant.device_code);
         if (poll.status === 'authorized') {
-            writeSession({ access_token: poll.access_token, email: poll.user.email, userId: poll.user.id });
+            const avatarUrl = poll.user.avatar_url ?? poll.user.picture;
+            writeSession({
+                access_token: poll.access_token,
+                email: poll.user.email,
+                userId: poll.user.id,
+                ...(avatarUrl ? { avatarUrl } : {}),
+            });
             console.log(chalk.green(`\n  Signed in as ${poll.user.email}.`));
             return;
         }

package/dist/commands/browser.js

@@ -3,13 +3,13 @@ import chalk from 'chalk';
 import { spawnSync } from 'node:child_process';
 import * as fs from 'fs';
 import * as path from 'path';
-import { listProfiles, getProfile, createProfile, deleteProfile, getConfiguredDefaultProfileName, resolveProfileRef, resolveProfileRefForStart, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, formatProfilesTable, editProfile, renameProfile, assertRegistrableProfileName, isProfileLaunchableHere, } from '../lib/browser/profiles.js';
+import { listProfiles, getProfile, createProfile, deleteProfile, getConfiguredDefaultProfileName, resolveProfileRef, resolveProfileRefForStart, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, formatProfilesTable, editProfile, renameProfile, assertRegistrableProfileName, isProfileLaunchableHere, isAttachOnlyProfile, resolveProfileDataDir, normalizeDataDir, } from '../lib/browser/profiles.js';
 import { declaringDevices, migrateCentralBrowserProfiles, profileKind } from '../lib/browser/registry.js';
 import { resolveActor } from '../lib/actor.js';
 import { loginsForProfile, profilesLoggedInto, serviceForUrl, loginsWithAccountsForProfile, accountsForProfile, credKeysForService, AUTH_SIGNATURES, } from '../lib/browser/login-detection.js';
 import { parseSecretRef } from '../lib/browser/secret-ref.js';
 import { readAndResolveBundleEnv, bundleExists, readBundle, describeBundle } from '../lib/secrets/bundles.js';
-import { findBrowserPath, getPortOccupant, isLauncherScript, listInstalledBrowsers } from '../lib/browser/chrome.js';
+import { findBrowserPath, getPortOccupant, getProcessUserDataDir, isLauncherScript, listInstalledBrowsers } from '../lib/browser/chrome.js';
 import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, buildProfilePrunePlan, pruneProfiles, PRUNE_REASON_TEXT, identityLoopbackMismatch, } from '../lib/browser/runtime-state.js';
 import { DEFAULT_VIEWPORT, parseWindowSize, parseWindowPosition } from '../lib/browser/devices.js';
 import { runBrowserSessionsCommand } from './browser-sessions-picker.js';
@@ -610,6 +610,8 @@ function registerProfilesCommands(browser) {
         .option('--binary <path>', 'Absolute path to the browser/app binary (required with --browser custom)')
         .option('--electron', 'Treat this profile as an Electron desktop app: never call Target.createTarget; bind to the visible window using --target-filter or the skip-invisible heuristic')
         .option('--target-filter <expr>', 'Pick the existing CDP page target to drive (Electron apps, and Arc — which reuses an open tab / Space rather than creating one). Format: url:<substring> or title:<substring>')
+        .option('--attach-only', 'Never spawn a rival window: attach to a browser you already started with remote debugging, else fail loud with a relaunch hint (PHNX-3967). The model for a canonical signed-in Comet; Arc is always attach-only. Pairs with a durable --user-data-dir.')
+        .option('--user-data-dir <path>', "Absolute durable --user-data-dir for this profile's browser. Default for attach-only: ~/.agents/.history/browser-profiles/<name>/chrome-data (outside .cache, so a one-time sign-in survives relaunch).")
         .action(async (name, opts) => {
         try {
             assertRegistrableProfileName(name);
@@ -676,6 +678,10 @@ function registerProfilesCommands(browser) {
             viewport.x = pos.x;
             viewport.y = pos.y;
         }
+        if (opts.userDataDir && !path.isAbsolute(String(opts.userDataDir))) {
+            console.error('--user-data-dir must be an absolute path');
+            process.exit(1);
+        }
         const profile = {
             name,
             description: opts.description,
@@ -684,6 +690,8 @@ function registerProfilesCommands(browser) {
             electron: opts.electron || undefined,
             targetFilter: opts.targetFilter,
             endpoints,
+            launchPolicy: opts.attachOnly ? 'attach-only' : undefined,
+            userDataDir: opts.userDataDir ? String(opts.userDataDir) : undefined,
             secrets: opts.secrets,
             chrome: opts.headless ? { headless: true } : undefined,
             viewport,
@@ -693,6 +701,15 @@ function registerProfilesCommands(browser) {
         console.log(port !== undefined
             ? `Added "${name}" on ${machineId()} (port ${port}).`
             : `Added "${name}" on ${machineId()}.`);
+        // Attach-only profiles never launch a browser — tell the user the one-time
+        // relaunch that makes their canonical instance attachable, pinned to the
+        // durable data dir so the sign-in persists (PHNX-3967).
+        if (isAttachOnlyProfile(profile) && profile.browser !== 'arc' && port !== undefined) {
+            const app = profile.browser === 'comet' ? 'Comet' : profile.browser;
+            console.log(`attach-only: agents will not spawn ${app}. Start the canonical one once with:\n` +
+                `  open -a ${app} --args --remote-debugging-port=${port} --user-data-dir=${resolveProfileDataDir(profile)}\n` +
+                `Sign in in that window; the data dir is durable so the login survives quit+relaunch.`);
+        }
         // Warn (don't fail) if the declared secrets bundle doesn't exist yet — it
         // may be created later, but a typo should surface now.
         if (opts.secrets && !bundleExists(opts.secrets)) {
@@ -717,6 +734,9 @@ function registerProfilesCommands(browser) {
         .option('--electron', 'Treat this profile as an Electron desktop app')
         .option('--no-electron', 'Stop treating it as an Electron app')
         .option('--target-filter <expr>', "url:<substring> or title:<substring>; consulted on Electron and Arc profiles (pass '' to clear)")
+        .option('--attach-only', 'Make this profile attach-only (never spawn a rival window) — PHNX-3967')
+        .option('--launch', 'Undo attach-only: let agents launch the browser when nothing is serving CDP on the port')
+        .option('--user-data-dir <path>', "Absolute durable --user-data-dir (pass '' to clear back to the default durable dir)")
         .option('--json', 'Output machine-readable JSON')
         .action(async (name, opts) => {
         // The browser type and the name are identity, not settings: both key the
@@ -734,6 +754,14 @@ function registerProfilesCommands(browser) {
                 process.exit(1);
             }
         }
+        if (opts.attachOnly && opts.launch) {
+            console.error('Pass either --attach-only or --launch, not both.');
+            process.exit(1);
+        }
+        if (opts.userDataDir && !path.isAbsolute(String(opts.userDataDir))) {
+            console.error('--user-data-dir must be an absolute path');
+            process.exit(1);
+        }
         const patch = {};
         if (opts.description !== undefined)
             patch.description = opts.description || undefined;
@@ -745,6 +773,15 @@ function registerProfilesCommands(browser) {
             patch.binary = opts.binary;
         if (opts.targetFilter !== undefined)
             patch.targetFilter = opts.targetFilter || undefined;
+        // launchPolicy toggle: --attach-only sets it, --launch clears it (back to
+        // the default launch behavior). commander leaves each undefined when unset.
+        if (opts.attachOnly)
+            patch.launchPolicy = 'attach-only';
+        else if (opts.launch)
+            patch.launchPolicy = undefined;
+        // '' clears back to the default durable dir; any other value pins it.
+        if (opts.userDataDir !== undefined)
+            patch.userDataDir = opts.userDataDir || undefined;
         // commander maps --electron/--no-electron and --headless/--no-headless onto
         // one boolean each, and leaves it undefined when neither was passed.
         if (opts.electron !== undefined)
@@ -879,6 +916,13 @@ function registerProfilesCommands(browser) {
             console.log(`Binary: ${profile.binary}`);
         if (profile.electron)
             console.log(`Electron: true`);
+        if (isAttachOnlyProfile(profile)) {
+            const why = profile.browser === 'arc' ? ' (Arc is always attach-only)' : '';
+            console.log(`Launch policy: attach-only${why} — agents attach, never spawn a rival window`);
+            if (profile.browser !== 'arc') {
+                console.log(`User-data-dir: ${resolveProfileDataDir(profile)} (durable)`);
+            }
+        }
         if (profile.targetFilter)
             console.log(`Target filter: ${profile.targetFilter}`);
         if (profile.description)
@@ -1049,6 +1093,17 @@ function registerProfilesCommands(browser) {
       \`prune\` only considers profiles this device declares. It never removes a
       profile that is in use, the configured default, or the \`auto-chrome\`
       profile a setup wizard created.
+
+      Arc is your PERSONAL browser and Comet is what agents drive (PHNX-3967).
+      Arc is single-instance with no debug port, so agents can only attach to a
+      running Arc, never launch one — it stays yours. Point agents at Comet as
+      one canonical signed-in profile that never spawns a second window:
+        agents browser profiles create agents-comet --browser comet --attach-only
+      An \`--attach-only\` profile (and Arc, always) attaches to a browser you
+      already started with remote debugging and fails loud with the relaunch
+      command otherwise, pinned to a durable --user-data-dir so the sign-in
+      survives quit+relaunch. A foreign browser squatting the canonical port is
+      rejected, not driven — \`agents browser profiles doctor <name>\` flags it.
     `,
     });
     profiles
@@ -1157,12 +1212,47 @@ function registerProfilesCommands(browser) {
                 try {
                     const { browser } = await discoverBrowserWsUrl(port, 'localhost', profile.name);
                     verifyBrowserIdentity(browser, profile.browser, port);
-                    checks.push({
-                        label: 'port',
-                        ok: true,
-                        detail: `${port} serving ${browser} (pid ${occupant.pid})`,
-                    });
-                    attachingToExistingBrowser = true;
+                    // Port-squat check (PHNX-3967): for an attach-only profile, a browser
+                    // of the right FAMILY on the canonical port is not enough — confirm
+                    // its --user-data-dir is this profile's durable dir. A logged-out
+                    // /tmp Comet answering CDP here would otherwise pass as ready and get
+                    // driven as if it were the credentialed browser.
+                    const expectedDir = resolveProfileDataDir(profile);
+                    const ownershipChecked = isAttachOnlyProfile(profile) && profile.browser !== 'arc';
+                    const runningDir = ownershipChecked ? getProcessUserDataDir(occupant.pid) : null;
+                    if (runningDir && normalizeDataDir(runningDir) !== normalizeDataDir(expectedDir)) {
+                        checks.push({
+                            label: 'port',
+                            ok: false,
+                            detail: `${port} serving ${browser} (pid ${occupant.pid}) but from a FOREIGN ` +
+                                `user-data-dir ${runningDir} (expected ${expectedDir}). This is a ` +
+                                `port-squatter, not this profile's browser — agents will refuse to drive ` +
+                                `it. Close it (\`kill ${occupant.pid}\`) and relaunch the canonical browser ` +
+                                `with --user-data-dir=${expectedDir}.`,
+                        });
+                    }
+                    else if (ownershipChecked && !runningDir) {
+                        // Attach-only, an occupant is serving CDP, but its --user-data-dir
+                        // couldn't be read — ownership is UNVERIFIED. Surface it rather than
+                        // report a silent green, matching the runtime guard which refuses to
+                        // attach to an unverifiable instance (PHNX-3967).
+                        checks.push({
+                            label: 'port',
+                            ok: false,
+                            detail: `${port} serving ${browser} (pid ${occupant.pid}) but its --user-data-dir ` +
+                                `could not be read, so ownership can't be confirmed. agents will refuse to ` +
+                                `attach to an unverified instance. Relaunch the canonical browser with ` +
+                                `--user-data-dir=${expectedDir} so the attach-only guard can verify it.`,
+                        });
+                    }
+                    else {
+                        checks.push({
+                            label: 'port',
+                            ok: true,
+                            detail: `${port} serving ${browser} (pid ${occupant.pid})`,
+                        });
+                        attachingToExistingBrowser = true;
+                    }
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
@@ -1174,8 +1264,12 @@ function registerProfilesCommands(browser) {
                 }
             }
         }
-        // 3. User-data-dir exists and is writable
-        const userDataDir = path.join(getProfileRuntimeDir(name), 'chrome-data');
+        // 3. User-data-dir exists and is writable. An attach-only profile's login
+        //    lives in the DURABLE dir (outside .cache) the canonical browser is
+        //    launched with; a launch-policy profile uses the managed cache dir.
+        const userDataDir = isAttachOnlyProfile(profile) && profile.browser !== 'arc'
+            ? resolveProfileDataDir(profile)
+            : path.join(getProfileRuntimeDir(name), 'chrome-data');
         try {
             if (!fs.existsSync(userDataDir)) {
                 checks.push({

package/dist/commands/commands.js

@@ -1,3 +1,4 @@
+import { withAliases } from '../lib/verbs.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
@@ -42,8 +43,8 @@ When to use:
   - New version: 'agents commands add --agents claude@2.1.112' to carry commands forward
   - Custom tooling: write a command markdown file, test it, then share via 'agents commands add ~/my-cmd.md'
 `);
-    commandsCmd
-        .command('list [agent]')
+    withAliases(commandsCmd
+        .command('list [agent]'), 'list')
         .option('--json', 'Emit machine-readable JSON instead of the table/picker')
         .description('Show which slash commands are installed and which agent versions they are synced to')
         .option('-a, --agent <agent>', 'Filter to a specific agent (alternative to positional arg)')
@@ -265,8 +266,8 @@ Examples:
             process.exit(1);
         }
     });
-    commandsCmd
-        .command('remove [name]')
+    withAliases(commandsCmd
+        .command('remove [name]'), 'remove')
         .description('Delete a command from agents (interactive picker if no name given)')
         .option('-a, --agents <list>', 'Limit removal to specific agents (e.g., claude,codex)')
         .addHelpText('after', `
@@ -405,8 +406,8 @@ Examples:
         console.error(chalk.gray('Use:  agents prune cleanup commands   (or `agents prune cleanup` for everything)'));
         process.exit(1);
     });
-    commandsCmd
-        .command('view [name]')
+    withAliases(commandsCmd
+        .command('view [name]'), 'view')
         .description('Read the full content of a command file with markdown rendering')
         .addHelpText('after', `
 Examples:

package/dist/commands/config.js

@@ -45,6 +45,8 @@ function parseValue(key, parsed, raw) {
             return raw.trim();
         case 'project':
             return raw.trim();
+        case 'summarizer':
+            return parsed.property === 'enabled' ? parseBool(raw, key) : raw.trim();
         case 'device': {
             const property = parsed.property;
             switch (property) {
@@ -126,6 +128,10 @@ function setConfig(parsed, value) {
         case 'project':
             setProjectRoot(value);
             return;
+        case 'summarizer': {
+            setConfigValue(`summarizer.${parsed.property}`, value);
+            return;
+        }
         case 'device': {
             const configName = devicePropertyToConfigName(parsed.property);
             if (parsed.property === 'notes') {
@@ -176,10 +182,18 @@ function unsetConfig(parsed) {
         }
         case 'project': {
             const had = getProjectRoot() !== undefined;
-            updateMeta((meta) => {
-                const { projectRoot: _projectRoot, ...rest } = meta;
-                return rest;
-            });
+            // `projectRoot` is a machine-local key that `writeMeta` persists to the
+            // device doc; it only clears that doc when the key is PRESENT-but-falsy
+            // (`writesProjectRoot` needs the own-property, state.ts). Dropping the key
+            // from the returned object left the device-doc value in place, so
+            // `config get` still returned it after unset. Set it undefined instead.
+            updateMeta((meta) => ({ ...meta, projectRoot: undefined }));
+            return had;
+        }
+        case 'summarizer': {
+            const name = `summarizer.${parsed.property}`;
+            const had = getConfigValue(name).value !== undefined;
+            unsetConfigValue(name);
             return had;
         }
         case 'device': {
@@ -212,6 +226,8 @@ function getConfig(parsed) {
         }
         case 'project':
             return getProjectRoot();
+        case 'summarizer':
+            return getConfigValue(`summarizer.${parsed.property}`).value;
         case 'device': {
             const configName = devicePropertyToConfigName(parsed.property);
             return getConfigValue(configName, { device: parsed.device }).value;
@@ -287,6 +303,13 @@ function* listCentralConfigEntries() {
         const key = 'browser.device';
         yield { key, value: browserDevice, hint: configKeyStorageHint(parseConfigKey(key)) };
     }
+    // Session-summarizer keys (PHNX-3939) — user scope, syncs fleet-wide.
+    for (const key of ['summarizer.enabled', 'summarizer.baseUrl', 'summarizer.model']) {
+        const value = getConfigValue(key).value;
+        if (value !== undefined) {
+            yield { key, value, hint: configKeyStorageHint(parseConfigKey(key)) };
+        }
+    }
 }
 /** Collect device-scope config entries. */
 function* listDeviceConfigEntries(device) {

package/dist/commands/cost.js

@@ -11,12 +11,13 @@ export function registerCostCommand(insightsCmd) {
         .description('Roll up $ cost and duration across local agent sessions')
         .option('--json', 'Output the rollup as JSON')
         .option('--since <time>', 'Only sessions newer than this (e.g., 7d, 4w, or ISO date)')
-        .option('--by <dimension>', 'Group the breakdown by: agent (default), project, day, or account (the Claude org that produced each session)')
+        .option('--by <dimension>', 'Group the breakdown by: agent (default), project, day, model, or account (the Claude org that produced each session)')
         .addHelpText('after', `
 Examples:
   agents insights cost                   Daily histogram + top sessions + per-agent breakdown
   agents insights cost --since 30d       Last 30 days only
   agents insights cost --by project      Break down by project instead of agent
+  agents insights cost --by model --json Per-model output tokens and recorded cost
   agents insights cost --by day --json   Machine-readable daily rollup
 
 Cost is computed offline from a versioned per-model price table (${PRICING_VERSION}).
@@ -35,9 +36,9 @@ Cost is computed offline from a versioned per-model price table (${PRICING_VERSI
 function resolveGroup(by) {
     if (by === undefined)
         return 'agent';
-    if (by === 'agent' || by === 'project' || by === 'day' || by === 'account')
+    if (by === 'agent' || by === 'project' || by === 'day' || by === 'model' || by === 'account')
         return by;
-    console.error(chalk.red('error: --by must be one of: agent, project, day, account'));
+    console.error(chalk.red('error: --by must be one of: agent, project, day, model, account'));
     process.exit(1);
 }
 async function costAction(options) {
@@ -111,7 +112,8 @@ async function costAction(options) {
     const groupLabel = groupBy === 'agent' ? 'agent'
         : groupBy === 'project' ? 'project'
             : groupBy === 'account' ? 'account'
-                : 'day';
+                : groupBy === 'model' ? 'model'
+                    : 'day';
     out.push(chalk.bold(`By ${groupLabel}`));
     const cols = terminalWidth();
     const costW2 = Math.max(...breakdown.map(r => formatUsd(r.costUsd).length), 4);