@phnx-labs/agents-cli 1.20.67 → 1.20.69

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # Changelog
 
+## 1.20.69
+
+- **Choose a safe account with `agents run <agent>@`.** A trailing `@` opens a
+  per-run picker showing each installed version's account identity, login state,
+  plan, and available session/weekly/monthly capacity. Logged-out, rate-limited,
+  and out-of-credit accounts remain visible but disabled; signed-in accounts
+  without quota data remain selectable and say `limits unavailable`. Source:
+  `apps/cli/src/commands/run-account-picker.ts`,
+  `apps/cli/src/commands/exec.ts`, `apps/cli/src/lib/rotate.ts`.
+
+- **The macOS `agents computer` helper now ships as a signed + notarized release asset,
+  downloaded on demand.** A fresh `npm i -g @phnx-labs/agents-cli` no longer needs to build
+  the Swift helper from source: `agents computer setup` / `agents setup computer` fetch
+  `ComputerHelper.app.zip` from the matching `v<version>` GitHub release, verify it against
+  the published `.sha256`, and re-check the code signature (Developer ID Team `2HTP252L87`)
+  and notarization (`spctl --assess`) before it is ever copied to /Applications — mirroring
+  the Windows helper's distribution. The download cache is never a trusted resolver source;
+  a cached bundle is only ever read back through the verifying downloader. The helper is
+  version-stamped at build time and the release pipeline publishes the asset automatically.
+  Source: `apps/cli/src/lib/computer/download.ts`, `apps/cli/src/lib/computer-rpc.ts`,
+  `apps/cli/src/commands/computer.ts`, `native/computer-mac/scripts/build.sh`,
+  `apps/cli/scripts/publish-computer-helper-mac.sh`, `apps/cli/scripts/release.sh`.
+
+- **Live fleet auth health (`agents fleet ping`) + `agents view` chip (#1285).** New `agents fleet ping` completes a real authenticated request for every agent account across the fleet — the ground truth the local "signed in" flag can't give (it can't tell a revoked-but-unexpired token from a good one). Claude/Kimi/Droid are network-verified; Codex/Grok are best-effort. `agents view` now shows a live-status chip per version, read from the shared cache the ping writes. The probe hits the usage endpoint (no model tokens, no session created). Source: `apps/cli/src/lib/auth-health.ts`, `apps/cli/src/commands/ssh.ts`, `apps/cli/src/commands/view.ts`.
+
+- **`agents fork` — branch a session into a new independent copy.** Copies a Claude
+  session transcript to a fresh session id (rewriting only the `sessionId` field so the
+  per-message uuid chain stays intact) beside the original, then registers it so it
+  resumes independently from the same cwd and version — the original is left untouched.
+  `--name` labels the fork. Source: `apps/cli/src/lib/session/fork.ts`,
+  `apps/cli/src/commands/fork.ts`.
+
+- **`agents setup` is now a capability hub with guided `browser` / `computer` / `share`
+  subcommands.** Bare `agents setup` still clones the system repo and imports unmanaged
+  agents, but on a TTY it now also offers to set up the optional capabilities a fresh
+  machine needs. Each is also runnable on its own and is idempotent (re-run to change
+  settings): `agents setup browser` detects an installed Chromium-family browser and
+  creates/points the `default` profile; `agents setup share` provisions or joins a
+  Cloudflare share endpoint (reusing `agents share setup`/`join`); `agents setup computer`
+  installs the macOS helper and walks you through the Accessibility + Screen-Recording
+  grants — opening the exact System Settings panes and polling until trust lands. The
+  existing `agents share setup` / `agents computer setup` remain for scripted use. Source:
+  `apps/cli/src/commands/setup.ts`, `setup-browser.ts`, `setup-computer.ts`,
+  `setup-share.ts`, `apps/cli/src/lib/browser/chrome.ts`, `apps/cli/src/commands/share.ts`.
+
+## 1.20.68
+
+- **MCP resource handler now syncs project-level agent configs alongside user-level configs (RUSH-671).** `McpHandler.sync` previously wrote resolved MCP servers only to the version-home (user-level) config path. It now also writes project-layer MCP servers to each agent CLI's project-level config path (e.g., `.mcp.json` for Claude, `.codex/config.toml` for Codex) so agent CLIs can discover project-scoped MCPs natively. User-level sync is unchanged. Source: `apps/cli/src/lib/resources/mcp.ts`, `apps/cli/src/lib/agents.ts` (`getProjectMcpConfigPath` exported), `apps/cli/src/lib/resources/mcp.test.ts`.
+- **Production MCP sync path also writes project-level configs.** `installMcpServers` now merges project-layer servers into the agent's project-level config file, using a shared `writeMcpConfig` serializer with overwrite/merge modes. OpenClaw serialization is corrected to nest under `mcp.servers`, matching the existing reader; Grok/OpenClaw user-level configs are written directly with merge mode so multiple servers don't clobber each other; and `installMcpServers` only reports `applied` for agents it actually wrote a config for. Source: `apps/cli/src/lib/mcp.ts`, `apps/cli/src/lib/mcp.test.ts`.
+
+- **Accurate account tier and legible usage limits in `agents view`.** Each row's plan
+  tier is now derived from `organizationType` (Max/Pro/Team/Enterprise) instead of a
+  billingType guess that mislabelled every Max account as "Pro", and the redundant tier
+  badge next to the email is dropped for personal plans (multi-seat orgs keep their org
+  name, which is real identity). The compact `S:`/`W:` usage bars now show the exact
+  percentage and a compact reset hint (`S: ███░░ 58% (3d)`), a signed-in account whose
+  usage can't be fetched reads `usage unavailable` instead of a blank gauge, and a new
+  `agents view --refresh` (`-r`) forces a live usage refresh past the cache. Source:
+  `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/usage.ts`, `apps/cli/src/commands/view.ts`.
+
+- **Fleet health status and drift gate.** `agents fleet status` now renders a fleet-wide warnings rollup plus a device matrix for reachability, resource headroom, sync drift, CLI readiness, and agents-cli version skew; `--json` emits the same report for scripts and `--strict` exits non-zero when any warning is present. `agents check --devices` now fans the existing drift gate across registered devices and exits non-zero when any device is drifted or unreachable. Source: `apps/cli/src/commands/ssh.ts`, `apps/cli/src/commands/check.ts`, `apps/cli/src/lib/devices/fleet.ts`, `apps/cli/src/lib/devices/health-report.ts`.
+
+- **Login state per agent — `agents doctor` shows signed-in/logged-out, and `agents run` warns before launching into a logged-out account.** `agents doctor`'s **Agent CLIs** section now renders a `✓ signed in <account>` / `✗ logged out` badge per installed agent (also surfaced in `--json` under `signIn`), and an interactive `agents run <agent>` now prints a one-line stderr warning — `⚠ <agent> looks logged out — log in with: <cmd>. Launching anyway...` — when the account looks logged out, so you find out **before** the TUI opens instead of after typing a prompt and getting `/login` back. It is advisory (file-based `getAccountInfo`, no Keychain ACL prompt) and **never blocks**: skipped for `--json`/`--quiet`, when a rotation already picked a signed-in account, for `--host`/`--lease`, and via `--no-auth-check` / `AGENTS_NO_AUTH_CHECK=1`. `agents view`'s logged-out line now names the exact login command too. One shared badge/hint renderer keeps all three surfaces consistent across claude, codex, kimi, grok, opencode, and gemini. Source: `apps/cli/src/lib/signin-badge.ts` (+ `signin-badge.test.ts`), `apps/cli/src/commands/exec.ts`, `apps/cli/src/commands/doctor.ts`, `apps/cli/src/commands/view.ts`.
+
+- **`agents repos add` adopts an existing checkout instead of dead-ending.** When
+  the target `~/.agents-<alias>/` already holds a git repo whose origin matches the
+  requested source, `repos add` now registers it in place (no re-clone) rather than
+  erroring `Directory already exists`. A repo with a *different* origin is left
+  untouched unless you pass `--adopt`. This removes the trap that forced a second,
+  inconsistent install method when a repo had been cloned by hand. Remote matching
+  is transport-agnostic (SSH and HTTPS forms of the same repo compare equal). Source:
+  `apps/cli/src/commands/repo.ts`, `apps/cli/src/lib/git.ts`.
+
+- **`--json` for `repos list` and `plugins list`.** Both list commands now emit
+  machine-readable JSON with `--json`, matching the `repos view --json` /
+  `plugins marketplaces --json` that already existed — so an agent can enumerate
+  registered repos (with per-repo sync/drift state) and installed plugins (with
+  per-agent-version sync targets) without scraping the human table. Source:
+  `apps/cli/src/commands/repo.ts`, `apps/cli/src/commands/plugins.ts`.
+
+- **`teams add --remote-cwd` now fails loud instead of silently doing nothing.** The
+  flag rides the shared `--host` option family but `teams add` treats
+  `--host`/`--device` as placement and never reads it, so passing it used to be a
+  silent no-op that misled you into thinking it set the teammate's repo path. It is
+  now rejected with guidance (place with `--device`, set the code with the team's
+  `--repo`, one team per repo). The shared `--remote-cwd` help also warns that a
+  local `~` expands on your machine, not the remote host — pass a single-quoted
+  `'$HOME/…'` path or a valid remote absolute path. Teams docs + skill lead with
+  this. Source: `apps/cli/src/commands/teams.ts` (`remoteCwdOnAddError`),
+  `apps/cli/src/lib/hosts/option.ts`, `apps/cli/docs/teams.md`, `skills/teams/SKILL.md`.
+
+- **No more CLIXML blobs from Windows hosts.** A remote `agents …` invocation
+  routed to a Windows box (`--host win-mini`, `agents doctor --devices`,
+  `agents fleet status`) no longer comes back wrapped in a raw `#< CLIXML <Objs …>`
+  envelope. PowerShell 5.1 serializes its progress stream ("Preparing modules for
+  first use.") to CLIXML when stderr is a captured pipe rather than a console; the
+  Windows command builder now silences that stream (`$ProgressPreference =
+  'SilentlyContinue'`) so failures read as plain text for humans and the JSON
+  parsers that consume the output. Source: `apps/cli/src/lib/hosts/remote-cmd.ts`.
+
 ## 1.20.67
 
 - **Interactive session browser — `agents sessions --active` and a bare `agents sessions`

package/README.md

@@ -151,10 +151,18 @@ agents run claude "refactor auth module" --mode edit --fallback codex,gemini
 ```bash
 # Picks the signed-in account you haven't used recently.
 agents run claude "summarize recent commits" --strategy balanced
+
+# Or choose one account/version interactively for only this run.
+agents run claude@
+agents run codex@ "review this branch"
 ```
 
 `--strategy balanced` spreads work across available versions of the same agent -- useful when you have multiple accounts and want to avoid burning through one.
 
+A trailing `@` opens an account picker before either an interactive or prompt-based run. Each installed version shows its account identity, exact version, login state, plan, and every available session, weekly, or monthly limit. Logged-out, rate-limited, and out-of-credit accounts remain visible with the reason they cannot be selected; signed-in accounts whose provider does not expose quota data stay selectable and say `limits unavailable`. The choice pins only that run and does not change your default version.
+
+Account selection is available for Claude, Codex, Gemini, Grok, Antigravity, Kimi, Droid, and OpenCode. It requires a terminal and cannot be combined with `--resume`, `--strategy`/`--balanced`, `--lease`, or `--host`/`--device`; profiles and workflows must use their concrete host agent instead.
+
 ### Chain agents
 
 ```bash
@@ -424,6 +432,9 @@ agents sync --host gpu-box              # make the remote machine current
 agents doctor --devices                 # readiness matrix for every registered device
 agents doctor --devices --json          # machine-readable fleet readiness
 agents doctor --device mac-mini         # same matrix, scoped to one device
+agents fleet status                     # warnings rollup + health/sync/version matrix
+agents fleet status --json --strict     # scriptable fleet health gate
+agents check --devices                  # CI drift gate across every registered device
 
 # Your Tailscale fleet, auto-discovered
 agents devices sync                     # ingest `tailscale status`
@@ -431,7 +442,9 @@ agents devices list                     # fleet + live headroom: load, mem, idle
 agents devices list --full              # add per-device cores and free/total RAM
 agents devices list --no-stats          # instant: names/addresses only, skip the probe
 agents ssh mac-mini                     # hardened SSH: fails fast if offline,
-                                        # PowerShell on Windows, password-from-Keychain
+                                        # PowerShell on Windows, password-from-Keychain,
+                                        # auto-syncs your terminfo (Ghostty/kitty/…) so
+                                        # backspace, colors & clear work on the remote
 agents hosts list                       # devices show up here too (one host pool)
 agents hosts add mac-mini --cap gpu     # tag a device for capability routing (--host gpu)
 

package/dist/commands/check.js

@@ -2,6 +2,11 @@ import chalk from 'chalk';
 import { AGENTS, ALL_AGENT_IDS } from '../lib/agents.js';
 import { setHelpSections } from '../lib/help.js';
 import { computeDrift } from '../lib/drift.js';
+import { loadDevices } from '../lib/devices/registry.js';
+import { fanOutDevices, planFleetTargets, remoteFleetTargets } from '../lib/devices/fleet.js';
+import { machineId } from '../lib/session/sync/config.js';
+import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
+import { sshExecAsync } from '../lib/ssh-exec.js';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
 function label(row) {
     return `${AGENT_NAMES[row.agent] || row.agent}@${row.version}`;
@@ -12,7 +17,8 @@ export function registerCheckCommand(program) {
         .description('CI drift gate: exit non-zero when any installed version is out of sync (stale or never-synced), zero when clean.')
         .option('--json', 'Output machine-readable JSON')
         .option('-q, --quiet', 'Suppress per-version lines; print only the one-line verdict')
-        .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())');
+        .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())')
+        .option('--devices', 'Run the drift gate across every registered online device');
     setHelpSections(checkCmd, {
         examples: `
       # Fail the build if anything drifted (exit 1), pass if clean (exit 0)
@@ -24,12 +30,19 @@ export function registerCheckCommand(program) {
       # Machine-readable, for scripting
       agents check --json
 
+      # Gate every registered device
+      agents check --devices
+
       # Gate in a CI step
       agents check || { echo "resources drifted — run 'agents doctor --fix'"; exit 1; }
     `,
     });
-    checkCmd.action((opts) => {
+    checkCmd.action(async (opts) => {
         const cwd = opts.cwd ? opts.cwd : process.cwd();
+        if (opts.devices) {
+            await runDevicesCheck(opts, cwd);
+            return;
+        }
         const drift = computeDrift(cwd);
         if (opts.json) {
             console.log(JSON.stringify({
@@ -82,3 +95,84 @@ export function registerCheckCommand(program) {
         process.exit(1);
     });
 }
+function checkPayload(device, drift) {
+    return {
+        device,
+        hasDrift: drift.hasDrift,
+        stale: drift.staleCount,
+        neverSynced: drift.neverSyncedCount,
+        orphanVersions: drift.orphanVersionCount,
+    };
+}
+async function probeDeviceCheck(target) {
+    const isWin = /^win/i.test((target.platform ?? '').trim());
+    const remoteCmd = buildRemoteAgentsInvocation(['check', '--json'], undefined, isWin ? 'windows' : undefined, isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' });
+    const res = await sshExecAsync(target.name, remoteCmd, { timeoutMs: 30000, multiplex: true });
+    if (res.code !== 0 && !res.stdout.trim()) {
+        throw new Error(res.timedOut ? 'timed out' : (res.stderr.trim() || `exit ${res.code ?? 'unknown'}`));
+    }
+    try {
+        const parsed = JSON.parse(res.stdout);
+        return {
+            device: target.name,
+            hasDrift: Boolean(parsed.hasDrift),
+            stale: parsed.stale ?? 0,
+            neverSynced: parsed.neverSynced ?? 0,
+            orphanVersions: parsed.orphanVersions ?? 0,
+        };
+    }
+    catch (err) {
+        throw new Error(`invalid JSON (${err?.message ?? 'parse error'})`);
+    }
+}
+async function runDevicesCheck(opts, cwd) {
+    const registry = await loadDevices();
+    const self = machineId();
+    const planned = planFleetTargets(registry);
+    const local = checkPayload(self, computeDrift(cwd));
+    const remoteTargets = remoteFleetTargets(planned, self)
+        .map((t) => ({
+        name: t.device.name,
+        platform: t.device.platform,
+        skip: t.skip,
+    }));
+    const remote = await fanOutDevices(remoteTargets, probeDeviceCheck);
+    const devices = [local];
+    for (const result of remote) {
+        if (result.status === 'ok' && result.value) {
+            devices.push(result.value);
+        }
+        else {
+            devices.push({
+                device: result.name,
+                hasDrift: true,
+                stale: 0,
+                neverSynced: 0,
+                orphanVersions: 0,
+                error: result.error ?? String(result.reason ?? 'skipped'),
+            });
+        }
+    }
+    const hasDrift = devices.some((d) => d.hasDrift || d.error);
+    if (opts.json) {
+        console.log(JSON.stringify({ hasDrift, devices }, null, 2));
+        process.exit(hasDrift ? 1 : 0);
+    }
+    if (!hasDrift) {
+        console.log(chalk.green('ok') + chalk.gray(`  ${devices.length} device(s) in sync`));
+        process.exit(0);
+    }
+    console.error(chalk.red('drift') + chalk.gray(`  ${devices.filter((d) => d.hasDrift || d.error).length} of ${devices.length} device(s)`));
+    if (!opts.quiet) {
+        for (const d of devices) {
+            if (!d.hasDrift && !d.error)
+                continue;
+            const detail = d.error
+                ? d.error
+                : [`${d.stale} stale`, `${d.neverSynced} never-synced`].filter((p) => !p.startsWith('0 ')).join(', ');
+            console.error(`  ${chalk.yellow(d.device.padEnd(18))} ${detail || 'drift'}`);
+        }
+        console.error(chalk.gray('\nReconcile each device with `agents doctor --fix` or `agents repo pull user`.'));
+    }
+    process.exit(1);
+}

package/dist/commands/computer.d.ts

@@ -38,5 +38,31 @@ export declare function reconcileScreenshotExt(outPath: string, buf: Buffer): {
 export declare function registerComputerCommand(program: Command): void;
 export declare function registerComputerSubcommands(program: Command): void;
 export declare function buildRestartTaskScript(taskName: string, exeName: string): string;
+/**
+ * Install the macOS helper locally: resolve (or download + verify) the signed,
+ * notarized .app, copy it to /Applications, verify the destination signature,
+ * and write the LaunchAgent plist (inactive — activation is a separate opt-in
+ * step via `start`). Throws on any failure. Shared by `agents computer setup`
+ * and the unified `agents setup computer` wizard so there is one install path.
+ */
+export declare function installComputerHelperMacLocal(): Promise<{
+    appDest: string;
+    plistPath: string;
+}>;
+/**
+ * Activate the local helper daemon via launchd (render policy + peers, bootout
+ * → bootstrap → kickstart, wait for the socket, probe AX trust). Throws on any
+ * failure. Returns the trust status so callers can guide the permission grant.
+ * Shared by `agents computer start` and the `agents setup computer` wizard.
+ */
+export declare function activateComputerHelperMacLocal(): Promise<{
+    trusted: boolean;
+    socketPath: string;
+    logPath: string;
+}>;
+/** Probe the running daemon's Accessibility trust status without re-activating.
+ * Returns false (never throws) if the socket is down or the RPC errors — used to
+ * poll while the user grants permissions in System Settings. */
+export declare function probeComputerTrust(): Promise<boolean>;
 export { resolveHelperExec as resolveHelperPath };
 export { resolveSocketPath };

package/dist/commands/computer.js

@@ -441,6 +441,172 @@ const HELPER_BUNDLE_ID = 'com.phnx-labs.computer-helper';
 const HELPER_APP_NAME = 'Computer Helper.app';
 const HELPER_APP_DEST = `/Applications/${HELPER_APP_NAME}`;
 const HELPER_LABEL = HELPER_BUNDLE_ID;
+/**
+ * Install the macOS helper locally: resolve (or download + verify) the signed,
+ * notarized .app, copy it to /Applications, verify the destination signature,
+ * and write the LaunchAgent plist (inactive — activation is a separate opt-in
+ * step via `start`). Throws on any failure. Shared by `agents computer setup`
+ * and the unified `agents setup computer` wizard so there is one install path.
+ */
+export async function installComputerHelperMacLocal() {
+    let srcApp = resolveHelperApp();
+    if (!srcApp || !fs.existsSync(srcApp)) {
+        // No local build / bundled copy (the normal case on an npm-installed CLI).
+        // Fetch the signed + notarized helper release asset for this CLI version;
+        // it is sha256- and signature-verified before we touch /Applications.
+        const { ensureMacHelperApp } = await import('../lib/computer/download.js');
+        srcApp = await ensureMacHelperApp();
+        console.log(`helper:  ${srcApp} (downloaded + verified)`);
+    }
+    const socketPath = resolveSocketPath();
+    const logPath = resolveLogPath();
+    const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', `${HELPER_LABEL}.plist`);
+    console.log(`source:  ${srcApp}`);
+    console.log(`dest:    ${HELPER_APP_DEST}`);
+    // 1. Copy to /Applications/ via ditto (preserves xattrs + codesign metadata).
+    if (fs.existsSync(HELPER_APP_DEST)) {
+        try {
+            fs.rmSync(HELPER_APP_DEST, { recursive: true, force: true });
+        }
+        catch (err) {
+            throw new Error(`failed to remove prior install at ${HELPER_APP_DEST}: ${err.message}. try: sudo rm -rf "${HELPER_APP_DEST}"`);
+        }
+    }
+    try {
+        execFileSync('/usr/bin/ditto', [srcApp, HELPER_APP_DEST], { stdio: 'inherit' });
+    }
+    catch (err) {
+        throw new Error(`ditto copy failed: ${err.message}`);
+    }
+    console.log(`copied to ${HELPER_APP_DEST}`);
+    // 2. Verify codesign on the destination — TCC needs a valid signature.
+    try {
+        execFileSync('/usr/bin/codesign', ['--verify', '--deep', '--strict', HELPER_APP_DEST], { stdio: 'inherit' });
+        console.log('codesign verify: OK');
+    }
+    catch {
+        throw new Error(`codesign verify FAILED for ${HELPER_APP_DEST}. The destination .app is unsigned or its signature was stripped.`);
+    }
+    // 3. Ensure socket + log parent dirs exist.
+    fs.mkdirSync(path.dirname(socketPath), { recursive: true });
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    // 4. Write the LaunchAgent plist but DO NOT bootstrap it (opt-in via `start`).
+    const execInsideApp = path.join(HELPER_APP_DEST, 'Contents', 'MacOS', 'ComputerHelper');
+    const plistContent = renderLaunchAgentPlist({ label: HELPER_LABEL, exec: execInsideApp, socketPath, logPath });
+    fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+    fs.writeFileSync(plistPath, plistContent);
+    console.log(`wrote plist: ${plistPath} (NOT activated)`);
+    return { appDest: HELPER_APP_DEST, plistPath };
+}
+/**
+ * Activate the local helper daemon via launchd (render policy + peers, bootout
+ * → bootstrap → kickstart, wait for the socket, probe AX trust). Throws on any
+ * failure. Returns the trust status so callers can guide the permission grant.
+ * Shared by `agents computer start` and the `agents setup computer` wizard.
+ */
+export async function activateComputerHelperMacLocal() {
+    const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', `${HELPER_LABEL}.plist`);
+    const socketPath = resolveSocketPath();
+    const logPath = resolveLogPath();
+    if (!fs.existsSync(plistPath))
+        throw new Error(`plist not found at ${plistPath}. run: agents computer setup`);
+    if (!fs.existsSync(HELPER_APP_DEST))
+        throw new Error(`helper app not found at ${HELPER_APP_DEST}. run: agents computer setup`);
+    const uid = process.getuid?.();
+    if (typeof uid !== 'number')
+        throw new Error('cannot resolve uid');
+    const domain = `gui/${uid}`;
+    // Render the policy file BEFORE bootstrap so the daemon reads a fresh allow
+    // list at startup (fail-safe: missing/unparseable → everything denied).
+    const allowed = loadComputerAllowList();
+    writeComputerPolicy(allowed);
+    console.log(`policy: ${allowed.length} app${allowed.length === 1 ? '' : 's'} allowed (${resolvePolicyPath()})`);
+    if (allowed.length > 0) {
+        const preview = allowed.slice(0, 5).join(', ');
+        const more = allowed.length > 5 ? ` (+${allowed.length - 5} more)` : '';
+        console.log(`        ${preview}${more}`);
+    }
+    else {
+        console.log(`        (no Computer(...) patterns found — everything will be denied)`);
+        console.log(`        add to ~/.agents/permissions/groups/<name>.yaml under allow:`);
+        console.log(`          - "Computer(com.apple.finder)"`);
+    }
+    // Peer-auth allow list — which caller executables may connect to the socket.
+    const callers = loadDefaultPeers();
+    writeComputerPeers(callers);
+    console.log(`peers:  ${callers.length} caller${callers.length === 1 ? '' : 's'} allowed (${resolvePeersPath()})`);
+    for (const p of callers)
+        console.log(`        ${p}`);
+    // Bootout first to clear any prior registration (best-effort).
+    try {
+        execFileSync('/bin/launchctl', ['bootout', domain, plistPath], { stdio: 'pipe' });
+    }
+    catch {
+        // expected when not previously loaded
+    }
+    try {
+        execFileSync('/bin/launchctl', ['bootstrap', domain, plistPath], { stdio: 'pipe' });
+    }
+    catch (err) {
+        throw new Error(`launchctl bootstrap failed: ${err.message}`);
+    }
+    // Force restart so we pick up the latest binary.
+    try {
+        execFileSync('/bin/launchctl', ['kickstart', '-k', `${domain}/${HELPER_LABEL}`], { stdio: 'pipe' });
+    }
+    catch (err) {
+        throw new Error(`launchctl kickstart failed: ${err.message}`);
+    }
+    // Wait up to 5s for the socket.
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline) {
+        if (fs.existsSync(socketPath))
+            break;
+        await sleep(100);
+    }
+    if (!fs.existsSync(socketPath)) {
+        throw new Error(`socket did not appear at ${socketPath} within 5s. check ${logPath} for helper startup errors`);
+    }
+    // Probe trust through the socket.
+    let trusted = false;
+    let trustStr = 'unknown';
+    try {
+        const client = openComputerClient();
+        try {
+            const r = await client.call('trust_status');
+            trusted = Boolean(r.result?.trusted);
+            trustStr = r.error ? `error (${r.error.code})` : (trusted ? 'granted' : 'denied');
+        }
+        finally {
+            await client.close();
+        }
+    }
+    catch (err) {
+        trustStr = `error (${err.message})`;
+    }
+    console.log(`daemon: running`);
+    console.log(`socket: ${socketPath}`);
+    console.log(`trust:  ${trustStr}`);
+    return { trusted, socketPath, logPath };
+}
+/** Probe the running daemon's Accessibility trust status without re-activating.
+ * Returns false (never throws) if the socket is down or the RPC errors — used to
+ * poll while the user grants permissions in System Settings. */
+export async function probeComputerTrust() {
+    try {
+        const client = openComputerClient();
+        try {
+            const r = await client.call('trust_status');
+            return Boolean(r.result?.trusted);
+        }
+        finally {
+            await client.close();
+        }
+    }
+    catch {
+        return false;
+    }
+}
 function registerSetupCommand(program) {
     program
         .command('setup')
@@ -462,66 +628,14 @@ function registerSetupCommand(program) {
             }
             return;
         }
-        const srcApp = resolveHelperApp();
-        if (!srcApp || !fs.existsSync(srcApp)) {
-            console.error('helper not built. Run: ./native/computer-mac/scripts/build.sh debug');
-            process.exit(1);
-        }
-        const home = os.homedir();
-        const socketPath = resolveSocketPath();
-        const logPath = resolveLogPath();
-        const plistPath = path.join(home, 'Library', 'LaunchAgents', `${HELPER_LABEL}.plist`);
-        console.log(`source:  ${srcApp}`);
-        console.log(`dest:    ${HELPER_APP_DEST}`);
-        // 1. Copy to /Applications/. Use ditto to preserve xattrs (Gatekeeper
-        // provenance + codesign metadata). Wipe any prior install first.
-        if (fs.existsSync(HELPER_APP_DEST)) {
-            try {
-                fs.rmSync(HELPER_APP_DEST, { recursive: true, force: true });
-                console.log(`removed prior install`);
-            }
-            catch (err) {
-                console.error(`failed to remove prior install at ${HELPER_APP_DEST}: ${err.message}`);
-                console.error('try: sudo rm -rf "' + HELPER_APP_DEST + '"');
-                process.exit(1);
-            }
-        }
+        let plistPath;
         try {
-            execFileSync('/usr/bin/ditto', [srcApp, HELPER_APP_DEST], { stdio: 'inherit' });
+            ({ plistPath } = await installComputerHelperMacLocal());
         }
         catch (err) {
-            console.error(`ditto copy failed: ${err.message}`);
-            process.exit(1);
-        }
-        console.log(`copied to ${HELPER_APP_DEST}`);
-        // 2. Verify codesign on the destination. Fail loud if the copy
-        // somehow stripped the signature — TCC needs a valid signature.
-        try {
-            execFileSync('/usr/bin/codesign', ['--verify', '--deep', '--strict', HELPER_APP_DEST], { stdio: 'inherit' });
-            console.log('codesign verify: OK');
-        }
-        catch {
-            console.error('codesign verify FAILED. The destination .app is unsigned or its signature was stripped.');
-            console.error('rebuild the helper with a Developer ID cert: ./native/computer-mac/scripts/build.sh release');
+            console.error(`error: ${err.message}`);
             process.exit(1);
         }
-        // 3. Ensure socket + log parent dirs exist.
-        fs.mkdirSync(path.dirname(socketPath), { recursive: true });
-        fs.mkdirSync(path.dirname(logPath), { recursive: true });
-        // 4. Write the LaunchAgent plist but DO NOT bootstrap it. The user
-        // explicitly opts into running the daemon via `agents computer start`.
-        // Screen Recording + Accessibility are scary permissions; we don't
-        // want an always-on listener that can drive any app the user could.
-        const execInsideApp = path.join(HELPER_APP_DEST, 'Contents', 'MacOS', 'ComputerHelper');
-        const plistContent = renderLaunchAgentPlist({
-            label: HELPER_LABEL,
-            exec: execInsideApp,
-            socketPath,
-            logPath,
-        });
-        fs.mkdirSync(path.dirname(plistPath), { recursive: true });
-        fs.writeFileSync(plistPath, plistContent);
-        console.log(`wrote plist: ${plistPath} (NOT activated)`);
         console.log('');
         console.log('Helper installed (inactive).');
         console.log('');
@@ -563,105 +677,15 @@ function registerStartCommand(program) {
             }
             return;
         }
-        const home = os.homedir();
-        const plistPath = path.join(home, 'Library', 'LaunchAgents', `${HELPER_LABEL}.plist`);
-        const socketPath = resolveSocketPath();
-        const logPath = resolveLogPath();
-        if (!fs.existsSync(plistPath)) {
-            console.error(`plist not found at ${plistPath}`);
-            console.error('run: agents computer setup');
-            process.exit(1);
-        }
-        if (!fs.existsSync(HELPER_APP_DEST)) {
-            console.error(`helper app not found at ${HELPER_APP_DEST}`);
-            console.error('run: agents computer setup');
-            process.exit(1);
-        }
-        const uid = process.getuid?.();
-        if (typeof uid !== 'number') {
-            console.error('cannot resolve uid');
-            process.exit(1);
-        }
-        const domain = `gui/${uid}`;
-        // Render the policy file BEFORE launchctl bootstrap so the daemon
-        // reads a fresh allow list at startup. The helper falls back to an
-        // empty allow list (everything denied) if this file is missing or
-        // unparseable — fail-safe.
-        const allowed = loadComputerAllowList();
-        writeComputerPolicy(allowed);
-        console.log(`policy: ${allowed.length} app${allowed.length === 1 ? '' : 's'} allowed (${resolvePolicyPath()})`);
-        if (allowed.length > 0) {
-            const preview = allowed.slice(0, 5).join(', ');
-            const more = allowed.length > 5 ? ` (+${allowed.length - 5} more)` : '';
-            console.log(`        ${preview}${more}`);
-        }
-        else {
-            console.log(`        (no Computer(...) patterns found — everything will be denied)`);
-            console.log(`        add to ~/.agents/permissions/groups/<name>.yaml under allow:`);
-            console.log(`          - "Computer(com.apple.finder)"`);
-        }
-        // Peer-auth allow list — which caller executables may connect to
-        // the socket. Default: this CLI's Node binary, plus Rush.app if
-        // installed. A `nc -U socket` from a malicious npm postinstall has
-        // a different exec path and gets refused at accept().
-        const callers = loadDefaultPeers();
-        writeComputerPeers(callers);
-        console.log(`peers:  ${callers.length} caller${callers.length === 1 ? '' : 's'} allowed (${resolvePeersPath()})`);
-        for (const p of callers)
-            console.log(`        ${p}`);
-        // Bootout first to clear any prior registration. Best-effort.
-        try {
-            execFileSync('/bin/launchctl', ['bootout', domain, plistPath], { stdio: 'pipe' });
-        }
-        catch {
-            // expected when not previously loaded
-        }
-        try {
-            execFileSync('/bin/launchctl', ['bootstrap', domain, plistPath], { stdio: 'pipe' });
-        }
-        catch (err) {
-            console.error(`launchctl bootstrap failed: ${err.message}`);
-            process.exit(1);
-        }
-        // Force restart so we pick up the latest binary.
+        let trusted;
         try {
-            execFileSync('/bin/launchctl', ['kickstart', '-k', `${domain}/${HELPER_LABEL}`], { stdio: 'pipe' });
+            ({ trusted } = await activateComputerHelperMacLocal());
         }
         catch (err) {
-            console.error(`launchctl kickstart failed: ${err.message}`);
+            console.error(`error: ${err.message}`);
             process.exit(1);
         }
-        // Wait up to 5s for the socket.
-        const deadline = Date.now() + 5000;
-        while (Date.now() < deadline) {
-            if (fs.existsSync(socketPath))
-                break;
-            await sleep(100);
-        }
-        if (!fs.existsSync(socketPath)) {
-            console.error(`socket did not appear at ${socketPath} within 5s`);
-            console.error(`check ${logPath} for helper startup errors`);
-            process.exit(1);
-        }
-        // Probe trust through the socket.
-        let trustStr = 'unknown';
-        try {
-            const client = openComputerClient();
-            try {
-                const r = await client.call('trust_status');
-                trustStr = r.error ? `error (${r.error.code})` : (r.result?.trusted ? 'granted' : 'denied');
-            }
-            finally {
-                await client.close();
-            }
-        }
-        catch (err) {
-            trustStr = `error (${err.message})`;
-        }
-        console.log(`daemon: running`);
-        console.log(`socket: ${socketPath}`);
-        console.log(`trust:  ${trustStr}`);
-        if (trustStr === 'denied') {
+        if (!trusted) {
             console.log('');
             console.log('Grant Accessibility + Screen Recording to Computer Helper.app, then run `agents computer start` again.');
         }