@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/open-url.d.ts

@@ -1,2 +1,60 @@
-/** Best-effort: open a URL in the user's default browser. Never throws. */
-export declare function openUrl(url: string): void;
+/** Where a "show the human this" call actually landed. */
+export type ShowOutcome = {
+    via: 'profile';
+    profile: string;
+    tabId?: string;
+} | {
+    via: 'os';
+    command: string;
+} | {
+    via: 'none';
+    reason: string;
+};
+export interface ShowOptions {
+    /**
+     * Force the OS default handler, ignoring `browser.viewer`. This is the
+     * The programmatic escape hatch, for a caller that must use the user's own
+     * browser regardless of configuration. There is deliberately no CLI flag for
+     * it: `agents config set browser.viewer os` is the user-facing control.
+     */
+    osBrowser?: boolean;
+    /** Explicit profile override, ahead of `browser.viewer`. */
+    profile?: string;
+    /** Injected opener so the OS branch is testable without spawning anything. */
+    spawnOpen?: (cmd: string, args: string[]) => boolean;
+}
+/**
+ * Launch a detached opener and report whether it actually started.
+ *
+ * Detection without blocking, which is the whole trick here. A bare detached
+ * `spawn` cannot tell success from "xdg-open is not installed" — it does not
+ * throw for a missing binary, it emits `error` asynchronously — so the failure
+ * branches of every caller were dead. But `spawnSync` is not the answer either:
+ * it waits for the child's whole lifetime, and `devices lease` opens a console
+ * and then immediately prompts for a pasted key, so a blocking open would stall
+ * that prompt behind the browser.
+ *
+ * Racing `spawn` against `error` gives both: Node emits `spawn` as soon as the
+ * child is successfully created (measured: 1ms, and it does NOT wait for exit),
+ * and `error` for ENOENT. We unref on success so the opener outlives us.
+ */
+export declare function trySpawn(cmd: string, args: string[]): Promise<boolean>;
+/**
+ * Decide the viewer for this call. Exported for its own test — this is the one
+ * place the policy lives.
+ *
+ * Every fall back to the OS handler prints one stderr line naming why. A silent
+ * downgrade here is what made the original bug invisible for so long: the user
+ * had configured a profile and had no way to see that it was being ignored.
+ */
+export declare function resolveViewer(opts?: ShowOptions): Promise<'os' | {
+    profile: string;
+}>;
+/** Show a URL to the human at this machine. Never throws. */
+export declare function showUrl(url: string, opts?: ShowOptions): Promise<ShowOutcome>;
+/**
+ * Show a local file. Browser-renderable kinds go through {@link showUrl}; every
+ * other kind goes to the OS default APP, which for a screenshot or a recording
+ * is the right viewer.
+ */
+export declare function showFile(filePath: string, opts?: ShowOptions): Promise<ShowOutcome>;

package/dist/lib/open-url.js

@@ -1,19 +1,174 @@
 /**
- * Open a URL in the user's default browser, cross-platform. Best-effort and
- * detached — never throws and never blocks the caller. Shared by `agents devices lease`
- * (Hetzner console) and `agents fleet login` (the local login dashboard).
+ * The one place that decides WHERE a URL or file is shown to the human.
+ *
+ * Two browsers exist on a machine like this: the OS default handler, and the
+ * profile `agents browser` drives. They are not interchangeable. The configured
+ * profile is where the fleet's logins accumulate — `agents browser profiles
+ * logins` lists them — so a page opened there is a page the user is already
+ * signed in for, and a login acquired there is inherited by every later agent.
+ * The OS handler has none of that.
+ *
+ * Before this seam existed, `agents browser navigate` honoured the configured
+ * profile and nothing else did: `fleet login`, `devices lease`, `feedback`, and
+ * the browser-session artifact opener each shelled straight to `open`/`xdg-open`,
+ * so every one of them landed in whatever the OS handler happened to be. This
+ * module replaces all of those call sites; do not add a sixth raw `open`.
+ *
+ * Never throws. A viewer that cannot be reached degrades to the OS handler with
+ * one stderr line naming the reason, and a total failure returns `via: 'none'`
+ * so the caller can print the URL rather than silently doing nothing.
  */
 import { spawn } from 'child_process';
