@phnx-labs/agents-cli 1.22.49 → 1.22.51

package/CHANGELOG.md

@@ -1,5 +1,234 @@
 # Changelog
 
+## 1.22.51
+
+- **`publish-computer-helper-mac.sh` cuts the helper's own tag (PHNX-3228).**
+  It published `ComputerHelper.app.zip` to the CLI's `v<version>` release, but since the
+  client was repointed at per-helper tags the resolver asks for `computer-mac/v<x.y.z>`
+  (`helperTag` in `cli/src/lib/helper-versions.ts`). The asset therefore landed at an
+  address nothing requests, and there was **no way to cut a new computer-mac release at
+  all** — the last publisher still coupled to the CLI's version line. It now cuts
+  `computer-mac/v<x.y.z>`, requires the helper's version explicitly instead of defaulting
+  to `cli/package.json` (that default was the coupling), and refuses an existing tag, since
+  the upload uses `--clobber` and would otherwise replace a binary an installed CLI already
+  pins. Symmetric with `publish-computer-win.sh`. Source:
+  `cli/scripts/publish-computer-helper-mac.sh`.
+  It also cuts the tag itself now. `gh release create --verify-tag` refuses to invent a
+  tag absent from the remote, and nothing else pushed `computer-mac/v<x.y.z>` — `release.sh`
+  delegates helper tagging to "where the helper is released", which is this script. So it
+  ran green through build + notarize and then failed at the release step, meaning no new
+  helper version could be cut. The tag is pushed AFTER a successful build, deliberately:
+  pushing first would leave a published, immutable address with nothing behind it whenever
+  notarization failed.
+  Origin, not the local ref, is what makes a helper release immutable. Adding tag creation
+  introduced a wedge: a run that tagged and then failed to push left a local tag, and the
+  guard read that as "published" and told the operator to cut the next patch — burning a
+  version over a transient network error, and (since the guard precedes the build) making
+  that version uncuttable from the checkout without a manual `git tag -d`. A local-only tag
+  now resumes the interrupted publish instead.
+  Immutability keys on the published RELEASE, not the tag. A tag with no release is an
+  interrupted run — whether the push failed or the release creation did — and both now
+  resume rather than burning the version. The asset is what an installed CLI downloads, so
+  the release is the thing that must never be replaced.
+  The published-release check fails CLOSED. A non-zero `gh` is not evidence of absence —
+  unauthenticated, offline, and rate-limited all exit non-zero — so reading that as "not
+  published" would have carried on into `gh release upload --clobber` over a live binary,
+  the exact outcome the guard exists to prevent. Only an explicit not-found means not-found;
+  anything else stops the release and prints what `gh` actually said.
+
+- **`agents traces sync` retains and reports failed sessions instead of stranding them (PHNX-3267).**
+  The sync watermark advanced to the max mtime of *successful* uploads, so a later
+  success moved it past an earlier failed session and the next run's
+  `file_mtime_ms > watermark` filter skipped that session forever — the "failures are
+  retried" comment was false. A live 1.22.49 sync on a real device reported 11,073
+  uploaded and 6,050 errors with no way to tell a transcript cleaned off disk from a
+  genuine upload failure. Sync now records each failed session's identity and typed,
+  redacted evidence in the ledger and unions those retry-worthy ids back into the row
+  query regardless of the watermark, so a stranded session is re-attempted until it
+  succeeds. Failures are classified `transcript-unavailable` (the file is gone —
+  expected history, not re-read, aged out after 14 days), `parse-failed`, or
+  `upload-failed` (both retried); `agents traces sync` prints the breakdown
+  (`… errors (N transcripts no longer on disk · M parse/upload failures — will retry)`)
+  and `agents traces status` lists the outstanding retry set with example detail.
+  Source: `cli/src/lib/traces/sync.ts`, `cli/src/commands/traces.ts`.
+
+- **Helper binaries no longer download through a repository-rename redirect.**
+  `HELPER_RELEASE_REPO` still named `phnx-labs/agents-cli` after the repository was renamed
+  to `phnx-labs/agi-cli`. Nothing was broken — GitHub redirects a renamed repo, and both
+  slugs returned HTTP 200 — but every signed helper asset (`MenubarHelper.app.zip`,
+  `Agents_CLI.app.zip`, `ComputerHelper.app.zip`, `computer-helper-win.exe`) was resolving
+  through that redirect, which is one re-created repository away from pointing elsewhere.
+  What actually protects the download is the sha256 + `codesign` + designated-requirement +
+  Team ID verification in `helper-download.ts`; this removes the reliance on the redirect.
+  The `agents.yaml` `$schema` URL, the CHANGELOG link, the star nudge, and the
+  `package.json` repository/issues metadata moved with it.
+  **The npm package name is deliberately unchanged** — it is still
+  `@phnx-labs/agents-cli`, and renaming it would orphan every installed CLI. That
+  distinction is now pinned by a test. Source: `cli/src/lib/helper-download.ts`.
+  `publish-computer-helper-mac.sh` carried the old slug too, and that one is a **write**
+  path: `REPO_SLUG` reaches `gh release view` (the immutability guard), `gh release create`,
+  and `gh release upload --clobber`. Publishing signed helper binaries was going through the
+  rename redirect. Found by sweeping `scripts/` and `.github/` after the source tree was
+  already clean — the source sweep alone would have missed it.
+  Three further live paths carried the old slug and were missed by the first sweep:
+  `ssh-tunnel.ts:170` `WIN_HELPER_RELEASE_REPO` (a **separately hardcoded** constant — the
+  download URL for `computer-helper-win.exe`, the fourth signed asset, which the first
+  version of this change claimed to cover and did not); `commands/feedback.ts:14`, which
+  opens real GitHub issues; and `factory/snapshot.ts:30`, which polls this repo's PRs.
+  `installations/migrate.ts` also wrote the old URL into the `agents.yaml` header it
+  generates. Separately, `.github/workflows/tests-windows-host-e2e.yml:54` gated on
+  `github.repository == 'phnx-labs/agents-cli'`, which is permanently false after a rename
+  — that job had silently stopped running on every push to main and on its daily cron.
+  The JSON Schema's own `$id` moved with it — `state.ts` and `migrate.ts` write that URL as
+  the `$schema` hint into every user's `agents.yaml`, so a mismatched `$id` would make
+  editors reject their own config.
+
+- **The menu-bar helper's staleness check compares the HELPER's version, not the CLI's
+  (RUSH-3230).** `installAndStartService` stamped `getCliVersion()` as the installed
+  helper's version, and `menubarSetupStale()` compared against `getCliVersion()` too. Once
+  helpers gained their own version line that was wrong in both directions: every CLI
+  release made an unchanged helper look stale and reinstalled it — recopying the bundle
+  under the running helper, which `KeepAlive` then restarts (the #2109 storm: a new pid
+  every 5-15s, 578 launches in one log) — while a genuinely newer helper at the same CLI
+  version never looked stale at all, so it could never install.
+  The stamp is now JSON recording what the helper actually IS: `release` with its helper
+  version, or `local` with the source path + mtime for a dev build (menubar's build.sh
+  hardcodes `CFBundleShortVersionString`, so a local build has no version to compare).
+  Staleness compares like with like, treats a kind change (local <-> release) as stale, and
+  never downgrades when the installed helper is ahead of the floor. A pre-JSON stamp is
+  stale exactly once and is re-stamped in the new format, so the migration cannot loop.
+  `agents menubar status` / `doctor` now print three labelled lines — helper installed,
+  helper available, CLI version — instead of conflating two axes into one, and the
+  permanent false "(mismatch — `agents menubar setup` updates it)" hint is gone.
+  Source: `cli/src/lib/menubar/install-menubar.ts`.
+
+- **The Windows helper's "asset missing" error names a tag that exists (RUSH-3230).**
+  `downloadWinHelperExe` built its error message from `` `v${version}` `` — the CLI's tag
+  shape — while the URL it had just tried came from `helperTag('computer-win', version)`.
+  So a genuine 404 sent the reader looking for `v1.0.0`, which does not exist, instead of
+  `computer-win/v1.0.0`, which does. The mac path was corrected when helpers moved to their
+  own tags; the Windows path was left behind. Also drops a `getCliVersion` import that had
+  no call site — the last trace of the old CLI-version coupling in that file.
+  Source: `cli/src/lib/computer/ssh-tunnel.ts`.
+
+- **Claude status-line delegate no longer fork-bombs the machine.** The delegate
+  self-reference guard compared the saved command against the exact literal
+  `agents __claude-statusline`, so a delegate seeded with the same private
+  subcommand under a *different* binary name (e.g. `agents-dev __claude-statusline`
+  from a dev install, or an absolute path) was not recognized as us. Every
+  status-line render then `spawnSync`ed that command, which read the same delegate
+  and spawned another — unbounded recursion. Observed on a real box: ~4,900 live
+  `node __claude-statusline` processes accumulated over a 2-day uptime, exhausting
+  96 GB of swap and driving load past 300, so keystrokes lagged. The guard now
+  matches the `__claude-statusline` subcommand under any binary name or path
+  (`isStatusLineSelfReference`), `installClaudeStatusLine` refuses to persist such
+  a command as a delegate (and deletes an already-poisoned delegate on re-install),
+  a `AGENTS_CLAUDE_STATUSLINE_DELEGATED` env marker hard-caps delegation at one hop,
+  and the delegate `spawnSync` now carries a 5 s timeout. Source:
+  `cli/src/lib/claude-statusline.ts`.
+
+## 1.22.50
+
+### Fixed
+
+- **Teams now persist observed teammate failure evidence and keep independent DAG branches moving.** Placement, local/remote launch, cloud dispatch, dependency, and process-exit failures carry a stable code, sanitized message, exit code, retryability, and observation time in `teams status` text/JSON. A runnable node with a durable placement failure fails independently; a node blocked only by pool capacity or load stays pending with retryable evidence so a later wave can launch it. Descendants name failed or missing `--after` blockers instead of spinning until `--max-waves`. `teams start` (no `--watch`) reports teammates that failed during the wave in a `Failed this wave` section (JSON: `failed[]` with evidence) and exits non-zero when a wave produced only failures. Because a failed launch now keeps its record (evidence) instead of deleting it, re-running the identical `teams add --name <name>` after a failure requires `teams remove <team> <name>` first.
+  Successfully resuming a failed teammate clears the prior attempt's evidence as
+  the replacement enters `running`; a replacement that fails to launch restores
+  the original terminal state and evidence intact.
+
+- **Register the Phoenix session with Prix after sync (PHNX-3257).** A successful
+  (non-dry-run) `agents traces sync` now fire-and-forget POSTs the Phoenix bearer
+  to `api.prix.dev/api/v1/traces/link`, so the Prix web console can mint a token
+  and serve live trajectories instead of fixtures. Scoped to the managed Phoenix
+  backend only — a BYO/self-hosted `AGENTS_TRACES_WRITE_TOKEN` is never sent to
+  Prix. Source: `cli/src/lib/traces/sync.ts`.
+
+- **Ship `traces-daily-sync` routine (PHNX-3258).** Daily `agents traces sync` at 02:00 UTC
+  to accumulate `bucketHistory` for drift signals; requires a device pin
+  (`agents routines devices traces-daily-sync --set <name>`) before it fires.
+  Source: `cli/routines/traces-daily-sync.yml`.
+
+- **`--strategy balanced` now spreads across your provider accounts, not just
+  native logins (RUSH-3182).** A setup-token or API-key account added with
+  `agents accounts add` is now a first-class balancing candidate for every harness
+  its provider can authenticate — claude, codex, grok, cursor, opencode (a harness
+  with only a native login and no provider adapter, like kimi, keeps balancing its
+  native logins). Before, balanced only rotated across accounts that sat in a version
+  home, so a worker's shared setup-tokens never participated and `--account`
+  couldn't select them. The run path folds those provider accounts into the
+  candidate list and injects the picked one through the existing `--account` path
+  (a setup-token still authenticates via `CLAUDE_CODE_OAUTH_TOKEN`); the other
+  candidate consumers — the watchdog, session recovery, teams placement — keep the
+  native-only list, so nothing else changes. On a box dominated by verified native
+  logins a usage-less provider account is deprioritized until the daemon fetches
+  its usage; on a worker (setup-token majority) it participates immediately.
+  Source: `cli/src/lib/accounting/account-pool.ts`,
+  `cli/src/lib/accounting/account-pool-collect.ts`,
+  `cli/src/lib/accounting/rotate.ts`, `cli/src/commands/exec.ts`.
+
+- **The attestation producer skips the helper manifest by default too (RUSH-3216).**
+  `release.sh` gained `--with-helpers` so an ordinary release does no helper work, but
+  `release-attestation-produce.sh` kept the same unconditional
+  `release-manifest.sh` verification — so the coupling survived one step upstream. Found
+  live: a one-line **comment** fix in `native/computer-mac/scripts/build.sh` (an
+  `apps/cli/` → `cli/` path in prose) changed that helper's input digest and aborted an
+  otherwise-clean 1.22.49 attestation, for a helper the tarball no longer ships and the
+  CLI resolves from its own tag. The producer now takes the same `--with-helpers` flag,
+  default off. Source: `cli/scripts/release-attestation-produce.sh`.
+
+- **`scripts/publish-computer-win.sh` — a publish path for the Windows helper (RUSH-3228).**
+  Its release now triggers on `computer-win/v<x.y.z>` rather than the CLI's `v*` tag, but
+  nothing in the repo cut such a tag, so the trigger would have been dead — trading a
+  wasteful 165 MB rebuild on every CLI release for no rebuild at all. The tag *is* the
+  publish action (`release-exe` builds, smokes on a real windows-latest runner, and
+  uploads the exe + sha256), so a mis-shaped tag is a silent no-op: the script refuses a
+  `v`-prefixed or non-semver version, refuses an existing tag because the upload uses
+  `--clobber` and an installed CLI may already pin it, and is dry-run by default.
+  Symmetric with `publish-computer-helper-mac.sh`. Source: `cli/scripts/publish-computer-win.sh`.
+
+- **`scripts/test.sh --shard <n>` — fan the suite across n fleet workers (RUSH-3230).**
+  Uses vitest's own `--shard=i/n`, drawing workers from the same auto pool a single
+  `--device auto` run uses, so `role=worker`/`role=personal` marks govern the fan-out too.
+  This is the change that moves release time, and the reason is arithmetic: a measured full
+  run is 3,079s of CPU at 11.5× parallelism on one box, so wall equals CPU/workers (269s) —
+  the suite is **throughput-bound**, not bound by any single slow file. Adding boxes divides
+  the CPU: 3 ≈ 93s, 6 ≈ 47s, 9 ≈ 31s. Shards run concurrently and every one is waited on
+  before reporting, so a failure in one does not hide the others. Requires `agents` ≥ 1.22.49
+  for `devices pick --json`; an older CLI fails naming the version and the fix rather than
+  passing through a commander error. Source: `cli/scripts/test.sh`.
+- **`scripts/test.sh --devices a,b,c` — name the shard workers explicitly (RUSH-3230).**
+  Pins the fan-out to known-idle boxes instead of auto-picking, and skips the
+  `devices pick --json` dependency, so sharding also works from a machine whose installed
+  CLI predates 1.22.49. Source: `cli/scripts/test.sh`.
+- **`--shard` fails loud on a count below 2 and on a conflicting target flag (RUSH-3230).**
+  `--shard 0` previously passed the numeric check, ran zero shards, and still printed
+  `All 0 shards passed.` with exit 0 — a false green that reported success having run no
+  tests. It now requires at least 2 (a single worker is `--device auto`). Separately, `MODE`
+  was last-write-wins with no cross-flag validation, so `--shard 6 --device box` silently
+  dropped one of the two purely on argument order; conflicting target flags now die naming
+  both. Source: `cli/scripts/test.sh`.
+- **`--devices` obeys the same 2-worker floor, and is validated before prerequisites (RUSH-3230).**
+  `--devices onebox` derived the shard count from the list length and skipped the floor
+  entirely, running a one-shard fan-out. The list is now resolved and checked immediately
+  after argument parsing rather than inside the dispatch branch, so a bad invocation reports
+  its own problem instead of dying on a missing `rsync` first. Source: `cli/scripts/test.sh`.
+
+- **Split `ssh.device-config.test.ts`, the second-slowest file (RUSH-3230).** 18 subprocess
+  tests in one file at ~44s locally (151s on a loaded worker) — 8.4s *per test*. Now three
+  files along its existing `describe` boundaries (per-device config / fleet-wide defaults +
+  role + describe / retired-subcommand tombstones) over a shared
+  `device-config-test-harness.ts`: **45s → 19s wall, all 18 tests still passing**, none
+  changed, skipped, or dropped. Source: `cli/src/commands/device-config-test-harness.ts`.
+
+- **Split `daemon.test.ts`, the suite's floor (RUSH-3230).** It was 35 subprocess tests in
+  one file at ~53s locally (159s on a loaded worker) — the slowest file in the repo, and
+  therefore the whole suite's floor, because vitest parallelises across *files* and runs
+  one file's tests sequentially in a single worker. Now three files by theme (command
+  surface / services + webhooks / doctor + logs) over a shared
+  `daemon-test-harness.ts`, so they run concurrently: **53.5s → 26s wall, all 35 tests
+  still passing**. No test was changed, skipped, or dropped. Source:
+  `cli/src/commands/daemon-test-harness.ts`.
+
 ## 1.22.49
 
 - **Check CLI benchmark numbers into `docs/benchmarks.md` (RUSH-2385).** Commander-bootstrap and audit-hook means from the yosemite-s1 vitest bench (PR #2349) plus pointers to OPT-01/OPT-02 live in git. Linear is not the ledger. Source: `cli/docs/benchmarks.md`.

package/README.md

@@ -741,6 +741,16 @@ Teammates run detached -- close your terminal, they keep working. Check in with
 
 Team state is observable via `agents teams list --json` / `agents teams status --json` (compact by default; add `--verbose` for the full per-teammate shape). External tools join it with `sessions --json` (teammates get `isTeamOrigin: true`) and `cloud list --json` (for `--cloud` teammates) to build a unified fleet view. See [docs/observability.md](cli/docs/observability.md).
 
+Placement, spawn, dependency, and non-zero-exit failures are persisted as sanitized
+evidence on the teammate record and shown by `teams status`. A failed root does not stop
+independent DAG branches; descendants name the failed or missing `--after` dependency
+that blocked them instead of remaining pending indefinitely. Capacity- or load-blocked
+placement stays pending with retryable evidence and is reconsidered on the next wave.
+`teams start` reports
+teammates that failed during the wave (`Failed this wave` / JSON `failed[]`) and exits
+non-zero when a wave produced only failures. A failed teammate keeps its record as
+evidence, so re-adding the same name needs `teams remove <team> <name>` first.
+
 ---
 
 ## Cloud

package/dist/bootstrap.js

@@ -322,7 +322,7 @@ async function showWhatsNew(fromVersion, toVersion) {
             for (const line of relevantChanges) {
                 console.log(line);
             }
-            console.log(chalk.gray('\nFull notes: https://github.com/phnx-labs/agents-cli/blob/main/CHANGELOG.md'));
+            console.log(chalk.gray('\nFull notes: https://github.com/phnx-labs/agi-cli/blob/main/CHANGELOG.md'));
             console.log();
         }
     }

