@phnx-labs/agents-cli 1.22.0 → 1.22.1

package/dist/lib/devices/doctor-overview-cache.js

@@ -0,0 +1,168 @@
+/**
+ * Singleflight + short-TTL disk cache for the `agents doctor --json` OVERVIEW
+ * payload (the bare, no-target form the menu-bar helper and other pollers read).
+ *
+ * Why this exists (RUSH-2153): the bare `doctor --json` overview is expensive —
+ * it probes every host CLI, spawns every installed agent CLI for its sign-in,
+ * and diffs every agent×version against its source. On an idle box that is a few
+ * seconds; on a loaded one it is minutes. The menu-bar helper polls it on a 60s
+ * timer with a per-*process* in-flight guard, so nothing coalesces ACROSS
+ * processes: a helper relaunch (or any second poller) each launches its own
+ * live compute, and a helper killed mid-run orphans its `doctor --json` child,
+ * which keeps spinning. In steady state this stacked to dozens of concurrent
+ * `doctor --json` processes pinning ~14 cores and driving load to ~300.
+ *
+ * The fix mirrors the {@link readStatsCache}/`writeStatsCache` mirror-file
+ * convention: reads are cache-first, and when a live compute IS needed exactly
+ * ONE runs at a time. The singleflight is the shared `proper-lockfile` lock (via
+ * `ensureLockTarget` + `lockfile.lock`) — the SAME battle-tested lock the rest of
+ * the CLI uses (fs-atomic.ts) — which owns two things a hand-rolled lock got
+ * wrong: (1) it auto-refreshes the lock's mtime on a timer while held, so a live
+ * computer whose compute runs for minutes is never mistaken for a crashed one
+ * and stolen; (2) `release()` only ever releases the lock THIS caller acquired,
+ * so a slow computer can't delete a successor's lock. Waiters block on the lock
+ * up to a bounded budget, then serve the last snapshot rather than pile on.
+ *
+ * The cache write is tmp+rename so a concurrent reader never sees a partial file.
+ * All IO is best-effort: a failure degrades to a live compute, never a throw.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import lockfile from 'proper-lockfile';
+import { getCacheDir } from '../state.js';
+import { ensureLockTarget } from '../fs-atomic.js';
+const CACHE_FILE = '.doctor-overview.json';
+const LOCK_TARGET_FILE = '.doctor-overview.lock-target';
+/** Serve a cached snapshot without recomputing while it is younger than this. */
+export const DOCTOR_OVERVIEW_FRESH_MS = 90_000;
+/**
+ * A held lock older than this is treated as a crashed computer and broken. The
+ * lock's mtime is auto-refreshed by proper-lockfile every `stale/2` while a live
+ * computer holds it (the event loop turns during the compute's `await`ed
+ * subprocess spawns), so this only ever breaks a genuinely dead holder.
+ */
+const LOCK_STALE_MS = 60_000;
+/**
+ * How long a waiter blocks on the lock before giving up and serving the last
+ * snapshot. Sized to comfortably exceed a slow (multi-second-to-minutes) compute
+ * so a waiter normally gets the winner's fresh write; capped so a truly wedged
+ * holder never hangs the CLI (it serves stale instead).
+ */
+const LOCK_RETRIES = { retries: 240, factor: 1, minTimeout: 500, maxTimeout: 500 };
+function cachePath(dir) {
+    return path.join(dir, CACHE_FILE);
+}
+/** Read the last snapshot (best-effort; missing/corrupt/wrong-version → null). */
+export function readDoctorOverviewCache(deps = {}) {
+    const dir = deps.dir ?? getCacheDir();
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath(dir), 'utf-8'));
+        if (parsed && parsed.version === 1 && typeof parsed.fetchedAt === 'number') {
+            return { fetchedAt: parsed.fetchedAt, payload: parsed.payload };
+        }
+    }
+    catch {
+        // missing or corrupt — treat as no snapshot
+    }
+    return null;
+}
+/** Persist a fresh overview payload (best-effort; tmp+rename so reads are atomic). */
+export function writeDoctorOverviewCache(payload, deps = {}) {
+    const dir = deps.dir ?? getCacheDir();
+    const now = deps.now ?? Date.now;
+    try {
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const body = { version: 1, fetchedAt: now(), payload };
+        const tmp = `${cachePath(dir)}.tmp.${process.pid}`;
+        fs.writeFileSync(tmp, JSON.stringify(body, null, 2));
+        fs.renameSync(tmp, cachePath(dir));
+    }
+    catch {
+        // best-effort; a failed write just means the next read falls back to live
+    }
+}
+/**
+ * Enter the doctor-overview singleflight gate. Returns a cached string to print,
+ * or a lock token telling the caller to compute (and then write + release).
+ *
+ * Contract:
+ *  - Fresh snapshot present (and not `forceRefresh`) → `{ cached }`, no lock.
+ *  - Otherwise exactly one caller holds the lock and gets `{ cached: null,
+ *    release }`; everyone else blocks on the lock, then (on acquiring it)
+ *    double-checks and serves the winner's fresh write — or, if the winner runs
+ *    past the wait budget, serves the last snapshot — rather than recomputing.
+ *  - Never throws: any IO/lock failure degrades to a compute token or a served
+ *    snapshot.
+ */
+export async function enterDoctorOverviewGate(opts = {}, deps = {}) {
+    const dir = deps.dir ?? getCacheDir();
+    const now = deps.now ?? Date.now;
+    const freshMs = opts.freshMs ?? DOCTOR_OVERVIEW_FRESH_MS;
+    const serveFresh = () => {
+        if (opts.forceRefresh)
+            return null;
+        const c = readDoctorOverviewCache({ dir });
+        if (c && now() - c.fetchedAt < freshMs)
+            return JSON.stringify(c.payload, null, 2);
+        return null;
+    };
+    // 1. Fast path: a fresh snapshot serves without any compute or lock.
+    const fast = serveFresh();
+    if (fast !== null)
+        return { cached: fast };
+    try {
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        // Can't even make the cache dir — fall back to an unguarded compute.
+        return { cached: null, release: () => { } };
+    }
+    const lockTarget = path.join(dir, LOCK_TARGET_FILE);
+    ensureLockTarget(lockTarget);
+    // 2. Singleflight via proper-lockfile: one caller holds the lock and computes;
+    //    the rest block here until it releases.
+    let release = null;
+    try {
+        release = await lockfile.lock(lockTarget, {
+            stale: LOCK_STALE_MS,
+            retries: LOCK_RETRIES,
+            // A peer broke our lock (only possible if we somehow went stale). Don't
+            // crash on the async callback; we re-check the cache and serve/recompute.
+            onCompromised: () => { },
+        });
+    }
+    catch {
+        // 3. Winner held the lock past our wait budget. Serve the last snapshot
+        //    (even if stale) rather than pile on; only if there is genuinely none do
+        //    we compute unguarded (rare cold-start under sustained load).
+        const c = readDoctorOverviewCache({ dir });
+        if (c)
+            return { cached: JSON.stringify(c.payload, null, 2) };
+        return { cached: null, release: () => { } };
+    }
+    // 4. Acquired. The winner may have written a fresh snapshot while we waited —
+    //    serve it and release, instead of recomputing.
+    const afterWait = serveFresh();
+    if (afterWait !== null) {
+        // AWAIT, don't fire-and-forget: returning while the lockfile is still on
+        // disk makes the next caller retry against a lock that is logically free —
+        // the same pile-up this gate exists to prevent, just narrowed to the window
+        // between return and unlink. We are already in an async function, so the
+        // wait costs one unlink.
+        await release().catch(() => { });
+        return { cached: afterWait };
+    }
+    const rel = release;
+    let released = false;
+    return {
+        cached: null,
+        release: () => {
+            if (released)
+                return;
+            released = true;
+            void rel();
+        },
+    };
+}

