@phnx-labs/agents-cli 1.22.0 → 1.22.1

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## 1.22.1
+
+- **`agents doctor` de-noise: never-synced and cross-version hook drift are warnings, not criticals (RUSH-2162).** The CRITICAL section now holds only "needs you now" problems — a logged-out account, or a hook/plugin missing from a version you keep synced. A version that was never synced (an old/unused install with nothing installed) and a hook that merely *differs* across versions (installed but stale) are surfaced as WARNINGs instead, cutting the critical count on a busy machine from ~11 to the handful that actually need action. Source: `apps/cli/src/lib/devices/doctor-findings.ts`.
+
+- **The "… is damaged and can't be opened" dialog stops — both helper `.app` bundles now install atomically and serialized.** The secrets keychain helper (`Agents CLI.app`) and the menu-bar helper (`MenubarHelper.app`) are each (re)installed on the hot path of ordinary `agents` invocations, and both did a non-atomic `rm -rf dest` + `cp -R src dest` straight onto the live bundle. On a busy box dozens of concurrent invocations raced that path, so a reader (Gatekeeper, or an exec of the bundle) could see a half-written `.app` — a truncated Mach-O / mismatched code signature — which macOS reports as damaged. A new shared installer (`lib/app-bundle-install.ts`, replacing the two duplicated copy functions) stages the copy in a sibling dir and swaps it in with renames (the live bundle is only ever a complete, signed `.app`, and a failed copy never touches it), and serializes concurrent installers behind the shared `withFileLock` with a double-checked skip so a burst copies once instead of stampeding. Source: `apps/cli/src/lib/app-bundle-install.ts`, `apps/cli/src/lib/secrets/install-helper.ts`, `apps/cli/src/lib/menubar/install-menubar.ts`.
+
+- **`agents doctor --json` no longer stampedes into dozens of concurrent runs — the overview is singleflighted and cached, with a new `--refresh` to force a live recompute.** The bare `doctor --json` overview probes every host CLI, every agent's sign-in, and every agent×version diff — seconds on an idle box, minutes on a loaded one. The menu-bar helper polls it on a timer with only a per-*process* in-flight guard, so a helper relaunch (or any second poller) each launched its own live compute, and a helper killed mid-run orphaned a `doctor --json` that kept spinning — stacking to dozens of concurrent runs pinning the CPU. Now a fresh snapshot (< 90s) serves instantly from a disk cache, and when a live compute IS needed exactly one runs while every other caller serves its result (a lock-directory singleflight that self-heals if the computer dies). `agents doctor --json --refresh` bypasses the cache. Source: `apps/cli/src/lib/devices/doctor-overview-cache.ts`, `apps/cli/src/commands/doctor.ts`.
+
+- **`doctor --json` releases its singleflight lock before it returns.** The overview gate
+  fired the lock release without awaiting it on the path where a waiter serves the winner's
+  fresh snapshot, so the call returned with the lockfile still on disk. The next caller then
+  retried against a lock that was already logically free — the pile-up the gate exists to
+  prevent, narrowed to the window between return and unlink. The release is now awaited.
+  The existing coalescing test failed 5 times in 15 runs before this and 0 in 15 after.
+  Source: `apps/cli/src/lib/devices/doctor-overview-cache.ts`.
+
+- **`agents add grok@latest` no longer strands the freshly-downloaded binary in the old version's home.** When the post-install version probe (`<cli> --version`) transiently failed right after grok's self-updating installer exited, `installVersion` silently fell back to the literal string `'latest'` as the resolved version — creating a bogus `versions/grok/latest/` directory and defeating `relocateGrokBinaryToVersionHome`'s exact-filename match (its regex could never match `grok-latest-...`, since the real file is named `grok-<semver>-<platform>`). The real multi-hundred-MB binary was left behind in the PREVIOUS default's downloads dir, and `agents view grok` never listed the new version as installed even though `agents add` reported success. The probe now retries briefly instead of silently falling back, and fails loudly if it still can't resolve a version rather than corrupting the version bookkeeping. Relocation also now self-heals: if the current `~/.grok` symlink target has nothing matching, it sweeps every other installed grok version home for a binary stranded by a past occurrence of this bug. Source: `apps/cli/src/lib/versions.ts`.
+
+- **A blocked menu-bar row now takes you to the session (RUSH-2110).** A NEEDS-YOU row
+  exists because an agent is waiting on you, but its only action was "Reveal working
+  dir", which unblocks nothing — you still had to go find the session by hand. Blocked
+  rows now lead with **Focus session**, which runs `agents focus <id>`: attach the live
+  terminal, or open a new tab and resume, cross-host. Reveal stays underneath. Both
+  render paths are covered — the single inline row and each entry inside a collapsed
+  multi-waiter group. A row the engine could not identify (a cloud task, a stale
+  sentinel) simply omits the item rather than offering an action that would do nothing.
+  Source: `apps/cli/menubar/Sources/MenubarHelper/StatusItemController.swift`,
+  `AgentsCLI.swift`.
+
+- **Two projects sharing one monorepo checkout are no longer indistinguishable.** Session,
+  activity, and feed attribution anchored a project on `root ?? defaultPath`, so a subproject
+  whose `root` is the monorepo and whose `defaultPath` is a subdir collapsed onto the same
+  path as its umbrella — the longest-match tiebreak had nothing to separate them, and work in
+  `rush/apps/cli` counted toward whichever definition happened to be listed first. A
+  `defaultPath` nested under `root` now takes precedence over that `root` (the root says where
+  the checkout is; `defaultPath` says which work is this project's), and each bound repo's
+  checkout and subpath anchor too. A narrowed `root` still covers the rest of its checkout as
+  a fallback, so a lone project defined with `--path` keeps attributing work across its own
+  repo instead of only inside the subdir. Source: `apps/cli/src/lib/projects.ts`.
+
+- **`agents projects view <name>` now shows more than `status`, not less.** The command you
+  open to learn everything about one project built its own short list — root, repos, a raw
+  Linear project id, an issue count, milestones — and never called the card renderer, so it
+  omitted the agents roster, merged PRs and release, focus areas, the schedule verdict,
+  tickets, and artifacts that `status` had shown all along. `view` and `status` now gather
+  through one function and render through one card; `view` adds every milestone (instead of
+  just the next) and the stored definition in full underneath — each repo with its subpath and
+  checkout, each context with its purpose, each integration with its URL. It also takes
+  `--window <days>` to match `status`. Source: `apps/cli/src/commands/projects.ts`.
+- **The `agents` roster on the card lists live sessions only.** It included every matched
+  session, so a card headed `23 live` went on to print `claude · crashed ×25` — the corpses the
+  `dead` row already reports, counted twice and contradicting the headline. Both now derive
+  from one `isDeadStatus` predicate, pinned by a test across every `ActiveStatus`. Source:
+  `apps/cli/src/lib/project-status.ts`.
+
+- **`--host <self>` and the fleet-health fan-out now short-circuit ALL of the
+  local machine's names, not just its short hostname (RUSH-2114).** A `--host`
+  target or fleet probe that referenced this box by its **tailscale dnsName**
+  (`zion.tail1a85a1.ts.net`) slipped past a `=== machineId()` check and SSH'd to
+  the local box over its own name; on a loaded machine that self-SSH'd `doctor
+  --json` orphaned on timeout and piled up until the host was crushed. A new
+  `isSelfHost()` matches every identity the box answers to (short id, loopback,
+  tailscale dnsName + its short form) and gates all four self-checks — the
+  generic `--host` passthrough (`maybeRunOnHost`), the `--devices`-all fan-out
+  (`runFleetPassthrough`), `remoteFleetTargets`, and `runFleet` — so a
+  self-reference runs locally instead of self-SSHing. Source:
+  `apps/cli/src/lib/devices/self-host.ts`, `apps/cli/src/lib/hosts/passthrough.ts`,
+  `apps/cli/src/lib/devices/fleet.ts`.
+
 ## 1.22.0
 
 - **`agents run auto` — full-auto dispatch (RUSH-2132).** `run auto` composes all three routing layers: host (14d launch affinity, unless `--host` is given), harness (installed CLIs weighted by best-account headroom), and account (the configured strategy). `balanced`/`available` now exit nonzero when every installed account is unhealthy — naming each excluded account, the earliest window reset, and the `--strategy pinned` escape hatch — instead of warning "falling back to defaults" and launching the exhausted pinned default. The error text is a machine-readable contract (`no healthy` + `resets <iso-time>`) the Factory watchdog tail-detects for rotate cooldowns. Source: `apps/cli/src/lib/rotate.ts`, `apps/cli/src/commands/exec.ts`, `apps/cli/src/lib/runner.ts`.

package/dist/commands/doctor.js

@@ -4,6 +4,7 @@ import { addHostOption } from '../lib/hosts/option.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
 import { loadDevices, isControlDevice } from '../lib/devices/registry.js';
 import { fanOutDevices, planFleetTargets, remoteFleetTargets } from '../lib/devices/fleet.js';
+import { enterDoctorOverviewGate, writeDoctorOverviewCache } from '../lib/devices/doctor-overview-cache.js';
 import { fleetDialTarget } from '../lib/devices/connect.js';
 import { compareFleetInventories } from '../lib/devices/fleet-divergence.js';
 import { collectLocalFleetInventory } from '../lib/devices/fleet-inventory.js';
@@ -1155,12 +1156,18 @@ export function registerDoctorCommand(program) {
         .option('--devices', 'Check agent readiness AND cross-device harness divergence (missing resources/versions, repo drift) on every registered device (alias --hosts)')
         .option('--hosts', 'Alias of --devices')
         .option('--check', 'CI drift gate: exit non-zero when any installed version is out of sync (stale or never-synced), zero when clean. Combine with --devices to gate the whole fleet.')
+        .option('--refresh', 'Bypass the cached overview snapshot: recompute the bare `doctor --json` overview live and refresh the shared cache that the menu-bar and other pollers read')
         .option('-q, --quiet', 'With --check, suppress per-version lines; print only the one-line verdict');
     setHelpSections(doctorCmd, {
         examples: `
       # Overview: CLI availability + sync status + orphans across all defaults
       agents doctor
 
+      # Machine-readable overview (served from a ~90s cache for pollers like the
+      # menu-bar helper); --refresh recomputes live and refreshes that cache
+      agents doctor --json
+      agents doctor --json --refresh
+
       # Full per-resource report for the active default
       agents doctor claude@default
 
@@ -1288,6 +1295,26 @@ export function registerDoctorCommand(program) {
             return;
         }
         if (!target) {
+            // Singleflight + short-TTL cache for the bare `doctor --json` overview.
+            // This overview probes every host CLI, every agent's sign-in, and every
+            // agent×version diff — seconds on an idle box, minutes on a loaded one.
+            // The menu-bar helper polls it with only a per-*process* in-flight guard,
+            // so a helper relaunch (or any second poller) each launched its own live
+            // compute, and a helper killed mid-run orphaned a `doctor --json` that
+            // kept spinning — stacking to dozens of concurrent runs pinning the CPU
+            // (RUSH-2153). Now: a fresh snapshot serves instantly, and when a compute
+            // IS needed exactly one runs while every other caller serves its result.
+            // A crashed computer never wedges the gate — the lock is stolen once its
+            // directory mtime goes stale (see enterDoctorOverviewGate).
+            let releaseOverviewGate;
+            if (opts.json) {
+                const gate = await enterDoctorOverviewGate({ forceRefresh: !!opts.refresh });
+                if (gate.cached !== null) {
+                    console.log(gate.cached);
+                    return;
+                }
+                releaseOverviewGate = gate.release;
+            }
             const clis = checkAllClis();
             const syncRows = checkSyncStatus(cwd);
             const orphanRows = countOrphans();
@@ -1355,7 +1382,7 @@ export function registerDoctorCommand(program) {
                 isolatedVersions,
             });
             if (opts.json) {
-                console.log(JSON.stringify({
+                const overviewPayload = {
                     clis,
                     signIn,
                     // Cached auth-health rollup for THIS host — lets `agents fleet status`
@@ -1398,7 +1425,12 @@ export function registerDoctorCommand(program) {
                         branch: m.branch,
                         fetchedAt: m.fetchedAt,
                     })),
-                }, null, 2));
+                };
+                // Persist for the next poller and release the singleflight lock BEFORE
+                // printing, so a concurrent caller picks up the fresh snapshot at once.
+                writeDoctorOverviewCache(overviewPayload);
+                releaseOverviewGate?.();
+                console.log(JSON.stringify(overviewPayload, null, 2));
                 return;
             }
             // Single-machine hybrid: CRITICAL section + one `▸ <machine>` block.

