@phnx-labs/agents-cli 1.20.67 → 1.20.69

package/dist/lib/cli-entry.js

@@ -0,0 +1,116 @@
+/**
+ * Resolve how to re-invoke THIS `agents` CLI as a child process, correctly across
+ * both install shapes:
+ *
+ *   1. **JS install** — `agents` is a `dist/index.js` (or a symlink / `#!node`
+ *      shim to it). `process.execPath` is `node`, `process.argv[1]` is the script.
+ *      Relaunch as `node <entry> <sub…>`.
+ *   2. **Bun standalone binary** (#315) — `agents` is a compiled Mach-O/ELF/PE.
+ *      `process.execPath` is the physical signed binary, and `process.argv[1]` is
+ *      the *virtual* embedded entry `/$bunfs/root/agents`, which Bun reports as an
+ *      existing path. Passing that virtual path as an argv element makes the CLI
+ *      receive it as a subcommand and die with `unknown command '/$bunfs/root/agents'`.
+ *      Relaunch by executing the physical binary directly: `<binary> <sub…>`.
+ *
+ * Both `getDaemonLaunch` (daemon.ts) and the secrets-broker `cliSpawn`
+ * (secrets/agent.ts) route through here so the two never drift. This module is a
+ * leaf — it imports nothing from `lib/` — so it can be pulled into either without
+ * an import cycle (daemon.ts ↔ secrets/agent.ts already form one).
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+export const BUN_VIRTUAL_ROOT = /[/\\]\$bunfs[/\\]root[/\\]/;
+function resolveBunStandaloneEntry(entry, execPath) {
+    if (!BUN_VIRTUAL_ROOT.test(entry))
+        return entry;
+    if (!execPath || BUN_VIRTUAL_ROOT.test(execPath) || !fs.existsSync(execPath)) {
+        throw new Error(`Cannot resolve agents CLI: Bun standalone executable not found at ${execPath || '(empty path)'}`);
+    }
+    return execPath;
+}
+export function getAgentsBinPath(argv1 = process.argv[1], execPath = process.execPath) {
+    // Prefer the binary actively executing this code. `which agents` returns
+    // whatever happens to be first on PATH, which means a side-by-side dev
+    // build at ~/.local/bin would silently spawn the registry-installed
+    // daemon and run stale code. For a JS install, process.argv[1] is the
+    // absolute entrypoint the user actually invoked. A Bun standalone instead
+    // exposes its embedded /$bunfs/root entry at argv[1] and its physical signed
+    // executable at process.execPath; Bun reports both as existing paths.
+    const runningEntry = argv1 ? resolveBunStandaloneEntry(argv1, execPath) : undefined;
+    if (runningEntry && fs.existsSync(runningEntry)) {
+        // The package's browser/computer entrypoints are sibling shims without a
+        // `daemon` command. A daemon started as their IPC side effect must launch
+        // through the main agents entrypoint instead of replaying the shim path.
+        const entryName = path.basename(runningEntry);
+        const compiledShim = /^(browser|computer)\.(c|m)?js$/.test(entryName);
+        const installedShim = /^(browser|computer)$/.test(entryName);
+        if (compiledShim || installedShim) {
+            const agentsEntry = path.join(path.dirname(runningEntry), compiledShim ? 'index.js' : 'agents');
+            if (!fs.existsSync(agentsEntry)) {
+                throw new Error(`Cannot start agents daemon: main CLI entry not found at ${agentsEntry}`);
+            }
+            return agentsEntry;
+        }
+        return runningEntry;
+    }
+    try {
+        return execFileSync('which', ['agents'], { encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return 'agents';
+    }
+}
+/**
+ * A CLI entry must be launched through the Node runtime when it is a Node
+ * script — a `.js`/`.cjs`/`.mjs` file, OR a symlink/extension-less shim whose
+ * shebang names `node`. Package installs link `bin/agents` to a `dist/index.js`
+ * (a symlink) or drop an extension-less `#!/usr/bin/env node` shim, so an
+ * extension check alone misses them and they get run directly. A real compiled
+ * binary (Mach-O/ELF/PE) has no `#!node` shebang, so it takes the direct branch
+ * and owns its own runtime resolution.
+ */
+export function isNodeScriptEntry(agentsBin) {
+    let resolved = agentsBin;
+    try {
+        resolved = fs.realpathSync(agentsBin);
+    }
+    catch {
+        // Unresolvable (e.g. a template path that does not exist on this box): fall
+        // back to the extension check on the path as given.
+    }
+    if (/\.(c|m)?js$/.test(resolved))
+        return true;
+    try {
+        const fd = fs.openSync(resolved, 'r');
+        try {
+            const buf = Buffer.alloc(128);
+            const n = fs.readSync(fd, buf, 0, 128, 0);
+            const firstLine = buf.toString('utf-8', 0, n).split('\n', 1)[0];
+            return firstLine.startsWith('#!') && /\bnode\b/.test(firstLine);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build the `{ command, args }` to re-invoke this CLI with `sub` as its argv,
+ * resolving the JS-vs-standalone shape above. This is the single primitive behind
+ * both the daemon launch and the secrets-broker spawn — never hand-roll
+ * `[process.execPath, process.argv[1], …]`, which appends the bun virtual entry
+ * as a bogus subcommand on standalone builds.
+ */
+export function getCliLaunch(sub, agentsBin = getAgentsBinPath()) {
+    // Resolve a bun virtual entry to the physical executable even when a caller
+    // passes agentsBin explicitly (getAgentsBinPath already does this for the
+    // default), so a `/$bunfs/root/agents` never becomes the command or an argv.
+    const bin = resolveBunStandaloneEntry(agentsBin, process.execPath);
+    if (isNodeScriptEntry(bin)) {
+        return { command: process.execPath, args: [bin, ...sub] };
+    }
+    return { command: bin, args: [...sub] };
+}

package/dist/lib/computer/download.d.ts

@@ -0,0 +1,51 @@
+/**
+ * On-demand download + verification of the macOS `agents computer` helper
+ * ("ComputerHelper.app").
+ *
+ * The helper is a signed + notarized universal `.app` bundle published as a
+ * GitHub release asset per tagged CLI version — the same distribution model as
+ * the Windows helper (see `lib/ssh-tunnel.ts`). A fresh `npm i -g` machine has
+ * no local build, so `agents computer setup` / `agents setup computer` fetch the
+ * asset for the running CLI version, verify its sha256 against the published
+ * `.sha256`, then verify the code signature (Developer ID Team + notarization)
+ * before it is ever copied to /Applications.
+ *
+ * A `.app` is a directory, so the asset is a zip (`ditto -c -k --keepParent`);
+ * we extract it with `ditto -x -k` after the checksum passes.
+ */
+/** GitHub repo whose `v<version>` releases carry the helper asset. */
+export declare const HELPER_RELEASE_REPO = "phnx-labs/agents-cli";
+/** The zipped `.app` release asset name. */
+export declare const MAC_HELPER_ASSET = "ComputerHelper.app.zip";
+/** The bundle directory name once extracted. */
+export declare const MAC_HELPER_APP_NAME = "ComputerHelper.app";
+/** Apple Developer ID Team the helper must be signed by (defense in depth on top
+ * of `spctl` notarization assessment). "Developer ID Application: Muqit Nawaz". */
+export declare const EXPECTED_TEAM_ID = "2HTP252L87";
+/** Cache dir for the downloaded helper, one subdir per release tag. */
+export declare function macHelperCacheDir(version: string): string;
+/** Release-asset URLs for the helper zip + its checksum at one `v<version>` tag. */
+export declare function macHelperAssetUrls(version: string): {
+    zip: string;
+    sha256: string;
+};
+/**
+ * Verify a helper `.app` bundle is intact, signed by the expected Developer ID
+ * Team, and notarized (Gatekeeper-accepted). Throws with an actionable message
+ * on any failure — a downloaded bundle is never trusted without this.
+ */
+export declare function verifyMacHelper(appPath: string): void;
+/**
+ * Download the helper release asset for `version`, verify sha256, extract the
+ * `.app`, and verify its signature. Returns the path to the extracted
+ * `ComputerHelper.app`. A missing asset is a hard error naming the exact tag —
+ * never a silent fallback to another release.
+ */
+export declare function downloadMacHelperApp(version: string): Promise<string>;
+/**
+ * Resolve the helper `.app` to install from: a local build / bundled copy first
+ * (repo checkout), else the checksum + signature-verified release-asset download
+ * for the running CLI version. Throws with the tag it checked when neither
+ * exists. macOS only.
+ */
+export declare function ensureMacHelperApp(version?: string): Promise<string>;

package/dist/lib/computer/download.js

@@ -0,0 +1,145 @@
+/**
+ * On-demand download + verification of the macOS `agents computer` helper
+ * ("ComputerHelper.app").
+ *
+ * The helper is a signed + notarized universal `.app` bundle published as a
+ * GitHub release asset per tagged CLI version — the same distribution model as
+ * the Windows helper (see `lib/ssh-tunnel.ts`). A fresh `npm i -g` machine has
+ * no local build, so `agents computer setup` / `agents setup computer` fetch the
+ * asset for the running CLI version, verify its sha256 against the published
+ * `.sha256`, then verify the code signature (Developer ID Team + notarization)
+ * before it is ever copied to /Applications.
+ *
+ * A `.app` is a directory, so the asset is a zip (`ditto -c -k --keepParent`);
+ * we extract it with `ditto -x -k` after the checksum passes.
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { getCacheDir } from '../state.js';
+import { getCliVersion } from '../version.js';
+import { parseSha256Asset, sha256File } from '../ssh-tunnel.js';
+import { resolveHelperApp } from '../computer-rpc.js';
+/** GitHub repo whose `v<version>` releases carry the helper asset. */
+export const HELPER_RELEASE_REPO = 'phnx-labs/agents-cli';
+/** The zipped `.app` release asset name. */
+export const MAC_HELPER_ASSET = 'ComputerHelper.app.zip';
+/** The bundle directory name once extracted. */
+export const MAC_HELPER_APP_NAME = 'ComputerHelper.app';
+/** Apple Developer ID Team the helper must be signed by (defense in depth on top
+ * of `spctl` notarization assessment). "Developer ID Application: Muqit Nawaz". */
+export const EXPECTED_TEAM_ID = '2HTP252L87';
+/** Cache dir for the downloaded helper, one subdir per release tag. */
+export function macHelperCacheDir(version) {
+    return path.join(getCacheDir(), 'computer', 'mac-helper', `v${version}`);
+}
+/** Release-asset URLs for the helper zip + its checksum at one `v<version>` tag. */
+export function macHelperAssetUrls(version) {
+    const base = `https://github.com/${HELPER_RELEASE_REPO}/releases/download/v${version}`;
+    return { zip: `${base}/${MAC_HELPER_ASSET}`, sha256: `${base}/${MAC_HELPER_ASSET}.sha256` };
+}
+/**
+ * Verify a helper `.app` bundle is intact, signed by the expected Developer ID
+ * Team, and notarized (Gatekeeper-accepted). Throws with an actionable message
+ * on any failure — a downloaded bundle is never trusted without this.
+ */
+export function verifyMacHelper(appPath) {
+    // 1. Structural + signature integrity.
+    try {
+        execFileSync('/usr/bin/codesign', ['--verify', '--deep', '--strict', appPath], { stdio: 'pipe' });
+    }
+    catch (e) {
+        throw new Error(`code signature invalid for ${appPath}: ${e.message}`);
+    }
+    // 2. Team identity — must be our Developer ID, not some other valid signer.
+    let info = '';
+    try {
+        info = execFileSync('/usr/bin/codesign', ['-dv', '--verbose=4', appPath], { stdio: 'pipe' }).toString();
+    }
+    catch (e) {
+        // codesign -dv writes to stderr; capture whatever it emitted.
+        info = (e.stderr?.toString() ?? '') + (e.stdout?.toString() ?? '');
+        if (!info)
+            throw new Error(`could not read code signature of ${appPath}: ${e.message}`);
+    }
+    const team = info.match(/TeamIdentifier=([A-Z0-9]+)/)?.[1];
+    if (team !== EXPECTED_TEAM_ID) {
+        throw new Error(`helper signed by unexpected Team (${team ?? 'none'}), expected ${EXPECTED_TEAM_ID}. Refusing to install.`);
+    }
+    // 3. Notarization / Gatekeeper — confirms Apple stapled a notarization ticket.
+    try {
+        execFileSync('/usr/sbin/spctl', ['--assess', '--type', 'execute', '--verbose', appPath], { stdio: 'pipe' });
+    }
+    catch (e) {
+        throw new Error(`helper is not notarized / rejected by Gatekeeper: ${e.message}. Refusing to install.`);
+    }
+}
+/**
+ * Download the helper release asset for `version`, verify sha256, extract the
+ * `.app`, and verify its signature. Returns the path to the extracted
+ * `ComputerHelper.app`. A missing asset is a hard error naming the exact tag —
+ * never a silent fallback to another release.
+ */
+export async function downloadMacHelperApp(version) {
+    const dir = macHelperCacheDir(version);
+    const cachedApp = path.join(dir, MAC_HELPER_APP_NAME);
+    if (fs.existsSync(cachedApp)) {
+        // Re-verify a cached bundle cheaply; a tampered cache must not be trusted.
+        verifyMacHelper(cachedApp);
+        return cachedApp;
+    }
+    const tag = `v${version}`;
+    const { zip: zipUrl, sha256: shaUrl } = macHelperAssetUrls(version);
+    const missing = (status, url) => new Error(`no ${MAC_HELPER_ASSET} release asset for tag ${tag} (HTTP ${status} on ${url}). ` +
+        `The macOS helper ships as a GitHub release asset per tagged CLI version; ` +
+        `from a repo checkout you can build it locally instead: ` +
+        `bash native/computer-mac/scripts/build.sh release`);
+    // Checksum first: it is tiny and 404s fast when the tag has no assets.
+    const shaRes = await fetch(shaUrl, { signal: AbortSignal.timeout(30_000) });
+    if (!shaRes.ok)
+        throw missing(shaRes.status, shaUrl);
+    const expected = parseSha256Asset(await shaRes.text());
+    console.error(`Downloading ${MAC_HELPER_ASSET} ${tag} from GitHub releases...`);
+    const zipRes = await fetch(zipUrl, { signal: AbortSignal.timeout(15 * 60_000) });
+    if (!zipRes.ok || !zipRes.body)
+        throw missing(zipRes.status, zipUrl);
+    fs.mkdirSync(dir, { recursive: true });
+    const partial = path.join(dir, `${MAC_HELPER_ASSET}.download`);
+    try {
+        await pipeline(Readable.fromWeb(zipRes.body), fs.createWriteStream(partial));
+        const actual = await sha256File(partial);
+        if (actual !== expected) {
+            throw new Error(`sha256 mismatch for ${zipUrl}: expected ${expected}, got ${actual}`);
+        }
+        // Extract the zip (created with `ditto -c -k --keepParent`, so it contains
+        // ComputerHelper.app/ at top level) into the version cache dir.
+        fs.rmSync(cachedApp, { recursive: true, force: true });
+        execFileSync('/usr/bin/ditto', ['-x', '-k', partial, dir], { stdio: 'pipe' });
+        if (!fs.existsSync(cachedApp)) {
+            throw new Error(`extracted asset did not contain ${MAC_HELPER_APP_NAME}`);
+        }
+        verifyMacHelper(cachedApp);
+    }
+    finally {
+        fs.rmSync(partial, { force: true });
+    }
+    return cachedApp;
+}
+/**
+ * Resolve the helper `.app` to install from: a local build / bundled copy first
+ * (repo checkout), else the checksum + signature-verified release-asset download
+ * for the running CLI version. Throws with the tag it checked when neither
+ * exists. macOS only.
+ */
+export async function ensureMacHelperApp(version = getCliVersion()) {
+    if (os.platform() !== 'darwin') {
+        throw new Error('The macOS computer helper is only available on macOS.');
+    }
+    const local = resolveHelperApp();
+    if (local)
+        return local;
+    return downloadMacHelperApp(version);
+}

package/dist/lib/computer-rpc.js

@@ -163,14 +163,20 @@ export function writeComputerPeers(allowedExecPaths) {
     }
     fs.writeFileSync(resolvePeersPath(), JSON.stringify({ allow: allowedExecPaths }, null, 2), { mode: 0o600 });
 }
-// Resolve the helper executable inside the dist .app bundle. Used by the
-// stdio fallback and by install-helper to find the source bundle.
+// Resolve the helper executable inside the dist .app bundle. Used by the stdio
+// fallback and by install-helper to find the source bundle. Only TRUSTED sources
+// are listed here: a local checkout build and the bundled tarball copy. The
+// download cache is deliberately NOT a candidate — a cached bundle is
+// user-writable and must only ever be read through downloadMacHelperApp(), which
+// re-verifies its signature + Team ID + notarization on every cache hit
+// (lib/computer/download.ts). Listing the cache here would let a same-user
+// process plant a differently-signed .app that install-helper trusts.
 export function resolveHelperExec() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const candidates = [
         // Local build (running from the agents-cli checkout). apps/cli/dist/lib -> repo root (4 up) -> native/computer-mac.
         path.resolve(here, '..', '..', '..', '..', 'native', 'computer-mac', 'dist', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
-        // Bundled with the npm package (later: CDN download lands here).
+        // Bundled with the npm package.
         path.resolve(here, '..', 'computer-helper', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
     ];
     for (const c of candidates) {

package/dist/lib/daemon.d.ts

@@ -6,6 +6,7 @@
  * (macOS), systemd (Linux), or as a plain detached process. PID tracking,
  * log output, reload (SIGHUP), and graceful shutdown are handled here.
  */
+import { getAgentsBinPath } from './cli-entry.js';
 /** Read the stored daemon PID from disk. Returns null if not present or invalid. */
 export declare function readDaemonPid(): number | null;
 /** Write the daemon PID to the pid file. */
@@ -101,7 +102,7 @@ export declare function generateLaunchdPlist(agentsBin?: string): string;
  * store and never touches the unit file.
  */
 export declare function generateSystemdUnit(agentsBin?: string): string;
-export declare function getAgentsBinPath(argv1?: string | undefined, execPath?: string): string;
+export { getAgentsBinPath };
 /** Start the daemon via launchd, systemd, or as a detached process. */
 export declare function startDaemon(agentsBin?: string): {
     pid: number | null;
@@ -201,4 +202,3 @@ export declare function getDaemonStatus(): {
 export declare function readDaemonLog(lines?: number): string;
 /** Send SIGHUP to the daemon to trigger a job reload. */
 export declare function signalDaemonReload(): boolean;
-export {};

package/dist/lib/daemon.js

@@ -21,6 +21,7 @@ import { BrowserService } from './browser/service.js';
 import { BrowserIPCServer } from './browser/ipc.js';
 import { readAndResolveBundleEnv } from './secrets/bundles.js';
 import { redactSecrets } from './redact.js';
+import { getAgentsBinPath, getCliLaunch, BUN_VIRTUAL_ROOT } from './cli-entry.js';
 const PID_FILE = 'daemon.pid';
 const LOCK_FILE = 'daemon.lock';
 const LOG_FILE = 'logs.jsonl';
@@ -781,47 +782,11 @@ Environment=PATH=${daemonNodeBinDir()}:/usr/local/bin:/usr/bin:/bin
 [Install]
 WantedBy=default.target`;
 }
-const BUN_VIRTUAL_ROOT = /[/\\]\$bunfs[/\\]root[/\\]/;
-function resolveBunStandaloneEntry(entry, execPath) {
-    if (!BUN_VIRTUAL_ROOT.test(entry))
-        return entry;
-    if (!execPath || BUN_VIRTUAL_ROOT.test(execPath) || !fs.existsSync(execPath)) {
-        throw new Error(`Cannot resolve agents CLI: Bun standalone executable not found at ${execPath || '(empty path)'}`);
-    }
-    return execPath;
-}
-export function getAgentsBinPath(argv1 = process.argv[1], execPath = process.execPath) {
-    // Prefer the binary actively executing this code. `which agents` returns
-    // whatever happens to be first on PATH, which means a side-by-side dev
-    // build at ~/.local/bin would silently spawn the registry-installed
-    // daemon and run stale code. For a JS install, process.argv[1] is the
-    // absolute entrypoint the user actually invoked. A Bun standalone instead
-    // exposes its embedded /$bunfs/root entry at argv[1] and its physical signed
-    // executable at process.execPath; Bun reports both as existing paths.
-    const runningEntry = argv1 ? resolveBunStandaloneEntry(argv1, execPath) : undefined;
-    if (runningEntry && fs.existsSync(runningEntry)) {
-        // The package's browser/computer entrypoints are sibling shims without a
-        // `daemon` command. A daemon started as their IPC side effect must launch
-        // through the main agents entrypoint instead of replaying the shim path.
-        const entryName = path.basename(runningEntry);
-        const compiledShim = /^(browser|computer)\.(c|m)?js$/.test(entryName);
-        const installedShim = /^(browser|computer)$/.test(entryName);
-        if (compiledShim || installedShim) {
-            const agentsEntry = path.join(path.dirname(runningEntry), compiledShim ? 'index.js' : 'agents');
-            if (!fs.existsSync(agentsEntry)) {
-                throw new Error(`Cannot start agents daemon: main CLI entry not found at ${agentsEntry}`);
-            }
-            return agentsEntry;
-        }
-        return runningEntry;
-    }
-    try {
-        return execFileSync('which', ['agents'], { encoding: 'utf-8' }).trim();
-    }
-    catch {
-        return 'agents';
-    }
-}
+// Binary-resolution helpers (getAgentsBinPath / isNodeScriptEntry / getCliLaunch)
+// live in ./cli-entry.js — a leaf module the secrets broker also imports without
+// forming a cycle. Re-exported so existing `from './daemon.js'` importers of
+// getAgentsBinPath keep resolving.
+export { getAgentsBinPath };
 /**
  * Ask the service manager for the daemon's live PID. Used as a fallback when
  * the daemon hasn't yet written its pid file but launchd/systemd already report
@@ -980,49 +945,7 @@ export function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
     const { warnings } = validateDaemonBinary(agentsBin);
     for (const w of warnings)
         process.stderr.write(`[agents] ${w}\n`);
-    if (isNodeScriptEntry(agentsBin)) {
-        return { command: process.execPath, args: [agentsBin, 'daemon', '_run'] };
-    }
-    return { command: agentsBin, args: ['daemon', '_run'] };
-}
-/**
- * A daemon entry must be launched through the Node runtime when it is a Node
- * script — a `.js`/`.cjs`/`.mjs` file, OR a symlink/extension-less shim whose
- * shebang names `node`. Package installs link `bin/agents` to a `dist/index.js`
- * (a symlink) or drop an extension-less `#!/usr/bin/env node` shim, so an
- * extension check alone misses them and they get run directly. Executing such an
- * entry then relies on the shebang resolving `node` off the daemon's PATH — and
- * when that PATH points at a pruned nvm version (or an ancient system node), the
- * daemon crash-loops at import (`node:util` has no `styleText` on Node 18). A
- * real compiled binary (Mach-O/ELF/PE) has no `#!node` shebang, so it takes the
- * direct branch and owns its own runtime resolution.
- */
-function isNodeScriptEntry(agentsBin) {
-    let resolved = agentsBin;
-    try {
-        resolved = fs.realpathSync(agentsBin);
-    }
-    catch {
-        // Unresolvable (e.g. a template path that does not exist on this box): fall
-        // back to the extension check on the path as given.
-    }
-    if (/\.(c|m)?js$/.test(resolved))
-        return true;
-    try {
-        const fd = fs.openSync(resolved, 'r');
-        try {
-            const buf = Buffer.alloc(128);
-            const n = fs.readSync(fd, buf, 0, 128, 0);
-            const firstLine = buf.toString('utf-8', 0, n).split('\n', 1)[0];
-            return firstLine.startsWith('#!') && /\bnode\b/.test(firstLine);
-        }
-        finally {
-            fs.closeSync(fd);
-        }
-    }
-    catch {
-        return false;
-    }
+    return getCliLaunch(['daemon', '_run'], agentsBin);
 }
 /**
  * The directory of the Node runtime that generated this service manifest, kept
@@ -1050,11 +973,7 @@ function daemonNodeBinDir() {
  * getAgentsBinPath() resolves that virtual entry to the physical process.execPath.
  */
 export function getAgentsInvocation(subArgs, agentsBin = getAgentsBinPath()) {
-    const resolvedBin = resolveBunStandaloneEntry(agentsBin, process.execPath);
-    if (/\.(c|m)?js$/.test(resolvedBin)) {
-        return { command: process.execPath, args: [resolvedBin, ...subArgs] };
-    }
-    return { command: resolvedBin, args: subArgs };
+    return getCliLaunch(subArgs, agentsBin);
 }
 export function validateDaemonBinary(binPath) {
     const warnings = [];

package/dist/lib/devices/connect.d.ts

@@ -43,6 +43,21 @@ export declare function buildSshInvocation(device: DeviceProfile, cmd: string[],
     args: string[];
     env: Record<string, string>;
 };
+/**
+ * Build the askpass shim's `#!/bin/sh` body: a script that re-invokes this CLI
+ * as `agents ssh __askpass`. The relaunch argv comes from {@link getCliLaunch},
+ * never a hand-rolled `[process.execPath, process.argv[1], …]` — on a Bun
+ * standalone binary `process.argv[1]` is the *virtual* embedded entry
+ * `/$bunfs/root/agents`, which the CLI would then receive as a bogus subcommand
+ * (`unknown command '/$bunfs/root/agents'`), print nothing, and hand ssh an
+ * empty password. `getCliLaunch` resolves the physical executable so the shim
+ * works on both the standalone and JS/dev builds. Every argv element is
+ * shell-quoted. Pure (takes the launch as a parameter) so it is unit-testable.
+ */
+export declare function buildAskpassShimBody(launch?: {
+    command: string;
+    args: string[];
+}): string;
 /**
  * Write (idempotently) the askpass shim — a tiny executable that re-invokes
  * this CLI as `agents ssh __askpass`. ssh execs `SSH_ASKPASS` with no usable

package/dist/lib/devices/connect.js

@@ -16,6 +16,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { getCliLaunch } from '../cli-entry.js';
 import { encodePwshBase64 } from '../pwsh.js';
 import { getCacheDir } from '../state.js';
 import { hostKeyCheckingOpts } from './known-hosts.js';
@@ -92,6 +93,21 @@ export function buildSshInvocation(device, cmd, askpassShimPath, hostKey = {}) {
         args.push(remote);
     return { args, env };
 }
+/**
+ * Build the askpass shim's `#!/bin/sh` body: a script that re-invokes this CLI
+ * as `agents ssh __askpass`. The relaunch argv comes from {@link getCliLaunch},
+ * never a hand-rolled `[process.execPath, process.argv[1], …]` — on a Bun
+ * standalone binary `process.argv[1]` is the *virtual* embedded entry
+ * `/$bunfs/root/agents`, which the CLI would then receive as a bogus subcommand
+ * (`unknown command '/$bunfs/root/agents'`), print nothing, and hand ssh an
+ * empty password. `getCliLaunch` resolves the physical executable so the shim
+ * works on both the standalone and JS/dev builds. Every argv element is
+ * shell-quoted. Pure (takes the launch as a parameter) so it is unit-testable.
+ */
+export function buildAskpassShimBody(launch = getCliLaunch(['ssh', '__askpass'])) {
+    const exec = [launch.command, ...launch.args].map(shellQuote).join(' ');
+    return `#!/bin/sh\n# Generated by agents-cli — bridges ssh SSH_ASKPASS back into the CLI.\nexec ${exec}\n`;
+}
 /**
  * Write (idempotently) the askpass shim — a tiny executable that re-invokes
  * this CLI as `agents ssh __askpass`. ssh execs `SSH_ASKPASS` with no usable
@@ -102,10 +118,6 @@ export function writeAskpassShim() {
     const dir = path.join(getCacheDir(), 'devices');
     fs.mkdirSync(dir, { recursive: true });
     const shimPath = path.join(dir, 'askpass.sh');
-    // process.execPath = the node/bun binary; argv[1] = this CLI's entry script.
-    const node = process.execPath;
-    const entry = process.argv[1] ?? '';
-    const body = `#!/bin/sh\n# Generated by agents-cli — bridges ssh SSH_ASKPASS back into the CLI.\nexec ${shellQuote(node)} ${shellQuote(entry)} ssh __askpass\n`;
-    fs.writeFileSync(shimPath, body, { mode: 0o700 });
+    fs.writeFileSync(shimPath, buildAskpassShimBody(), { mode: 0o700 });
     return shimPath;
 }

package/dist/lib/devices/fleet.d.ts

@@ -24,6 +24,17 @@ export interface FleetRunResult {
     /** Truncated combined stderr/stdout for failures. */
     detail?: string;
 }
+export interface FanOutDeviceTarget {
+    name: string;
+    skip?: FleetSkipReason | string;
+}
+export interface FanOutDeviceResult<T> {
+    name: string;
+    status: 'ok' | 'failed' | 'skipped';
+    value?: T;
+    error?: string;
+    reason?: FleetSkipReason | string;
+}
 /**
  * Classify each registered device for a fleet operation.
  *
@@ -34,6 +45,16 @@ export interface FleetRunResult {
  *   it has a registry address — same path as any other box).
  */
 export declare function planFleetTargets(reg: DeviceRegistry): FleetTarget[];
+/**
+ * Remote fan-out targets for the fleet health/drift gates (`fleet status`,
+ * `check --devices`): every planned device except this machine and control-only
+ * cockpits. A control device never runs agents (mirrors doctor's fan-out, which
+ * drops it via `isControlDevice`), so counting it as unreachable/drift would make
+ * the CI gate fail on every run for a fleet that merely has a cockpit registered.
+ * Offline / no-address devices are kept — those are genuine faults a gate should
+ * surface — so their `skip` reason still flows through as an `unreachable` row.
+ */
+export declare function remoteFleetTargets(planned: FleetTarget[], self: string): FleetTarget[];
 /** Human label for a skip reason. */
 export declare function skipLabel(reason: FleetSkipReason): string;
 /**
@@ -61,3 +82,5 @@ export declare function upgradeCommand(version?: string): string[];
  * the runner are recorded as `failed` so one bad device never aborts the rest.
  */
 export declare function runFleet(targets: FleetTarget[], cmd: string[], runner?: typeof runOnDevice): FleetRunResult[];
+/** Run one async probe per device in parallel, preserving input order. */
+export declare function fanOutDevices<T, Target extends FanOutDeviceTarget = FanOutDeviceTarget>(targets: Target[], probe: (target: Target) => Promise<T>): Promise<FanOutDeviceResult<T>[]>;

package/dist/lib/devices/fleet.js

@@ -42,6 +42,18 @@ export function planFleetTargets(reg) {
         return { device };
     });
 }
+/**
+ * Remote fan-out targets for the fleet health/drift gates (`fleet status`,
+ * `check --devices`): every planned device except this machine and control-only
+ * cockpits. A control device never runs agents (mirrors doctor's fan-out, which
+ * drops it via `isControlDevice`), so counting it as unreachable/drift would make
+ * the CI gate fail on every run for a fleet that merely has a cockpit registered.
+ * Offline / no-address devices are kept — those are genuine faults a gate should
+ * surface — so their `skip` reason still flows through as an `unreachable` row.
+ */
+export function remoteFleetTargets(planned, self) {
+    return planned.filter((t) => t.device.name !== self && t.skip !== 'control');
+}
 /** Human label for a skip reason. */
 export function skipLabel(reason) {
     switch (reason) {
@@ -135,3 +147,29 @@ export function runFleet(targets, cmd, runner = runOnDevice) {
     }
     return results;
 }
+/** Run one async probe per device in parallel, preserving input order. */
+export async function fanOutDevices(targets, probe) {
+    return Promise.all(targets.map(async (target) => {
+        if (target.skip) {
+            return {
+                name: target.name,
+                status: 'skipped',
+                reason: target.skip,
+            };
+        }
+        try {
+            return {
+                name: target.name,
+                status: 'ok',
+                value: await probe(target),
+            };
+        }
+        catch (err) {
+            return {
+                name: target.name,
+                status: 'failed',
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }));
+}