package/dist/lib/devices/fleet.js

@@ -9,6 +9,7 @@
  */
 import { spawnSync } from 'child_process';
 import { isControlDevice } from './registry.js';
+import { isSelfHost } from './self-host.js';
 import { buildSshInvocation, sshTargetFor, writeAskpassShim } from './connect.js';
 /** npm dist-tags / semver pins only — rejects shell metacharacters. */
 export const FLEET_VERSION_RE = /^[A-Za-z0-9._-]+$/;
@@ -52,7 +53,11 @@ export function planFleetTargets(reg) {
  * 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');
+    // Exclude self by name AND by full identity (tailscale dnsName, loopback): a
+    // device referenced by its dnsName slipped past the bare name check and got a
+    // remote version+doctor dial back to THIS box, which orphaned on timeout and
+    // piled up (RUSH-2114). `isSelfHost` matches every alias the box answers to.
+    return planned.filter((t) => t.device.name !== self && !isSelfHost(t.device.name) && t.skip !== 'control');
 }
 /**
  * Decide whether a fleet-health target should skip the expensive version+doctor
@@ -189,7 +194,7 @@ export function runFleet(targets, cmd, opts = {}) {
             continue;
         }
         try {
-            const isSelf = opts.self !== undefined && t.device.name === opts.self;
+            const isSelf = (opts.self !== undefined && t.device.name === opts.self) || isSelfHost(t.device.name);
             const res = isSelf ? localRunner(cmd) : runner(t.device, cmd);
             const ok = res.code === 0;
             const detail = (res.stderr || res.stdout).trim().slice(0, 200);

package/dist/lib/devices/self-host.d.ts

@@ -0,0 +1,9 @@
+/**
+ * True when `name` refers to the local machine. Case-insensitive and
+ * trailing-dot-tolerant. Use this everywhere a `--host`/fleet target is compared
+ * against "self" so a tailscale-name reference short-circuits to a local run
+ * instead of self-SSHing.
+ */
+export declare function isSelfHost(name: string | undefined | null): boolean;
+/** Test hook: drop the memoized alias set so a fresh registry/env is re-read. */
+export declare function resetSelfHostCache(): void;