package/dist/commands/projects.js

@@ -25,7 +25,7 @@ import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
 import { factoryProjectsPath } from '../lib/auto-dispatch.js';
 import { formatFleetWorkspaces, parseRemoteProbe, probeProjectWorkspaces, workspaceTargetsForDef, } from '../lib/project-probe.js';
 import { listProjectDefs, loadProjectDef, writeProjectDef, removeProjectDef, projectDefPath, isSafeProjectName, } from '../lib/projects.js';
-import { rollupSessionsByProject, liveDeadSplit, enrichProjectSignals, formatProjectMembers, } from '../lib/project-status.js';
+import { rollupSessionsByProject, isDeadStatus, liveDeadSplit, enrichProjectSignals, formatProjectMembers, } from '../lib/project-status.js';
 import { fetchLinearProjectCounts } from '../lib/linear-project-counts.js';
 import { listLinearProjects, pickLinearProject } from '../lib/linear-projects.js';
 import { checkRepoSlug } from '../lib/project-doctor.js';
@@ -268,11 +268,45 @@ function statusBar(r) {
         parts.push(chalk.gray(`+${live - shown} other`));
     return parts.join(' · ') || chalk.gray('no live agents');
 }
+/**
+ * Gather the live/remote/Linear/focus signals for the projects about to be
+ * rendered. `status` and `view` share this deliberately: `view` used to build
+ * its own thinner picture, so the command you open to learn everything about
+ * ONE project showed strictly less than the roll-up across all of them — no
+ * agents, no ships, no focus, no schedule verdict. One gatherer means a signal
+ * added for either surface appears on both.
+ *
+ * Only the shown projects are enriched. `skipRemote` still reads the local
+ * artifact log and git focus, and skips just the network calls (`gh`, Linear).
+ */
+async function enrichProjectsForRender(defs, all, opts) {
+    const roll = rollupSessionsByProject(all, [...(await getActiveSessions()), ...(opts.extraSessions ?? [])]);
+    const remote = new Map();
+    const linear = new Map();
+    // Local git, no API, no rate limit — measured 0.23s over a 897-commit week.
+    const focus = new Map();
+    await Promise.all(defs.map(async (d) => {
+        const [sig, counts] = await Promise.all([
+            enrichProjectSignals(d, opts.windowDays, opts.nowMs, { skipRemote: opts.skipRemote }),
+            !opts.skipRemote && d.linear?.projectId
+                ? fetchLinearProjectCounts(d.linear.projectId)
+                : Promise.resolve(undefined),
+        ]);
+        remote.set(d.name, sig);
+        if (counts)
+            linear.set(d.name, counts);
+        if (d.root)
+            focus.set(d.name, await readFocusAreas(expandLocalHome(d.root), opts.windowDays));
+    }));
+    return { roll, remote, linear, focus };
+}
 function renderCard(def, r, remote, fleet, linear, nowMs = Date.now(), 
 /** How many milestones to print. `status` shows the next one; `view` shows all. */
 milestoneLimit = 1, 
 /** Directories the window's work landed in, from local git. */
-focus = []) {
+focus = [], 
+/** `view` mode: the caller prints the stored definition in full afterwards. */
+detail = false) {
     // The headline counts LIVE agents. It used to be every matched session, which
     // read `39 agents` on a project where 19 had crashed. `planPct` used to sit
     // here too and is gone: it summed each session's latest checklist snapshot,
@@ -288,8 +322,12 @@ focus = []) {
         const detail = split.deadByStatus.map((d) => `${d.n} ${d.status}`).join(', ');
         console.log(`  ${chalk.dim('dead')}     ${chalk.yellow(`${split.dead} finished or lost`)} ${chalk.dim(`(${detail})`)}`);
     }