package/dist/commands/accounts.js

@@ -18,7 +18,7 @@ import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
 import { runDevicesAccounts } from './ssh.js';
 import { discoverNativeAccounts } from '../lib/account-catalog.js';
 import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
-import { getAccountProvider, listAccountProviders } from '../lib/account-provider-registry.js';
+import { getAccountProvider, listAccountProviders, providerAuthenticatesHarness } from '../lib/account-provider-registry.js';
 import { accountBindings, addAccount, addNativeAccount, bindAccount, findAccount, findUnifiedAccount, inspectAccount, labelNativeAccount, listNativeAccounts, readAccountRegistry, removeAccount, renameAccount, setAccountSecret, unbindAccount } from '../lib/account-registry.js';
 function cleanCommandError(command, err) {
     command.error(err instanceof Error ? err.message : String(err), { exitCode: 1, code: 'accounts.error' });
@@ -288,18 +288,6 @@ async function pickLabelIdentity(agent, identities) {
         throw err;
     }
 }
-function providerAuthenticatesHarness(provider, auth, agent) {
-    try {
-        getAccountProvider(provider).envFor(agent, auth);
-        return true;
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (message.includes('cannot authenticate'))
-            return false;
-        throw err;
-    }
-}
 /** Every account (native + provider) registered/usable for this harness, oldest-first by name. */
 function accountsForHarness(agent) {
     const meta = readMeta();

package/dist/commands/browser.d.ts

@@ -1,6 +1,16 @@
 import { Command } from 'commander';
 import { type BrowserProfile } from '../lib/browser/profiles.js';
 import { listInstalledBrowsers } from '../lib/browser/chrome.js';
+/**
+ * The fleet browser hub this box drives by default (`browser.device`), or
+ * undefined to drive locally. It is one fleet-synced value in the central
+ * agents.yaml, so every box reads the same hub name — but the hub itself resolves
+ * to a self-host, and a fleet-dispatched invocation is already ON its target, so
+ * both return undefined. That self short-circuit is what lets a single synced
+ * value be safe: only the boxes that are NOT the hub forward to it, and the hub
+ * never forwards to itself.
+ */
+export declare function defaultBrowserHub(): string | undefined;
 export declare function registerBrowserCommand(program: Command): void;
 export declare function registerBrowserSubcommands(program: Command): void;
 interface BrowserUseOptions {

package/dist/commands/browser.js

@@ -248,6 +248,23 @@ function assertDeviceDeclaresProfile(device, profileName) {
     throw new Error(`Device "${device}" does not declare browser profile "${profileName}". ${where}\n` +
         `Next: run \`agents browser profiles add ${profileName} --browser <b>\` on ${device}.`);
 }
+/**
+ * The fleet browser hub this box drives by default (`browser.device`), or
+ * undefined to drive locally. It is one fleet-synced value in the central
+ * agents.yaml, so every box reads the same hub name — but the hub itself resolves
+ * to a self-host, and a fleet-dispatched invocation is already ON its target, so
+ * both return undefined. That self short-circuit is what lets a single synced
+ * value be safe: only the boxes that are NOT the hub forward to it, and the hub
+ * never forwards to itself.
+ */
+export function defaultBrowserHub() {
+    if (isFleetRemoteInvocation())
+        return undefined;
+    const hub = getConfigValue('browser.device').value;
+    if (!hub || isSelfHost(hub))
+        return undefined;
+    return hub;
+}
 // Help groups — surfaces the actual mental model an agent follows
 // ("open a session / drive the page / capture evidence / rare extras")
 // instead of an alphabetical dump. Everything not listed falls into a
@@ -356,7 +373,14 @@ export async function runBrowserUse(name, opts, interactive = isInteractiveTermi
             console.log(current
                 ? `Default browser profile (this machine): ${current}`
                 : 'Default browser profile (this machine): auto-detect');
+            const hub = getConfigValue('browser.device').value;
+            if (hub) {
+                console.log(isSelfHost(hub)
+                    ? `Browser hub (browser.device): ${hub} — this machine, so drives locally`
+                    : `Browser hub (browser.device): ${hub} — bare \`agents browser start\` drives ${hub}'s browser`);
+            }
             console.log('Usage: agents browser use <name>  (or --unset)');
+            console.log('Fleet hub: agents config set browser.device <device>  (drive that box\'s browser from every machine)');
             return true;
         }
         const choices = buildBrowserUseChoices(await listProfiles(), listInstalledBrowsers(), current);
@@ -1353,7 +1377,7 @@ function registerTaskCommands(browser) {
         .option('--title <label>', 'Human label shown in `browser status` (defaults to first navigated host)')
         .option('-e, --endpoint <name>', 'Endpoint preset (defaults to the profile\'s default)')
         .option('-u, --url <url>', 'Open URL in first tab')
-        .option('--device <name>', 'Device that hosts this task; later verbs resolve it from --task (not valid on page verbs)')
+        .option('--device <name>', 'Device that hosts this task (defaults to the browser.device hub when set; use `local` to force this machine). Later verbs resolve it from --task; not valid on page verbs')
         .option('--fresh', 'Always open a new tab, skipping the reclaim of a tab an abandoned task is holding on that URL')
         .option('--no-skills', 'Skip auto-discovery of site-specific SKILL.md from ~/.agents/skills/browser/domain-skills/')
         .option('--record', 'Start recording right after the tab opens (shorthand for `agents browser record start` as a follow-up)')
@@ -1373,6 +1397,54 @@ function registerTaskCommands(browser) {
             console.error(err instanceof Error ? err.message : String(err));
             process.exit(1);
         }
+        // Thin-client hub (PHNX-2010): when this box has a fleet browser hub
+        // (`browser.device`) and the caller gave no explicit --device, forward the
+        // WHOLE start there — bare OR --profile — and skip the local profile/browser
+        // resolution below. The hub owns its profiles, browser, and consent, so this
+        // box needs no local browser and need not carry the named profile; forwarding
+        // the local pre-checks here would reject a profile that lives only on the hub.
+        // Later page verbs follow the task to the hub via the task→device index bound
+        // here. `--device local`/`--device self` (below) force a local run instead;
+        // `defaultBrowserHub()` is undefined on the hub itself and on a fleet-remote
+        // re-exec, so neither forwards to itself.
+        if (!opts.device) {
+            const hub = defaultBrowserHub();
+            if (hub) {
+                // No local profile validation: the hub is the authority on its own
+                // profiles (including fleet-scoped ones this box can't see in
+                // `declaringDevices`), so a bad `--profile` is caught by the hub's own
+                // start and streamed back with its exit code, rather than second-guessed
+                // here against a registry that doesn't carry the hub's profiles.
+                try {
+                    const result = await dispatchBrowserToDevice(hub, browserForwardedArgv(), 'capture');
+                    process.stdout.write(result.stdout);
+                    process.stderr.write(result.stderr);
+                    if (result.code !== 0)
+                        process.exit(result.code);
+                    const taskName = opts.task || result.stdout.trim().split('\n').find((line) => line.length > 0);
+                    if (!taskName) {
+                        console.error(`Remote start on ${hub} produced no task name.`);
+                        process.exit(1);
+                    }
+                    bindTask(taskName, {
+                        device: hub,
+                        // Only what the caller named; the hub's own default (bare start) is
+                        // opaque here. Name-based `done`/`stop --task` and the post-stop
+                        // unbind GC these regardless.
+                        profile: opts.profile,
+                        url: opts.url,
+                        sessionId: callerSessionId(),
+                        launchId: callerLaunchId(),
+                        createdAt: Date.now(),
+                    });
+                }
+                catch (err) {
+                    console.error(err instanceof Error ? err.message : String(err));
+                    process.exit(1);
+                }
+                return;
+            }
+        }
         // One resolution order for every command (RUSH-2709): `--profile default`
         // means the same profile here as it does in stop / status / navigate.
         // `start` is the one command that LAUNCHES, so its implicit path goes
@@ -1409,7 +1481,10 @@ function registerTaskCommands(browser) {
                 process.exit(1);
             }
         }
-        const deviceName = opts.device;
+        // The `browser.device` hub default is applied above (bare/--profile, no
+        // --device). Here only an EXPLICIT --device remains — with `local`/`self` as
+        // the escape that forces a local run when a hub is configured.
+        const deviceName = opts.device === 'local' || opts.device === 'self' ? undefined : opts.device;
         if (deviceName) {
             const lowered = deviceName.toLowerCase();
             if (lowered === 'all' || lowered === 'auto') {

package/dist/commands/config.js

@@ -111,6 +111,11 @@ function setConfig(parsed, value) {
             return;
         }
         case 'browser': {
+            if (parsed.property === 'device') {
+                // Fleet hub: user scope, one central value, never peer-targeted.
+                setConfigValue('browser.device', value);
+                return;
+            }
             // Device-local default lives in the per-device doc's config: block
             // (same store `agents devices config` / getConfigValue use). Bare
             // browser.profile targets this machine; devices.<name>.browser.profile
@@ -155,6 +160,11 @@ function unsetConfig(parsed) {
             return had;
         }
         case 'browser': {
+            if (parsed.property === 'device') {
+                const had = getConfigValue('browser.device').value !== undefined;
+                unsetConfigValue('browser.device');
+                return had;
+            }
             const target = parsed.device ? { device: parsed.device } : undefined;
             // Must follow parsed.property. Hardcoding 'browser.profile' here meant
             // `config unset browser.viewer` deleted the user's browser.profile while
@@ -195,6 +205,9 @@ function getConfig(parsed) {
         case 'auto':
             return getConfigValue('auto.pool').value;
         case 'browser': {
+            if (parsed.property === 'device') {
+                return getConfigValue('browser.device').value;
+            }
             return getConfigValue(parsed.property === 'viewer' ? 'browser.viewer' : 'browser.profile', parsed.device ? { device: parsed.device } : undefined).value;
         }
         case 'project':
@@ -267,6 +280,13 @@ function* listCentralConfigEntries() {
         const key = 'browser.viewer';
         yield { key, value: browserViewer, hint: configKeyStorageHint(parseConfigKey(key)) };
     }
+    // Fleet browser hub — user scope, so it belongs in the central listing next to
+    // its siblings. Omitting it repeats the browser.viewer invisibility bug.
+    const browserDevice = getConfigValue('browser.device').value;
+    if (browserDevice !== undefined) {
+        const key = 'browser.device';
+        yield { key, value: browserDevice, hint: configKeyStorageHint(parseConfigKey(key)) };
+    }
 }
 /** Collect device-scope config entries. */
 function* listDeviceConfigEntries(device) {

package/dist/commands/daemon-test-harness.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared harness for the `agents daemon` CLI subprocess suites (RUSH-2354).
+ *
+ * Every test spawns the real CLI against an isolated mkdtemp HOME with no
+ * daemon running — no mocks. Modeled on routines.test.ts.
+ *
+ * EXTRACTED so the suite can live in several files. `daemon.test.ts` was 35
+ * tests in ONE file at 159s — the slowest file in the repo and therefore the
+ * SUITE'S FLOOR, because vitest parallelises across files and runs the tests
+ * inside one file sequentially in a single worker. Splitting the tests across
+ * files lets them run concurrently; sharing the harness is what makes that
+ * possible without duplicating the spawn plumbing.
+ */
+import { spawnSync, type ChildProcess } from 'child_process';
+export declare const REPO_ROOT: string;
+export declare const TSX_IMPORT: string;
+export declare const CLI_ENTRYPOINT: string;
+/**
+ * win32: subprocess CLI + process-group signals / path spawn assumptions
+ * (RUSH-2215). Exported as a PREDICATE, not as a pre-bound `describe.skip` —
+ * vitest's suite type is not nameable across a module boundary (TS4023), so
+ * each suite builds its own `describe` from this.
+ */
+export declare const DAEMON_TESTS_SUPPORTED: boolean;
+/** Provision an isolated HOME with just enough scaffolding for the CLI to boot. */
+export declare function makeHome(): string;
+/** Run `agents daemon <args>` against an isolated HOME — no daemon process ever started. */
+export declare function run(home: string, args: string[]): ReturnType<typeof spawnSync>;
+/**
+ * Spawn a real, long-lived process whose command line ends in `__daemon-run`
+ * (so `isDaemonRunProcess`'s `ps` check accepts it — see
+ * `lib/daemon.test.ts`'s "reaps a live __daemon-run registrant" test, same
+ * technique) and register it in `home`'s OWN instance registry, exactly the
+ * marker `registerDaemonInstance` would write. A real live process, not a
+ * mock — `agents daemon status` reads it through the actual registry +
+ * `ps`-liveness path, the same one the reaper and `stopDaemon`'s postcondition
+ * use.
+ */
+export declare function spawnFakeRegisteredDaemon(home: string): Promise<ChildProcess>;
+/** Register a pid in `home`'s instance registry — the scope stale/duplicate reporting uses. */
+export declare function registerInstance(home: string, pid: number): void;
+export declare function killFakeDaemon(child: ChildProcess): void;

package/dist/commands/daemon-test-harness.js

@@ -0,0 +1,90 @@
+/**
+ * Shared harness for the `agents daemon` CLI subprocess suites (RUSH-2354).
+ *
+ * Every test spawns the real CLI against an isolated mkdtemp HOME with no
+ * daemon running — no mocks. Modeled on routines.test.ts.
+ *
+ * EXTRACTED so the suite can live in several files. `daemon.test.ts` was 35
+ * tests in ONE file at 159s — the slowest file in the repo and therefore the
+ * SUITE'S FLOOR, because vitest parallelises across files and runs the tests
+ * inside one file sequentially in a single worker. Splitting the tests across
+ * files lets them run concurrently; sharing the harness is what makes that
+ * possible without duplicating the spawn plumbing.
+ */
+import { spawnSync, spawn } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { createRequire } from 'module';
+export const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const require = createRequire(import.meta.url);
+export const TSX_IMPORT = pathToFileURL(require.resolve('tsx')).href;
+export const CLI_ENTRYPOINT = path.join(REPO_ROOT, 'src', 'index.ts');
+/**
+ * win32: subprocess CLI + process-group signals / path spawn assumptions
+ * (RUSH-2215). Exported as a PREDICATE, not as a pre-bound `describe.skip` —
+ * vitest's suite type is not nameable across a module boundary (TS4023), so
+ * each suite builds its own `describe` from this.
+ */
+export const DAEMON_TESTS_SUPPORTED = process.platform !== 'win32';
+/** Provision an isolated HOME with just enough scaffolding for the CLI to boot. */
+export function makeHome() {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-daemon-test-'));
+    fs.mkdirSync(path.join(home, '.agents', '.system', '.git'), { recursive: true });
+    fs.writeFileSync(path.join(home, '.agents', 'agents.yaml'), 'agents: {}\n');
+    return home;
+}
+/** Run `agents daemon <args>` against an isolated HOME — no daemon process ever started. */
+export function run(home, args) {
+    return spawnSync('node', ['--import', TSX_IMPORT, CLI_ENTRYPOINT, 'daemon', ...args], {
+        cwd: REPO_ROOT,
+        env: {
+            ...process.env,
+            HOME: home,
+            USERPROFILE: home,
+            AGENTS_SKIP_MIGRATION: '1',
+            AGENTS_NO_AUTOPULL: '1',
+            AGENTS_CLI_DISABLE_AUTO_UPDATE: '1',
+            AGENTS_DAEMON_DIR: path.join(home, '.agents', '.cache', 'helpers', 'daemon'),
+        },
+        encoding: 'utf-8',
+        timeout: 30_000,
+    });
+}
+/**
+ * Spawn a real, long-lived process whose command line ends in `__daemon-run`
+ * (so `isDaemonRunProcess`'s `ps` check accepts it — see
+ * `lib/daemon.test.ts`'s "reaps a live __daemon-run registrant" test, same
+ * technique) and register it in `home`'s OWN instance registry, exactly the
+ * marker `registerDaemonInstance` would write. A real live process, not a
+ * mock — `agents daemon status` reads it through the actual registry +
+ * `ps`-liveness path, the same one the reaper and `stopDaemon`'s postcondition
+ * use.
+ */
+export async function spawnFakeRegisteredDaemon(home) {
+    const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1e9)', '__daemon-run'], {
+        stdio: 'ignore',
+    });
+    // Give the exec a moment to land before `ps` (read by the status command's
+    // isDaemonRunProcess check) is asked to see its real argv — mirrors
+    // lib/daemon.test.ts's identical fake-daemon technique.
+    await new Promise((r) => setTimeout(r, 150));
+    const instancesDir = path.join(home, '.agents', '.cache', 'helpers', 'daemon', 'instances');
+    fs.mkdirSync(instancesDir, { recursive: true });
+    fs.writeFileSync(path.join(instancesDir, String(child.pid)), '__daemon-run', 'utf-8');
+    return child;
+}
+/** Register a pid in `home`'s instance registry — the scope stale/duplicate reporting uses. */
+export function registerInstance(home, pid) {
+    const dir = path.join(home, '.agents', '.cache', 'helpers', 'daemon', 'instances');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, String(pid)), '__daemon-run', 'utf-8');
+}
+export function killFakeDaemon(child) {
+    try {
+        if (child.pid)
+            process.kill(child.pid, 'SIGKILL');
+    }
+    catch { /* already gone */ }
+}

package/dist/commands/device-config-test-harness.d.ts

@@ -0,0 +1,11 @@
+export declare const REPO_ROOT: string;
+export declare const INDEX: string;
+export declare function guardedHome(): void;
+export declare function run(args: string[], extraEnv?: Record<string, string>): {
+    stdout: string;
+    stderr: string;
+    status: number | null;
+};
+export declare function centralDoc(): string;
+export declare function deviceDoc(name: string): string;
+export declare function addDevice(name: string, target?: string): void;