package/dist/lib/devices/self-host.js

@@ -0,0 +1,61 @@
+/**
+ * "Is this hostname the local machine?" — matched against every identity the box
+ * answers to, not just its short id.
+ *
+ * The self-checks that gate `--host` dispatch and the fleet-health fan-out used to
+ * compare only against {@link machineId} (the lowercased short hostname, e.g.
+ * `zion`). A caller that referenced the box by its **tailscale MagicDNS name**
+ * (`zion.tail1a85a1.ts.net`) — which is exactly what `fleetDialTarget` and the
+ * Factory floor's `--host` probes use — slipped past the check and SSH'd to the
+ * LOCAL box over its own tailscale name. On a loaded machine that self-SSH'd
+ * `doctor --json` orphaned on timeout and piled up until the host was crushed
+ * (RUSH-2114). Matching the full identity set closes that gap at the source.
+ */
+import { machineId } from '../machine-id.js';
+import { loadDevicesSync } from './registry.js';
+const LOOPBACK = ['localhost', '127.0.0.1', '::1'];
+/** Lowercase + strip a trailing dot (FQDNs are equivalent with or without it). */
+function normalize(name) {
+    return name.trim().toLowerCase().replace(/\.$/, '');
+}
+let cached = null;
+/**
+ * Every name that resolves to THIS machine: the short id, loopback, and the self
+ * device's tailscale dnsName plus its short form. Computed once per process — the
+ * self identity does not change under a running CLI — and reads the registry
+ * best-effort (an unreadable registry still leaves the short id + loopback).
+ */
+function selfAliases() {
+    if (cached)
+        return cached;
+    const aliases = new Set([machineId(), ...LOOPBACK]);
+    try {
+        const dns = loadDevicesSync()[machineId()]?.address?.dnsName;
+        if (dns) {
+            const d = normalize(dns);
+            aliases.add(d);
+            aliases.add(d.split('.')[0]); // the short form of the FQDN
+        }
+    }
+    catch {
+        /* registry unreadable — the short id + loopback aliases still hold */
+    }
+    cached = aliases;
+    return cached;
+}
+/**
+ * True when `name` refers to the local machine. Case-insensitive and
+ * trailing-dot-tolerant. Use this everywhere a `--host`/fleet target is compared
+ * against "self" so a tailscale-name reference short-circuits to a local run
+ * instead of self-SSHing.
+ */
+export function isSelfHost(name) {
+    if (!name)
+        return false;
+    const n = normalize(name);
+    return n.length > 0 && selfAliases().has(n);
+}
+/** Test hook: drop the memoized alias set so a fresh registry/env is re-read. */
+export function resetSelfHostCache() {
+    cached = null;
+}