-    if (r && r.members.length)
-        console.log(`  ${chalk.dim('agents')}   ${formatProjectMembers(r.members)}`);
+    // Live only. The roster used to list every matched session, so a card headed
+    // `23 live` went on to show `crashed ×25` — the corpses the `dead` row above
+    // already accounts for, counted twice and contradicting the headline.
+    const liveMembers = r?.members.filter((m) => !isDeadStatus(m.status)) ?? [];
+    if (liveMembers.length)
+        console.log(`  ${chalk.dim('agents')}   ${formatProjectMembers(liveMembers)}`);
     const ships = [];
     if (remote?.mergedPrs) {
         ships.push(chalk.green(`${remote.mergedPrs}${remote.mergedPrsTruncated ? '+' : ''} merged (${remote.windowDays}d)`));
@@ -343,13 +381,16 @@ focus = []) {
         console.log(`  ${chalk.yellow('!')}        ${chalk.yellow(mismatch.message)}`);
         console.log(`  ${' '.repeat(8)}${chalk.gray(mismatch.remediation)}`);
     }
-    if (def.contexts?.length) {
+    // `view` prints these in full (path + purpose, label + URL) right below, so
+    // the compact one-line summaries would just say the same thing twice.
+    if (!detail && def.contexts?.length) {
         console.log(`  ${chalk.dim('context')}  ${def.contexts.map((c) => c.path).join(' · ')}`);
     }
-    if (def.integrations?.length) {
+    if (!detail && def.integrations?.length) {
         console.log(`  ${chalk.dim('links')}    ${def.integrations.map((i) => i.label ?? i.kind).join(' · ')}`);
     }
-    console.log('');
+    if (!detail)
+        console.log('');
 }
 export function registerProjectsCommands(program) {
     const enabled = isBetaEnabled('projects');
@@ -468,58 +509,70 @@ export function registerProjectsCommands(program) {
     projects
         .command('view <name>')
         .alias('show')
-        .description('Show a project definition, resolved paths, repos, contexts, links, and milestones.')
+        .description('Everything about one project: the full status card, every milestone, and the stored definition.')
         .option('--json', 'Machine-readable output')
-        .option('--no-remote', 'Skip the Linear lookup; definition only')
+        .option('--window <days>', 'Window for merged PRs, artifacts, and focus areas', '7')
+        .option('--no-remote', 'Skip the GitHub and Linear lookups; definition only')
         .action(async (name, opts) => {
         const def = loadProjectDef(name);
         if (!def) {
             console.error(chalk.red(`No project named "${name}". List them: agents projects list`));
             process.exit(1);
         }
-        // Every milestone the project declares, not just the next one — the whole
-        // point of opening ONE project is to see the shape of its plan.
-        const counts = opts.remote !== false && def.linear?.projectId
-            ? await fetchLinearProjectCounts(def.linear.projectId)
-            : undefined;
+        // `view` is `status` for one project PLUS the stored definition and every
+        // milestone. It used to render its own short list — root, repos, a raw
+        // Linear id, issues — so opening a single project told you LESS than the
+        // roll-up did: no agents, no ships, no focus, no schedule verdict.
+        const windowDays = Math.max(1, Number.parseInt(opts.window ?? '7', 10) || 7);
+        const nowMs = Date.now();
+        const all = listProjectDefs();
+        const { roll, remote, linear, focus } = await enrichProjectsForRender([def], all, {
+            windowDays,
+            nowMs,
+            skipRemote: opts.remote === false,
+        });
+        const r = roll.get(def.name);
+        const sig = remote.get(def.name);
+        const counts = linear.get(def.name);
         if (opts.json) {
-            console.log(JSON.stringify({ ...def, linear: { ...def.linear, ...(counts ?? {}) } }, null, 2));
+            console.log(JSON.stringify({
+                ...def,
+                linear: { ...def.linear, ...(counts ?? {}) },
+                schedule: counts?.milestones?.length ? scheduleVerdict(counts.milestones, nowMs) : null,
+                live: r ? liveDeadSplit(r.byStatus).live : 0,
+                dead: r ? liveDeadSplit(r.byStatus).dead : 0,
+                byStatus: r?.byStatus ?? {},
+                members: r?.members ?? [],
+                openPrs: r?.openPrs ?? [],
+                tickets: r?.tickets ?? [],
+                mergedPrs: sig?.mergedPrs ?? 0,
+                latestRelease: sig?.latestRelease ?? null,
+                artifacts: sig?.artifacts ?? 0,
+                focus: focus.get(def.name) ?? [],
+            }, null, 2));
             return;
         }
-        console.log(chalk.bold(def.name) + (def.description ? chalk.dim(`  — ${def.description}`) : ''));
+        // The same card `status` prints, with every milestone instead of the next.
+        renderCard(def, r, sig, undefined, counts, nowMs, Number.POSITIVE_INFINITY, focus.get(def.name) ?? [], true);
+        // Then what only `view` shows: the stored definition, in full.
+        console.log();
         if (def.root)
-            console.log(`  root         ${def.root}`);
+            console.log(`  ${chalk.dim('root')}     ${def.root}`);
         if (def.defaultPath)
-            console.log(`  defaultPath  ${def.defaultPath}`);
-        const repos = [def.repo, ...(def.repos ?? []).map((r) => (r.subpath ? `${r.slug} (${r.subpath})` : r.slug))].filter(Boolean);
-        if (repos.length)
-            console.log(`  repos        ${repos.join(', ')}`);
+            console.log(`  ${chalk.dim('path')}     ${def.defaultPath}`);
+        for (const rp of def.repos ?? []) {
+            const where = [rp.subpath ? `subpath ${rp.subpath}` : undefined, rp.path].filter(Boolean).join(' · ');
+            console.log(`  ${chalk.dim('repo')}     ${rp.slug}${where ? chalk.dim(`  (${where})`) : ''}`);
+        }
         for (const c of def.contexts ?? [])
-            console.log(`  context      ${chalk.cyan(c.path)} — ${c.purpose}`);
-        for (const i of def.integrations ?? [])
-            console.log(`  ${i.kind.padEnd(12)} ${i.url}${i.label ? chalk.dim(`  (${i.label})`) : ''}`);
+            console.log(`  ${chalk.dim('context')}  ${chalk.cyan(c.path)} ${chalk.dim('—')} ${c.purpose}`);
+        for (const ig of def.integrations ?? []) {
+            console.log(`  ${chalk.dim(ig.kind.padEnd(8))} ${ig.url}${ig.label ? chalk.dim(`  (${ig.label})`) : ''}`);
+        }
         if (def.linear?.url || def.linear?.projectId)
-            console.log(`  linear       ${def.linear.url ?? def.linear.projectId}`);
+            console.log(`  ${chalk.dim('linear')}   ${def.linear.url ?? def.linear.projectId}`);
         for (const d of def.docs ?? [])
-            console.log(`  doc          ${d}`);
-        if (counts) {
-            const staleNote = counts.stale ? chalk.dim('  (cached)') : '';
-            console.log(`  issues       ${counts.done}/${counts.total}${counts.truncated ? '+' : ''} done · ${counts.inProgress} in progress${staleNote}`);
-        }
-        const ms = counts?.milestones ?? [];
-        if (ms.length) {
-            console.log(`  ${chalk.bold('milestones')}`);
-            for (const m of ms) {
-                const mark = m.name === counts?.nextMilestone?.name ? chalk.cyan('next') : '';
-                console.log(`    ${mark.padEnd(6)}     ${formatNextMilestone(m, Date.now())}`);
-            }
-            // A milestone nothing is filed against cannot report progress. Say that
-            // once, plainly, rather than printing a row of silent 0%s.
-            const unfiled = ms.filter((m) => m.total === 0).length;
-            if (unfiled === ms.length) {
-                console.log(`    ${chalk.yellow('!')}          ${chalk.yellow(`no issues are assigned to any milestone — progress against them cannot be measured`)}`);
-            }
-        }
+            console.log(`  ${chalk.dim('doc')}      ${d}`);
         console.log(chalk.gray(`  ${projectDefPath(name)}`));
     });
     // ---- edit ----
@@ -590,27 +643,12 @@ export function registerProjectsCommands(program) {
             fleetSkipped = probeRes.skipped;
             fleetSessions = activeRes.sessions;
         }
-        const roll = rollupSessionsByProject(all, [...await getActiveSessions(), ...fleetSessions]);
-        // Enrich only the shown projects. --no-remote still reads the local artifact
-        // log but skips the gh calls + Linear counts (both are network).
-        const remote = new Map();
-        const linear = new Map();
-        // Local git, no API, no rate limit — measured 0.23s over a 897-commit week.
-        const focus = new Map();
-        await Promise.all(defs.map(async (d) => {
-            const skipRemote = opts.remote === false;
-            const [sig, counts] = await Promise.all([
-                enrichProjectSignals(d, windowDays, nowMs, { skipRemote }),
-                !skipRemote && d.linear?.projectId
-                    ? fetchLinearProjectCounts(d.linear.projectId)
-                    : Promise.resolve(undefined),
-            ]);
-            remote.set(d.name, sig);
-            if (counts)
-                linear.set(d.name, counts);
-            if (d.root)
-                focus.set(d.name, await readFocusAreas(expandLocalHome(d.root), windowDays));
-        }));
+        const { roll, remote, linear, focus } = await enrichProjectsForRender(defs, all, {
+            windowDays,
+            nowMs,
+            skipRemote: opts.remote === false,
+            extraSessions: fleetSessions,
+        });
         /** This def's slice of the fleet probe, in its own target order. */
         const fleetFor = (d) => {
             const targets = new Set(workspaceTargetsForDef(d));

package/dist/lib/app-bundle-install.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copy an `.app` bundle to `dest` atomically. Stages into a sibling dir, then
+ * swaps with renames — the window where `dest` is absent shrinks from the
+ * seconds-long `cp` to a single microsecond rename, and a failed copy leaves the
+ * existing bundle untouched. Serialize concurrent callers with {@link withInstallLock}
+ * so the two-step swap never races another swap.
+ */
+export declare function copyAppBundle(src: string, dest: string, io?: {
+    renameSync?: (from: string, to: string) => void;
+}): void;
+/**
+ * Serialize installs across the many concurrent `agents` invocations that pass
+ * through the helper-install path, so a burst copies once instead of stampeding
+ * the atomic swap. Locks a sentinel file beside the bundle (the bundle itself may
+ * not exist yet on first install) via the shared {@link withFileLock}.
+ */
+export declare function withInstallLock(dest: string, fn: (heartbeat: () => void) => void): void;

package/dist/lib/app-bundle-install.js

@@ -0,0 +1,94 @@
+/**
+ * Atomic, serialized install of a macOS `.app` bundle to a stable user path.
+ *
+ * Shared by the two helpers agents-cli installs on darwin — the secrets keychain
+ * helper (`lib/secrets/install-helper.ts`) and the menu-bar helper
+ * (`lib/menubar/install-menubar.ts`) — both of which are (re)installed on the hot
+ * path of ordinary `agents` invocations. Both previously did a non-atomic
+ * `rm -rf dest` + `cp -R src dest` straight onto the live bundle. That copy takes
+ * long enough that a concurrent reader (Gatekeeper, or an exec of the bundle) sees
+ * a half-written `.app` — a truncated Mach-O / mismatched `_CodeSignature` hash —
+ * which macOS reports as **"is damaged and can't be opened."** On a busy box dozens
+ * of concurrent invocations raced the same path, so the dialog fired intermittently.
+ *
+ * {@link copyAppBundle} stages the copy in a sibling directory and swaps it into
+ * place with renames, so a reader sees either the old or the new complete bundle,
+ * never a half-written one — the only moment `dest` is briefly absent is the
+ * sub-millisecond gap between the two renames (vs the seconds-long `cp`), and a
+ * failed copy never touches the live bundle. {@link withInstallLock} serializes concurrent
+ * installers (via the shared `withFileLock`) so a burst of invocations installs
+ * once instead of stampeding.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { withFileLock, ensureLockTarget } from './fs-atomic.js';
+// A helper `cp -R` under load can take a few seconds; the lock must outlast it so
+// a peer never treats a live installer as crashed and interleaves a second swap.
+// (fs-atomic's 5s default is tuned for sub-second read-modify-writes.)
+const INSTALL_LOCK_STALE_MS = 60_000;
+const INSTALL_LOCK_ACQUIRE_TIMEOUT_MS = 60_000;
+/**
+ * Copy an `.app` bundle to `dest` atomically. Stages into a sibling dir, then
+ * swaps with renames — the window where `dest` is absent shrinks from the
+ * seconds-long `cp` to a single microsecond rename, and a failed copy leaves the
+ * existing bundle untouched. Serialize concurrent callers with {@link withInstallLock}
+ * so the two-step swap never races another swap.
+ */
+export function copyAppBundle(src, dest, io = {}) {
+    const rename = io.renameSync ?? fs.renameSync;
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const staging = `${dest}.installing.${process.pid}`;
+    const backup = `${dest}.replaced.${process.pid}`;
+    fs.rmSync(staging, { recursive: true, force: true });
+    fs.rmSync(backup, { recursive: true, force: true });
+    // `cp -R` preserves the bundle's signature, symlinks, and resource forks;
+    // `fs.cpSync({recursive:true})` has historically mishandled xattrs on `.app`
+    // bundles, breaking codesign.
+    const r = spawnSync('cp', ['-R', src, staging], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+    if (r.status !== 0) {
+        fs.rmSync(staging, { recursive: true, force: true });
+        const msg = (r.stderr || r.stdout || '').toString().trim();
+        throw new Error(`Failed to copy ${src} -> ${staging}: ${msg || 'unknown error'}`);
+    }
+    // rename(2) cannot replace a non-empty directory, so move the current bundle
+    // aside, then move staging into place. If the second rename fails, restore the
+    // backup so `dest` is never left missing.
+    try {
+        if (fs.existsSync(dest))
+            rename(dest, backup);
+        rename(staging, dest);
+    }
+    catch (err) {
+        if (!fs.existsSync(dest) && fs.existsSync(backup)) {
+            try {
+                rename(backup, dest);
+            }
+            catch {
+                /* best-effort restore */
+            }
+        }
+        fs.rmSync(staging, { recursive: true, force: true });
+        throw new Error(`Failed to install ${src} -> ${dest}: ${err.message}`);
+    }
+    fs.rmSync(backup, { recursive: true, force: true });
+}
+/**
+ * Serialize installs across the many concurrent `agents` invocations that pass
+ * through the helper-install path, so a burst copies once instead of stampeding
+ * the atomic swap. Locks a sentinel file beside the bundle (the bundle itself may
+ * not exist yet on first install) via the shared {@link withFileLock}.
+ */
+export function withInstallLock(dest, fn) {
+    const lockTarget = `${dest}.install-lock`;
+    ensureLockTarget(lockTarget);
+    // Pass proper-lockfile's `heartbeat` straight through: the install body is a
+    // fully SYNCHRONOUS chain of blocking `spawnSync`s (`cp -R`, then codesign /
+    // spctl), so the event loop never turns and proper-lockfile's own async mtime
+    // refresh can't fire. Callers invoke heartbeat() between those steps to keep a
+    // long hold from ageing past staleMs and being broken by a contending peer.
+    withFileLock(lockTarget, (heartbeat) => fn(heartbeat), {
+        staleMs: INSTALL_LOCK_STALE_MS,
+        acquireTimeoutMs: INSTALL_LOCK_ACQUIRE_TIMEOUT_MS,
+    });
+}

package/dist/lib/devices/doctor-findings.js

@@ -304,8 +304,12 @@ export function buildLocalFindings(input) {
             }
         }
         if (neverSynced) {
-            // Everything is "missing" because it was never synced — one line, and a
-            // CRITICAL one: nothing this version declares is actually installed.
+            // Everything is "missing" because it was never synced — collapse to ONE
+            // line. A never-synced version is almost always an old/unused install (you
+            // don't run a version you never synced), so this is a WARNING, not a "needs
+            // you now" critical: it isn't hurting anything until you actually launch it.
+            // The real criticals are a logged-out account or a hook/plugin missing from
+            // a version you DO keep synced (the `else` branch below).
             const total = missingHooks.length + missingPlugins.length + missingOther.length;
             if (total > 0) {
                 const breakdown = [
@@ -313,7 +317,7 @@ export function buildLocalFindings(input) {
                     missingPlugins.length ? `${missingPlugins.length} plugin${missingPlugins.length === 1 ? '' : 's'}` : '',
                 ].filter(Boolean).join(', ');
                 out.push(finding({
-                    severity: 'critical', kind: 'never-synced', device, agent, version,
+                    severity: 'warning', kind: 'never-synced', device, agent, version,
                     message: `never synced — ${total} resource${total === 1 ? '' : 's'}${breakdown ? ` (incl. ${breakdown})` : ''} not installed`,
                 }));
             }
@@ -464,7 +468,11 @@ function duplicateHookFindings(device, dups) {
                 `${versions.length} version${versions.length === 1 ? '' : 's'} ` +
                 `(incl. ${group.slice(0, 2).map((d) => `'${d.name}'`).join(', ')}) — ${authority}`;
         out.push({
-            severity: drift ? 'critical' : 'warning',
+            // A hook that DIFFERS across versions is still installed and firing — it's
+            // stale/sync drift, not a missing hook. Resolvable by one sync; a WARNING,
+            // not a "needs you now" critical. (A genuinely MISSING hook stays critical
+            // via the missing-hook path.)
+            severity: 'warning',
             kind: drift ? 'duplicate-hook-drift' : 'duplicate-hook',
             device, agent, versions, message,
             remediation: `agents sync ${agent}@all --yes`,

package/dist/lib/devices/doctor-overview-cache.d.ts

@@ -0,0 +1,45 @@
+/** Serve a cached snapshot without recomputing while it is younger than this. */
+export declare const DOCTOR_OVERVIEW_FRESH_MS = 90000;
+/** Injectable IO + clock so tests exercise the real fs at a temp dir, no mocks. */
+export interface DoctorOverviewCacheDeps {
+    /** Cache directory (default: the real `~/.agents/.cache`). */
+    dir?: string;
+    /** Clock (default: {@link Date.now}). */
+    now?: () => number;
+}
+/** Read the last snapshot (best-effort; missing/corrupt/wrong-version → null). */
+export declare function readDoctorOverviewCache(deps?: DoctorOverviewCacheDeps): {
+    fetchedAt: number;
+    payload: unknown;
+} | null;
+/** Persist a fresh overview payload (best-effort; tmp+rename so reads are atomic). */
+export declare function writeDoctorOverviewCache(payload: unknown, deps?: DoctorOverviewCacheDeps): void;
+/**
+ * Result of {@link enterDoctorOverviewGate}.
+ *  - `cached` non-null → the caller MUST print this string and return; no compute.
+ *  - `cached` null     → the caller holds the singleflight lock: compute the
+ *    overview, call {@link writeDoctorOverviewCache}, and invoke `release()` on
+ *    the way out. Call `release()` in a `finally` so a compute that throws still
+ *    frees the lock promptly (idempotent).
+ */
+export interface OverviewGate {
+    cached: string | null;
+    release?: () => void;
+}
+/**
+ * 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 declare function enterDoctorOverviewGate(opts?: {
+    forceRefresh?: boolean;
+    freshMs?: number;
+}, deps?: DoctorOverviewCacheDeps): Promise<OverviewGate>;