-/** Best-effort: open a URL in the user's default browser. Never throws. */
-export function openUrl(url) {
-    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
-    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+import * as path from 'path';
+import { pathToFileURL } from 'url';
+/**
+ * Extensions a CDP tab renders at least as well as the OS default app.
+ *
+ * Deliberately narrow. `sessions-list.ts` EXT_KIND covers .png/.jpg/.webp/.pdf/
+ * .webm, and for those Preview and QuickTime are the better viewer — routing a
+ * screenshot into a browser tab is a downgrade, not a fix.
+ */
+const BROWSER_RENDERABLE = new Set(['.html', '.htm', '.svg', '.xhtml']);
+async function osOpen(target, spawnOpen) {
+    const candidates = process.platform === 'darwin'
+        ? [['open', [target]]]
+        : process.platform === 'win32'
+            ? // `start` treats a lone quoted first argument as the window TITLE, so the
+                // empty title placeholder is required before the target. The three copies
+                // of this that predated the seam disagreed on it ('' vs '""').
+                [['cmd', ['/c', 'start', '', target]]]
+            : [
+                ['xdg-open', [target]],
+                ['gnome-open', [target]],
+            ];
+    for (const [cmd, args] of candidates) {
+        if (spawnOpen) {
+            if (spawnOpen(cmd, args))
+                return { via: 'os', command: cmd };
+            continue;
+        }
+        if (await trySpawn(cmd, args))
+            return { via: 'os', command: cmd };
+    }
+    return { via: 'none', reason: 'no working OS opener on this platform' };
+}
+/**
+ * Launch a detached opener and report whether it actually started.
+ *
+ * Detection without blocking, which is the whole trick here. A bare detached
+ * `spawn` cannot tell success from "xdg-open is not installed" — it does not
+ * throw for a missing binary, it emits `error` asynchronously — so the failure
+ * branches of every caller were dead. But `spawnSync` is not the answer either:
+ * it waits for the child's whole lifetime, and `devices lease` opens a console
+ * and then immediately prompts for a pasted key, so a blocking open would stall
+ * that prompt behind the browser.
+ *
+ * Racing `spawn` against `error` gives both: Node emits `spawn` as soon as the
+ * child is successfully created (measured: 1ms, and it does NOT wait for exit),
+ * and `error` for ENOENT. We unref on success so the opener outlives us.
+ */
+export function trySpawn(cmd, args) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(ok);
+        };
+        try {
+            const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+            child.on('error', () => done(false));
+            child.on('spawn', () => {
+                child.unref();
+                done(true);
+            });
+        }
+        catch {
+            done(false);
+        }
+    });
+}
+/**
+ * Decide the viewer for this call. Exported for its own test — this is the one
+ * place the policy lives.
+ *
+ * Every fall back to the OS handler prints one stderr line naming why. A silent
+ * downgrade here is what made the original bug invisible for so long: the user
+ * had configured a profile and had no way to see that it was being ignored.
+ */
+export async function resolveViewer(opts = {}) {
+    if (opts.osBrowser)
+        return 'os';
+    const { getConfigValue } = await import('./device-config.js');
+    const configured = opts.profile ?? (getConfigValue('browser.viewer').value || undefined);
+    // Unset means "follow the profile agents drive" — the whole point is that a
+    // machine with a configured browser stops leaking pages to the OS handler.
+    const { getConfiguredDefaultProfileName, resolveProfileRef, getProfile, isProfileLaunchableHere } = await import('./browser/profiles.js');
+    const name = configured ?? getConfiguredDefaultProfileName();
+    if (!name)
+        return 'os';
+    if (name === 'os')
+        return 'os';
+    let resolved;
     try {
-        const p = spawn(cmd, args, { stdio: 'ignore', detached: true });
-        p.on('error', () => { });
-        p.unref();
+        resolved = await resolveProfileRef(name);
+    }
+    catch (err) {
+        console.error(`[viewer] ${name}: ${err instanceof Error ? err.message : String(err)} — using the OS browser.`);
+        return 'os';
+    }
+    if (!resolved) {
+        console.error(`[viewer] "${name}" does not resolve to a profile — using the OS browser.`);
+        return 'os';
     }
-    catch {
-        /* best-effort */
+    const profile = await getProfile(resolved);
+    if (!profile) {
+        console.error(`[viewer] profile "${resolved}" is not configured — using the OS browser.`);
+        return 'os';
+    }
+    if (profile.browser === 'arc') {
+        // Arc exposes no CDP page targets and crashes on tab creation, so it can be
+        // a configured profile but never a drivable viewer.
+        console.error(`[viewer] "${resolved}" is Arc, which cannot be driven — using the OS browser.`);
+        return 'os';
+    }
+    if (!isProfileLaunchableHere(profile)) {
+        console.error(`[viewer] "${resolved}" cannot launch on this machine — using the OS browser.`);
+        return 'os';
+    }
+    return { profile: resolved };
+}
+/** Show a URL to the human at this machine. Never throws. */
+export async function showUrl(url, opts = {}) {
+    const viewer = await resolveViewer(opts);
+    if (viewer === 'os')
+        return osOpen(url, opts.spawnOpen);
+    try {
+        const { sendIPCRequest } = await import('./browser/ipc.js');
+        // Deliberately does NOT auto-start the browser daemon. Showing a page is a
+        // side errand — `devices lease` opens a console and immediately prompts for
+        // a pasted key — so blocking that on a daemon cold start is a surprising
+        // multi-second stall. Daemon already up: use the viewer. Not up: the OS
+        // handler is the fast, correct answer.
+        const response = await sendIPCRequest({ action: 'show', url, profile: viewer.profile }, { autoStartDaemon: false });
+        if (response.ok)
+            return { via: 'profile', profile: viewer.profile, tabId: response.tabId };
+        console.error(`[viewer] ${viewer.profile}: ${response.error} — using the OS browser.`);
+    }
+    catch (err) {
+        console.error(`[viewer] ${viewer.profile}: ${err instanceof Error ? err.message : String(err)} — using the OS browser.`);
+    }
+    return osOpen(url, opts.spawnOpen);
+}
+/**
+ * Show a local file. Browser-renderable kinds go through {@link showUrl}; every
+ * other kind goes to the OS default APP, which for a screenshot or a recording
+ * is the right viewer.
+ */
+export async function showFile(filePath, opts = {}) {
+    if (!BROWSER_RENDERABLE.has(path.extname(filePath).toLowerCase())) {
+        return osOpen(filePath, opts.spawnOpen);
     }
+    return showUrl(pathToFileURL(filePath).href, opts);
 }

package/dist/lib/project-probe.d.ts

@@ -58,7 +58,7 @@ export declare function probeProjectWorkspaces(paths: string[]): RepoWorkspaceSt
  */
 export declare function workspaceTargetsForDef(def: ProjectDef): string[];
 /**
- * Parse a peer's `projects probe --json` stdout, tagging each row with the
+ * Parse a peer's `projects probe` stdout, tagging each row with the
  * machine that answered. Defensive against version skew / partial output, the
  * same boundary contract as `parseRemoteActive`: non-JSON or a non-array
  * yields `[]`, and rows without a `path`/`present` core are dropped.

package/dist/lib/project-probe.js

@@ -96,7 +96,7 @@ export function workspaceTargetsForDef(def) {
     return projectProbeTargets(def);
 }
 /**
- * Parse a peer's `projects probe --json` stdout, tagging each row with the
+ * Parse a peer's `projects probe` stdout, tagging each row with the
  * machine that answered. Defensive against version skew / partial output, the
  * same boundary contract as `parseRemoteActive`: non-JSON or a non-array
  * yields `[]`, and rows without a `path`/`present` core are dropped.

package/dist/lib/project-pull.d.ts

@@ -93,7 +93,7 @@ export declare function decodePullTargets(raw: string): ProjectRepoTarget[];
 export declare function pullProjectTargets(targets: ProjectRepoTarget[], host?: string): Promise<ProjectPullResult[]>;
 export declare function buildPullEnvelope(results: ProjectPullResult[], targets: ProjectRepoTarget[]): ProjectPullEnvelope;
 /**
- * Parse a peer's `projects pull-local --json` stdout. Fails CLOSED **and
+ * Parse a peer's `projects pull-local` stdout. Fails CLOSED **and
  * LOUD**: any structural anomaly (wrong schema version, wrong kind, machine
  * mismatch, fingerprint mismatch, non-array results, malformed rows) returns
  * `{ items: [], valid: false }` rather than silently accepting a partial or

package/dist/lib/project-pull.js

@@ -66,7 +66,7 @@ export function encodePullTargets(targets) {
  * test can exercise the real caller-side arguments rather than a retyped copy.
  */
 export function pullLocalArgs(targets) {
-    return ['projects', 'pull-local', '--json', '--targets', encodePullTargets(targets)];
+    return ['projects', 'pull-local', '--targets', encodePullTargets(targets)];
 }
 /**
  * Decode the `--targets` argument back into targets on the peer. THROWS on any
@@ -226,7 +226,7 @@ export function buildPullEnvelope(results, targets) {
 // Envelope parser (fail-closed — every validation failure returns [])
 // ---------------------------------------------------------------------------
 /**
- * Parse a peer's `projects pull-local --json` stdout. Fails CLOSED **and
+ * Parse a peer's `projects pull-local` stdout. Fails CLOSED **and
  * LOUD**: any structural anomaly (wrong schema version, wrong kind, machine
  * mismatch, fingerprint mismatch, non-array results, malformed rows) returns
  * `{ items: [], valid: false }` rather than silently accepting a partial or

package/dist/lib/projects.d.ts

@@ -204,7 +204,7 @@ export declare function projectDirsAbs(def: ProjectDef, opts: {
  * with `expandLocalHome` and resolved, so this matches sessions whose cwd shares
  * this machine's home layout. A session recorded on a different-home machine
  * (`/Users/x/…` vs `/home/x/…`) will not match until the fleet-wide,
- * home-relative variant lands (see the deferred item in docs/projects.md).
+ * home-relative variant lands (see docs/concepts.md).
  */
 export declare function projectNameForCwd(cwd: string | undefined, defs: ProjectDef[]): string | undefined;
 /**

package/dist/lib/projects.js

@@ -429,7 +429,7 @@ function isUnder(child, parent) {
  * with `expandLocalHome` and resolved, so this matches sessions whose cwd shares
  * this machine's home layout. A session recorded on a different-home machine
  * (`/Users/x/…` vs `/home/x/…`) will not match until the fleet-wide,
- * home-relative variant lands (see the deferred item in docs/projects.md).
+ * home-relative variant lands (see docs/concepts.md).
  */
 export function projectNameForCwd(cwd, defs) {
     if (!cwd)

package/dist/lib/refresh-coordinator.d.ts

@@ -15,7 +15,7 @@ export interface RefreshLeaseOptions<T> {
  * Serialize refresh work across every agents-cli process on this device.
  *
  * In-process promise maps only protect one Node process. Factory, the daemon,
- * `agents view`, and `agents usage` are separate processes, so they need an
+ * and `agents view` are separate processes, so they need an
  * OS-visible lease. The result is re-read after lock acquisition: a waiter
  * consumes the winner's publication and never calls the provider a second
  * time. `proper-lockfile` supplies heartbeat + stale-owner recovery while an

package/dist/lib/refresh-coordinator.js

@@ -18,7 +18,7 @@ function lockTarget(scope, key) {
  * Serialize refresh work across every agents-cli process on this device.
  *
  * In-process promise maps only protect one Node process. Factory, the daemon,
- * `agents view`, and `agents usage` are separate processes, so they need an
+ * and `agents view` are separate processes, so they need an
  * OS-visible lease. The result is re-read after lock acquisition: a waiter
  * consumes the winner's publication and never calls the provider a second
  * time. `proper-lockfile` supplies heartbeat + stale-owner recovery while an

package/dist/lib/sandbox.js

@@ -209,11 +209,11 @@ export function assertSandboxForwardsHostGhAuth(spawnEnv) {
 }
 /** Link this host's Cursor login and CLI config into the disposable overlay. */
 export function generateCursorConfig(overlayHome) {
-    const realConfigHome = process.env.XDG_CONFIG_HOME || path.join(resolveRealHome(), '.config');
-    const realAuth = path.join(realConfigHome, 'cursor', 'auth.json');
+    const realCursorDir = path.join(process.env.AGENTS_REAL_HOME || resolveRealHome(), '.cursor');
+    const realAuth = path.join(realCursorDir, 'auth.json');
     if (!fs.existsSync(realAuth))
         return;
-    const overlayCursorDir = path.join(overlayHome, '.config', 'cursor');
+    const overlayCursorDir = path.join(overlayHome, '.cursor');
     fs.mkdirSync(overlayCursorDir, { recursive: true });
     const overlayAuth = path.join(overlayCursorDir, 'auth.json');
     if (process.platform === 'win32') {
@@ -227,10 +227,9 @@ export function generateCursorConfig(overlayHome) {
     else {
         fs.symlinkSync(realAuth, overlayAuth);
     }
-    // Setting XDG_CONFIG_HOME makes Cursor look for cli-config.json beside auth.json.
-    // This file carries account identity (authId, displayName, email, userId) as
-    // well as preferences, so it must remain linked rather than copied.
-    const realCliConfig = path.join(resolveRealHome(), '.cursor', 'cli-config.json');
+    // cli-config.json carries account identity alongside the file-store token, so
+    // it must remain linked rather than copied.
+    const realCliConfig = path.join(realCursorDir, 'cli-config.json');
     if (fs.existsSync(realCliConfig)) {
         const overlayCliConfig = path.join(overlayCursorDir, 'cli-config.json');
         try {

package/dist/lib/secrets/download-keychain.d.ts

@@ -0,0 +1,47 @@
+/**
+ * On-demand download + verification of the macOS keychain broker helper
+ * ("Agents CLI.app").
+ *
+ * Mirrors the ComputerHelper / MenubarHelper download model
+ * (`../helper-download.ts`): the helper ships as a signed + notarized `.app`
+ * zipped as a GitHub release asset on the helper's own `keychain/v<x.y.z>` tag,
+ * NOT the CLI's tag (see `helper-versions.ts`). A fresh `npm i -g`
+ * machine whose tarball lacks a bundled copy fetches the asset for the running
+ * CLI version, verifies its sha256 + code signature before install.
+ *
+ * Unlike the menu-bar helper, the keychain helper pins NO designated
+ * requirement (no `expectedBundleId`). The menu-bar `expectedBundleId` exists
+ * because macOS keys the Accessibility (TCC) grant to the bundle's designated
+ * requirement, so a substituted bundle whose DR does not pin (id, team) would
+ * silently revoke that upgrade-stable grant. The keychain helper has no such
+ * DR-keyed grant to protect: its items are gated by the access-group
+ * entitlement (`keychain-helper.swift` → `kSecAttrAccessGroup`, the
+ * `keychain-access-groups` entitlement) plus a biometry `SecAccessControl`
+ * (user presence) — NOT a `SecTrustedApplication` ACL keyed to a bundle-id/DR.
+ * The release-time gate `scripts/verify-keychain-helper.sh` correspondingly
+ * pins the executable's sha256, not a designated requirement. So Team +
+ * notarization is the verification boundary here, exactly like ComputerHelper.
+ */
+import { type HelperSpec } from '../helper-download.js';
+/** The zipped `.app` release asset name (the bundle name has a space). */
+export declare const KEYCHAIN_HELPER_ASSET = "Agents_CLI.app.zip";
+/** The bundle directory name once extracted. */
+export declare const KEYCHAIN_HELPER_APP_NAME = "Agents CLI.app";
+/** Keychain-helper identity + verification policy — Team + notarization only,
+ *  no DR pin (see docblock). */
+export declare const KEYCHAIN_HELPER_SPEC: HelperSpec;
+/** Release-asset URLs for the keychain helper zip + its checksum at `v<version>`. */
+export declare function keychainHelperAssetUrls(version: string): {
+    zip: string;
+    sha256: string;
+};
+/** Cache dir for the downloaded keychain helper, one subdir per release tag. */
+export declare function keychainHelperCacheDir(version: string): string;
+/** Verify a keychain helper `.app`: codesign + Team + notarization (no DR pin). */
+export declare function verifyKeychainHelper(appPath: string): void;
+/**
+ * Download the keychain helper release asset for `version`, verify sha256 +
+ * signature, and return the path to the extracted `Agents CLI.app` in the
+ * cache. A missing asset is a hard error naming the exact tag.
+ */
+export declare function downloadKeychainHelperApp(version: string): Promise<string>;

package/dist/lib/secrets/download-keychain.js

@@ -0,0 +1,70 @@
+/**
+ * On-demand download + verification of the macOS keychain broker helper
+ * ("Agents CLI.app").
+ *
+ * Mirrors the ComputerHelper / MenubarHelper download model
+ * (`../helper-download.ts`): the helper ships as a signed + notarized `.app`
+ * zipped as a GitHub release asset on the helper's own `keychain/v<x.y.z>` tag,
+ * NOT the CLI's tag (see `helper-versions.ts`). A fresh `npm i -g`
+ * machine whose tarball lacks a bundled copy fetches the asset for the running
+ * CLI version, verifies its sha256 + code signature before install.
+ *
+ * Unlike the menu-bar helper, the keychain helper pins NO designated
+ * requirement (no `expectedBundleId`). The menu-bar `expectedBundleId` exists
+ * because macOS keys the Accessibility (TCC) grant to the bundle's designated
+ * requirement, so a substituted bundle whose DR does not pin (id, team) would
+ * silently revoke that upgrade-stable grant. The keychain helper has no such
+ * DR-keyed grant to protect: its items are gated by the access-group
+ * entitlement (`keychain-helper.swift` → `kSecAttrAccessGroup`, the
+ * `keychain-access-groups` entitlement) plus a biometry `SecAccessControl`
+ * (user presence) — NOT a `SecTrustedApplication` ACL keyed to a bundle-id/DR.
+ * The release-time gate `scripts/verify-keychain-helper.sh` correspondingly
+ * pins the executable's sha256, not a designated requirement. So Team +
+ * notarization is the verification boundary here, exactly like ComputerHelper.
+ */
+import { EXPECTED_TEAM_ID, downloadHelperApp, helperAssetUrls, helperCacheDir, verifyHelperApp, } from '../helper-download.js';
+/** The zipped `.app` release asset name (the bundle name has a space). */
+// Underscore, and NOT a space. GitHub rewrites a space in a release-asset name
+// to a dot on upload, so an asset staged as `Agents CLI.app.zip` is SERVED as
+// `Agents.CLI.app.zip` and a client asking for the spaced name 404s forever --
+// which is exactly what shipped. The fix is to CHOOSE a name GitHub leaves
+// alone rather than to mirror its rewrite: `Agents.CLI.app.zip` would work by
+// matching an artifact of that behavior, and would silently break if the
+// normalization rule ever changed. Underscores are preserved verbatim (verified
+// against a real upload).
+//
+// The bundle DIRECTORY inside the zip keeps its space (`appName` below) -- that
+// is the on-disk bundle name macOS and the TCC grant key on, and it is unchanged.
+export const KEYCHAIN_HELPER_ASSET = 'Agents_CLI.app.zip';
+/** The bundle directory name once extracted. */
+export const KEYCHAIN_HELPER_APP_NAME = 'Agents CLI.app';
+/** Keychain-helper identity + verification policy — Team + notarization only,
+ *  no DR pin (see docblock). */
+export const KEYCHAIN_HELPER_SPEC = {
+    helper: 'keychain',
+    assetName: KEYCHAIN_HELPER_ASSET,
+    appName: KEYCHAIN_HELPER_APP_NAME,
+    cacheSubdir: ['secrets', 'mac-helper'],
+    expectedTeamId: EXPECTED_TEAM_ID,
+    localBuildHint: 'cli/scripts/build-keychain-helper.sh',
+};
+/** Release-asset URLs for the keychain helper zip + its checksum at `v<version>`. */
+export function keychainHelperAssetUrls(version) {
+    return helperAssetUrls(KEYCHAIN_HELPER_SPEC, version);
+}
+/** Cache dir for the downloaded keychain helper, one subdir per release tag. */
+export function keychainHelperCacheDir(version) {
+    return helperCacheDir(KEYCHAIN_HELPER_SPEC, version);
+}
+/** Verify a keychain helper `.app`: codesign + Team + notarization (no DR pin). */
+export function verifyKeychainHelper(appPath) {
+    verifyHelperApp(appPath, KEYCHAIN_HELPER_SPEC);
+}
+/**
+ * Download the keychain helper release asset for `version`, verify sha256 +
+ * signature, and return the path to the extracted `Agents CLI.app` in the
+ * cache. A missing asset is a hard error naming the exact tag.
+ */
+export function downloadKeychainHelperApp(version) {
+    return downloadHelperApp(KEYCHAIN_HELPER_SPEC, version);
+}

package/dist/lib/secrets/install-helper.d.ts

@@ -29,6 +29,20 @@ export declare function setInstallRootForTest(dir: string | null): string | null
 export declare function ensureKeychainHelperInstalled(opts?: {
     forceReinstall?: boolean;
 }): void;
+/**
+ * ASYNC, download-capable install — the EXPLICIT onboarding/upgrade path
+ * (`agents setup secrets`, the bootstrap upgrade self-heal). When a bundled or
+ * locally-built `.app` ships (the common case, and always true this release
+ * stage), it installs that copy with NO network. When the tarball lacks the
+ * bundle (a fresh `npm i -g` whose tarball dropped it), it fetches the signed +
+ * notarized release asset for the running CLI version — sha256 + codesign +
+ * Team + notarization verified before install — and installs from the cached
+ * copy. The sync `getKeychainHelperPath()` never routes here: it stays sync +
+ * network-free and fails loud toward this command when no source exists.
+ */
+export declare function ensureKeychainHelperInstalledAsync(opts?: {
+    forceReinstall?: boolean;
+}): Promise<void>;
 /**
  * Return the absolute path to the helper executable. If the installed bundle
  * is missing, or is stale relative to the bundled source helper, performs a
@@ -37,7 +51,12 @@ export declare function ensureKeychainHelperInstalled(opts?: {
  * `npm i -g`, so this call site is the only one every machine is guaranteed to
  * pass through.
  *
- * Throws on non-darwin.
+ * SYNC and network-free by design: this is the secrets hot path, called by
+ * every keychain op. It never downloads. When no bundled/local source exists
+ * (a tarball that dropped the bundle), the reinstall's `sourceAppPath()` throws
+ * loud, directing the user to `agents setup secrets` — the explicit, async,
+ * download-capable path (`ensureKeychainHelperInstalledAsync`). Throws on
+ * non-darwin.
  */
 export declare function getKeychainHelperPath(): string;
 /** Diagnostic snapshot of the installed Keychain helper. */

package/dist/lib/secrets/install-helper.js

@@ -19,6 +19,8 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { copyAppBundle, withInstallLock } from '../app-bundle-install.js';
+import { downloadKeychainHelperApp } from './download-keychain.js';
+import { helperFloor } from '../helper-versions.js';
 const APP_BUNDLE_NAME = 'Agents CLI.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 let installRootOverride = null;
@@ -60,7 +62,18 @@ function sourceAppPath() {
             return c;
     }
     throw new Error(`Source ${APP_BUNDLE_NAME} not found. Looked in:\n  ${candidates.join('\n  ')}\n` +
-        'The npm package may have been built without the signed helper bundle. Reinstall agents-cli.');
+        'The npm package shipped without the bundled keychain helper. Run `agents setup secrets` to ' +
+        'download the signed helper for this version, or reinstall agents-cli.');
+}
+/** The bundled/local source `.app`, or null when absent (no throw) — the async
+ *  download path resolves the missing bundle instead of failing. */
+function bundledSourceAppPathOrNull() {
+    try {
+        return sourceAppPath();
+    }
+    catch {
+        return null;
+    }
 }
 function assertDarwin() {
     if (process.platform !== 'darwin') {
@@ -122,6 +135,30 @@ function spctlAssess(appPath) {
  */
 export function ensureKeychainHelperInstalled(opts = {}) {
     assertDarwin();
+    installKeychainHelperFromSource(sourceAppPath(), opts);
+}
+/**
+ * ASYNC, download-capable install — the EXPLICIT onboarding/upgrade path
+ * (`agents setup secrets`, the bootstrap upgrade self-heal). When a bundled or
+ * locally-built `.app` ships (the common case, and always true this release
+ * stage), it installs that copy with NO network. When the tarball lacks the
+ * bundle (a fresh `npm i -g` whose tarball dropped it), it fetches the signed +
+ * notarized release asset for the running CLI version — sha256 + codesign +
+ * Team + notarization verified before install — and installs from the cached
+ * copy. The sync `getKeychainHelperPath()` never routes here: it stays sync +
+ * network-free and fails loud toward this command when no source exists.
+ */
+export async function ensureKeychainHelperInstalledAsync(opts = {}) {
+    assertDarwin();
+    const bundled = bundledSourceAppPathOrNull();
+    const src = bundled ?? (await downloadKeychainHelperApp(helperFloor('keychain')));
+    installKeychainHelperFromSource(src, opts);
+}
+/**
+ * Copy `src` (a verified `.app` bundle) to the stable user path, then verify.
+ * Shared by the sync (bundled-source) and async (download-capable) installers.
+ */
+function installKeychainHelperFromSource(src, opts = {}) {
     const dest = installedAppPath();
     const upToDate = () => fs.existsSync(dest) && codesignVerify(dest).ok && !installedHelperIsStale();
     // Fast path: already installed, valid, and current — no lock, no copy.
@@ -134,7 +171,6 @@ export function ensureKeychainHelperInstalled(opts = {}) {
     withInstallLock(dest, (heartbeat) => {
         if (!opts.forceReinstall && upToDate())
             return;
-        const src = sourceAppPath();
         copyAppBundle(src, dest);
         heartbeat(); // cp -R done; keep the lock fresh across the codesign/spctl spawns
         const verify = codesignVerify(dest);
@@ -160,7 +196,12 @@ export function ensureKeychainHelperInstalled(opts = {}) {
  * `npm i -g`, so this call site is the only one every machine is guaranteed to
  * pass through.
  *
- * Throws on non-darwin.
+ * SYNC and network-free by design: this is the secrets hot path, called by
+ * every keychain op. It never downloads. When no bundled/local source exists
+ * (a tarball that dropped the bundle), the reinstall's `sourceAppPath()` throws
+ * loud, directing the user to `agents setup secrets` — the explicit, async,
+ * download-capable path (`ensureKeychainHelperInstalledAsync`). Throws on
+ * non-darwin.
  */
 export function getKeychainHelperPath() {
     assertDarwin();