package/dist/lib/hosts/passthrough.js

@@ -25,6 +25,7 @@ import { stripRoutingFlags, buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, } f
 import { resolveRemoteOsSync } from './remote-os.js';
 import { machineId } from '../session/sync/config.js';
 import { loadDevices } from '../devices/registry.js';
+import { isSelfHost } from '../devices/self-host.js';
 import { fanOutDevices, planFleetTargets, runLocalCommand, runOnDevice, } from '../devices/fleet.js';
 import { platformGroupLabel } from '../devices/health-report.js';
 /**
@@ -334,7 +335,7 @@ export async function runFleetPassthrough(command, allArgs, spec, opts = {}) {
     const localRunner = opts.localRunner ?? runLocalCommand;
     const results = await fanOutDevices(targets, async (target) => {
         const cmd = ['agents', ...forwarded];
-        const isSelf = target.device.name.toLowerCase() === self.toLowerCase();
+        const isSelf = target.device.name.toLowerCase() === self.toLowerCase() || isSelfHost(target.device.name);
         const res = isSelf ? localRunner(cmd) : runner(target.device, cmd);
         if (res.code !== 0) {
             const detail = (res.stderr || res.stdout || 'unreachable').trim().slice(0, 200);
@@ -443,11 +444,12 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     if (!hostName)
         return false;
     // Running against your own machine is just a local run — skip the SSH round-trip.
-    // `machineId()` is the same self-identifier the device registry and session
-    // sync use (lowercased short hostname); compare case-insensitively.
-    // Strip the routing flags from process.argv so the local command never sees
-    // an unregistered `--host`/`--device` and dies with "unknown option".
-    if (hostName.toLowerCase() === machineId()) {
+    // Match EVERY identity the box answers to (short id, loopback, tailscale
+    // dnsName), not just machineId() — a `--host <self-dnsName>` used to slip past a
+    // short-hostname-only check and self-SSH (RUSH-2114). Strip the routing flags
+    // from process.argv so the local command never sees an unregistered
+    // `--host`/`--device` and dies with "unknown option".
+    if (isSelfHost(hostName)) {
         const stripped = stripRoutingFlags(allArgs, STRIP_SPECS);
         process.argv = [process.argv[0], process.argv[1], ...stripped];
         return false;

package/dist/lib/menubar/install-menubar.js

@@ -22,6 +22,7 @@ import * as path from 'path';
 import { sleepSync } from '../fs-atomic.js';
 import { getRuntimeStateDir, getHelpersDir } from '../state.js';
 import { getCliVersion, resolveAgentsBin, resolveInstalledLayout } from '../version.js';
+import { copyAppBundle, withInstallLock } from '../app-bundle-install.js';
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 const SERVICE_LABEL = 'com.phnx-labs.agents-menubar';
@@ -154,17 +155,6 @@ function resolveCliEntry() {
     }
     return null;
 }
-function copyAppBundle(src, dest) {
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    if (fs.existsSync(dest))
-        fs.rmSync(dest, { recursive: true, force: true });
-    // `cp -R` preserves the bundle's signature and resource forks (see install-helper.ts).
-    const r = spawnSync('cp', ['-R', src, dest], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
-    if (r.status !== 0) {
-        const msg = (r.stderr || r.stdout || '').toString().trim();
-        throw new Error(`Failed to copy ${src} -> ${dest}: ${msg || 'unknown error'}`);
-    }
-}
 /**
  * Register the freshly-installed bundle with LaunchServices.
  *
@@ -232,18 +222,32 @@ export function ensureMenubarAppInstalled(opts = {}) {
     if (!src)
         return null;
     const dest = installedAppPath();
-    if (!opts.forceReinstall && fs.existsSync(dest)) {
-        const sourceIsDevId = hasDeveloperIdSignature(src);
-        const destIsDevId = hasDeveloperIdSignature(dest);
-        if (!(sourceIsDevId && !destIsDevId)) {
-            return installedExecutablePath();
-        }
-    }
-    copyAppBundle(src, dest);
-    // A fresh copy is exactly when the bundle's icon can be new (first install) or
-    // superseded (upgrade) — register it so LaunchServices knows the bundle and can
-    // resolve its AppIcon for the left-hand slot of daemon notifications.
-    refreshBundleIconRegistration(dest);
+    // Heal an older install that was ad-hoc re-signed over a Developer ID source:
+    // that unstable identity made Accessibility re-prompt on every upgrade.
+    const needsInstall = () => {
+        if (opts.forceReinstall)
+            return true;
+        if (!fs.existsSync(dest))
+            return true;
+        return hasDeveloperIdSignature(src) && !hasDeveloperIdSignature(dest);
+    };
+    // Fast path: nothing to do.
+    if (!needsInstall())
+        return installedExecutablePath();
+    // Serialize the atomic install so concurrent `agents` invocations (this runs
+    // on the darwin startup path) don't race the swap or each re-copy — the
+    // stampede that transiently corrupted MenubarHelper.app and tripped the
+    // "damaged" dialog.
+    withInstallLock(dest, (heartbeat) => {
+        if (!needsInstall())
+            return;
+        copyAppBundle(src, dest);
+        heartbeat(); // cp -R done; keep the lock fresh across lsregister
+        // A fresh copy is exactly when the bundle's icon can be new (first install) or
+        // superseded (upgrade) — register it so LaunchServices knows the bundle and can
+        // resolve its AppIcon for the left-hand slot of daemon notifications.
+        refreshBundleIconRegistration(dest);
+    });
     return installedExecutablePath();
 }
 function xmlEscape(s) {

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

@@ -54,6 +54,13 @@ export interface ProjectSessionRollup {
  * with the full definition list to show zero-agent projects.
  */
 export declare function rollupSessionsByProject(defs: ProjectDef[], sessions: ActiveSession[]): Map<string, ProjectSessionRollup>;
+/**
+ * True when a session's status means it is over. Exported so the card can keep
+ * the `agents` roster to live sessions: the headline and the `dead` row already
+ * separate the two, and a roster that reads `crashed ×25` beside `23 live`
+ * makes the reader distrust both numbers.
+ */
+export declare function isDeadStatus(status: string): boolean;
 /** Live vs finished sessions on a project. */
 export interface LiveDeadSplit {
     live: number;

package/dist/lib/project-status.js

@@ -93,6 +93,15 @@ export function rollupSessionsByProject(defs, sessions) {
  * that are running unattended.
  */
 const DEAD_STATUSES = new Set(['closed', 'crashed']);
+/**
+ * True when a session's status means it is over. Exported so the card can keep
+ * the `agents` roster to live sessions: the headline and the `dead` row already
+ * separate the two, and a roster that reads `crashed ×25` beside `23 live`
+ * makes the reader distrust both numbers.
+ */
+export function isDeadStatus(status) {
+    return DEAD_STATUSES.has(status);
+}
 /**
  * Split a rollup's sessions into what is working and what is wreckage.
  *

package/dist/lib/projects.d.ts

@@ -5,8 +5,17 @@
  * directory by pure convention (`<projectRoot>/<slug>`, see `project-root.ts`).
  * This module adds editable definitions on top: one YAML file per project under
  * `~/.agents/projects/<name>.yaml`, sitting beside the existing `routines/`,
- * `monitors/`, and `teams/` dirs in the user repo (so definitions sync across
- * machines for free via `agents push/pull`). A defined project can name itself
+ * `monitors/`, and `teams/` dirs in the user repo.
+ *
+ * That location makes definitions SYNCABLE, not automatically synced: they ride
+ * the user repo only once they are committed to it, via `agents repo push user`
+ * (`agents push` was removed). Until then the directory is untracked, and a
+ * reconcile that cleans the working tree deletes it — observed twice on one
+ * machine, taking four definitions with it each time. The recovery is an
+ * orphaned `chore(local): save …-sync drift` commit, which is not a guarantee:
+ * unreachable objects are collected. Say "commit them" rather than "for free".
+ *
+ * A defined project can name itself
  * independently of its folder, bind more than one repo, pin a monorepo subpath,
  * describe context subdirectories an agent should start from, carry a Linear
  * link and external integrations, and set an explicit default path.

package/dist/lib/projects.js

@@ -5,8 +5,17 @@
  * directory by pure convention (`<projectRoot>/<slug>`, see `project-root.ts`).
  * This module adds editable definitions on top: one YAML file per project under
  * `~/.agents/projects/<name>.yaml`, sitting beside the existing `routines/`,
- * `monitors/`, and `teams/` dirs in the user repo (so definitions sync across
- * machines for free via `agents push/pull`). A defined project can name itself
+ * `monitors/`, and `teams/` dirs in the user repo.
+ *
+ * That location makes definitions SYNCABLE, not automatically synced: they ride
+ * the user repo only once they are committed to it, via `agents repo push user`
+ * (`agents push` was removed). Until then the directory is untracked, and a
+ * reconcile that cleans the working tree deletes it — observed twice on one
+ * machine, taking four definitions with it each time. The recovery is an
+ * orphaned `chore(local): save …-sync drift` commit, which is not a guarantee:
+ * unreachable objects are collected. Say "commit them" rather than "for free".
+ *
+ * A defined project can name itself
  * independently of its folder, bind more than one repo, pin a monorepo subpath,
  * describe context subdirectories an agent should start from, carry a Linear
  * link and external integrations, and set an explicit default path.
@@ -235,11 +244,40 @@ export function projectBasePath(def, forRemote) {
 }
 function projectRootsAbs(defs) {
     const out = [];
-    for (const def of defs) {
-        const raw = def.root ?? def.defaultPath;
+    const push = (name, raw) => {
         if (!raw)
-            continue;
-        out.push({ name: def.name, abs: path.resolve(expandLocalHome(raw)) });
+            return;
+        out.push({ name, abs: path.resolve(expandLocalHome(raw)) });
+    };
+    for (const def of defs) {
+        // `root` says where the CHECKOUT is; `defaultPath` says which work is this
+        // project's. For a monorepo subproject those differ, and only the narrower
+        // one is a membership claim — a project scoped to `rush/apps/cli` does not
+        // own `rush/apps/web`.
+        //
+        // The old `root ?? defaultPath` collapsed such a subproject onto the
+        // monorepo root, the same path its umbrella anchors at, so the longest-match
+        // tiebreak below had nothing to separate them and a session in
+        // `rush/apps/cli` counted toward whichever definition was listed first.
+        const rootAbs = def.root ? path.resolve(expandLocalHome(def.root)) : undefined;
+        const defaultAbs = def.defaultPath ? path.resolve(expandLocalHome(def.defaultPath)) : undefined;
+        const narrowed = !!(rootAbs && defaultAbs && defaultAbs !== rootAbs && isUnder(defaultAbs, rootAbs));
+        // A narrowed project's root is a WEAK claim: it still covers the rest of the
+        // checkout when nobody else wants it, but yields to any project that claims
+        // a path outright. Dropping it entirely regressed the single-project case —
+        // `add foo --root ~/src/foo --path apps/web` stopped attributing work
+        // anywhere else in its own repo, and `--path` means where agents START, not
+        // which work counts.
+        if (rootAbs)
+            out.push({ name: def.name, abs: rootAbs, weak: narrowed });
+        if (defaultAbs && defaultAbs !== rootAbs)
+            out.push({ name: def.name, abs: defaultAbs });
+        for (const r of def.repos ?? []) {
+            push(def.name, r.path);
+            // A repo pinned to a monorepo subpath anchors at that subpath too.
+            if (r.path && r.subpath)
+                push(def.name, path.join(expandLocalHome(r.path), r.subpath));
+        }
     }
     return out;
 }
@@ -269,13 +307,23 @@ export function projectNameForCwd(cwd, defs) {
     const abs = path.resolve(expandLocalHome(cwd));
     let best;
     let bestLen = -1;
-    for (const { name, abs: root } of projectRootsAbs(defs)) {
-        if (isUnder(abs, root) && root.length > bestLen) {
+    let weakBest;
+    let weakLen = -1;
+    for (const { name, abs: root, weak } of projectRootsAbs(defs)) {
+        if (!isUnder(abs, root))
+            continue;
+        if (weak) {
+            if (root.length > weakLen) {
+                weakBest = name;
+                weakLen = root.length;
+            }
+        }
+        else if (root.length > bestLen) {
             best = name;
             bestLen = root.length;
         }
     }
-    return best;
+    return best ?? weakBest;
 }
 /**
  * The canonical project label for a cwd, for every surface that buckets work by

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

@@ -18,6 +18,7 @@ import { createHash } from 'crypto';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { copyAppBundle, withInstallLock } from '../app-bundle-install.js';
 const APP_BUNDLE_NAME = 'Agents CLI.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 let installRootOverride = null;
@@ -107,19 +108,6 @@ function spctlAssess(appPath) {
     });
     return { ok: r.status === 0, output: (r.stderr || r.stdout || '').toString().trim() };
 }
-function copyAppBundle(src, dest) {
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    if (fs.existsSync(dest))
-        fs.rmSync(dest, { recursive: true, force: true });
-    // `cp -R` preserves the bundle's signature, symlinks, and resource forks.
-    // `fs.cpSync({recursive: true})` works on simple trees but has historically
-    // mishandled extended attributes on `.app` bundles, breaking codesign.
-    const r = spawnSync('cp', ['-R', src, dest], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
-    if (r.status !== 0) {
-        const msg = (r.stderr || r.stdout || '').toString().trim();
-        throw new Error(`Failed to copy ${src} -> ${dest}: ${msg || 'unknown error'}`);
-    }
-}
 /**
  * Idempotent install. Copies the bundled `.app` to the stable user path. Skips
  * if the destination already exists, `codesign --verify` passes, AND the
@@ -135,25 +123,34 @@ function copyAppBundle(src, dest) {
 export function ensureKeychainHelperInstalled(opts = {}) {
     assertDarwin();
     const dest = installedAppPath();
-    if (!opts.forceReinstall && fs.existsSync(dest)) {
-        const { ok } = codesignVerify(dest);
-        if (ok && !installedHelperIsStale())
+    const upToDate = () => fs.existsSync(dest) && codesignVerify(dest).ok && !installedHelperIsStale();
+    // Fast path: already installed, valid, and current — no lock, no copy.
+    if (!opts.forceReinstall && upToDate())
+        return;
+    // Serialize the install so concurrent `agents` invocations don't race the
+    // atomic swap (and don't each run a redundant `cp`). The re-check inside the
+    // lock means a burst of callers copies once, not N times — the stampede that
+    // transiently corrupted the bundle and tripped the "damaged" dialog.
+    withInstallLock(dest, (heartbeat) => {
+        if (!opts.forceReinstall && upToDate())
             return;
-    }
-    const src = sourceAppPath();
-    copyAppBundle(src, dest);
-    const verify = codesignVerify(dest);
-    if (!verify.ok) {
-        throw new Error(`Installed helper failed codesign verification at ${dest}.\n${verify.output}\n` +
-            'The bundle may be corrupted. Try `agents helper install` to reinstall, or reinstall agents-cli.');
-    }
-    const assess = spctlAssess(dest);
-    if (!assess.ok) {
-        // Warn, do not fail. Gatekeeper ticket lookup needs network; offline
-        // installs and CI runners commonly fail this check. The ACL semantics
-        // we care about depend on codesign, not spctl.
-        process.stderr.write(`agents-cli: notarization check (spctl) did not pass for ${dest}: ${assess.output}\n`);
-    }
+        const src = sourceAppPath();
+        copyAppBundle(src, dest);
+        heartbeat(); // cp -R done; keep the lock fresh across the codesign/spctl spawns
+        const verify = codesignVerify(dest);
+        if (!verify.ok) {
+            throw new Error(`Installed helper failed codesign verification at ${dest}.\n${verify.output}\n` +
+                'The bundle may be corrupted. Try `agents helper install` to reinstall, or reinstall agents-cli.');
+        }
+        heartbeat(); // codesign done; spctl does a network Gatekeeper lookup — refresh again
+        const assess = spctlAssess(dest);
+        if (!assess.ok) {
+            // Warn, do not fail. Gatekeeper ticket lookup needs network; offline
+            // installs and CI runners commonly fail this check. The ACL semantics
+            // we care about depend on codesign, not spctl.
+            process.stderr.write(`agents-cli: notarization check (spctl) did not pass for ${dest}: ${assess.output}\n`);
+        }
+    });
 }
 /**
  * Return the absolute path to the helper executable. If the installed bundle